Proofpoint User Management API Guide

Auth method: HTTP Basic Authentication (service principal credentials: API key as username, secret as password) for Essentials; Service Principal (client_id + client_secret) for Enterprise/TAP APIs

Setup steps

1. Log in to the Proofpoint Essentials admin console.
2. Navigate to Settings > API Keys to generate an API key and secret.
3. Base64-encode 'apikey:secret' and pass as Authorization: Basic header.
4. For Enterprise/TAP APIs, obtain a service principal from your Proofpoint account team and use client credentials flow against https://api.proofpoint.com.

Required scopes

List Users

• Method: GET
• URL: https://api.proofpoint.com/v2/users
• Watch out for: Returns only users within the organization associated with the API key. Pagination required for orgs with >100 users.

Request example

GET /v2/users?page=1&pageSize=100
Authorization: Basic <base64(apikey:secret)>

Response example

{
  "users": [
    {"primaryEmail": "user@example.com", "firstName": "Jane", "lastName": "Doe", "type": "User", "status": "active"}
  ],
  "total": 1
}

Get User

• Method: GET
• URL: https://api.proofpoint.com/v2/users/{primaryEmail}
• Watch out for: Email address in path must be URL-encoded.

Request example

GET /v2/users/user%40example.com
Authorization: Basic <base64(apikey:secret)>

Response example

{
  "primaryEmail": "user@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "type": "User",
  "roles": ["USER"],
  "status": "active"
}

Create User

• Method: POST
• URL: https://api.proofpoint.com/v2/users
• Watch out for: primaryEmail must be within a domain already registered in the Proofpoint Essentials organization.

Request example

POST /v2/users
Content-Type: application/json

{"primaryEmail":"newuser@example.com","firstName":"John","lastName":"Smith","type":"User","password":"Temp@1234"}

Response example

{
  "primaryEmail": "newuser@example.com",
  "firstName": "John",
  "lastName": "Smith",
  "type": "User",
  "status": "active"
}

Update User

• Method: PUT
• URL: https://api.proofpoint.com/v2/users/{primaryEmail}
• Watch out for: Uses full PUT semantics; omitting optional fields may reset them. primaryEmail cannot be changed via update.

Request example

PUT /v2/users/user%40example.com
Content-Type: application/json

{"firstName":"Jane","lastName":"Updated","roles":["ADMINISTRATOR"]}

Response example

{
  "primaryEmail": "user@example.com",
  "firstName": "Jane",
  "lastName": "Updated",
  "roles": ["ADMINISTRATOR"]
}

Delete User

• Method: DELETE
• URL: https://api.proofpoint.com/v2/users/{primaryEmail}
• Watch out for: Deletion is immediate and irreversible. Aliases associated with the user are also removed.

Request example

DELETE /v2/users/user%40example.com
Authorization: Basic <base64(apikey:secret)>

Response example

HTTP 204 No Content

List Groups

• Method: GET
• URL: https://api.proofpoint.com/v2/groups
• Watch out for: Group membership changes do not propagate to policy enforcement in real time; allow up to 15 minutes.

Request example

GET /v2/groups?page=1&pageSize=100
Authorization: Basic <base64(apikey:secret)>

Response example

{
  "groups": [
    {"id": "grp_001", "name": "Sales", "memberCount": 12}
  ]
}

Add User to Group

• Method: POST
• URL: https://api.proofpoint.com/v2/groups/{groupId}/members
• Watch out for: User must already exist in the organization before being added to a group.

Request example

POST /v2/groups/grp_001/members
Content-Type: application/json

{"primaryEmail":"user@example.com"}

Response example

HTTP 201 Created
{"groupId":"grp_001","primaryEmail":"user@example.com"}

Remove User from Group

• Method: DELETE
• URL: https://api.proofpoint.com/v2/groups/{groupId}/members/{primaryEmail}
• Watch out for: Removing a user from all groups does not delete the user account.

Request example

DELETE /v2/groups/grp_001/members/user%40example.com
Authorization: Basic <base64(apikey:secret)>

Response example

HTTP 204 No Content

• Rate limits: Proofpoint Essentials API enforces rate limits per API key. Official documentation states a limit of 100 requests per minute per API key. Enterprise/TAP API limits are not publicly documented.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: HTTP 429 is returned when the rate limit is exceeded. Retry-After header presence is not confirmed in official docs. Back off exponentially on 429 responses.
• Pagination method: offset
• Default page size: 100
• Max page size: 1000
• Pagination pointer: page and pageSize (Essentials); offset and limit in some endpoints

• Webhooks available: No
• Webhook notes: Proofpoint Essentials API does not expose a webhook/event subscription mechanism for user lifecycle events. Proofpoint TAP (Targeted Attack Protection) provides a SIEM API for security event streaming, but this is not user-management webhooks.
• Alternative event strategy: Poll GET /v2/users on a schedule to detect changes, or use Proofpoint's SIEM integration (TAP API) for security event data.

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• Proofpoint does not publish a native SCIM 2.0 endpoint as of the latest available documentation.
• IdP-driven provisioning (Okta, Entra ID, OneLogin) is supported via those IdPs' Proofpoint app connectors, which use the Essentials REST API under the hood rather than SCIM.
• Enterprise customers should contact Proofpoint account team to confirm current SCIM availability, as this may vary by product line.

Bulk onboarding requires pre-registering target email domains in the admin console before any POST to /v2/users will succeed - domain registration cannot be done via API.

Each user creation call requires primaryEmail, firstName, lastName, type, and a temporary password; group assignment is a separate POST to /v2/groups/{groupId}/members. Throttle to under 100 req/min and implement exponential backoff on HTTP 429, as no Retry-After header is confirmed in official documentation.

For deprovisioning, the API offers no soft-delete: DELETE /v2/users/{primaryEmail} is immediate and irreversible, including removal of all associated aliases. If temporary suspension is required, set the status field to inactive via a full PUT (the API uses PUT, not PATCH - omitting fields risks resetting them).

For IdP sync without native SCIM, configure the Proofpoint Essentials app connector in Okta or Entra ID, map profile attributes, and monitor IdP provisioning logs for 400 (domain-not-registered) and 429 (rate limit) errors. group push support varies by connector version.

Bulk onboard new employees

1. Verify target email domains are registered in the Proofpoint Essentials admin console.
2. Generate an API key with administrator privileges under Settings > API Keys.
3. For each new user, POST to /v2/users with primaryEmail, firstName, lastName, type='User', and a temporary password.
4. Optionally POST to /v2/groups/{groupId}/members to assign the user to the appropriate policy group.
5. Throttle requests to stay under 100 req/min; implement exponential backoff on HTTP 429.

Watch out for: If a user's email domain is not pre-registered in Proofpoint Essentials, the POST will return a 400 error. Domain registration must be done via the admin UI, not the API.

Deprovision a departed employee

1. Call GET /v2/users/{primaryEmail} to confirm the user exists and retrieve current group memberships.
2. Call DELETE /v2/groups/{groupId}/members/{primaryEmail} for each group to remove policy associations.
3. Call DELETE /v2/users/{primaryEmail} to permanently remove the account.
4. Verify deletion with GET /v2/users/{primaryEmail}; expect HTTP 404.

Watch out for: Deletion is immediate and irreversible. There is no soft-delete or suspend state via the API; if temporary suspension is needed, update the user's status field to 'inactive' instead of deleting.

Sync users from an IdP (Okta/Entra) without native SCIM

1. Configure the Proofpoint Essentials app connector in Okta or Entra ID, which uses the Essentials REST API for provisioning.
2. Map IdP profile attributes (firstName, lastName, email, groups) to Proofpoint Essentials user fields in the IdP connector settings.
3. Enable provisioning actions: Create Users, Update User Attributes, Deactivate Users in the IdP connector.
4. Test with a pilot user; verify the user appears in GET /v2/users after IdP push.
5. Monitor IdP provisioning logs for API errors; common failures are domain-not-registered (400) and rate limit (429).

Watch out for: Okta and Entra connectors for Proofpoint Essentials use the REST API, not SCIM. Group push behavior depends on the IdP connector version; verify group mapping is supported before relying on it.

The primary integration risk is the Essentials/Enterprise API split: different base URLs, different auth mechanisms, and different capability sets exist across Proofpoint product lines, and the developer portal (developer.proofpoint.com) documents TAP/TRAP/PSAT APIs - not the Essentials user-management API, which lives in the help center.

API keys are scoped to a single Essentials organization; MSP or reseller accounts must manage per-org keys explicitly. The PUT-only update semantics are a silent data-loss risk: any field omitted from an update payload may be reset to default.

primaryEmail is immutable after creation, so email address changes require a delete-and-recreate cycle, which also removes all aliases. Webhooks are not available for user lifecycle events in Essentials; the only detection mechanism for external systems is polling GET /v2/users on a schedule.

The TAP SIEM API provides security event streaming but is not a substitute for user-management event hooks.

Teams building automated identity graph reconciliation against Proofpoint should account for the absence of a last-login field, the 15-minute propagation delay for group membership changes to reach policy enforcement, and the re-creation risk when directory sync is active alongside API-driven deletions.