> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Numbers API

> Numbers endpoints exposed by the Devotel CPaaS API

# Numbers API

Numbers endpoints exposed by the Devotel CPaaS API

**Base path:** `/api/v1/numbers/lookup`

**Endpoint count:** 1

***

### Full phone number intelligence lookup

<Note>
  `GET /api/v1/numbers/lookup/{phoneNumber}`
</Note>

Full number intelligence (carrier / portability / SIM swap / roaming / live status) for a single E.164 phone number. Uses Devotel HLR as primary and Telnyx as fallback. When `fields=` is supplied (comma-separated or JSON array), the response also carries a `dataPackages` map keyed by the requested field names — each entry carries a discriminated `status` enum (`available` | `coming_soon` | `not_implemented` | `error`), a `reason` string, the intended `provider`, and an optional `data` payload when realised. The `number_reputation` field (Twilio Lookup v2 Number Reputation parity) returns a transparent 0-1 spam/fraud risk score in `data.risk_score` with a `data.risk_bucket` (`low`/`medium`/`high`), the `data.factors` that fired, and the contributing signals (`line_type`, `reachable`, `ported`, `sim_swapped`) — DERIVED from the same HLR/Telnyx upstream the lookup already fetched (flagged `data.derived: true`, NOT a paid reputation feed) whenever any usable HLR signal is present, and falls back to `not_implemented` only when no usable signal exists. `call_forwarding` returns a derived, best-effort signal in `data.call_forwarding` (boolean) inferred from the HLR reachability dip — flagged `data.derived: true` with `data.confidence: low` (not an operator-asserted flag; the paid Telnyx forwarding add-on is not contracted), falling back to `coming_soon` only when HLR returns no usable reachability signal. `cnam` and its Twilio-compat alias `caller_name` resolve against the Telnyx Lookup v2 caller-name dip and return `available` with the registered caller name, falling back to `coming_soon` only when Telnyx is not configured. Mirrors the Twilio Lookup v2 add-on selector.

<ParamField path="phoneNumber" type="string" required>
  Phone number in E.164 format. URL-encode the leading `+` (or use `%2B`). The route also accepts an unencoded `+` for back-compat — decodeURIComponent runs server-side.
</ParamField>

<ParamField query="fields" type="string">
  Optional Twilio-compat data-package selector. Comma-separated list of field names from the enumeration below (case-insensitive, deduped server-side, max 16 fields per request). Unknown field names reject the whole request with 422.
</ParamField>

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/lookup/{phoneNumber}" \
      -H "X-API-Key: dv_live_sk_your_key_here" 
    ```

    ```typescript Node.js theme={null}
    import { Orbit } from '@devotel/orbit-sdk'

    const orbit = new Orbit({
      apiKey: process.env.ORBIT_API_KEY!,
    })

    const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/lookup/{phoneNumber}', {
      method: 'GET',
      headers: {
        'X-API-Key': process.env.ORBIT_API_KEY!,
      },
    })
    console.log(await res.json())


    ```

    ```python Python theme={null}
    import os, requests

    headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
    r = requests.get("https://api.orbit.devotel.io/api/v1/numbers/lookup/{phoneNumber}", headers=headers)
    print(r.json())
    ```

    ```go Go theme={null}
    package main

    import (
    	"bytes"
    	"net/http"
    	"os"
    )

    func main() {
    	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/numbers/lookup/{phoneNumber}", nil)
    	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

    	http.DefaultClient.Do(req)
    }
    ```

    ```ruby Ruby theme={null}
    require 'net/http'
    require 'json'

    uri = URI('https://api.orbit.devotel.io/api/v1/numbers/lookup/{phoneNumber}')
    req = Net::HTTP::Get.new(uri)
    req['X-API-Key'] = ENV['ORBIT_API_KEY']


    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    puts res.body
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init('https://api.orbit.devotel.io/api/v1/numbers/lookup/{phoneNumber}');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-API-Key: ' . getenv('ORBIT_API_KEY'),

    ]);

    echo curl_exec($ch);
    ```
  </CodeGroup>
</RequestExample>

***