Skip to main content

​
Number Lookup

Look up any E.164 phone number to validate it and enrich it with carrier, line-type, portability, SIM-swap, roaming, and live-reachability intelligence. Orbit uses Devotel HLR as the primary source and Telnyx as a fallback. Lookup is a billable operation — see Billing below.

​
Single Lookup (quick validation)

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/lookup \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+14155550100" }'
Returns validity, country, line type, and HLR enrichment. The phone field must be valid E.164 (+ followed by 1–15 digits).

​
Full Intelligence Lookup

curl "https://api.orbit.devotel.io/api/v1/numbers/lookup/%2B14155550100" \
  -H "X-API-Key: dv_live_sk_..."
URL-encode the leading + as %2B (an unencoded + is also accepted for back-compat).

​
Response

{
  "data": {
    "phoneNumber": "+14155550100",
    "valid": true,
    "callingCountryCode": "US",
    "nationalFormat": "(415) 555-0100",
    "carrier": { "name": "Verizon", "type": "mobile", "mcc": "310", "mnc": "004" },
    "portability": { "ported": false, "mnp_original_carrier": null },
    "simSwap": { "swapped": null, "lastSwapDate": null, "riskLevel": "unknown" },
    "roaming": { "roaming": null, "servingMcc": null, "homeMcc": null, "servingCountry": null },
    "liveStatus": "yes",
    "reachable": true,
    "cached": false
  }
}

​
Data Packages (Twilio Lookup v2 compatible)

Add a fields= selector (comma-separated, or a JSON array) to request per-field intelligence packages — the same selector shape Twilio Lookup v2 uses, so migration scripts work unchanged. 
curl "https://api.orbit.devotel.io/api/v1/numbers/lookup/%2B14155550100?fields=line_type_intelligence,sim_swap" \
  -H "X-API-Key: dv_live_sk_..."
The selector is case-insensitive, deduped server-side, and capped at 16 fields per request. An unknown field name rejects the whole request with 400.

​
Available fields

FieldStatus todaySource
line_type_intelligenceavailableDevotel HLR (type, network, mcc, mnc)
operator_nameavailableDevotel HLR home-network operator name
phone_number_quality_scoreavailablederived from reachability + portability + carrier signals
sim_swapavailable when Telnyx hints presentTelnyx Lookup v2
caller_namenot_implementedCNAM subscriber display (pairs with cnam)
cnamcoming_soonDevotel wholesale softswitch CNAM dip
identity_matchcoming_soonKYC vendor (not contracted)
call_forwardingcoming_soonTelnyx forwarding add-on (not contracted)
number_reputationcoming_soonTelnyx Number Insights / Trust Hub (not contracted)
Each entry in the response dataPackages map carries a discriminated status:
StatusMeaning
availableThe provider returned real data in data.
coming_soonThe field is advertised in the catalog but the upstream provider is not yet contracted (reason: "upstream_provider_not_contracted"). Replaying will not change the answer until the vendor work lands — do not design integrations assuming a payload.
not_implementedNo provider has wired this field yet (transient).
errorThe provider call failed for this specific field; the base lookup may still have succeeded (per-field isolation).
{
  "dataPackages": {
    "line_type_intelligence": {
      "status": "available",
      "reason": "hlr_live",
      "provider": "devotel-hlr",
      "data": { "type": "mobile", "carrier_name": "Verizon", "mobile_country_code": "310", "mobile_network_code": "004" }
    },
    "cnam": {
      "status": "coming_soon",
      "reason": "upstream_provider_not_contracted",
      "provider": "devotel-wholesale"
    }
  }
}

​
Bulk Lookup

Validate up to 100 numbers in a single request. 
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/bulk-lookup \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "numbers": ["+14155550100", "+14155550101"] }'
Bulk lookup requires the HLR provider to be configured; when it isn’t, the response carries available: false with an explanatory message and an empty results array. The endpoint is rate-limited more tightly than single lookup (a 100-number batch checks for ~$1.00 of wallet headroom up front).

​
Billing

Each lookup that an upstream actually answers is charged to your wallet on the number_lookup channel (fallback 1¢/query; per-org overrides apply). Key rules:
  • Single lookup is charged after the upstream returns. A request that falls through to local E.164 detection (no upstream call) is free.
  • Bulk lookup pre-checks your balance for N × unit price and fails fast with 402 before fanning out, then charges per successful result.
  • A per-tenant daily cost cap (default $50/day) protects against runaway spend — exceeding it returns 429.
  • Sandbox requests (testMode) are never billed.
Insufficient balance returns 402 INSUFFICIENT_BALANCE with balance_cents and cost_cents so you can prompt a top-up.