Numbers

Die Beschreibungen der Endpoints und der Felder erscheinen auf Englisch, genau so, wie die API sie ausliefert. Das ist Absicht: Sie lesen hier, was Sie auch in den Antworten sehen.

POST /v1/numbers#

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

Anfragetext

application/json Schema: NumberClaimRequest

Antworten

Beispielanfrage

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

Eine erfolgreiche Antwort liefert ein NumberClaimResponse.

Beispielantwort

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

GET /v1/numbers/available#

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

Parameter

Antworten

Beispielanfrage

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

Beispielantwort

{
  "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.

Anfragetext

application/json Schema: NumberRegisterRequest

Antworten

Beispielanfrage

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"
}'

Eine erfolgreiche Antwort liefert ein NumberRouteResponse.

Beispielantwort

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

DELETE /v1/numbers/{e164}#

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

Parameter

Antworten

Beispielanfrage

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.

Parameter

Anfragetext

application/json Schema: NumberRouteRequest

Antworten

Beispielanfrage

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"
}'

Eine erfolgreiche Antwort liefert ein NumberRouteResponse.

Beispielantwort

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

Schemata#

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#