Phone numbers linking

Link or unlink phone numbers from your assistants. When you link a phone number to an assistant, incoming calls to that number will be handled by that assistant.

Endpoints

Endpoint	Method	Description
`/v1/assistants/{id}/phone-number`	GET	Get linked phone number
`/v1/assistants/{id}/phone-number`	POST	Link a phone number
`/v1/assistants/{id}/phone-number`	DELETE	Unlink phone number

Get Linked Phone Number

Retrieve the phone number currently linked to an assistant.

Endpoint

GET /v1/assistants/{id}/phone-number

Path Parameters

Parameter	Type	Required	Description
`id`	uuid	Yes	Assistant ID

Example Request

Example Response

{
  "data": {
    "assistant_id": "660e8400-e29b-41d4-a716-446655440000",
    "assistant_name": "Customer Support Agent",
    "phone_number": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "number": "+31201234567",
      "type": "local",
      "locality": "Amsterdam",
      "origin": "custom"
    }
  }
}

Response (No Phone Number Linked)

{
  "data": {
    "assistant_id": "660e8400-e29b-41d4-a716-446655440000",
    "assistant_name": "Customer Support Agent",
    "phone_number": null
  }
}

Link Phone Number

Link a phone number to an assistant. If the assistant already has a phone number, it will be automatically unlinked first.

Endpoint

POST /v1/assistants/{id}/phone-number

Path Parameters

Parameter	Type	Required	Description
`id`	uuid	Yes	Assistant ID

Request Body

Field	Type	Required	Description
`phone_number_id`	uuid	Yes	The ID of the phone number to link

Example Request

Example Response

{
  "message": "Phone number linked successfully",
  "data": {
    "assistant_id": "660e8400-e29b-41d4-a716-446655440000",
    "phone_number": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "number": "+31201234567",
      "type": "local",
      "locality": "Amsterdam"
    },
    "previous_phone_number_id": null,
    "released_assistants": 0
  }
}

Note: When linking a shared (default) number, any other assistants using a default number will be automatically unlinked. The released_assistants field shows how many were affected.

Unlink Phone Number

Remove the phone number from an assistant. The phone number becomes available again.

Endpoint

DELETE /v1/assistants/{id}/phone-number

Path Parameters

Parameter	Type	Required	Description
`id`	uuid	Yes	Assistant ID

Example Request

Example Response

{
  "message": "Phone number unlinked successfully",
  "data": {
    "assistant_id": "660e8400-e29b-41d4-a716-446655440000",
    "unlinked_phone_number": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "number": "+31201234567"
    }
  }
}

Request JSON Schema (POST)

{
  "type": "object",
  "properties": {
    "phone_number_id": {
      "type": "string",
      "format": "uuid",
      "description": "The ID of the phone number to link (from GET /v1/phone-numbers)"
    }
  },
  "required": ["phone_number_id"]
}

Response JSON Schema (GET)

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "assistant_id": { "type": "string", "format": "uuid" },
        "assistant_name": { "type": "string" },
        "phone_number": {
          "type": "object",
          "nullable": true,
          "properties": {
            "id": { "type": "string", "format": "uuid" },
            "number": { "type": "string" },
            "type": { "type": "string", "enum": ["local", "mobile", "national"], "nullable": true },
            "locality": { "type": "string", "nullable": true },
            "origin": { "type": "string", "enum": ["default", "custom"] }
          }
        }
      }
    }
  }
}

Response JSON Schema (POST)

{
  "type": "object",
  "properties": {
    "message": { "type": "string" },
    "data": {
      "type": "object",
      "properties": {
        "assistant_id": { "type": "string", "format": "uuid" },
        "phone_number": {
          "type": "object",
          "properties": {
            "id": { "type": "string", "format": "uuid" },
            "number": { "type": "string" },
            "type": { "type": "string", "nullable": true },
            "locality": { "type": "string", "nullable": true }
          }
        },
        "previous_phone_number_id": { "type": "string", "format": "uuid", "nullable": true },
        "released_assistants": { "type": "integer" }
      }
    }
  }
}

Response JSON Schema (DELETE)

{
  "type": "object",
  "properties": {
    "message": { "type": "string" },
    "data": {
      "type": "object",
      "properties": {
        "assistant_id": { "type": "string", "format": "uuid" },
        "unlinked_phone_number": {
          "type": "object",
          "nullable": true,
          "properties": {
            "id": { "type": "string", "format": "uuid" },
            "number": { "type": "string" }
          }
        }
      }
    }
  }
}

Error Codes

Code	HTTP Status	Description
`invalid_parameters`	400	Invalid phone_number_id format
`not_found`	404	Assistant or phone number not found
`forbidden`	403	Phone number does not belong to you
`already_linked`	400	Phone number already linked to this assistant
`already_in_use`	400	Custom phone number is linked to another assistant
`no_phone_number`	400	No phone number to unlink

Next:
Learn about phone numbers or verification groups.

Phone numbers linking

Endpoints#

Get Linked Phone Number#

Endpoint#

Path Parameters#

Example Request#

Example Response#

Response (No Phone Number Linked)#

Link Phone Number#

Endpoint#

Path Parameters#

Request Body#

Example Request#

Example Response#

Unlink Phone Number#

Endpoint#

Path Parameters#

Example Request#

Example Response#

Request JSON Schema (POST)#

Response JSON Schema (GET)#

Response JSON Schema (POST)#

Response JSON Schema (DELETE)#

Error Codes#

Endpoints

Get Linked Phone Number

Endpoint

Path Parameters

Example Request

Example Response

Response (No Phone Number Linked)

Link Phone Number

Endpoint

Path Parameters

Request Body

Example Request

Example Response

Unlink Phone Number

Endpoint

Path Parameters

Example Request

Example Response

Request JSON Schema (POST)

Response JSON Schema (GET)

Response JSON Schema (POST)

Response JSON Schema (DELETE)

Error Codes