Numbers

POST /v1/numbers#

Claim a number. Claims a specific number, or any available number when the body is empty.

Request body

application/json Schema: NumberClaimRequest

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/numbers" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "e164": "+15550000001"
}'

A successful response returns a NumberClaimResponse.

Example response

{
  "e164": "+15550000001",
  "status": "claimed"
}

GET /v1/numbers/available#

List available numbers. Numbers you can claim from the pool.

Parameters

Responses

Example request

curl "https://api.voiceland.ai/v1/numbers/available" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "items": [
    "+15550000001"
  ]
}

POST /v1/numbers/register#

Register an external number. Records an externally-provisioned number as claimed and (optionally) routed to an agent in one call.

Request body

application/json Schema: NumberRegisterRequest

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/numbers/register" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent": "front-desk",
  "e164": "+15550000009"
}'

A successful response returns a NumberRouteResponse.

Example response

{
  "agent": "front-desk",
  "e164": "+15550000009"
}

DELETE /v1/numbers/{e164}#

Release a number. Returns a claimed number to the pool.

Parameters

Responses

Example request

curl -X DELETE "https://api.voiceland.ai/v1/numbers/{e164}" \
  -H "Authorization: Bearer VL_API_KEY"

POST /v1/numbers/{e164}/route#

Route a number to an agent. Binds a claimed number to an agent; calls to it reach that agent.

Parameters

Request body

application/json Schema: NumberRouteRequest

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/numbers/{e164}/route" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent": "front-desk"
}'

A successful response returns a NumberRouteResponse.

Example response

{
  "agent": "front-desk",
  "e164": "+15550000001"
}

Schemas#

Error#

Error envelope returned for non-2xx responses.

NumberClaimRequest#

Claim a number. Empty body claims any available number.

NumberClaimResponse#

NumberRegisterRequest#

Register an externally-provisioned number as claimed (and optionally routed).

NumberRouteRequest#

NumberRouteResponse#