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.
curl 'https://api.trovacast.com/v1/lookup/%2B919876543210' \
-H "Authorization: Bearer $TROVACAST_API_KEY"{
"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 still200, withinvalidReason:too_short,too_long,invalid_lengthornot_in_numbering_plan; itstypeisunknownandnationalFormatandcountryarenull.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,voicemailorunknown: 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;nullfor 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; readnameonly whenavailableis 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
| Code | Status | Meaning and what to do |
|---|---|---|
API_KEY_SCOPE_MISSING | 403 | The 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_MALFORMED | 400 | The 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_LIMITED | 429 | Too 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_FAILED | 400 | The 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. |