Dialpad User Management API Guide

Auth method: API Key (Bearer token in Authorization header)

Setup steps

1. Sign in as a Company Admin in Dialpad.
2. Navigate to Admin Settings -> My Company -> Authentication -> API keys.
3. Create a new API key and store the value securely; the secret is shown once.
4. Pass the key as Authorization: Bearer on API requests.

List Users

• Method: GET
• URL: https://dialpad.com/api/v2/users
• Watch out for: Returns only users in the authenticated admin's scope. Use cursor for pagination; absence of cursor in response indicates last page.

Request example

GET /api/v2/users?limit=25&cursor=<cursor_token>
Authorization: Bearer <api_key>

Response example

{
  "items": [{"id":"123","email":"user@co.com","first_name":"Jane"}],
  "cursor": "next_cursor_token"
}

Get User

• Method: GET
• URL: https://dialpad.com/api/v2/users/{user_id}
• Watch out for: user_id is Dialpad's internal numeric ID, not email. Use List Users to resolve email to ID first.

Request example

GET /api/v2/users/123456
Authorization: Bearer <api_key>

Response example

{
  "id": "123456",
  "email": "jane@co.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "state": "active"
}

Create User

• Method: POST
• URL: https://dialpad.com/api/v2/users
• Watch out for: A license must be available in the account; creation fails if no licenses remain. office_id is required.

Request example

POST /api/v2/users
Authorization: Bearer <api_key>
Content-Type: application/json
{
  "email":"new@co.com",
  "first_name":"John",
  "last_name":"Smith",
  "office_id":"789"
}

Response example

{
  "id": "654321",
  "email": "new@co.com",
  "state": "active"
}

Update User

• Method: PATCH
• URL: https://dialpad.com/api/v2/users/{user_id}
• Watch out for: Only include fields to be changed; omitted fields are not modified. Email changes may trigger re-verification.

Request example

PATCH /api/v2/users/654321
Authorization: Bearer <api_key>
Content-Type: application/json
{
  "first_name": "Jonathan",
  "timezone": "America/Chicago"
}

Response example

{
  "id": "654321",
  "first_name": "Jonathan",
  "timezone": "America/Chicago"
}

Delete User

• Method: DELETE
• URL: https://dialpad.com/api/v2/users/{user_id}
• Watch out for: Deletion is permanent and releases the user's DID back to inventory. Consider setting state=suspended for reversible deactivation.

Request example

DELETE /api/v2/users/654321
Authorization: Bearer <api_key>

Response example

HTTP 204 No Content

Get User by Email

• Method: GET
• URL: https://dialpad.com/api/v2/users/{email}
• Watch out for: Email must be URL-encoded. This is a convenience endpoint; the response is identical to GET /users/{user_id}.

Request example

GET /api/v2/users/jane%40co.com
Authorization: Bearer <api_key>

Response example

{
  "id": "123456",
  "email": "jane@co.com",
  "state": "active"
}

List Offices

• Method: GET
• URL: https://dialpad.com/api/v2/offices
• Watch out for: Required to obtain valid office_id values before creating users.

Request example

GET /api/v2/offices
Authorization: Bearer <api_key>

Response example

{
  "items": [{"id":"789","name":"HQ","country":"US"}],
  "cursor": null
}

Assign User to Call Center

• Method: POST
• URL: https://dialpad.com/api/v2/callcenters/{callcenter_id}/operators
• Watch out for: User must already exist and be active. Separate endpoint from user creation; not part of the POST /users payload.

Request example

POST /api/v2/callcenters/111/operators
Authorization: Bearer <api_key>
Content-Type: application/json
{
  "user_id": "654321"
}

Response example

{
  "user_id": "654321",
  "callcenter_id": "111",
  "status": "active"
}

• Rate limits: Dialpad documents a company-level limit of 20 requests per second, and some endpoints also document per-endpoint caps such as 1200 requests per minute.
• Rate-limit headers: Unknown
• Retry-After header: Unknown
• Rate-limit notes: Handle HTTP 429 responses and consult endpoint-specific limits when bulk-syncing users.
• Pagination method: cursor
• Default page size: 25
• Max page size: 100
• Pagination pointer: cursor

• Webhooks available: Yes
• Webhook notes: Dialpad supports webhooks for real-time event notifications. Webhooks are configured per-event type in the Admin Portal or via the API. Payloads are delivered via HTTP POST to a registered URL.
• Alternative event strategy: Poll GET /users with a cursor for user-change detection if webhooks are not feasible.
• Webhook events: call.started, call.ended, call.missed, sms.created, voicemail.created, user.created, user.updated, user.deleted

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Varies by Dialpad product and IdP integration; verify current Dialpad support docs

• Endpoint: https://dialpad.com/scim/v2

• Supported operations: GET /Users, GET /Users/{id}, POST /Users, PUT /Users/{id}, PATCH /Users/{id}, DELETE /Users/{id}, GET /Groups, POST /Groups, PATCH /Groups/{id}, DELETE /Groups/{id}

Limitations:

• SSO/SAML setup must be validated before enabling SCIM provisioning.
• Supported IdP flows and plan availability vary by Dialpad product and connector.
• SCIM group-to-office mapping should be tested before enabling group push at scale.

Three scenarios cover the majority of programmatic use cases. For onboarding: call GET /offices first to resolve a valid office_id, then POST /users with email, name, office, and license - the API returns 400 if no license seats remain, so availability checks must precede bulk provisioning runs.

For offboarding: resolve the internal numeric ID via GET /users/{email} (URL-encode the address), then PATCH /users/{id} with {"state": "suspended"} for reversible deactivation.

reserve DELETE /users/{id} for post-retention permanent removal, as deletion is irreversible and immediately releases the user's DID back to inventory. For IdP-driven bulk sync via SCIM 2.

0 (https://dialpad.com/scim/v2): SAML SSO must be fully active before SCIM can be enabled - enabling SCIM without SSO fails silently in some IdP flows. Supported IdPs are Okta, Microsoft Entra ID, Google Workspace, JumpCloud, and OneLogin.

SCIM Groups map to Dialpad Offices; pre-create offices in Dialpad before the first sync to avoid orphaned users.

Onboard a new employee

1. GET /api/v2/offices to retrieve the target office_id.
2. POST /api/v2/users with email, first_name, last_name, office_id, and license.
3. Capture the returned user id.
4. PATCH /api/v2/users/{id} to set timezone, language, and phone_number if required.
5. Optionally POST /api/v2/callcenters/{id}/operators to add user to a call center queue.

Watch out for: License availability must be confirmed before POST /users; the API returns 400 if no seats remain.

Offboard a departing employee

1. GET /api/v2/users and filter by email to resolve the internal user id.
2. PATCH /api/v2/users/{id} to suspend or update access state if your workflow requires a non-destructive hold before deletion.
3. Reassign or release the user's DID and related routing configuration via the appropriate telephony endpoints.
4. DELETE /api/v2/users/{id} only after number and routing cleanup is complete.

Watch out for: Do not assume email is a stable path parameter. Resolve the Dialpad user id first, then clean up telephony dependencies before deletion.

Bulk sync users via SCIM from Okta

1. Confirm Pro/Premium plan and that SAML SSO is active in Dialpad Admin Portal.
2. In Okta, add the Dialpad SCIM application and configure the SCIM base URL: https://dialpad.com/scim/v2.
3. Generate a SCIM bearer token in Dialpad Admin Portal under Integrations > SCIM.
4. Map Okta profile attributes to SCIM attributes (userName=email, name.givenName, name.familyName).
5. Assign Okta groups to the Dialpad SCIM app; groups will map to Dialpad Offices.
6. Enable provisioning features: Create Users, Update User Attributes, Deactivate Users.
7. Run an initial import/sync and validate user states in Dialpad Admin Portal.

Watch out for: SCIM Groups in Okta map to Dialpad Offices; ensure office names match or pre-create offices in Dialpad before the first sync to avoid orphaned users.

Dialpad automation fails in production when teams treat the user record as the whole problem. It is not. You also have to manage company-admin API key ownership, company-level rate limits, seat availability at create time, and separate cleanup of numbers and routing.

The identity record and the telephony configuration have to be handled together.