Developer API

Get started

Create a token in Settings → Developer API. Read access is enabled by default; enable list imports if needed. Tokens belong to your user and the organization in which you created them. Calls are limited to calls you made; lists are shared within that organization.

export DORADO_API_TOKEN='your-token'
curl 'https://app.withdorado.com/api/v1/calls?limit=20' \
  -H "Authorization: Bearer $DORADO_API_TOKEN"

Tokens are shown once, expire after the selected duration, and can be revoked in settings. Keep them on your server or in your secret store. Requests require a token; browser login cookies do not authorize this API.

Endpoints

All GET endpoints require data:read. Creating a list requires lists:write. Calling, modifying calls, and deleting or editing lists are outside this API.

Find calls and export results

Filter calls with query (prospect or company), contentQuery (transcript or summary text), createdAfter, createdBefore, listId, dispositionDefinitionId, status, outcome, hasTranscript, or minDurationSeconds. Dates are ISO 8601 timestamps with a timezone. Use each parameter once.

curl --get 'https://app.withdorado.com/api/v1/calls' \
  -H "Authorization: Bearer $DORADO_API_TOKEN" \
  --data-urlencode 'createdAfter=2026-10-01T00:00:00Z' \
  --data-urlencode 'hasTranscript=true' \
  --data-urlencode 'limit=50'

Call, list, and contact collections return { data: [...], nextCursor: string | null }. Send nextCursor as the next request’s cursor, URL-encoded, until it is null. Keep filters and sort unchanged. Calls default to 20 per page (maximum 50), sorted newest first; use sort=oldest for oldest first. Lists and contacts default to 50 (maximum 100); lists are ordered newest ID first and contacts follow list order.

Single calls and lists return { data: {...} }. Calls include their disposition and available summary. A null summary means no summary is currently available. Exports use these same paginated JSON endpoints; pages reflect current data, not a frozen snapshot.

For transcript text, GET /api/v1/calls/{callId}/transcript. Its response contains status, segments, nextCursor, and transcript identity/revision. Segments include speaker, start/end milliseconds, and complete text. Pending, processing, disabled, failed, or unavailable transcripts return an empty page; ready transcripts return up to 100 segments. A changed transcript invalidates its cursor: restart that transcript’s pagination.

Import a list

Send a name and 1–500 contacts. Imports finish in the request and return the list’s ID and contact count. Each contact needs a phone number or email. Use phoneNumber/email for one value or phones/emails arrays for multiple values. The OpenAPI reference describes all fields.

curl 'https://app.withdorado.com/api/v1/lists' \
  -H "Authorization: Bearer $DORADO_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: conference-leads-2026-10' \
  --data '{
    "name": "Conference leads",
    "contacts": [
      { "name": "Alex Chen", "companyName": "Example", "email": "alex@example.com" }
    ]
  }'

The required Idempotency-Key is scoped to your user and organization. Retrying with the same key returns the original list, even across tokens; use a new key for changed input. Contact validation is atomic: invalid data rejects the import. Phone numbers must be supported US numbers, preferably in E.164 form. No calls start when you import a list.

Limits and errors

Each token allows 120 requests per minute. On 429, wait the number of seconds in Retry-After. Request bodies are limited to 2 MiB. Retry transient 500 responses with backoff; reuse the import’s idempotency key.

{
  "error": { "code": "unauthenticated", "message": "A valid API token is required." },
  "requestId": "..."
}

400 means invalid input, 401 missing/invalid/expired credentials, 403 insufficient permission, 404 unavailable resource or endpoint, 413 oversized body, and 415 incorrect content type. Include the X-Request-Id response header when requesting support.

The /api/v1 contract supports additive fields. Clients should ignore unknown response fields. Breaking changes require a new API version.