Lookup
Check and format a phone number, and look up the caller name registered for it. Paths are relative to
https://api.contactivity.io/v1/projects/{project_id}; see the overview.
| Method | Path | Scope | Purpose |
|---|---|---|---|
| GET | /lookup/{phone_number} |
lookup:read |
Validate and format a number; with fields=caller_name, also its caller name |
| GET | /lookups |
lookup:read |
List caller name lookups, newest first (paged) |
{phone_number} is E.164, URL-encoded: +12125550100 is %2B12125550100.
Validate and format (free)
Without fields, a lookup only checks and formats the number. It is free and is not listed in /lookups.
curl https://api.contactivity.io/v1/projects/$PROJECT_ID/lookup/%2B12125550100 \
-H "Authorization: Bearer $API_KEY"{
"phone_number": "+12125550100",
"country": "US",
"calling_country_code": "1",
"national_format": "(212) 555-0100",
"valid": true,
"caller_name": null,
"price": {"amount": "0.000000", "currency": "USD"}
}| Field | Description |
|---|---|
phone_number |
The number in E.164 |
country |
ISO country code, or null when unknown |
calling_country_code |
The country calling code, without + |
national_format |
The number as dialed in its country (+1 numbers only; null otherwise) |
valid |
Whether the number can be a real number in its country |
caller_name |
null unless fields=caller_name |
price |
What this request cost |
Caller name
Add fields=caller_name to look up the name registered for the number. US and Canada (+1) numbers only.
curl "https://api.contactivity.io/v1/projects/$PROJECT_ID/lookup/%2B12125550100?fields=caller_name" \
-H "Authorization: Bearer $API_KEY"{
"id": "lk_us1_6f0c1d2e3a4b5c6d7e8f9a0b",
"phone_number": "+12125550100",
"fields": ["caller_name"],
"country": "US",
"calling_country_code": "1",
"national_format": "(212) 555-0100",
"valid": true,
"caller_name": {"name": "ACME CORP", "error_code": null},
"price": {"amount": "0.010000", "currency": "USD"},
"created_at": "2026-10-30T14:03:11.123Z"
}caller_name.name is the name, up to 15 characters, or null. caller_name.error_code says why there is no name:
error_code |
Meaning | Charged |
|---|---|---|
null |
A name was found | Yes |
not_found |
No name is registered for the number | Yes |
unavailable |
The lookup could not be done right now; try again later | No |
Each caller name lookup is stored and listed in GET /lookups ({data, has_more, next_cursor}, limit and
starting_after as in every list). Lookups are never deleted.
Pricing
- Validation and formatting (no
fields) are free. - Each
fields=caller_namerequest is charged the caller name price, including a repeat lookup of the same number. - A lookup with
error_code: "unavailable"is not charged.
The price is in GET /pricing under number_features.lookup_caller_name (null: not offered on your account) and
on the portal's Pricing page. Charges show in your ledger as Lookup. Your balance must be above zero.
Errors
| Status | code |
When |
|---|---|---|
| 400 | invalid_parameter (param: phone_number) |
The number is not E.164 |
| 400 | invalid_parameter (param: fields) |
An unknown field, or caller_name for a number outside +1 |
| 402 | insufficient_balance |
Your balance is zero or below |
| 403 | insufficient_scope |
The API key does not have lookup:read |
| 409 | feature_unavailable |
Caller name lookup is not offered on your account |
Twilio-compatible route
Code written for Twilio Lookup v2 can call
GET https://api.contactivity.io/compat/twilio/v2/PhoneNumbers/{PhoneNumber}?Fields=caller_name with the same
Basic credentials as the other Twilio-compatible routes. The response has Twilio's shape (caller_name,
caller_type, error_code); billing is the same as above. See the
compatibility guide.

