Skip to content
Browse documentation
On this page

Calls API

List calls, fetch a call with its recording, transcript and AI summary, and start click-to-call calls through the Dialstitch API.

Read your organization's call history and start calls from another system. Reading needs the calls:read scope. Click-to-call needs calls:write.

List calls

GET /calls

Returns calls newest first, with pagination.

  • limit, cursor: pagination.
  • direction: inbound or outbound.
  • user_id: only calls handled by this user.
  • created_after, created_before: ISO 8601 dates.
curl "https://dialstitch.com/api/v1/calls?direction=inbound&limit=2" \
  -H "Authorization: Bearer dpk_..."

The call object

{
  "id": "3f1c2a9e-8d4b-4c1e-9a7f-2b6d5e8c1a40",
  "direction": "inbound",
  "state": "ended",
  "from": "+14155550123",
  "to": "+16045550188",
  "remote_number": "+14155550123",
  "phone_number_id": "b8e2f7c4-1d3a-4e5b-8c9d-0a1b2c3d4e5f",
  "user_id": 42,
  "contact_id": "7a9b0c1d-2e3f-4a5b-6c7d-8e9f0a1b2c3d",
  "route": null,
  "started_at": "2026-11-02T15:04:05.000Z",
  "answered_at": "2026-11-02T15:04:12.000Z",
  "ended_at": "2026-11-02T15:09:40.000Z",
  "duration_seconds": 328,
  "end_reason": null,
  "has_recording": true,
  "transcription_status": "completed",
  "created_at": "2026-11-02T15:04:05.000Z"
}
  • user_id is the person who handled the call, or null.
  • contact_id links to the contact whose number matched, or null.
  • has_recording tells you whether the recording endpoint will return audio.
  • transcription_status is null until transcription starts.

Get a call

GET /calls/{id}

Returns { "data": <call> }, or 404 if the call isn't in your organization.

Download the recording

GET /calls/{id}/recording

Returns the audio as audio/mpeg. It supports Range requests, so you can stream or resume a download. If the call has no recording, you get 404.

curl -o call.mp3 https://dialstitch.com/api/v1/calls/3f1c2a9e-8d4b-4c1e-9a7f-2b6d5e8c1a40/recording \
  -H "Authorization: Bearer dpk_..."

Get the transcript

GET /calls/{id}/transcript
{
  "data": {
    "call_id": "3f1c2a9e-8d4b-4c1e-9a7f-2b6d5e8c1a40",
    "status": "completed",
    "text": "Thanks for calling. How can I help?...",
    "segments": [ ... ]
  }
}

text is the full transcript. segments holds the timed pieces. Both are empty until the transcript is ready. Subscribe to the call.recapped webhook to know when it is.

Get the AI summary

GET /calls/{id}/summary
{
  "data": {
    "call_id": "3f1c2a9e-8d4b-4c1e-9a7f-2b6d5e8c1a40",
    "status": "completed",
    "summary": "Customer asked to move their delivery to Friday...",
    "action_items": [ ... ]
  }
}

Click-to-call

POST /calls

Asks a user's softphone to call a number. Dialstitch doesn't place the call by itself: the user gets a notification that opens their dialer on the number, and they press call.

  • user_id (required): the user whose softphone places the call.
  • to (required): the number to call. One number per request.
  • from_number_id: the number to call from. Defaults to the user's own number, then a team number they can use.
curl -X POST https://dialstitch.com/api/v1/calls \
  -H "Authorization: Bearer dpk_..." \
  -H "Content-Type: application/json" \
  -d '{"user_id": 42, "to": "+14155550123"}'

Response, 202 Accepted:

{
  "data": {
    "status": "requested",
    "user_id": 42,
    "to": "+14155550123",
    "from_number_id": "b8e2f7c4-1d3a-4e5b-8c9d-0a1b2c3d4e5f",
    "dial_url": "https://dialstitch.com/app/phone?to=%2B14155550123"
  }
}

API overview

Keys, scopes, rate limits, pagination and errors.

Contacts API

Create, update, look up and delete contacts.

Webhooks

Get a signed POST when calls, texts and contacts change.