Skip to main content

Numbers

The authenticated API client can list, search, and update number settings through the CORE API.

Use this page to answer four practical questions:

  1. which numbers does this API client control
  2. which number should I send from
  3. is the selected number configured for the message type I need
  4. are webhook overrides configured where I expect them to be

Canonical example values​

  • access_token: rc_token_example
  • numberId: num_abc123
  • phone: +15551234567

List assigned numbers​

Request​

curl "$BASE_URL/api/core/numbers" \
  -H "Authorization: Bearer rc_token_example"

Response​

{
  "numbers": [
    {
      "numberId": "num_abc123",
      "e164": "+15551234567",
      "status": "ACTIVE",
      "campaignRegId": "A1B2C3",
      "smsEnabled": true,
      "mmsEnabled": true,
      "webhookInboundOverride": "https://example.com/webhooks/inbound",
      "webhookDeliveryOverride": "https://example.com/webhooks/delivery"
    }
  ]
}

How to read the list response​

For each returned number, pay attention to:

  • numberId
    • this is the value you send in sendFrom
  • e164
    • this is the phone number humans recognize
  • status
    • the number should normally be ACTIVE before you use it
  • smsEnabled
    • must be true for SMS sends
  • mmsEnabled
    • must be true for MMS sends
  • campaignRegId
    • useful for operational verification when campaign-linked messaging is involved
  • webhookInboundOverride
    • optional inbound webhook override at the number level
  • webhookDeliveryOverride
    • optional delivery webhook override at the number level

Choosing the correct sendFrom​

For outbound sends:

  • use numberId in sendFrom
  • do not use the E.164 phone number in sendFrom

Correct:

{
  "sendFrom": "num_abc123"
}

Incorrect:

{
  "sendFrom": "+15551234567"
}

Search available numbers​

Use POST /api/core/numbers/search.

Example request​

curl -X POST "$BASE_URL/api/core/numbers/search" \
  -H "Authorization: Bearer rc_token_example" \
  -H "Content-Type: application/json" \
  -d '{
    "npa": "555",
    "city": "Austin",
    "state": "TX"
  }'

Example response​

{
  "groups": [
    {
      "rateCenter": "AUSTIN",
      "count": 1,
      "numbers": [
        {
          "e164": "+15551234567",
          "nationalDisplay": "(555) 123-4567",
          "city": "Austin",
          "state": "TX",
          "rateCenter": "AUSTIN"
        }
      ]
    }
  ],
  "providerResultCount": 1,
  "requestedQuantity": 250
}

Search constraints​

  • nxx requires npa
  • city requires state
  • rateCenter requires state
  • rateCenter search is currently validation-blocked in the implementation

Use search when you need to:

  • find inventory in a specific geography
  • inspect available numbers before provisioning or assignment
  • compare rate-center or city options

Do not use search to determine what your API client already owns. Use GET /api/core/numbers for that.

Update number settings​

Use PATCH /api/core/numbers/{numberId}.

Example request​

curl -X PATCH "$BASE_URL/api/core/numbers/num_abc123" \
  -H "Authorization: Bearer rc_token_example" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignregId": "A1B2C3",
    "smsEnabled": true,
    "mmsEnabled": true,
    "webhookInboundOverride": "https://example.com/webhooks/inbound",
    "webhookDeliveryOverride": "https://example.com/webhooks/delivery"
  }'

Example response​

{
  "number": {
    "numberId": "num_abc123",
    "e164": "+15551234567",
    "status": "ACTIVE",
    "campaignRegId": "A1B2C3",
    "smsEnabled": true,
    "mmsEnabled": true,
    "webhookInboundOverride": "https://example.com/webhooks/inbound",
    "webhookDeliveryOverride": "https://example.com/webhooks/delivery"
  }
}

What to update carefully​

The number update route changes operational behavior. Treat it as configuration, not a casual test endpoint.

Typical reasons to update a number:

  • enable or disable SMS
  • enable or disable MMS
  • set inbound webhook override
  • set delivery webhook override
  • apply or correct campaign registration linkage

Recommended practice:

  1. list the number first
  2. confirm you are targeting the correct numberId
  3. patch only the fields you intend to change
  4. re-read the number after the update
  5. run a controlled outbound test if messaging behavior changed

Number-readiness checklist before sending​

Before you use a number in production or staging tests, confirm:

  • the number appears in GET /api/core/numbers
  • status is ACTIVE
  • sendFrom will use the numberId
  • smsEnabled is true for SMS traffic
  • mmsEnabled is true for MMS traffic
  • webhook overrides are correct, if you rely on number-level webhook behavior

Common mistakes​

  • using E.164 instead of numberId in sendFrom
  • assuming a listed number is usable without checking status
  • attempting MMS with mmsEnabled: false
  • changing webhook overrides without re-testing event receipt
  • treating number search results as already-assigned numbers

Important naming note​

The request field name is:

  • campaignregId

That spelling reflects the actual implemented request contract and should not be normalized client-side.