List phone numbers

Retrieve all phone numbers associated with your account.

Endpoint

GET /v1/phone-numbers

Query Parameters

Parameter	Type	Required	Default	Description
`include_default`	string	No	`false`	Set to `true` to include shared default numbers
`limit`	integer	No	`50`	Maximum results (1-100)
`offset`	integer	No	`0`	Pagination offset

Example Request

Example Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phone_number": "+31201234567",
      "locality": "Amsterdam",
      "number_type": "local",
      "available": true,
      "created_at": "2025-01-15T10:30:00Z",
      "linked_assistant": null
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "phone_number": "+31851234567",
      "locality": null,
      "number_type": "national",
      "available": false,
      "created_at": "2025-01-10T08:00:00Z",
      "linked_assistant": {
        "id": "660e8400-e29b-41d4-a716-446655440000",
        "name": "Customer Support Agent"
      }
    }
  ],
  "shared_numbers": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "phone_number": "+31850001234",
      "locality": null,
      "number_type": "national"
    }
  ],
  "meta": {
    "total": 2,
    "limit": 20,
    "offset": 0
  }
}

Response Fields

Field	Type	Description
`id`	uuid	Unique phone number ID
`phone_number`	string	Phone number in E.164 format
`locality`	string	City/region for local numbers
`number_type`	string	Type: `local`, `mobile`, or `national`
`available`	boolean	Whether the number can be linked to an assistant
`created_at`	datetime	When the number was added
`linked_assistant`	object	Assistant currently using this number

Response JSON Schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "phone_number": { "type": "string" },
          "locality": { "type": "string", "nullable": true },
          "number_type": { "type": "string", "enum": ["local", "mobile", "national"], "nullable": true },
          "available": { "type": "boolean" },
          "created_at": { "type": "string", "format": "date-time" },
          "linked_assistant": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": { "type": "string", "format": "uuid" },
              "name": { "type": "string" }
            }
          }
        }
      }
    },
    "shared_numbers": {
      "type": "array",
      "description": "Only present when include_default=true"
    },
    "meta": {
      "type": "object",
      "properties": {
        "total": { "type": "integer" },
        "limit": { "type": "integer" },
        "offset": { "type": "integer" }
      }
    }
  }
}

Next:
Learn how to search available numbers or link a number to an assistant.

List phone numbers

Endpoint#

Query Parameters#

Example Request#

Example Response#

Response Fields#

Response JSON Schema#

Endpoint

Query Parameters

Example Request

Example Response

Response Fields

Response JSON Schema