Contactivity
Numbers and SIPMarkdown

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.

bash
curl https://api.contactivity.io/v1/projects/$PROJECT_ID/lookup/%2B12125550100 \
  -H "Authorization: Bearer $API_KEY"
json
{
  "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.

bash
curl "https://api.contactivity.io/v1/projects/$PROJECT_ID/lookup/%2B12125550100?fields=caller_name" \
  -H "Authorization: Bearer $API_KEY"
json
{
  "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_name request 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.