Order a phone number

Order a new phone number to use with your assistants. This endpoint supports all number types, but local numbers require an approved verification group.

Endpoint

POST /v1/phone-numbers

Request Body

Field	Type	Required	Description
`phone_number`	string	Yes	The phone number to order (from available numbers)
`number_type`	string	No	Type: `local`, `mobile`, or `national` (default: `national`)
`verification_group_id`	uuid	Conditional	Required for `local` numbers

Example Request (National Number)

Example Request (Local Number)

Example Response

{
  "message": "Phone number ordered",
  "data": {
    "order_id": "660e8400-e29b-41d4-a716-446655440000",
    "phone_number": "+31851234567",
    "number_type": "national",
    "status": "pending",
    "credits_used": 10,
    "remaining_credits": 90
  }
}

Response Fields

Field	Type	Description
`order_id`	uuid	Unique order ID for tracking
`phone_number`	string	The ordered phone number
`number_type`	string	Type of number ordered
`status`	string	Order status: `pending`, `success`, or `failed`
`credits_used`	integer	Credits deducted (10)
`remaining_credits`	integer	Your remaining credit balance

Request JSON Schema

{
  "type": "object",
  "properties": {
    "phone_number": {
      "type": "string",
      "description": "The phone number to order in E.164 format"
    },
    "number_type": {
      "type": "string",
      "enum": ["local", "mobile", "national"],
      "default": "national"
    },
    "verification_group_id": {
      "type": "string",
      "format": "uuid",
      "description": "Required for local numbers"
    }
  },
  "required": ["phone_number"]
}

Response JSON Schema

{
  "type": "object",
  "properties": {
    "message": { "type": "string" },
    "data": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string", "format": "uuid" },
        "phone_number": { "type": "string" },
        "number_type": { "type": "string" },
        "status": { "type": "string" },
        "credits_used": { "type": "integer" },
        "remaining_credits": { "type": "integer" }
      }
    }
  }
}

Error Codes

Code	HTTP Status	Description
`insufficient_credits`	402	Not enough credits (need 10)
`invalid_parameters`	400	Invalid phone number or missing verification group
`invalid_status`	400	Verification group not approved (for local numbers)

Next:
Track your order with phone number orders, or link it to an assistant once completed.

Order a phone number

Endpoint#

Request Body#

Example Request (National Number)#

Example Request (Local Number)#

Example Response#

Response Fields#

Request JSON Schema#

Response JSON Schema#

Error Codes#