Purchase

StateSet Voice API operation.

POST /api/v1/customer/numbers

cURL

curl --request POST \
  --url 'https://api.voice.stateset.com/api/v1/customer/numbers' \
  --header "Authorization: Bearer $STATESET_VOICE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "phone_number": "[phone]"
}'

201

{
  "ok": true,
  "number": {
    "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "agent_key": "string",
    "agent_name": "string",
    "agent_version_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_at": "2026-08-31T14:22:05Z",
    "direction": "inbound",
    "greeting": "string",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "phone_number": "[phone]",
    "resolved_agent_version_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "resolved_version_number": 1001,
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "updated_at": "2026-08-31T14:22:05Z"
  }
}

StateSet Voice API operation.

Request body

PurchaseBody

phone_number · string · required

E.164 phone number to purchase, as returned by GET /api/v1/customer/numbers/search

Response

object

ok · boolean · required

number · PhoneNumberRoute · required

Show PhoneNumberRoute

agent_id · string (uuid) · required

agent_key · string · required

agent_name · string · required

agent_version_id · string,null (uuid)

created_at · string (date-time) · required

direction · PhoneNumberRouteDirection · required

greeting · string,null

id · string (uuid) · required

phone_number · string · required

resolved_agent_version_id · string,null (uuid)

resolved_version_number · integer,null (int32)

tenant_id · string · required

updated_at · string (date-time) · required

Status codes

Code	Meaning
201	Phone number purchased and routed to the tenant
402	Payment method required
404	Number provisioning disabled or customer self-serve plane disabled
409	Number limit reached or number already claimed
502	Number provider (Twilio) error

cURL

curl --request POST \
  --url 'https://api.voice.stateset.com/api/v1/customer/numbers' \
  --header "Authorization: Bearer $STATESET_VOICE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "phone_number": "[phone]"
}'

201

{
  "ok": true,
  "number": {
    "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "agent_key": "string",
    "agent_name": "string",
    "agent_version_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_at": "2026-08-31T14:22:05Z",
    "direction": "inbound",
    "greeting": "string",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "phone_number": "[phone]",
    "resolved_agent_version_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "resolved_version_number": 1001,
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "updated_at": "2026-08-31T14:22:05Z"
  }
}