A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Dialpad API is how an app or AI agent works with a Dialpad account: placing and transferring calls, sending an SMS, listing call history, and managing the users, contacts, and call centers behind a phone system. Access is granted through an API key tied to one company or an OAuth connection, and sensitive areas like recordings and message content require their own scope on top. Dialpad can also push events to a registered endpoint as calls and messages happen, so an integration reacts in near real time.
How an app or AI agent connects to Dialpad determines what it can reach. There is a route for making calls to the API, a route for receiving events as they happen, and the connection is governed by the key behind it and any scopes that key carries.
The REST API takes JSON request bodies, returns JSON, and pages through lists with a cursor token, at https://dialpad.com/api/v2 in production and https://sandbox.dialpad.com/api/v2 in the sandbox. A call authenticates with an API key or OAuth bearer token in the Authorization header.
Dialpad POSTs events to an HTTPS endpoint that is registered as a webhook and then attached to an event subscription, one per event type such as call events, SMS events, or contact events. Each subscription is scoped to a target like a company, office, call center, or user, and delivers matching events in near real time.
As an alternative to an HTTPS webhook, Dialpad can deliver events over a websocket that an integration creates and then attaches to an event subscription. The same event types and targeting apply, so an integration receives call, SMS, contact, and other events on a persistent connection.
An administrator generates an API key for their own Dialpad company. The key reaches that company's data and is sent as a bearer token in the Authorization header. It is intended for internal apps that act on a single company, and Dialpad recommends the header over the query-parameter option so the key does not appear in logs.
OAuth 2.0 uses a three-legged authorization-code flow following RFC 6749: a user is redirected to authorize, Dialpad returns a code, and the app exchanges it at the token endpoint for a bearer access token. Scopes requested in the flow narrow what the token can reach, and offline_access returns a refresh token. It is the route for third-party apps connecting accounts across different companies.
The Dialpad API is split into areas an agent can act on, like calls, messages, users, contacts, and the offices, departments, and call centers that route work. Each area has its own methods, and writes in some areas place real phone calls, send real messages, or change who can answer a line.
Methods for placing, retrieving, transferring, and managing phone calls.
Methods for sending SMS and scheduling or bulk-sending messages.
Methods for working with the people on a Dialpad account.
Methods for working with shared and personal contacts.
Methods for working with offices and their operators.
Methods for working with departments and their operators.
Methods for working with call centers and their operators.
Methods for subscribing to events and registering delivery targets.
Methods for requesting and retrieving usage and performance data.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
CallsMethods for placing, retrieving, transferring, and managing phone calls.6 | ||||||
| POST | /api/v2/users/{user_id}/calls | Initiate an outbound call on behalf of a user. | write | — | Current | |
Places a real call; limited to 5 calls per minute per user target. Reachable with a standard company key. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook event call.eventRate limit5 per minute per user target SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/calls/{call_id} | Get the status and details of a call. | read | — | Current | |
Read-only; reachable with a standard company key. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/calls | List calls that have concluded, in reverse-chronological order, filtered by parameters. | read | calls:list | Current | |
Requires the calls:list scope. Returns only calls that have already ended. Acts oncall Permission (capability) calls:listVersionAvailable since the API’s base version Webhook eventNone Rate limit1200 per minute SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/calls/{call_id}/transfer | Transfer an active call to another destination. | write | — | Current | |
Redirects a live call; reachable with a standard company key. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook event call.eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/calls/{call_id}/hangup | Hang up an active call. | write | — | Current | |
Ends a live call; reachable with a standard company key. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook event call.eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/calls/{call_id}/ai_recap | Get the AI-generated recap of a call. | read | ai_recap | Current | |
Requires the ai_recap scope. Limited to 12 per minute. Acts oncall Permission (capability) ai_recapVersionAvailable since the API’s base version Webhook eventNone Rate limit12 per minute SourceOfficial documentation ↗ | ||||||
Messaging (SMS)Methods for sending SMS and scheduling or bulk-sending messages.2 | ||||||
| POST | /api/v2/sms/send | Send an SMS to a phone number or a Dialpad channel on behalf of a user. | write | — | Current | |
Sends a real message; max request size 1MB including attachments. Reachable with a standard company key. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook event sms.eventRate limit100 per minute (tier 0), 800 per minute (tier 1) SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/message/schedule | Schedule a message to be sent at a future time. | write | — | Current | |
Queues a real message for later delivery. Acts onscheduled_message Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersMethods for working with the people on a Dialpad account.6 | ||||||
| POST | /api/v2/users | Create a user on the company account. | write | — | Current | |
A core write; may consume a license. Reachable with a standard company key. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/users | List the users on the company account. | read | — | Current | |
Read-only; reachable with a standard company key. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/users/{user_id} | Get a user. The id 'me' returns the authenticated user. | read | — | Current | |
Read-only; reachable with a standard company key. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/users/{user_id} | Update a user's properties. | write | — | Current | |
A core write; reachable with a standard company key. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/users/{user_id} | Delete a user from the company account. | write | — | Current | |
Irreversible; removes the user. Reachable with a standard company key. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/users/{user_id}/devices/{device_id}/screen_pop | Trigger a screen pop on a user's device, surfacing context for an incoming interaction. | write | screen_pop | Current | |
Requires the screen_pop scope. Limited to 5 per minute. Acts onscreen_pop Permission (capability) screen_popVersionAvailable since the API’s base version Webhook eventNone Rate limit5 per minute SourceOfficial documentation ↗ | ||||||
ContactsMethods for working with shared and personal contacts.4 | ||||||
| POST | /api/v2/contacts | Create a shared or personal contact. | write | — | Current | |
Limited to 100 contacts created per minute. Reachable with a standard company key. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event contact.eventRate limit100 per minute SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/contacts | List contacts. | read | — | Current | |
Read-only; reachable with a standard company key. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/contacts/{contact_id} | Update a contact. | write | — | Current | |
A core write; reachable with a standard company key. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event contact.eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/contacts/{contact_id} | Delete a contact. | write | — | Current | |
Irreversible; reachable with a standard company key. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event contact.eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OfficesMethods for working with offices and their operators.2 | ||||||
| GET | /api/v2/offices | List the offices on the company account. | read | — | Current | |
Read-only; reachable with a standard company key. Acts onoffice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/offices/{office_id}/operators | Add an operator to an office. | write | — | Current | |
Changes who operates the office; reachable with a standard company key. Acts onoffice_operator Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DepartmentsMethods for working with departments and their operators.2 | ||||||
| GET | /api/v2/departments | List the departments on the company account. | read | — | Current | |
Read-only; reachable with a standard company key. Acts ondepartment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/departments/{department_id}/operators | Add an operator to a department. | write | — | Current | |
Changes who answers the department; reachable with a standard company key. Acts ondepartment_operator Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Call centersMethods for working with call centers and their operators.3 | ||||||
| GET | /api/v2/callcenters | List the call centers on the company account. | read | — | Current | |
Read-only; reachable with a standard company key. Acts oncall_center Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/callcenters/{call_center_id}/operators | Add an operator to a call center. | write | — | Current | |
Changes who staffs the call center; reachable with a standard company key. Acts oncall_center_operator Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/callcenters/{call_center_id}/status | Get the live status of a call center, like queue and operator state. | read | — | Current | |
Read-only; reachable with a standard company key. Acts oncall_center Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Event subscriptions & webhooksMethods for subscribing to events and registering delivery targets.3 | ||||||
| POST | /api/v2/call_event_subscriptions | Subscribe to call events for a target, delivered to a webhook or websocket. | write | — | Current | |
Sets up which call events an integration receives. Acts oncall_event_subscription Permission (capability)None required VersionAvailable since the API’s base version Webhook event call.eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/sms_event_subscriptions | Subscribe to SMS events for a target, delivered to a webhook or websocket. | write | — | Current | |
Message content in delivered events may require the message_content_export scope. Acts onsms_event_subscription Permission (capability)None required VersionAvailable since the API’s base version Webhook event sms.eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/webhooks | Register a webhook (an HTTPS endpoint) that event subscriptions can deliver to. | write | — | Current | |
Creates a delivery target; reachable with a standard company key. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Stats & analyticsMethods for requesting and retrieving usage and performance data.2 | ||||||
| POST | /api/v2/stats | Start an asynchronous stats job for usage and performance data. | write | — | Current | |
Creates a processing job; the result is fetched separately by request id. Acts onstats_request Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/stats/{request_id} | Get the result of a stats job once it has finished processing. | read | — | Current | |
Read-only; can return company-wide call and agent activity. Acts onstats_request Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Dialpad can notify an app when something happens, like a call starting or an SMS arriving. It delivers the event to a registered webhook or websocket through an event subscription, so an integration learns about activity in near real time without polling.
| Event | What it signals | Triggered by |
|---|---|---|
Call event | Fires as a call changes state, like ringing, connecting, or hanging up. Delivered through a call event subscription to a webhook or websocket, scoped to a target like a company, office, call center, or user. | /api/v2/users/{user_id}/calls/api/v2/calls/{call_id}/transfer/api/v2/calls/{call_id}/hangup |
SMS event | Fires when an SMS is sent or received for the company or a user, in near real time. Delivered through an SMS event subscription, and message content delivery may require the message_content_export scope. | /api/v2/sms/send |
Contact event | Fires when a contact is created, updated, or deleted. Delivered through a contact event subscription to a registered webhook or websocket. | /api/v2/contacts/api/v2/contacts/{contact_id}/api/v2/contacts/{contact_id} |
Dialpad limits how fast an app can call, with a company-wide ceiling measured per minute and tighter per-minute caps on specific actions like placing calls or creating contacts.
Dialpad meters requests by rate, not by a per-method point cost. The default ceiling is 1200 requests per minute (20 per second) per company across the API, and specific actions carry tighter per-minute caps shown on the rows, like 5 calls per minute per user target, 100 contacts created per minute, and SMS send at 100 per minute on the lower tier. Going over returns HTTP 429, and Dialpad notes the limits may change.
List endpoints return a page of results with a cursor token for the next page, passed back on the following request until no cursor remains. Call lists come back in reverse-chronological order by start time and include only calls that have already concluded.
The SMS API enforces a maximum request size of 1MB including attachments, and an oversized request returns HTTP 413. Other size and page limits are stated per endpoint in the reference.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request has malformed syntax or is missing required parameters. | Fix the request body or parameters before resubmitting; do not retry the same request unchanged. |
| 401 | Unauthorized | Authentication credentials are missing or invalid. | Send a valid API key or OAuth bearer token in the Authorization header, and refresh the token if it has expired. |
| 403 | Forbidden | The credential is valid but lacks permission for this action, for example a missing scope like calls:list or screen_pop. | Grant the required scope on the OAuth connection or use a key with access to the resource. |
| 404 | Not Found | The requested resource does not exist or is not visible to this credential. | Verify the object id and that it belongs to the authenticated company. |
| 409 | Conflict | The resource state prevents completion, such as a duplicate creation attempt. | Reconcile the existing resource and retry without recreating it. |
| 413 | Request Entity Too Large | The payload exceeds the size limit, for example an SMS request over 1MB including attachments. | Reduce the payload or attachment size below the limit and resend. |
| 429 | Too Many Requests | A rate limit was exceeded, like the 1200 per minute company ceiling or a tighter per-action cap. | Back off and retry more slowly, smoothing the request rate beneath the limit. |
| 503 | Service Unavailable | An internal error or server overload. The response may include an error UUID for support. | Retry with backoff, and share the error UUID with Dialpad support if it persists. |
Dialpad serves one numbered version of its API and ships dated updates against it through its developer changelog, adding methods rather than minting a new version string for additive change.
Dialpad serves a single numbered API version, v2, in the request path, with no per-request version header. New methods and behavior changes are shipped against v2 in place and announced in the developer changelog rather than by minting a new version string.
A dated batch of additive API updates announced in the developer changelog, covering newly launched methods and improvements on v2.
A dated batch of additive API updates announced in the developer changelog.
A dated batch of additive API updates announced in the developer changelog.
Track the developer changelog for new methods and behavior changes on v2.
Dialpad API changelog ↗Bollard AI sits between a team's AI agents and Dialpad. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.