Look up a caller name

Look up a caller name

Retrieve an available caller-name result for a telephone number. This is a production lookup and can charge your account, including when the result comes from the service’s cache. It does not change the outbound calling name for a number you own.

A returned name is not verified identity, ownership or permission to call. Names can be missing, stale, abbreviated, geographical labels or a telephone-number fallback.

Request

Use your enabled API account from its allowed source IP address. Keep credentials in server-side secret storage. The example uses environment variables and a fictional North American number; do not place credentials in URLs or public browser code.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  https://api.multitel.net/v3/cnam/12025550123

Supply the full number as digits including the country code, for example eleven digits beginning with 1 for North America. Do not depend on the handler to normalize punctuation or a plus sign. No request body or region selector is required. Confirm supported coverage with MultiTEL for your intended use.

Response

Illustrative values only; the cost is not a price quote.

{
  "status": {
    "code": 200,
    "msg": ""
  },
  "response": {
    "number": "12025550123",
    "name": "EXAMPLE NAME",
    "cost": 0.0037,
    "balance": 9.9963
  }
}

Charges and reconciliation

Named results are charged at the account’s configured CNAM price. A repeated or cached lookup can create another charge; no idempotency key is exposed. Check the current account rate before enabling automated lookups.

There is a known response limitation for a blank cached name: the handler can return API code 200 with an empty name, a nonzero cost and a reduced calculated balance even though that branch does not debit the account. Do not treat that response alone as proof of a charge. Reconcile against account billing records and a fresh balance lookup, and contact support for ambiguous results.

The prepaid check currently requires at least 0.004 balance before the lookup, independently of the configured per-query price. An account with purchases disabled is also rejected. Those checks do not make this endpoint a price-quotation or spending-limit API.

Errors and retries

Check both HTTP status and JSON status.code/status.msg. API code 403 can mean insufficient prepaid credit, purchases prohibited, an account authorization problem or no caller name found. The no-name path can return the code as a string. Inspect the message rather than treating every 403 as bad credentials. Configuration conflicts may return API code 500.

A timeout can occur after a billable lookup. Use bounded retries with backoff only when appropriate for your application and reconcile uncertain attempts first. Do not repeatedly retry a rejected number or an account-permission/balance failure. A response cache in your own application can reduce repeated requests, subject to your agreement and accuracy requirements.

Other number operations

This read operation is separate from an outbound calling-name/LIDB update, a directory listing or caller registration. Those operations have their own required fields, authorization and fees. Use allocation coverage for a prefix-table check or number search for orderable inventory. None of these establishes that a caller is who they claim to be.