Pipedrive User Management API Guide

Auth method: API token (query param) or OAuth 2.0 (Authorization header Bearer token)

Setup steps

1. API Token: Navigate to Pipedrive Settings → Personal Preferences → API. Copy the personal API token.
2. API Token usage: Append ?api_token=YOUR_TOKEN to every request URL.
3. OAuth 2.0: Register an app at https://developers.pipedrive.com/. Obtain client_id and client_secret.
4. OAuth 2.0: Redirect user to https://oauth.pipedrive.com/oauth/authorize?client_id=...&redirect_uri=...&scope=....
5. OAuth 2.0: Exchange the returned authorization code for an access token via POST to https://oauth.pipedrive.com/oauth/token.
6. OAuth 2.0: Include Authorization: Bearer ACCESS_TOKEN header on all API requests.

Required scopes

List all users

• Method: GET
• URL: https://api.pipedrive.com/v1/users
• Watch out for: Returns all users in the company account. Requires admin-level token or OAuth scope. Inactive users are included; filter by active_flag client-side.

Request example

GET /v1/users?limit=100&start=0&api_token=TOKEN

Response example

{
  "success": true,
  "data": [{"id":1,"name":"Jane Doe","email":"jane@example.com","active_flag":true}],
  "additional_data": {"pagination":{"start":0,"limit":100,"more_items_in_collection":false}}
}

Get single user

• Method: GET
• URL: https://api.pipedrive.com/v1/users/{id}
• Watch out for: Returns the authenticated user's own data if the token belongs to a non-admin; admins can retrieve any user by ID.

Request example

GET /v1/users/42?api_token=TOKEN

Response example

{
  "success": true,
  "data": {"id":42,"name":"John Smith","email":"john@example.com","active_flag":true,"role_id":3}
}

Get current user (me)

• Method: GET
• URL: https://api.pipedrive.com/v1/users/me
• Watch out for: Useful for resolving the authenticated user's ID from an OAuth token without knowing the user ID in advance.

Request example

GET /v1/users/me?api_token=TOKEN

Response example

{
  "success": true,
  "data": {"id":1,"name":"Jane Doe","email":"jane@example.com","company_id":100}
}

Add user

• Method: POST
• URL: https://api.pipedrive.com/v1/users
• Watch out for: Requires company admin privileges. The new user receives an invitation email automatically. You cannot set a password via API.

Request example

POST /v1/users
Content-Type: application/json
{
  "name": "Alice Brown",
  "email": "alice@example.com",
  "active_flag": true
}

Response example

{
  "success": true,
  "data": {"id":55,"name":"Alice Brown","email":"alice@example.com","active_flag":true}
}

Update user

• Method: PUT
• URL: https://api.pipedrive.com/v1/users/{id}
• Watch out for: Setting active_flag to false deactivates the user. The endpoint uses PUT (full-style), but only supplied fields are changed in practice. Cannot deactivate the last admin.

Request example

PUT /v1/users/55
Content-Type: application/json
{
  "active_flag": false
}

Response example

{
  "success": true,
  "data": {"id":55,"name":"Alice Brown","active_flag":false}
}

Find users by name

• Method: GET
• URL: https://api.pipedrive.com/v1/users/find
• Watch out for: Use search_by_email=1 to search by email address instead of name. Returns partial matches.

Request example

GET /v1/users/find?term=alice&search_by_email=1&api_token=TOKEN

Response example

{
  "success": true,
  "data": [{"id":55,"name":"Alice Brown","email":"alice@example.com"}]
}

List user role assignments

• Method: GET
• URL: https://api.pipedrive.com/v1/users/{id}/roleAssignments
• Watch out for: Returns the role(s) assigned to the user. Role IDs must be resolved separately via GET /roles.

Request example

GET /v1/users/55/roleAssignments?api_token=TOKEN

Response example

{
  "success": true,
  "data": [{"id":10,"role_id":3,"user_id":55,"active_flag":true}]
}

List user permissions

• Method: GET
• URL: https://api.pipedrive.com/v1/users/{id}/permissions
• Watch out for: Returns a flat map of permission flags. These are derived from the user's role and permission set; they cannot be set directly on this endpoint.

Request example

GET /v1/users/55/permissions?api_token=TOKEN

Response example

{
  "success": true,
  "data": {"can_add_products":true,"can_bulk_edit_items":false,"can_delete_activities":true}
}

• Rate limits: Pipedrive enforces per-second and per-day rate limits that vary by plan. Limits apply per company token or OAuth app.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: When rate limited, API returns HTTP 429. Response headers include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and X-Daily-Requests-Left. Pipedrive recommends exponential backoff on 429 responses.
• Pagination method: offset
• Default page size: 100
• Max page size: 500
• Pagination pointer: start (offset) and limit (page size); response includes additional_data.pagination object with next_start

• Webhooks available: Yes
• Webhook notes: Pipedrive supports webhooks for real-time event notifications. Webhooks can be configured via the UI (Settings → Webhooks) or via the Webhooks API endpoint. Each webhook targets a URL and fires on specified object/action combinations.
• Alternative event strategy: Poll GET /v1/users with updated_since filter for change detection if webhooks are not available on lower-tier plans.
• Webhook events: user.added, user.updated, user.deleted, person.added, person.updated, deal.added, deal.updated

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Ultimate (formerly Enterprise); SSO must be configured first

• Endpoint: https://api.pipedrive.com/scim/v2

• Supported operations: GET /Users – list users, GET /Users/{id} – get user, POST /Users – provision user, PUT /Users/{id} – replace user, PATCH /Users/{id} – update user attributes, DELETE /Users/{id} – deprovision user, GET /Groups – list groups (roles), GET /ServiceProviderConfig, GET /Schemas

Limitations:

• Requires Ultimate plan with SAML SSO configured (Okta, Microsoft Entra ID supported).
• SCIM token is separate from the REST API token; generated in Security settings.
• Group provisioning maps to Pipedrive roles; not all role attributes are writable via SCIM.
• Password management is not supported via SCIM (SSO handles authentication).
• Deprovisioning sets active=false; it does not permanently delete the user or reassign their data automatically.

Provisioning a new user requires a POST /v1/users call with name, email, and active_flag: true. The user receives an invitation email automatically - there is no way to suppress this or set a password via API.

Role assignment is a separate call: POST /v1/roles/{role_id}/assignments with the returned user_id. Omitting this step leaves the user without a role assignment.

Deactivating a departing employee requires resolving their numeric user ID first - use GET /v1/users/find?term=user@example.com&search_by_email=1. Then send PUT /v1/users/{id} with {"active_flag": false}. Deactivation does not automatically reassign owned deals, activities, or contacts; these must be explicitly reassigned via separate API calls to /deals, /activities, etc.

SCIM 2.0 is available at https://api.pipedrive.com/scim/v2 and supports full user provisioning and deprovisioning, including Okta and Microsoft Entra ID. It requires the Ultimate plan with SAML SSO active. The SCIM bearer token is generated separately in Security settings and is distinct from the REST API token. SCIM group push maps to Pipedrive roles by name - a mismatch between Okta group names and Pipedrive role names causes silent failures or unintended role creation.

Provision a new employee and assign a role

1. POST /v1/users with name, email, active_flag=true to create the user (admin token required).
2. Capture the returned user id from the response.
3. GET /v1/roles to retrieve available role IDs.
4. POST /v1/roles/{role_id}/assignments with {user_id: } to assign the appropriate role.
5. Verify by calling GET /v1/users/{id}/roleAssignments.

Watch out for: The new user receives an invitation email automatically on POST /users. Role assignment is a separate API call; the user is created without a role if you omit this step.

Deactivate a departing employee

1. GET /v1/users/find?term=user@example.com&search_by_email=1 to resolve the user's numeric ID.
2. PUT /v1/users/{id} with body {"active_flag": false} to deactivate the account.
3. Optionally reassign open deals: GET /v1/deals?user_id={id}&status=open, then PATCH each deal with a new user_id.
4. Confirm deactivation: GET /v1/users/{id} and verify active_flag is false.

Watch out for: Deactivation does not automatically reassign owned deals, activities, or contacts. Data remains attributed to the deactivated user until explicitly reassigned.

Sync users via SCIM with Okta

1. Confirm the Pipedrive account is on the Ultimate plan with SAML SSO enabled.
2. In Pipedrive Security settings, generate a SCIM bearer token.
3. In Okta, add the Pipedrive application from the Okta Integration Network.
4. Configure SCIM provisioning in Okta: set SCIM connector base URL to https://api.pipedrive.com/scim/v2, authentication type Bearer Token, paste the SCIM token.
5. Enable Okta provisioning features: Push New Users, Push Profile Updates, Deactivate Users.
6. Assign users or groups in Okta to trigger provisioning to Pipedrive.

Watch out for: SCIM group push maps Okta groups to Pipedrive roles. If the role name in Pipedrive does not exactly match the Okta group name, group assignment will fail silently or create a new role.

The PUT /v1/users/{id} endpoint uses HTTP PUT but behaves as a partial update in practice - only supplied fields are modified. This is non-standard and can cause confusion when building integrations that assume PUT requires a full object payload.

Rate limits are enforced at 80 requests per 2 seconds and 80,000 requests per day across all plans. The X-RateLimit-Reset header returns a Unix timestamp, not a seconds-until-reset delta - a common misread that causes incorrect backoff timing. Pipedrive returns HTTP 429 on breach; implement exponential backoff.

Webhook delivery is not guaranteed. The user.added, user.updated, and user.deleted events are available, but idempotent handlers and periodic reconciliation via GET /v1/users polling are necessary for any provisioning workflow that requires correctness.

Pagination uses offset-based start and limit parameters with a default page size of 100 and a maximum of 500; the additional_data.pagination.next_start field drives iteration.