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 2–15 digits, the first non-zero).

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 422.

Available fields

Field	Status today	Source
`line_type_intelligence`	available	Devotel HLR (`type`, `network`, `mcc`, `mnc`)
`operator_name`	available	Devotel HLR home-network operator name
`phone_number_quality_score`	available	derived from reachability + portability + carrier signals
`sim_swap`	available when carrier signal present	CAMARA SIM Swap (GSMA Open Gateway) — carrier-asserted last-SIM-change; Telnyx Lookup v2 best-effort fallback
`identity_match`	available when a CAMARA operator is configured (coming_soon otherwise)	CAMARA KYC Match (GSMA Open Gateway) — operator-asserted phone→identity match. Supply the attributes to verify (`identity_name`, `identity_given_name`, `identity_family_name`, `identity_birthdate`, `identity_email`, `identity_id_document`) and receive per-attribute match verdicts, never the underlying PII. Selecting the field with no attribute returns a per-field `error` (`identity_attributes_required`).
`caller_name`	available (coming_soon if Telnyx unconfigured)	Telnyx Lookup v2 caller-name dip (CNAM subscriber display; pairs with `cnam`)
`cnam`	available (coming_soon if Telnyx unconfigured)	Telnyx Lookup v2 caller-name dip
`reassigned_number`	available (US-only; requires `consent_date`)	FCC Reassigned Numbers Database (reassigned.us)
`call_forwarding`	available (derived, low confidence)	Devotel HLR reachability — best-effort divert inference, `derived: true`
`number_reputation`	available (derived, devotel-hlr)	HLR-derived risk score — line-type + reachability + portability signals; `data.risk_score` (0-1), `data.risk_bucket`, `data.derived: true`. Contracted Telnyx / Trust Hub feed supersedes additively.
`sms_pumping_risk`	available (derived, devotel-hlr)	HLR-derived SMS-pumping (AIT) fraud score — line-type (VOIP/virtual signal) + on-network reachability + portability churn fused into a 0-100 score + bucket, with the contributing signals exposed and `data.derived: true`. Dip it before granting an OTP send. A contracted SMS-pumping feed supersedes the derivation additively.

Each entry in the response dataPackages map carries a discriminated status:

Status	Meaning
`available`	The provider returned real data in `data`.
`coming_soon`	The 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_implemented`	No provider has wired this field yet (transient).
`error`	The 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": "available",
      "reason": "telnyx_lookup_v2_caller_name",
      "provider": "telnyx",
      "data": { "caller_name": "ACME CORP" }
    },
    "call_forwarding": {
      "status": "available",
      "reason": "derived_from_hlr_reachability",
      "provider": "devotel-hlr",
      "data": {
        "call_forwarding": true,
        "forwarded": true,
        "confidence": "low",
        "derived": true,
        "signal": "hlr_reachability",
        "reachable": false,
        "line_status": "no"
      }
    }
  }
}

call_forwarding is a derived, best-effort signal, not an operator-asserted forwarding flag. It infers an active unconditional divert from the HLR reachability dip Orbit already runs — a valid line reported as unreachable on its home network is the classic proxy for calls forwarding elsewhere (a known SIM-swap / account-takeover indicator). Treat it as a low-confidence input (confidence: "low", derived: true), fuse it with other signals, and do not use it as ground truth. It falls back to coming_soon when HLR returns no usable reachability signal.

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 (see Configuration); 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).

Configuration

Lookup resolves its upstream from two environment variables on the API service:

Variable	Required	Default	Purpose
`DEVOTEL_HLR_API_KEY`	Yes, to enable HLR	(unset)	API key for Devotel’s HLR service. This is the credential that turns HLR on — it is the primary source for single lookup and the only source for bulk lookup. While it is unset, single lookup falls back to Telnyx (if `DEVOTEL_TELNYX_API_KEY` is set) and bulk lookup returns `available: false`.
`DEVOTEL_HLR_API_URL`	No	`https://hlr.orbit.devotel.io/api/v1/hlr`	Base URL of the HLR service. Override only when pointing at a non-default HLR endpoint.

Set DEVOTEL_HLR_API_KEY (and, if needed, DEVOTEL_HLR_API_URL) on the API service and restart it. Once the key is present, bulk lookup begins returning results and single lookup uses HLR as its primary source.

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.

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Billing

Webhooks

Compliance

Legal

Changelog

Number Lookup

Number Lookup

Single Lookup (quick validation)

Full Intelligence Lookup

Response

Data Packages (Twilio Lookup v2 compatible)

Available fields

Bulk Lookup

Configuration

Billing

​Number Lookup

​Single Lookup (quick validation)

​Full Intelligence Lookup

​Response

​Data Packages (Twilio Lookup v2 compatible)

​Available fields

​Bulk Lookup

​Configuration

​Billing

Number Lookup

Single Lookup (quick validation)

Full Intelligence Lookup

Response

Data Packages (Twilio Lookup v2 compatible)

Available fields

Bulk Lookup

Configuration

Billing