curl --request POST \
--url https://api.orbit.devotel.io/api/v1/numbers/hlr-lookup \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"numbers": [
"+14155550100",
"+442071838750"
]
}
'import requests
url = "https://api.orbit.devotel.io/api/v1/numbers/hlr-lookup"
payload = { "numbers": ["+14155550100", "+442071838750"] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({numbers: ['+14155550100', '+442071838750']})
};
fetch('https://api.orbit.devotel.io/api/v1/numbers/hlr-lookup', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.orbit.devotel.io/api/v1/numbers/hlr-lookup",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'numbers' => [
'+14155550100',
'+442071838750'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.orbit.devotel.io/api/v1/numbers/hlr-lookup"
payload := strings.NewReader("{\n \"numbers\": [\n \"+14155550100\",\n \"+442071838750\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.orbit.devotel.io/api/v1/numbers/hlr-lookup")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"numbers\": [\n \"+14155550100\",\n \"+442071838750\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.orbit.devotel.io/api/v1/numbers/hlr-lookup")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"numbers\": [\n \"+14155550100\",\n \"+442071838750\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"results": [
{
"number": "14155550100",
"valid": true,
"present": "yes",
"present_label": "Live on network",
"type": "mobile",
"network": "Verizon",
"ported": false,
"mcc": "310",
"mnc": "004",
"cached": false,
"status": 0,
"error_code": 0,
"note": null
}
],
"total": 1,
"charged_count": 1,
"charged_cents": 1
},
"meta": {
"request_id": "req_01J9Z8ABCDEF",
"timestamp": "2026-09-27T12:00:00.000Z"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "<string>",
"status": 429,
"retry_after": 2
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}Paid HLR lookup for up to 3 numbers
Run a paid HLR (Home Location Register) lookup on 1–3 E.164 phone numbers, returning per-number live status (present: yes / no / na), home-network operator (network), line type, ported, and mcc/mnc identification. Wallet balance is pre-checked for the whole batch before any provider call is made; only successfully-resolved rows are billed — upstream timeouts, auth failures, rate limiting, and server errors are never charged. Valid partial states (error codes 191 / 192 / 193, present: "na") are returned as labelled results, not errors. The endpoint is feature-flagged per workspace (feature_hlr_lookup) and priced from the admin-configured hlr rate — an unpriced workspace is rejected before any provider call. Scoped on the numbers resource (numbers:read or numbers:write).
curl --request POST \
--url https://api.orbit.devotel.io/api/v1/numbers/hlr-lookup \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"numbers": [
"+14155550100",
"+442071838750"
]
}
'import requests
url = "https://api.orbit.devotel.io/api/v1/numbers/hlr-lookup"
payload = { "numbers": ["+14155550100", "+442071838750"] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({numbers: ['+14155550100', '+442071838750']})
};
fetch('https://api.orbit.devotel.io/api/v1/numbers/hlr-lookup', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.orbit.devotel.io/api/v1/numbers/hlr-lookup",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'numbers' => [
'+14155550100',
'+442071838750'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.orbit.devotel.io/api/v1/numbers/hlr-lookup"
payload := strings.NewReader("{\n \"numbers\": [\n \"+14155550100\",\n \"+442071838750\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.orbit.devotel.io/api/v1/numbers/hlr-lookup")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"numbers\": [\n \"+14155550100\",\n \"+442071838750\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.orbit.devotel.io/api/v1/numbers/hlr-lookup")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"numbers\": [\n \"+14155550100\",\n \"+442071838750\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"results": [
{
"number": "14155550100",
"valid": true,
"present": "yes",
"present_label": "Live on network",
"type": "mobile",
"network": "Verizon",
"ported": false,
"mcc": "310",
"mnc": "004",
"cached": false,
"status": 0,
"error_code": 0,
"note": null
}
],
"total": 1,
"charged_count": 1,
"charged_cents": 1
},
"meta": {
"request_id": "req_01J9Z8ABCDEF",
"timestamp": "2026-09-27T12:00:00.000Z"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "<string>",
"status": 429,
"retry_after": 2
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}Authorizations
Dashboard JWT token from Clerk
Headers
Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.
1 - 255Sandbox opt-in for Clerk-session-authenticated requests — see Test mode explained for the full credential-header matrix and worked samples. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
true, false Body
The batch of E.164 numbers to look up (1–3).
The batch of E.164 numbers to look up (1–3).
The phone numbers to look up, 1–3 per request (capped to bound cost and latency).
E.164 phone number (e.g. +14155550100).
Response
Per-number HLR results with batch totals. charged_count / charged_cents report how many rows were billed to the wallet.