For Developers

Make Nab calls from your product.

Use a user access token to start outbound Nab calls and read back call status, summaries, transcripts, recordings, and structured results.

Get Nab

Base URL

Production API

All examples use the production service. Send JSON requests and pass tokens in the standard bearer authorization header.

https://app.heynab.com
Authorization: Bearer nab_your_token_here
Content-Type: application/json

Quick curl examples

Copy, paste, run.

Set your token

# Copy this from Nab mobile app Settings
export NAB_ACCESS_TOKEN="nab_your_access_token"

Start a call

export NAB_ACCESS_TOKEN="nab_your_access_token"

curl -sS -X POST https://app.heynab.com/call \
  -H "Authorization: Bearer $NAB_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+15551234567",
    "contactName": "City Clinic",
    "task": "Ask for the earliest available appointment next week.",
    "idempotencyKey": "appointment-2026-07-13",
    "estimatedDurationSec": 600
  }'

List recent calls

export NAB_ACCESS_TOKEN="nab_your_access_token"

curl -sS "https://app.heynab.com/calls?limit=10" \
  -H "Authorization: Bearer $NAB_ACCESS_TOKEN"

Get one result

export NAB_ACCESS_TOKEN="nab_your_access_token"
export NAB_CALL_ID="call-..."

curl -sS "https://app.heynab.com/call/$NAB_CALL_ID" \
  -H "Authorization: Bearer $NAB_ACCESS_TOKEN"

Step 1

Get an access token in Settings

Open the Nab mobile app, go to Settings, and copy your access token. Use that token from your backend to start calls and fetch call results. If you rotate the token in Settings, replace it anywhere your backend stores it.

# In Nab mobile app:
# Settings -> Access token -> Create -> Copy

export NAB_ACCESS_TOKEN="nab_your_access_token"

Find token GET /api/account/access-token

Account-management endpoint used by the signed-in mobile app to show the current token state.

Rotate token POST /api/account/access-token

Account-management endpoint. A fresh token replaces the previous one immediately.

Revoke token DELETE /api/account/access-token

Account-management endpoint used by Settings to revoke developer access.

Token boundary

Use the right bearer token.

The nab_... access token is the credential for /call, /calls, and /call/:callId. The account-management endpoints above are intended for the signed-in Nab app. Do not store a mobile account session token in your integration.

# Developer API
Authorization: Bearer nab_your_access_token

# Create, replace, or delete the token in Nab mobile Settings

Step 2

Start a call

Use the access token from your backend. Phone numbers must be E.164. The task should include the goal, context, and any hard boundaries for Nab.

curl -X POST https://app.heynab.com/call \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+15551234567",
    "contactName": "City Clinic",
    "task": "Call to ask for the earliest available appointment next week.",
    "idempotencyKey": "appointment-2026-07-13",
    "estimatedDurationSec": 600,
    "realtimeVoice": "marin",
    "attachments": [
      {
        "filename": "referral.txt",
        "contentType": "text/plain",
        "text": "Referral reference A-123. Ask whether it is sufficient."
      }
    ]
  }'

# 201 Created
{
  "call_id": "call-..."
}

Required phoneNumber, task

phoneNumber must use E.164 format. number and phone are accepted aliases.

Idempotency and duration idempotencyKey, estimatedDurationSec

Snake-case aliases are accepted. Calls are currently limited to 600 seconds.

Voice realtimeVoice

Optional alias: voice. Supported: alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, and cedar.

Attachments attachments[]

Up to 3 items containing extracted readable text, with a combined maximum of 24,000 characters.

Step 3

Get call results

Poll the call detail endpoint until the call reaches a final status. The detail response includes the summary, transcript, recording URL, and structured result when Nab has submitted one. Before those artifacts are ready, strings may be empty and recording_url may be null.

curl https://app.heynab.com/call/call-... \
  -H "Authorization: Bearer <access-token>"

# Response
{
  "call_id": "call-...",
  "date": "2026-07-13T...",
  "status": "completed",
  "number": "+15551234567",
  "task": "Call to ask for the earliest available appointment next week.",
  "summary": "The clinic has an opening on Tuesday at 10:30.",
  "transcript": "assistant: ...",
  "recording_url": "https://app.heynab.com/channels/voice/recording/...",
  "result": {
    "appointmentAvailable": true,
    "nextStep": "Confirm Tuesday at 10:30"
  }
}

Create POST /call

Starts a Nab call and returns a `call_id` for result lookup.

List GET /calls?limit=50

Returns recent calls for the token owner with status, number, task, and date. Limit range: 1-100.

Detail GET /call/:callId

Returns summary, transcript, recording URL, and structured result.

Polling

Know when a call is finished.

Continue polling while a call is starting or active. Treat these values as terminal: completed, failed, busy, no_answer, hung_up, canceled, cancelled, bridge_failed, transferred, and streaming.stopped.

while status is not terminal:
  GET /call/call-...
  wait before polling again

400 Bad Request invalid input

Invalid E.164 number, missing task, unsupported voice, unreadable attachments, or a duration above the allowed maximum.

401 Unauthorized caller-unauthorized

The bearer token is missing, invalid, revoked, or replaced.

402 Payment Required caller-no-minutes

The account has no included or available extra minutes.

409 Conflict caller-active-call-exists

Another Nab call is active for this account. The response includes active_call.

503 Unavailable voice calls disabled

Outbound calling is temporarily unavailable.

Security

Keep tokens server-side.

Treat access tokens like API keys. Store them in your backend or secret manager, never in a public client. Revoke and recreate the token if it may have been exposed.

# Store only on your backend
NAB_ACCESS_TOKEN="nab_..."

# If exposed: replace or delete it in Nab mobile Settings