Developer docs: Numbers

Numbers

Phone numbers and inbound routing.

List phone numbersLink to List phone numbers

GET/numbers

Scope: numbers:read

curl "https://bookifycall.com/api/v1/external/numbers" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY"

Example response · 200

{
  "success": true,
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000006",
      "organizationId": "00000000-0000-4000-8000-000000000100",
      "agentId": "00000000-0000-4000-8000-000000000002",
      "phoneNumber": "+15551230002",
      "provider": "twilio",
      "providerSid": "PN00000000000000000000000000000000",
      "status": "active",
      "capabilities": {
        "voice": true,
        "sms": true
      },
      "fallbackUrl": null,
      "providerAccountId": null,
      "previousRouting": null,
      "createdAt": "2026-01-02T10:00:00.000Z",
      "updatedAt": "2026-01-02T10:00:00.000Z",
      "agent": {
        "id": "00000000-0000-4000-8000-000000000002",
        "name": "Riley",
        "slug": "riley"
      }
    }
  ]
}

Bind a number to an agent (inbound routing)Link to Bind a number to an agent (inbound routing)

POST/numbers/{id}/assign

Scope: numbers:write
Idempotency-Key: supported
Not found: 404 PHONE_001

Path parameters

idstringrequired

Body (JSON)

aiAgentIdstring: Live name
agentIdstring

curl -X POST "https://bookifycall.com/api/v1/external/numbers/00000000-0000-4000-8000-000000000006/assign" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"aiAgentId":"00000000-0000-4000-8000-000000000002"}'

Example response · 200

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000006",
    "organizationId": "00000000-0000-4000-8000-000000000100",
    "agentId": "00000000-0000-4000-8000-000000000002",
    "phoneNumber": "+15551230002",
    "provider": "twilio",
    "providerSid": "PN00000000000000000000000000000000",
    "status": "active",
    "capabilities": {
      "voice": true,
      "sms": true
    },
    "fallbackUrl": null,
    "providerAccountId": null,
    "previousRouting": null,
    "createdAt": "2026-01-02T10:00:00.000Z",
    "updatedAt": "2026-01-02T10:00:00.000Z"
  }
}

Set or clear a number's fallback URLLink to Set or clear a number's fallback URL

PATCH/numbers/{id}/fallback

Twilio requests it only when BookifyCall cannot answer. Public https only (PHONE_021); numbers without a provider SID refuse (PHONE_020). Empty string clears it.

Scope: numbers:write
Not found: 404 PHONE_001

Path parameters

idstringrequired

Body (JSON)

fallbackUrlstringrequired: Public https URL Twilio calls if BookifyCall cannot answer. Empty string clears it.

curl -X PATCH "https://bookifycall.com/api/v1/external/numbers/00000000-0000-4000-8000-000000000006/fallback" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fallbackUrl":"https://app.example.com/voice/voicemail"}'

Example response · 200

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000006",
    "organizationId": "00000000-0000-4000-8000-000000000100",
    "agentId": "00000000-0000-4000-8000-000000000002",
    "phoneNumber": "+15551230002",
    "provider": "twilio",
    "providerSid": "PN00000000000000000000000000000000",
    "status": "active",
    "capabilities": {
      "voice": true,
      "sms": true
    },
    "fallbackUrl": "https://app.example.com/voice/voicemail",
    "providerAccountId": null,
    "previousRouting": null,
    "createdAt": "2026-01-02T10:00:00.000Z",
    "updatedAt": "2026-01-02T10:00:00.000Z"
  }
}

Next: Compliance