Numbers

Le descrizioni degli endpoint e dei campi restano in inglese, esattamente come le pubblica l'API. È una scelta voluta: qui legge ciò che vedrà anche nelle risposte.

POST /v1/numbers#

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

Corpo della richiesta

application/json Schema: NumberClaimRequest

Risposte

Esempio di richiesta

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

Una risposta riuscita restituisce un NumberClaimResponse.

Esempio di risposta

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

GET /v1/numbers/available#

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

Parametri

Risposte

Esempio di richiesta

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

Esempio di risposta

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

Corpo della richiesta

application/json Schema: NumberRegisterRequest

Risposte

Esempio di richiesta

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

Una risposta riuscita restituisce un NumberRouteResponse.

Esempio di risposta

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

DELETE /v1/numbers/{e164}#

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

Parametri

Risposte

Esempio di richiesta

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.

Parametri

Corpo della richiesta

application/json Schema: NumberRouteRequest

Risposte

Esempio di richiesta

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

Una risposta riuscita restituisce un NumberRouteResponse.

Esempio di risposta

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

Schemi#

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#