For Developers
DashboardLog InGet an API key
Calling

Phone numbers

List the phone numbers on your account and check whether each one can place calls.

Phone numbers are read-only through this API. Use them to find the phoneNumberId for placing a call, and to check a number's readiness first.

EndpointRequest
List phone numbersGET/v1/phone-numbers
Get a phone numberGET/v1/phone-numbers/{id}

The phone number object

Fields are in camelCase.

Identity

idstringrequired
The phone number's UUID. Send this as phoneNumberId when placing a call.
numberstringrequired
The phone number, in E.164 format.
countryCodestring | null
The number's two-letter country code.
localitystring | null
The number's city or locality.
regionstring | null
The number's state or region.
postalCodestring | null
The number's postal code.
monthlyCoststring | null
The number's monthly cost.
createdAtstringrequired
When the record was created, as an ISO 8601 timestamp.
updatedAtstringrequired
When the record last changed, as an ISO 8601 timestamp.
provisionedAtstring | null
When the number was provisioned.

Status

statusstringrequired
active, inactive, provisioning or failed.
syncStatusstringrequired
Sync progress: pending, provisioning, synced or error.
syncStatestringrequired
The current sync state, using the same values as syncStatus.
lastSyncedAtstring | null
When the number last synced.
regulatoryStatusstring | null
Regulatory approval state: pending, approved, blocked or unknown. pending and blocked make POST /v1/calls return 422. See Regulatory status.
addressValidatedAtstring | null
When the address on the number was validated.

Agent link and readiness

assignedAgentIdstring | null
UUID of the linked agent. A call's agentId must match this value.
linkedAssistantIdstring | null
The same agent's UUID, returned with its name and status.
linkedAssistantNamestring | null
The linked agent's display name.
linkedAssistantStatusstring | null
The linked agent's status.
isCallableForCampaignsbooleanrequired
true when the number is ready to place outbound calls with its linked agent.
campaignExecutionAvailabilitystringrequired
Why the number is or isn't callable. See the values below.
campaignExecutionMessagestringrequired
A readable explanation of campaignExecutionAvailability.
campaignExecutionActionstring | null
What to do to make the number callable. null when it already is.

Voice and messaging capabilities

voiceEnabledbooleanrequired
Whether the number supports voice.
smsEnabledbooleanrequired
Whether the number supports SMS.
mmsEnabledbooleanrequired
Whether the number supports MMS.
voiceInboundEnabledbooleanrequired
Whether the number can receive voice calls.
voiceInboundRestrictionCodestring | null
Why inbound voice is restricted.
voiceInboundOriginScopestring
Where inbound calls can come from: none, domestic_only, regional, international or unknown.
voiceOutboundEnabledbooleanrequired
Whether the number can place voice calls.
voiceOutboundRestrictionCodestring | null
Why outbound voice is restricted, such as VOICE_NOT_SUPPORTED, PHONE_NUMBER_NOT_PROVISIONED or AU_TOLL_FREE_DO_NOT_ORIGINATE.
voiceOutboundDestinationScopestring
Where the number can call: none, domestic_only, international_restricted, international, provider_managed or unknown.
voiceCapabilitiesEvaluatedAtstring | null
When voice capabilities were last checked.
voiceGeographyEvaluatedAtstring | null
When geographic dialing permissions were last checked.

Availability values

campaignExecutionAvailabilityMeaning
linked_callableThe number is ready to place calls.
assistant_callableThe agent is ready to place calls.
inventory_unlinkedNot assigned to an agent.
phone_inactiveThe number isn't active.
phone_outbound_unsupportedThe number can't make outbound voice calls.
phone_runtime_missingThe number's setup is incomplete.
phone_execution_account_missingThe number's setup is incomplete.
phone_execution_auth_missingThe number's setup is incomplete.
phone_execution_verification_requiredThe number must be verified before it can place calls.
phone_configuration_unsupportedThe number's setup can't place outbound calls.
phone_compliance_pendingRegulatory approval is pending.
phone_compliance_blockedRegulatory approval failed.
phone_sync_pendingThe number is still being set up.
phone_sync_failedThe number could not be set up.
linked_assistant_missingThe linked agent no longer exists.
linked_assistant_inactiveThe linked agent isn't active.
linked_assistant_runtime_missingThe linked agent isn't ready to place calls.
linked_assistant_binding_mismatchThe number and its linked agent are out of step.
assistant_inactiveThe agent isn't active.
assistant_runtime_missingThe agent isn't ready to place calls.
assistant_missing_linked_phoneThe agent has no phone number.
assistant_missing_callable_phoneNone of the agent's phone numbers can place calls.
unknownThe number isn't ready, for another reason.

campaignExecutionMessage and campaignExecutionAction explain each value in plain language, so show those to a person.

Regulatory status

Some countries require approval before a number can place calls.

regulatoryStatusEffect on POST /v1/calls
approved, unknown or nullDoesn't block the call.
pendingReturns 422 PHONE_NUMBER_COMPLIANCE_PENDING. Wait for approval, or use a different number.
blockedReturns 422 PHONE_NUMBER_COMPLIANCE_BLOCKED. Resolve the issue, or use a different number.

Nothing is queued in either 422 case. The same check runs again while a call waits, and a call stopped that way fails with call_not_ready.

List phone numbers

GET/v1/phone-numbersread key

Returns your phone numbers with a status of active or provisioning, newest first. Numbers awaiting regulatory approval are included. To read an inactive or failed number, use its ID with GET /v1/phone-numbers/{id}.

Query parameters

limitintegerdefault 50
Maximum results, from 1 to 100.
offsetintegerdefault 0
Number of results to skip, up to 1,000,000.
Request
curl "https://backend.synthesys.app/api/v1/phone-numbers?limit=10" \
  -H "SYNTH_API_KEY: YOUR_API_KEY"
Response
{
  "success": true,
  "data": [
    {
      "id": "b2c4d6e8-1a3f-4c5d-8e7f-90a1b2c3d4e5",
      "number": "+12025550123",
      "countryCode": "US",
      "status": "active",
      "syncStatus": "synced",
      "syncState": "synced",
      "regulatoryStatus": "approved",
      "assignedAgentId": "6f1d2a34-8b7c-4e21-9a10-3c5d7e9f1b20",
      "linkedAssistantId": "6f1d2a34-8b7c-4e21-9a10-3c5d7e9f1b20",
      "linkedAssistantName": "Sales Agent",
      "linkedAssistantStatus": "active",
      "voiceEnabled": true,
      "smsEnabled": true,
      "mmsEnabled": false,
      "voiceInboundEnabled": true,
      "voiceOutboundEnabled": true,
      "isCallableForCampaigns": true,
      "campaignExecutionAvailability": "linked_callable",
      "campaignExecutionMessage": "This phone number is ready for outbound calls.",
      "campaignExecutionAction": null,
      "createdAt": "2026-09-12T10:15:00.000Z",
      "updatedAt": "2026-10-30T08:22:41.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}

Get a phone number

GET/v1/phone-numbers/{id}read key

Returns one phone number.

Path parameters

idstringrequired
The phone number's UUID.

Errors

StatusWhen
400The ID isn't a valid UUID.
404No phone number with this ID exists on your account. code is NOT_FOUND.
Request
curl https://backend.synthesys.app/api/v1/phone-numbers/b2c4d6e8-1a3f-4c5d-8e7f-90a1b2c3d4e5 \
  -H "SYNTH_API_KEY: YOUR_API_KEY"
Response
{
  "success": true,
  "data": {
    "id": "b2c4d6e8-1a3f-4c5d-8e7f-90a1b2c3d4e5",
    "number": "+12025550123",
    "status": "active",
    "syncStatus": "synced",
    "syncState": "synced",
    "assignedAgentId": null,
    "voiceEnabled": true,
    "smsEnabled": true,
    "mmsEnabled": false,
    "voiceInboundEnabled": true,
    "voiceOutboundEnabled": true,
    "isCallableForCampaigns": false,
    "campaignExecutionAvailability": "inventory_unlinked",
    "campaignExecutionMessage": "This phone number is not assigned to an agent.",
    "campaignExecutionAction": "Assign this phone number to an agent.",
    "createdAt": "2026-09-12T10:15:00.000Z",
    "updatedAt": "2026-10-30T08:22:41.000Z"
  }
}
Not found (404)
{
  "success": false,
  "error": "Phone number not found",
  "code": "NOT_FOUND",
  "requestId": "e3a1c5d7-2b4f-4a6c-9d8e-1f2a3b4c5d6e",
  "timestamp": "2026-10-31T14:02:11.482Z"
}