Look up a caller's carrier and name

Voicephone number lookup (carrier and CNAM)

One GET returns a number's validity, formatting, country and type. include=carrier,cnam adds the carrier record and the caller-ID name.

identitynumbers

The claim

GET /api/relay/rest/lookup/phone_number/{e164} returns what the platform knows about a number. The vendored REST spec describes include as “further number information to include in the response, some of which are billable”. It takes two values, joined by a comma: carrier for “full carrier information” and cnam for “Caller ID information”. The SDK wraps the call as client.lookup.phone_number(e164, **params).

How it works

client = RestClient()

def enrich(e164):
    return client.lookup.phone_number(e164, include="carrier,cnam")

def check(e164):
    return client.lookup.phone_number(e164)

What the platform receives:

GET /api/relay/rest/lookup/phone_number/+15557654321?include=carrier,cnam

The spec’s response schema carries valid_number, e164, the national and international formatted forms, country_code, timezones and number_type, plus two objects you ask for with include. carrier holds lrn, spid, ocn, lata, city, state, jurisdiction, lec and linetype; cnam holds caller_id. check leaves include off, so it requests neither of the two extras the spec marks as possibly billable.

Limitations

The verifier proves the request and the documented response shape, not what a lookup returns for a real number. The spec says the included information is “some of which are billable”; it does not price it.

What to change first

Change include="carrier,cnam" to include="carrier" and run the verifier. The params assertion fails, which is the point: include names exactly the extra information you asked for.

Where this sits

Verify a caller id for outbound calls

python/app.py

"""Look up a caller's carrier and name.

One GET returns what the platform knows about a number: whether it is valid,
its formatted forms, its country and time zones. `include=carrier,cnam` adds
carrier details and the CNAM caller-ID name. The spec says the included
information is "some of which are billable".

Written against signalwire-sdk 3.0.1 (RestClient.lookup).
"""
from dotenv import load_dotenv
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

# RestClient() reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN /
# SIGNALWIRE_SPACE from the environment (signalwire/rest/client.py).
client = RestClient()


def enrich(e164):
    """Carrier and caller-ID name for a number, in one request."""
    return client.lookup.phone_number(e164, include="carrier,cnam")


def check(e164):
    """The base lookup, without requesting the carrier or CNAM extras."""
    return client.lookup.phone_number(e164)


if __name__ == "__main__":
    import sys

    if len(sys.argv) != 2 or not sys.argv[1].startswith("+"):
        raise SystemExit("usage: python app.py +1XXXXXXXXXX")
    print(enrich(sys.argv[1]))

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # then edit .env: your project id, API token and space
python app.py +1XXXXXXXXXX

There is no server to expose; the script speaks to the REST API and exits.

Verify it

No network, no account.

python verify.py          # from the recipe folder, not python/

You swap the SDK’s HTTP layer for a recorder, call both helpers, and assert the following.

enrich makes exactly one GET to the documented lookup path for the number with include=carrier,cnam and nothing else
check then makes exactly one GET to the same path with no query
the spec documents the path and the include parameter, and its description of include names carrier and cnam
the spec’s response schema carries every field this README names: the top-level ones, all nine under carrier, and caller_id under cnam

Report an issue