Quickstart

You need three things in your dashboard before you start: an active agent, a phone number assigned to that agent, and wallet funds. Agents and phone numbers are read-only through the API, so set them up in the dashboard first.

1. Create an API key

   Open Settings > API Keys, select Create New API Key, give it a name, and copy the key. Only workspace admins can create keys.

   Keys from the dashboard can read and write, which covers every step on this page. See Authentication for the full permission model.

2. List your agents

   Find the agent that will make the call and copy its id.

   Request

   cURLJavaScriptPython

   curl "https://backend.synthesys.app/api/v1/agents?limit=10" \
     -H "SYNTH_API_KEY: YOUR_API_KEY"

   The response below is trimmed to the fields you need here.

   JSON

   {
     "success": true,
     "data": [
       {
         "id": "8f14e45f-ceea-4e7a-9f3b-1a2b3c4d5e6f",
         "displayName": "Sales follow-up",
         "personaName": "Jane",
         "status": "active",
         "type": "outbound"
       }
     ],
     "pagination": { "total": 1, "limit": 10, "offset": 0 }
   }

   The agent's status must be active.

3. List your phone numbers

   Find the number assigned to that agent. Its assignedAgentId must match the agent's id, and copy the phone number's id, not the number itself.

   Request

   cURLJavaScriptPython

   curl "https://backend.synthesys.app/api/v1/phone-numbers" \
     -H "SYNTH_API_KEY: YOUR_API_KEY"

   This response is trimmed too.

   JSON

   {
     "success": true,
     "data": [
       {
         "id": "3c9d2b1a-7e6f-4a5b-8c9d-0e1f2a3b4c5d",
         "number": "+15555550100",
         "status": "active",
         "assignedAgentId": "8f14e45f-ceea-4e7a-9f3b-1a2b3c4d5e6f",
         "voiceOutboundEnabled": true
       }
     ],
     "pagination": { "total": 1, "limit": 50, "offset": 0 }
   }

4. Place a call

   Send the agent's ID, the phone number's ID, and the number to dial. Every call needs an Idempotency-Key header, which you choose. If a request times out, send it again with the same key, and you won't place a second call.

   Request

   cURLJavaScriptPython

   curl -X POST "https://backend.synthesys.app/api/v1/calls" \
     -H "SYNTH_API_KEY: YOUR_API_KEY" \
     -H "Idempotency-Key: quickstart-call-1" \
     -H "Content-Type: application/json" \
     -d '{
       "agentId": "8f14e45f-ceea-4e7a-9f3b-1a2b3c4d5e6f",
       "phoneNumberId": "3c9d2b1a-7e6f-4a5b-8c9d-0e1f2a3b4c5d",
       "phoneNumber": "+12025550123",
       "firstName": "Jane",
       "email": "jane@example.com"
     }'

   A successful request returns 201. Keep the callId.

   JSON

   {
     "success": true,
     "data": {
       "callId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
       "jobId": "b7e23ec2-9c1d-4f3a-8e5b-6d7c8b9a0f1e",
       "status": "queued"
     }
   }

   queued means the call was accepted, not that it connected. Calls only go out from 09:00 to 20:00 at the destination, so a call outside those hours stays queued until then.

5. Track the call

   Read the call with its callId. Check every 30 seconds or so until status is completed or failed.

   Request

   cURLJavaScriptPython

   curl "https://backend.synthesys.app/api/v1/calls/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" \
     -H "SYNTH_API_KEY: YOUR_API_KEY"

   This response is trimmed.

   JSON

   {
     "success": true,
     "data": {
       "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
       "status": "completed",
       "failure_code": null,
       "failure_message": null,
       "contact_phone": "+12025550123",
       "duration_seconds": 94,
       "cost_usd": 0.94,
       "completed_at": "2026-10-31T14:05:20.511Z"
     }
   }

   A failed call has a failure_code that says why, such as insufficient_balance. See Failure codes.

6. Get the transcript

   The transcript is on the call's log. List the agent's logs, and find the one whose directCallId matches your callId.

   Request

   cURLJavaScriptPython

   curl "https://backend.synthesys.app/api/v1/call-logs?agent_id=8f14e45f-ceea-4e7a-9f3b-1a2b3c4d5e6f&limit=100" \
     -H "SYNTH_API_KEY: YOUR_API_KEY" \
     | jq '.data[] | select(.directCallId == "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d") | .call_id'

   Then fetch the full record with that call_id.

   Request

   cURLJavaScriptPython

   curl "https://backend.synthesys.app/api/v1/call-logs/d4e5f6a7-b8c9-4d0e-a1f2-3b4c5d6e7f80" \
     -H "SYNTH_API_KEY: YOUR_API_KEY"

   This response is trimmed as well.

   JSON

   {
     "success": true,
     "data": {
       "callLog": {
         "call_id": "d4e5f6a7-b8c9-4d0e-a1f2-3b4c5d6e7f80",
         "directCallId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
         "contactPhoneNumber": "+12025550123",
         "agent_id": "8f14e45f-ceea-4e7a-9f3b-1a2b3c4d5e6f",
         "duration": 94,
         "status": "ended",
         "ended_reason": "customer-ended-call",
         "summary": "Jane asked for a follow-up next week.",
         "hasTranscript": true
       },
       "transcriptText": [
         { "role": "assistant", "message": "Hi Jane, thanks for taking my call." },
         { "role": "user", "message": "Hi, how can I help?" }
       ],
       "messages": []
     }
   }

   To get the audio, use Recordings.

Next steps