CNAM integration
CNAM over SIP
Authorize your SIP source, send a lookup transaction and read the returned caller identity.
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.
Authorize your source
- Add the public source IP used by your SBC or application in CNAM IP settings and associate the intended service.
- Send a SIP INVITE to
cnam.multitel.net, using the full telephone number as the request-URI user. The published transport is UDP on destination port 5060. - Use your SIP stack to generate the Via, From, To, Contact, Call-ID, CSeq and other required transaction headers. Do not send only the request line below.
- Complete the SIP transaction correctly and use the returned name only if a usable result is present.
INVITE sip:12025550123@cnam.multitel.net SIP/2.0This lookup service does not accept SIP registration. Authorization is based on the configured source address, which may be your NAT gateway’s public address.
Read the SIP lookup result
The service returns the result in a 380 SIP response with a P-Asserted-Identity header. This is the lookup result transaction, not an answered telephone call. The reason phrase can contain the returned name; parse the identity header rather than relying on one fixed phrase.
SIP/2.0 380 EXAMPLE CALLER
P-Asserted-Identity: "EXAMPLE CALLER" <sip:12025550123@192.0.2.10>
Content-Length: 0This excerpt omits transaction headers. 192.0.2.10 represents the requesting system in the example. The actual reply must be matched to your SIP stack’s Call-ID and CSeq.
- 380 with a usable name
- Read the display name from P-Asserted-Identity, acknowledge the final INVITE response through your SIP stack, and continue your calling workflow.
- No usable name
- Do not substitute an error message, blank value or the queried number as a verified caller name. Keep the call working with your ordinary unknown-name behavior.
- 403 or another rejection
- Check the request method, destination domain, source-IP authorization and account/service status. Do not retry an authorization error in a tight loop.
- Timeout
- Distinguish SIP transaction retransmissions from a new lookup. Limit new attempts because they can create another query charge.
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.