Endpoint reference

Create an outbound Voice AI call.

Use this endpoint when a tenant application needs StateSet Voice to place a customer-facing call with a specific phone route, agent, and greeting.

Request API key Start building Endpoint guides Authentication Production readiness

Runtime APIBearer tenant keys

Admin APIx-admin-key

TelephonyTwilio signatures

SpecsOpenAPI 3.1

Endpoint contract

Property	Value
Method	`POST`
Path	`/api/v1/make-call`
Authentication	`Authorization: Bearer ${STATESET_VOICE_API_KEY}`
Content type	`application/json`
Primary use	Create an outbound call for a tenant-scoped Voice AI Agent.

Request body

Field	Required	Description
`to`	Yes	Customer destination phone number. Use E.164 format for production traffic.
`from`	No	Caller ID or Twilio number. Defaults to the tenant phone route when omitted.
`agent_key`	No	Stable agent key that resolves to the published production agent version.
`agent_version_id`	No	Explicit agent version for controlled rollout, QA, or staged testing.
`greeting`	No	Opening message for the outbound call. Keep this approved by the business owner.
`org_id`	No	Organization context when one tenant serves multiple business units.

Example request

curl -sS -X POST "https://voice.stateset.app/api/v1/make-call" \
  -H "Authorization: Bearer ${STATESET_VOICE_API_KEY}" \
  -H "content-type: application/json" \
  -d '{
    "to": "+15555555678",
    "from": "+15555551234",
    "agent_key": "support_primary",
    "greeting": "Hi, this is Acme calling about your appointment."
  }'

Example response

{
  "ok": true,
  "call_sid": "CA1234567890abcdef1234567890abcdef",
  "status": "queued",
  "to": "+15555555678",
  "from": "+15555551234"
}

Error and retry behavior

Status	Action	Notes
`400`	Do not retry automatically.	Fix phone number, route, payload, agent key, or tenant configuration.
`401`/`403`	Rotate or scope credentials.	Tenant runtime keys must not be confused with admin keys.
`429`	Back off with jitter.	Preserve a business idempotency key so retries cannot create duplicate customer calls.
`500`/`503`	Retry only when call creation is not already accepted.	Reconcile against call logs before issuing a second call.

Production checklist

Persist call_sid with the business workflow that requested the call.
Reconcile final state from GET /api/v1/call-logs and webhook events.
Gate outbound traffic by tenant, phone route, allowed hours, DNC policy, and launch approval.
Alert on failed call creation, no-answer spikes, provider failures, and duplicate-call prevention.