Quickstart

Pick a voice, model, and transcriber#

An assistant is built from three catalogue picks: the voice it speaks with, the language model that powers its reasoning, and the transcriber that turns the caller's speech into text. List all three catalogues:

curl "https://core-api.heysadie.ai/voices?limit=50" \
  -H "Authorization: ApiKey YOUR_API_KEY"

curl "https://core-api.heysadie.ai/models?limit=50" \
  -H "Authorization: ApiKey YOUR_API_KEY"

curl "https://core-api.heysadie.ai/transcribers?limit=50" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Each response uses the same envelope — the list sits in data. The voices response, for example:

{
  "success": true,
  "data": {
    "voices": [
      {
        "id": "0195f1e2-...",
        "name": "Example Voice",
        "provider": "elevenlabs",
        "tags": ["Female", "American", "Calm"],
        "language": ["en"]
      }
    ],
    "total": 42
  }
}

Pick one entry from each catalogue and keep its id — the voice tags badges (gender, accent, personality) help you choose. You'll use the three IDs as voiceId, modelId, and transcriberId in the next step.

Create your assistant#

Now create the assistant itself. The create endpoint expects the full set of core fields up front, so the body below is the smallest assistant that works — swap in your three IDs from step 1:

curl -X POST https://core-api.heysadie.ai/assistants \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Front Desk",
    "voiceId": "VOICE_ID",
    "modelId": "MODEL_ID",
    "transcriberId": "TRANSCRIBER_ID",
    "firstMessage": "Hi! You have reached Riverside Dental. How can I help you today?",
    "endOfCallMessage": "Thanks for calling — goodbye!",
    "developerPrompt": "You answer the phone for Riverside Dental. Be warm and brief. The clinic is open 9am to 5pm, Monday to Friday.",
    "parameters": {},
    "recordingEnabled": true,
    "failoverNumber": "+15551234567",
    "failoverMode": false,
    "toolIds": [],
    "timezone": "America/New_York",
    "address": "123 River Street, Springfield",
    "phoneNumberPassThrough": true
  }'

Two fields to notice: firstMessage is the exact sentence the assistant answers the phone with — you'll hear it in step 6 — and developerPrompt is your section of its instructions, so it knows the opening hours you gave it. Failover is off (failoverMode: false); the failoverNumber is only used if you turn it on later.

The response returns the full assistant object. Copy data.id — that's your ASSISTANT_ID for the rest of this quickstart:

{
  "success": true,
  "data": {
    "id": "0195f1e2-...",
    "name": "Front Desk",
    "phoneNumberId": null,
    "...": "..."
  }
}

Notice phoneNumberId is null — your assistant exists, but callers can't reach it yet. Let's fix that.

Find an available phone number#

Search the provider inventory for numbers you can purchase:

curl "https://core-api.heysadie.ai/phone-numbers/available?country=US" \
  -H "Authorization: ApiKey YOUR_API_KEY"

You'll see a list of numbers with their location:

{
  "success": true,
  "data": {
    "phoneNumbers": [
      {
        "phoneNumber": "+12125550123",
        "locality": "New York",
        "region": "NY",
        "postalCode": "10001",
        "isoCountry": "US"
      }
    ],
    "total": 30
  }
}

Take the first phoneNumber in the list — that's the number you'll buy.

Buy the number#

Purchase the number into your account, exactly as it appeared in the search:

curl -X POST https://core-api.heysadie.ai/phone-numbers \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+12125550123",
    "name": "Front desk line"
  }'

The response confirms the purchase. Copy data.id — that's your PHONE_NUMBER_ID:

{
  "success": true,
  "data": {
    "id": "0195f1e2-...",
    "phoneNumber": "+12125550123",
    "country": "US",
    "assistantName": null,
    "...": "..."
  }
}

Attach the number to your assistant#

Link the two with a single PATCH — set phoneNumberId on the assistant:

curl -X PATCH https://core-api.heysadie.ai/assistants/ASSISTANT_ID \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumberId": "PHONE_NUMBER_ID" }'

The response echoes the assistant with phoneNumberId now set. From this moment, calls to your new number are answered by your assistant.

Call your assistant#

Pick up your phone and dial the number you bought.

You'll hear your assistant answer in the voice you chose: "Hi! You have reached Riverside Dental. How can I help you today?" — the exact firstMessage you wrote in step 2.

Talk to it. Ask "What are your opening hours?" — it knows the answer, because you put the hours in developerPrompt. When you're done, say goodbye and hang up.

That's it — you've built a voice assistant and spoken to it on a real phone line.

See the call record#

Every call your assistant handles is recorded as a call object. Fetch the one you just made:

curl "https://core-api.heysadie.ai/calls?assistantId=ASSISTANT_ID&limit=1" \
  -H "Authorization: ApiKey YOUR_API_KEY"

You'll see your call, with the conversation you just had written down for you:

{
  "success": true,
  "data": {
    "calls": [
      {
        "id": "0195f1e2-...",
        "status": "completed",
        "customerNumber": "+1...",
        "startedAt": "2026-08-14T10:02:11.000Z",
        "endedAt": "2026-08-14T10:03:05.000Z",
        "callDuration": 54,
        "transcript": "AI: Hi! You have reached Riverside Dental. ...",
        "summary": "Caller asked about opening hours. ...",
        "assistantName": "Front Desk",
        "...": "..."
      }
    ],
    "total": 1
  }
}

The transcript and summary are produced after the call ends — if they're still null, wait a moment and run the request again. See Calls for filters, statuses, and the full call payload.