Number Intelligence API

📘

API Endpoint

Number Intelligence is supported via

API endpoint for it is: https ://{YourRegion}.webexconnect.io/v1/number-intelligence/lookup.

Please modify YourRegion in the URL to reflect your tenant’s region. See Know Your Endpoint Page.

❗️

API Access

This API is currently in beta and only available to select regions and clients. Please reach out to your account manager for access.

Introduction

Number Intelligence Lookup API helps you validate and enrich SMS destination numbers before sending messages. Use this API to normalize phone numbers, confirm whether a number is valid and text-enabled, and retrieve carrier details. This information can be used to decide whether to send a communication via SMS or use a different channel such as voice. The API supports both single-number and bulk lookups, returning one result for each submitted destination.

Prerequisites

This API supports Cisco Webex Common Identity (CI) authentication and requires creation of a Service App in Webex Developer Portal (https://developer.webex.com/). For Webex Connect tenants that do not have a Webex Org ID assigned yet, there is an additional pre-requisite step of getting it generated by logging a request with your account manager.

Doing a Number Intelligence lookup via API

Use Number Intelligence API to validate and enrich SMS destination numbers before sending messages.

Request Body

{
    "destinations": [
        {
            "number": "+447911123456", // Mandatory. E.164 format is accepted as-is.
        },
        {
            "number": "14155552671",
            "countryISO": "US" // Optional. Required when number is in local or national format.
        }
    ]
}

Number Intelligence Lookup API Body Parameters

The following are the parameters of the request body:

📘

Note:

The request payload must not exceed 1MB.

Destination numbers in local or national format require countryISO. If countryISO is missing, that destination is returned as an item-level error and other destinations in the same request continue to be processed.

The order of results always matches the order of submitted destinations.

Sample Response Body

{
    "response": [
        {
            "transId": "7f3af32c-8d6a-4b1e-b1c8-4805135ada71",
            "timestamp": "2026-04-15T13:53:13.749+01:00",
            "status": "success",
            "number": "+447911123456",
            "valid": true,
            "textEnabled": true,
            "carrierId": "GBXXX",
            "carrierName": "Example Carrier",
            "mcc": "234",
            "mnc": "001",
            "countryISO": "GB"
        },
        {
            "transId": "7f3af32c-8d6a-4b1e-b1c8-4805135ada71_1",
            "timestamp": "2026-04-15T13:53:13.749+01:00",
            "status": "success",
            "number": "+14155552671",
            "valid": true,
            "textEnabled": true,
            "carrierId": "USXXX",
            "carrierName": "Example Mobile",
            "mcc": "310",
            "mnc": "410",
            "countryISO": "US"
        }
    ]
}

{
    "response": [
        {
            "transId": "7f3af32c-8d6a-4b1e-b1c8-4805135ada71",
            "timestamp": "2026-04-15T13:53:13.749+01:00",
            "status": "success",
            "number": "+447911123456",
            "valid": true,
            "textEnabled": true,
            "carrierId": "GBXXX",
            "carrierName": "Example Carrier",
            "mcc": "234",
            "mnc": "001",
            "countryISO": "GB"
        },
        {
            "transId": "7f3af32c-8d6a-4b1e-b1c8-4805135ada71_1",
            "timestamp": "2026-04-15T13:53:13.749+01:00",
            "status": "error",
            "number": "07911123456",
            "error": "destinations[1].number is in local/national format but destinations[1].country_iso                       is missing. Provide a valid ISO country code to normalize this number."
        }
    ]
}

{
    "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "Invalid request: request body is missing or contains malformed JSON."
    }
}

{
    "error": {
        "code": "INVALID_TOKEN",
        "message": "Unauthorized: Bearer token is missing or invalid."
    }
}

{
    "error": {
        "code": "MISSING_SCOPE",
        "message": "Forbidden: Token does not include the required scope 'cpaas:number_intelligence'."
    }
}

{
    "error": {
        "code": "ORG_RATE_LIMIT_EXCEEDED",
        "message": "Too Many Requests: You have exceeded the number intelligence API rate limit for your organization. Please try again later."
    }
}

{
    "error": {
        "code": "NIS_UNAVAILABLE",
        "message": "Service Unavailable: The number intelligence provider is currently unavailable. Please try again later."
    }
}

📘

API Response and Error Codes

The Number Intelligence Lookup API is a synchronous API. For a valid request, the API returns HTTP 200 with a response array. Each item in the array represents the lookup result for the corresponding item in the request. If one destination fails but at least one destination can still be processed, the API returns HTTP 200. Check response [i]. status for each destination. For more information, see Channel Specific Status Codes.

Number Intelligence Lookup API Response Parameters

The following are the parameters returned in a successful HTTP 200 response:

📘

Note:

If a destination number is not found, the API returns the item with status as success, valid as false, and textEnabled as false.

Error Codes

Item-Level Error Messages

Item-level failures are returned inside the HTTP 200 response body. These errors affect only the corresponding destination object.

Rate Limits

Number Intelligence Lookup API requests are subject to your organization's configured transactions-per-second limit. If the limit is exceeded, the API returns HTTP 429.

Limits

What’s Next
Tell your users what they should do after they've finished this page