CNAM integration
CNAM REST API reference
Request a caller name over HTTPS and handle the result, charge and errors.
Choose the lookup behavior
| Tier | Public price per query | What it does |
|---|---|---|
| Starter | $0.0026 | Uses proprietary and cached caller-name information. |
| Standard | $0.0037 | Makes a real-time network lookup for each query. |
| Mixed | $0.004 | Tries a real-time lookup first, then falls back to Starter data when no name is found. |
The selected service determines the lookup behavior; Mixed is not a cache-first lookup. Review the rate assigned to your account before production use. A caller name is not proof of identity or ownership.
Send an authenticated lookup
Endpoint: GET https://api.multitel.net/v3/cnam/NUMBER. Use international digits including the country code, without punctuation or a leading plus. Execute this from your application server using approved API credentials.
curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
"https://api.multitel.net/v3/cnam/12025550123"Supply the two environment variables through server-side secret configuration. A provisioned bearer credential is an alternative only when that access is enabled and its source-IP restrictions are satisfied. Never put an API secret into a public browser bundle.
Read the JSON response
This response is illustrative. The returned name and charge depend on the lookup and selected service.
{
"status": {
"code": 200,
"msg": ""
},
"response": {
"number": "12025550123",
"name": "EXAMPLE CALLER",
"cost": "0.004",
"balance": "24.9960"
}
}status.code- Application result code; normalize string/numeric values before comparing with 200.
status.msg- The accompanying outcome or rejection message.
response.number- The number queried.
response.name- The available caller name.
response.cost- The charge reported for this query; treat it as a decimal amount.
response.balance- The reported account balance, when present.
No-name results and errors
A successful request does not guarantee a useful caller name. Handle an empty name, a number returned in place of a name and a rejected lookup. Application code 403 can describe insufficient credit, a prohibited purchase or a number with no result; inspect the message.
Check both HTTP status and JSON status before accessing response.name. The response object may be absent on error. A missing name should not prevent the normal call from being routed.
Billing, retries and the difference from updating caller ID
A new lookup can incur a query charge. These lookup interfaces do not document an idempotency key, so a fresh retry can be a second billable query. Use limited backoff for transport/service failures, resolve account errors first, and reconcile the reported query charges. Cache only for a period appropriate to your application; caller-name data can change.
A CNAM lookup reads a name. It does not change the name presented on your outbound calls. A LIDB caller-name update is a separate operation with its own fields, authorization, price and processing.