Trovacast

Contacts

Lookup

Check a phone number before you store, message or dial it: whether it is valid, its formats, country and type, and whether an Indian number is on the do-not-call registry.

GET /v1/lookup/{phone} with the lookup:read scope reads a number from the numbering metadata Trovacast carries and India’s do-not-call list. Nothing leaves the platform, so a lookup is free; it counts against the key’s per-minute request budget like any request (Rate limits). Test keys may use it exactly as live keys do: it reads nothing of your project and writes nothing.

Look a number up

Send the number in E.164 — +, the country calling code, the number (%2B for the + if your HTTP client rewrites it) — or as it is written inside its country with ?country= (an ISO 3166 alpha-2 code: /v1/lookup/09876543210?country=IN). Spaces, dots, dashes and brackets are ignored.

Look up an Indian mobile
curl 'https://api.trovacast.com/v1/lookup/%2B919876543210' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
200 (json)
{
  "object": "phone_number_lookup",
  "valid": true,
  "invalidReason": null,
  "e164": "+919876543210",
  "nationalFormat": "098765 43210",
  "country": "IN",
  "countryCallingCode": "91",
  "type": "mobile",
  "carrier": {
    "name": null,
    "available": false
  },
  "dnd": {
    "registry": "ncpr",
    "status": "not_registered"
  }
}

What comes back

  • valid — whether the number is one its country’s numbering plan assigns (the right length, an allocated range). It does not say whether the number is in service. A number that is not valid is still 200, with invalidReason: too_short, too_long, invalid_length or not_in_numbering_plan; its type is unknown and nationalFormat and country are null.
  • type — mobile, fixed_line, fixed_line_or_mobile (the US and Canada do not tell them apart), toll_free, premium_rate, shared_cost, voip, personal_number, pager, uan, voicemail or unknown: the kind of range the number was issued from, so a ported number keeps its type.
  • country — the ISO 3166 alpha-2 country or territory; null for a non-geographic code (+800, +882, …).
  • carrier — always { "name": null, "available": false }. Naming a number’s operator needs a carrier lookup with a vendor, which Trovacast does not make; read name only when available is true.

India’s do-not-call registry

For a valid +91 number, dnd reads { "registry": "ncpr", "status": "registered" } or "not_registered": its place on India’s National Customer Preference Register as the platform operator last loaded it — the same list Trovacast scrubs promotional calls against (422 NCPR_REGISTERED). It is that extract, not a live check with a registry vendor, so a number registered since the last load reads not_registered. Outside India (and for a number that is not valid) it is { "registry": null, "status": "not_applicable" }.

Errors

CodeStatusMeaning and what to do
API_KEY_SCOPE_MISSING403The key lacks the scope the endpoint (or a webhook event) requires; requiredScope names it. See Scopes.What to do: Use a key that holds requiredScope: a project administrator creates one in Settings → Developers (an existing key's scopes can be narrowed, never widened). Retrying with this key cannot succeed.
PHONE_NUMBER_MALFORMED400The path of GET /v1/lookup/{phone} is not a phone number Trovacast can read: letters, no country calling code, or a code no country uses. The message never repeats what you sent. A number that reads but is not one its country assigns is not this error — it is 200 with valid: false. See Lookup.What to do: Send the number in E.164 — + and its country calling code (%2B for + if your client rewrites it) — or write it nationally with ?country=; the same path fails the same way.
RATE_LIMITED429Too many requests. Also a webhook test past its endpoint's budget, or a webhook URL past the project's hourly budget. See Rate limits.What to do: Wait Retry-After seconds, then retry the same request — with the same Idempotency-Key on a write — backing off exponentially with jitter if it repeats. See Backing off.
VALIDATION_FAILED400The request is malformed; message lists each problem. Also a bulk webhook resend whose until is not after since.What to do: Correct every problem message lists, then send the request again; the same body fails the same way. The API reference has each endpoint's fields.