​

Number Lookup model

​

What a Lookup is — and is not

• Lookup never gates a send. Nothing requires you to dip a number before messaging or dialing it. Lookup is an explicit, billable operation you choose to run — typically to decide whether a send is worth attempting, or to screen for fraud before an OTP goes out.
• Lookup is billable per answered dip. Each dip an upstream actually answers debits your wallet on the number_lookup pricing channel (see the cost model below). A dip that falls through to local E.164 validation with no upstream call — a malformed number — is free.
• Lookup is a snapshot, not a guarantee. Reachability and SIM-swap answers describe the moment the upstream answered. The caching model below bounds how stale a snapshot can get.

​

The data packages — which dip answers which question

​

Reading the response

• present / liveStatus — the raw HLR presence verdict: "yes", "no", or "na" when the upstream does not expose presence. The convenience flag reachable is liveStatus === "yes", and lineStatus flattens the same signal to active / inactive / unknown so fraud and win-back flows can branch on one discriminator — treat unknown as “no signal,” never as inactive.
• network (name, type, mcc, mnc) — the current (recipient) network and its line type, reported on the response as carrier: network.name is the operator label, network.type is mobile, landline, or voip, and the MCC/MNC pair identifies the network for pricing and routing.
• portability.ported — true when the number moved carriers. When the upstream supplies the donor carrier, portability.originalCarrier names the network the number was ported away from; when the upstream omits it, it is null rather than fabricated.
• simSwap (swapped, lastSwapDate, riskLevel) — the recency verdict. swapped is true when the SIM changed inside the carrier’s monitored window, null when the operator gives no answer; the date of the most recent change lands in lastSwapDate (mapped from the upstream SIM-swap package’s last_sim_swap_date) alongside a low / medium / high / unknown risk level.
• roaming — serving-network MCC versus home-network MCC, derived from the HLR dip. A SIM provisioned in one country and currently serving in another is a SIM-in-unexpected-country fraud signal. null means indeterminate — do not map it to “not roaming.”

​

Caching and freshness

• Tenant-scoped by construction. The key binds your organization plus the normalized E.164, so two organizations dipping the same number never share an entry.
• Sandbox-isolated. Test-mode dips key separately from live dips, so a simulator result never poisons a live cache entry.
• Single-flight. Concurrent misses for the same number coalesce onto one upstream dip and one debit — a poll-happy client re-bills itself at most once per TTL window.

​

Cost model — per-dip charges and the daily cap

• Bulk lookups pre-check your balance for N × unit price and fail fast with 402 before fanning out, then charge per successful result.
• Sandbox (testMode) dips are never billed.
• Insufficient balance returns 402 INSUFFICIENT_BALANCE with balance_cents and cost_cents so you can prompt a top-up.

​

What Lookup is not

• MCC/MNC resolution at send time — when you actually send, the pricing path resolves the recipient’s MCC/MNC through its own resolution cache so the send prices without a fresh network dip. That is platform-internal send-time plumbing, not a customer-initiated operation: it is never billed to you as a lookup, and it answers “how do I price this send,” not “what can I learn about this number.” The per-(organization, operator) rate override model that layers onto it is documented on the linked page.
• Number Lookup endpoint reference — the task-level walkthrough: request parameters, the fields= selector, bulk dips, provider configuration, and the full response schema. This page stays conceptual; that page is the reference.

​

Worked example — combined HLR + SIM-swap dip

curl "https://api.orbit.devotel.io/api/v1/numbers/lookup/%2B14155550100?fields=line_type_intelligence,sim_swap" \
  -H "X-API-Key: dv_live_sk_..."

{
  "data": {
    "phoneNumber": "+14155550100",
    "valid": true,
    "carrier": { "name": "Verizon", "type": "mobile", "mcc": "310", "mnc": "004" },
    "portability": { "ported": false, "originalCarrier": null },
    "simSwap": { "swapped": false, "lastSwapDate": "2026-04-02", "riskLevel": "low" },
    "liveStatus": "yes",
    "reachable": true,
    "lineStatus": "active",
    "cached": false
  },
  "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" }
    },
    "sim_swap": {
      "status": "available",
      "reason": "camara_sim_swap",
      "provider": "camara",
      "data": { "swapped": false, "last_sim_swap_date": "2026-04-02", "last_sim_swap_date_monitored_period": 240 }
    }
  }
}

​

Related pages

• Number Lookup — the endpoint walkthrough: selector syntax, bulk dips, provider configuration, billing edges, full schema.
• API reference → Numbers — the OpenAPI surface for GET /numbers/lookup/{phone}, POST /numbers/lookup, and POST /numbers/bulk-lookup.
• MCC/MNC override model — the send-time network-resolution cache and the per-operator pricing overrides that layer onto it.
• Sender resolution — which sender an outbound message goes out from; the side of the pipeline Lookup never touches.
• Number lifecycle — the lifecycle of numbers your organization owns, as opposed to the third-party numbers a Lookup describes.