API overview

The Dialstitch REST API lets your own systems read calls, transcripts and texts, manage contacts, send texts and start click-to-call calls. Everything a key touches belongs to one organization: the one that created the key.

Base URL

https://dialstitch.com/api/v1

Every endpoint below is relative to this URL. Requests and responses are JSON, except the recording download, which is audio.

OpenAPI description

The full OpenAPI 3.1 document is public at /api/v1/openapi.json. Import it into Postman, Insomnia or an SDK generator. In the app, Admin > API & Webhooks > API Docs shows the same reference.

Create an API key

1. 1

   Open API keys

   Go to Admin, then API & Webhooks. The API Keys tab opens.

2. 2

   Name the key

   Under New key, enter a Name, such as HubSpot sync, so you know later what uses it.

3. 3

   Pick an expiry

   Choose Never, In 30 days, In 90 days or In a year under Expires.

4. 4

   Choose scopes

   Tick only the scopes the integration needs. A key can't do anything outside its scopes.

5. 5

   Copy the key

   Select Create key and copy the key that starts with dpk_. It's shown once. If you lose it, revoke it and create another.

Authenticate

Send the key as a Bearer token on every request:

curl https://dialstitch.com/api/v1/calls?limit=10 \
  -H "Authorization: Bearer dpk_..." 

A missing, invalid, revoked or expired key gets 401 with the code unauthorized. A valid key without the scope an endpoint needs gets 403 with the code insufficient_scope.

Scopes

• calls:read: read calls, recordings, transcripts and summaries.
• calls:write: start click-to-call calls.
• contacts:read: read contacts and look them up by phone number.
• contacts:write: create, update and delete contacts.
• messages:read: read text messages.
• messages:write: send text messages.
• users:read: list users and phone numbers.
• webhooks:manage: list, add and remove event webhooks.
• analytics:read: read the analytics summary.

Rate limits

Each key can make 120 requests a minute. Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy headers. Over the limit, you get 429 with the code rate_limited and a Retry-After header in seconds.

Pagination

List endpoints return the newest items first, in pages:

• limit: how many items to return, 1 to 100. The default is 25.
• cursor: the next_cursor value from the previous page.

{
  "data": [ ... ],
  "next_cursor": "eyJ0IjoxNzMwNTU2MDAwMDAwLCJpZCI6Ii4uLiJ9"
}

When next_cursor is null, you've reached the last page.

Dates and phone numbers

• Dates are ISO 8601 in UTC, such as 2026-11-02T15:04:05.000Z. Filters like created_after accept any ISO 8601 date.
• Phone numbers come back in E.164 format, such as +14155550123. You can send a 10-digit US or Canadian number or a full + number.

Errors

Errors share one shape:

{
  "error": {
    "code": "not_found",
    "message": "Call not found"
  }
}

• 400: invalid_request, invalid_json, invalid_cursor or invalid_phone_number.
• 401: unauthorized. The key is missing, invalid, revoked or expired.
• 403: insufficient_scope, or a call or text that isn't allowed (for example a number on your do-not-call list).
• 404: not_found. The item doesn't exist or belongs to another organization.
• 409: a conflict, such as no_number when a user has no number to call from.
• 413: payload_too_large. Request bodies are limited to 64 KB.
• 429: rate_limited.
• 500: internal_error.

Manage keys

The API Keys tab lists every key with its scopes and expiry. Revoke a key there and it stops working right away. Expired keys stop working on their expiry date.

API reference