Languages: every operation supports cURL, Node.js (TypeScript), Python, Go, Ruby, and PHP. The first 15 operations on this page show all six languages; the remaining 99 show cURL and TypeScript — the two most-used.

Numbers API

Numbers endpoints exposed by the Devotel CPaaS API Base path: /api/v1/numbers Endpoint count: 114

Worked sequences

The endpoint list below documents each operation with its parameters, but the two flows that integrate against this surface — renting a number and porting one in — span several calls, and their response bodies are what you branch on. These two sequences show every call in order with the body each one returns.

Sequence 1 — rent a number

Go from inventory search to an active, capability-checked number in three calls. Step 1 — search inventory. Filter by country, line type, capability, and area code. Each result carries the per-number capability list and monthly price, so you can filter before you buy.

curl "https://api.orbit.devotel.io/api/v1/numbers/available?country=US&type=local&capabilities=sms,voice&area_code=415&limit=5" \
  -H "X-API-Key: dv_live_sk_your_key_here"

200

{
  "data": [
    {
      "number": "+14155550100",
      "country": "US",
      "type": "local",
      "region": "California",
      "capabilities": ["sms", "voice", "mms"],
      "monthly_cost": "1.50",
      "currency": "USD"
    },
    {
      "number": "+14155550101",
      "country": "US",
      "type": "local",
      "region": "California",
      "capabilities": ["sms", "voice", "mms"],
      "monthly_cost": "1.50",
      "currency": "USD"
    }
  ],
  "meta": {
    "request_id": "req_num_001",
    "timestamp": "2026-08-27T12:00:00Z"
  }
}

For a regulated country (most of the EU/EEA, GB, and several others), run GET /api/v1/numbers/regulatory-preview?country… before this step — it returns the documents and data fields the carrier requires, and whether a compliance profile you already hold satisfies them.

Step 2 — purchase the number. Submit the E.164 you picked. The 201 body returns the owned-number record — save the id, because every follow-up operation (configure, suspend, release) addresses the number by it. Billing starts immediately.

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/purchase \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155550100",
    "country_code": "US",
    "capabilities": ["sms", "voice"]
  }'

201

{
  "data": {
    "id": "num_abc123",
    "number": "+14155550100",
    "country": "US",
    "type": "local",
    "capabilities": ["sms", "voice", "mms"],
    "status": "active",
    "monthly_cost": "1.50",
    "currency": "USD",
    "created_at": "2026-08-27T12:00:00Z"
  },
  "meta": {
    "request_id": "req_num_002",
    "timestamp": "2026-08-27T12:00:00Z"
  }
}

Step 3 — verify the provisioned number. Read the number back by its id to confirm it is active and that the capabilities you ordered are the ones the carrier actually provisioned — a regulated country can hold the number at pending_compliance until the required documents clear.

curl https://api.orbit.devotel.io/api/v1/numbers/num_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here"

200

{
  "data": {
    "id": "num_abc123",
    "number": "+14155550100",
    "country": "US",
    "type": "local",
    "label": "Support line",
    "capabilities": ["sms", "voice", "mms"],
    "status": "active",
    "liveness": "healthy",
    "monthly_cost": "1.50",
    "currency": "USD",
    "created_at": "2026-08-27T12:00:00Z"
  },
  "meta": {
    "request_id": "req_num_003",
    "timestamp": "2026-08-27T12:00:00Z"
  }
}

Sequence 2 — port a number in

Move an existing number from a losing carrier onto the platform. A full port runs eligibility check → LOA upload → submit → poll status; the check step is optional but cheap, and it turns a multi-day carrier rejection into an instant answer. Step 1 — check eligibility (recommended). Run a live pre-flight against the losing carrier’s database. The response tells you in seconds whether the number can port; US and Canadian numbers are checked live, other countries return check-not-supported and proceed straight to submission.

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting/check \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+14155551234", "currentCarrier": "Acme Telecom" }'

200

{
  "data": {
    "phoneNumber": "+14155551234",
    "check_status": "portable",
    "carrier": "Acme Telecom"
  },
  "meta": {
    "request_id": "req_port_check_001",
    "timestamp": "2026-08-27T12:00:00Z"
  }
}

Step 2 — submit the port-in request. Send the numbers, the losing carrier, and the account details the carrier will verify. The 201 body returns the request id and the starting status — porting requests move submitted → reviewing → approved → completed, with rejected as the carrier-declined terminal state. Branch on these values; there is no pending state.

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["+14155551234"],
    "currentCarrier": "Acme Telecom",
    "authorizedSigner": "John Doe",
    "accountNumber": "ACC-12345",
    "accountPin": "4821",
    "country": "US",
    "contactEmail": "ops@example.com"
  }'

201

{
  "data": {
    "id": "port_abc123",
    "numbers": ["+14155551234"],
    "status": "submitted",
    "submittedAt": "2026-08-27T12:00:00Z"
  },
  "meta": {
    "request_id": "req_port_001",
    "timestamp": "2026-08-27T12:00:00Z"
  }
}

Step 3 — poll status until complete. Read the request’s status timeline; each stage transition appends an entry with the stage name and a recommendedAction when the port is waiting on you (for example, a supplement on a rejection). Porting typically takes 7–14 business days depending on the country and carrier — subscribe to the number.ported webhook instead of polling once you are past submission.

curl https://api.orbit.devotel.io/api/v1/numbers/porting/port_abc123/timeline \
  -H "X-API-Key: dv_live_sk_your_key_here"

200

{
  "data": {
    "id": "port_abc123",
    "status": "approved",
    "timeline": [
      {
        "stage": "submitted",
        "at": "2026-08-27T12:00:00Z"
      },
      {
        "stage": "validating_loa",
        "at": "2026-08-27T14:20:00Z"
      },
      {
        "stage": "carrier_review",
        "at": "2026-08-28T09:05:00Z"
      },
      {
        "stage": "foc_scheduled",
        "at": "2026-08-30T11:00:00Z",
        "focDate": "2026-09-03",
        "recommendedAction": "none"
      }
    ]
  },
  "meta": {
    "request_id": "req_port_timeline_001",
    "timestamp": "2026-09-01T12:00:00Z"
  }
}

When the timeline reaches completed, the numbers appear in your GET /api/v1/numbers/ inventory as active.

Error samples

Two purchase-time rejections account for most failed buys; both return the standard error envelope with a stable code you can branch on. Regulated country without a compliance profile — buying a number in a country that requires verified end-user documents before the carrier will activate it:

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/purchase \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+4915123456789", "country_code": "DE", "capabilities": ["sms","voice"] }'

422

{
  "error": {
    "code": "COMPLIANCE_PROFILE_REQUIRED",
    "status": 422,
    "message": "DE is a regulated country — the carrier won't activate a number without an approved compliance profile. Create / approve a profile that covers DE in Settings → Compliance, then retry the purchase. No wallet debit was attempted.",
    "details": { "country": "DE" }
  },
  "meta": {
    "request_id": "req_num_004",
    "timestamp": "2026-08-27T12:01:00Z"
  }
}

Fix it by creating and approving a compliance profile that covers the country (under Settings → Compliance in the dashboard), then passing its id as compliance_profile_id on the retry. No billing happens on this rejection — your balance is untouched. Number already owned — the number sold between your search and your purchase, or is already on an account:

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/purchase \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155550100", "country_code": "US" }'

409

{
  "error": {
    "code": "NUMBER_ALREADY_TAKEN",
    "status": 409,
    "message": "This number was just reserved by another user. Please select a different number.",
    "details": { "phone_number": "+1415****" }
  },
  "meta": {
    "request_id": "req_num_005",
    "timestamp": "2026-08-27T12:02:00Z"
  }
}

Fix it by re-running the search and submitting another candidate. Search results are live inventory, not holds — treat a purchase attempt as a claim race and retry with the next match.

List phone numbers

GET /api/v1/numbers/

List the organization’s owned phone numbers (DIDs), newest first, with keyset pagination. Filter by lifecycle status, a free-text search over the E.164 number and label, or one or more tags; each row is enriched with a passively-derived liveness state so the inventory table can flag numbers that have stopped receiving inbound traffic. Pass ?fields=id,phone_number,status for a slim projection suited to lightweight sender-id pickers. Org-scoped and read-only.

string

Filter by lifecycle status (e.g. active, pending_compliance, released, suspended).

string

Free-text match against the E.164 number and label.

string

Comma-separated tag slugs; a row matching any supplied tag is returned.

integer

Page size, most-recent first. Clamped server-side to the max page size.

string

Opaque keyset cursor from the previous page’s meta.pagination.cursor.

string

Optional comma-separated slim projection (e.g. id,phone_number,status).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

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

package main

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

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

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/numbers/')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/numbers/');
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);

"string"

Get a phone number

GET /api/v1/numbers/{id}

Fetch a single owned DID by id, including its capabilities, routing configuration (inbound webhook / forwarding number), attached compliance profile, monthly cost, and the per-DID STIR/SHAKEN attestation level the wholesale softswitch signs its outbound calls at. Org-ownership is enforced — an unknown or not-owned id returns 404 with no cross-tenant existence leak.

string

required

The phone number record id.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

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

package main

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

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

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/numbers/{id}')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/numbers/{id}');
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);

{
  "data": "string",
  "meta": "string"
}

Get per-DID branded-calling (Rich Call Data) answer-rate uplift

GET /api/v1/numbers/{id}/branded-calling-analytics

Per-DID branded-calling / Rich Call Data (RCD) answer-rate uplift readout. Compares this number’s OUTBOUND answer rate over the requested window against the immediately-preceding equal-length baseline window, and surfaces the org’s branded-calling registration status alongside, so a customer who registered a brand profile can see the contact-center answer-rate lift branded calling produces (Twilio / First-Orion parity). Pure read on call_logs plus the org’s branded-calling setting — no carrier round-trip. Org-ownership gated: a sibling subaccount sharing the tenant schema gets 404 on another subaccount’s DID id (enumeration-safe). Answer rates are 0..1 fractions and are null when no outbound calls were placed in the cohort; uplift values are null when a comparable baseline rate is undefined (no misleading 0% lift).

string

required

—

string (enum: 24h|7d|30d|90d)

Comparison window length. The baseline is the equal-length window immediately preceding it, so the effective scan is 2× the token span. Defaults to 30d.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/branded-calling-analytics" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

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

package main

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

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

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/numbers/{id}/branded-calling-analytics')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/numbers/{id}/branded-calling-analytics');
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);

{
  "data": {
    "phone_number_id": "string",
    "phone_number": "string",
    "window": "24h",
    "current_window": {
      "start": "1970-01-01T00:00:00.000Z",
      "end": "1970-01-01T00:00:00.000Z"
    },
    "baseline_window": {
      "start": "1970-01-01T00:00:00.000Z",
      "end": "1970-01-01T00:00:00.000Z"
    },
    "branded_calling": {
      "enabled": false,
      "display_name": "string",
      "registered_with_carriers": [
        "string"
      ]
    },
    "outbound": {
      "current": {
        "total": 0,
        "answered": 0,
        "answer_rate": 0
      },
      "baseline": {
        "total": 0,
        "answered": 0,
        "answer_rate": 0
      },
      "uplift": {
        "absolute_points": 0,
        "relative_pct": 0
      }
    }
  },
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Get a number’s 10DLC campaign assignment

GET /api/v1/numbers/{id}/campaign-assignment

Read the 10DLC A2P brand/campaign a DID is tied to for US carrier throughput segregation, or null when the number is not assigned. Org-ownership is enforced; read-only companion to the PUT/DELETE campaign-assignment writes.

string

required

The phone number record id.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/campaign-assignment" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

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

package main

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

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

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/numbers/{id}/campaign-assignment')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/numbers/{id}/campaign-assignment');
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);

{
  "data": {
    "id": "string",
    "assignment": "string"
  },
  "meta": "string"
}

Get a number’s CNAM registration

GET /api/v1/numbers/{id}/cnam

Read the branded outbound Caller-Name (CNAM) currently registered for a DID — the display name shown on the recipient handset — or null when none is set. Org-ownership is enforced; read-only. To register or change a name use the PUT verb on this path.

string

required

The phone number record id.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/cnam" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

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

package main

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

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

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/numbers/{id}/cnam')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/numbers/{id}/cnam');
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);

{
  "data": {
    "id": "string",
    "cnam": "string"
  },
  "meta": "string"
}

List regulatory documents for a number

GET /api/v1/numbers/{id}/documents

Return every regulatory / KYC document requirement raised by the number’s provider (identity, address proof, business registration) with its current review status, rejection reason, and uploaded-file metadata. Use it to render the compliance checklist for a provisioned number and see which requirements still block activation.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/documents" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

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

package main

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

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

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/numbers/{id}/documents')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/numbers/{id}/documents');
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);

{
  "data": [
    {
      "id": "string",
      "phone_number_id": "string",
      "requirement_type": "string",
      "requirement_label": "string",
      "description": "string",
      "status": "string",
      "rejection_reason": "string",
      "file_url": "string",
      "file_name": "string"
    }
  ],
  "meta": "string"
}

Get the emergency (E911) address for a number

GET /api/v1/numbers/{id}/emergency-address

Read the E911 dispatchable civic address registered against a number, including its lifecycle status (registered, valid, invalid, or dispatchable) and any provider PSAP/MSAG confirmation. Returns a null address when none has been registered yet.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/emergency-address" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

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

package main

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

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

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/numbers/{id}/emergency-address')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/numbers/{id}/emergency-address');
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);

{
  "data": {
    "id": "string",
    "address": "string"
  },
  "meta": "string"
}

Get the deliverability health score for a number

GET /api/v1/numbers/{id}/health

Per-DID deliverability health: a score, tier, last-computed timestamp, and a contributing-factor breakdown from the daily number-health-score job (read-only, no live re-compute). Use it to spot numbers with degrading delivery or rising complaint rates before they affect campaigns. Returns a null score until the job has enough sample data.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/health" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

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

package main

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

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

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/numbers/{id}/health')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/numbers/{id}/health');
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);

{
  "data": {
    "phone_number_id": "string",
    "phone_number": "string",
    "score": 0,
    "tier": "string",
    "last_computed_at": "1970-01-01T00:00:00.000Z",
    "breakdown": {},
    "lookback_days": 0,
    "min_sample_size": 0
  },
  "meta": "string"
}

Get the deliverability health trend and forecast for a number

GET /api/v1/numbers/{id}/health/trend

Per-DID predictive deliverability trajectory: a per-period score series, trend direction and slope, a linear forecast at a configurable horizon, and a step-change anomaly flag (read-only, live bucketed scan over locally-stored message rows). Periods below the sample-size floor return score: null, tier: "unknown" and are excluded from the trend fit. Distinct from /api/v1/numbers//health, which serves the daily point-in-time snapshot.

string

required

—

string (enum: 30d|60d|90d)

Lookback window

string (enum: day|week)

Period granularity of the score series

integer

Forecast horizon in days

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/health/trend" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

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

package main

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

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

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/numbers/{id}/health/trend')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/numbers/{id}/health/trend');
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);

{
  "data": {
    "phone_number_id": "string",
    "phone_number": "string",
    "window": "30d",
    "bucket": "day",
    "window_start": "1970-01-01T00:00:00.000Z",
    "window_end": "1970-01-01T00:00:00.000Z",
    "lookback_days": 0,
    "min_sample_size": 0,
    "points": [
      {
        "period_start": "1970-01-01T00:00:00.000Z",
        "period_end": "1970-01-01T00:00:00.000Z",
        "score": 0,
        "tier": "string",
        "sample_size": 0
      }
    ],
    "scored_periods": 0,
    "direction": "string",
    "slope_per_day": 0,
    "forecast": {
      "horizon_days": 0,
      "projected_score": 0,
      "projected_tier": "string",
      "slope_per_day": 0
    },
    "anomaly": {
      "detected": false,
      "latest_score": 0,
      "baseline_mean": 0,
      "deviation": 0
    }
  },
  "meta": "string"
}

Get port-out PIN protection status for a number

GET /api/v1/numbers/{id}/port-out-protection

Report whether port-out PIN protection is enabled on a number and when it was last set. The PIN value is never returned — only the on/off status and set-at timestamp are observable — so you can show the protection state without exposing the secret.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/port-out-protection" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

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

package main

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

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

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/numbers/{id}/port-out-protection')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/numbers/{id}/port-out-protection');
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);

{
  "data": {
    "enabled": false,
    "set_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

Get a Mexican number’s active telecom regulator

GET /api/v1/numbers/{id}/regulator

Read which regulator currently owns a Mexican (MX) number’s carrier-side onboarding requirements during the IFT → CRT telecom-regulator transition. Returns IFT (the default until a number is migrated) or CRT once an operator confirms the transition is live for their inventory; non-MX numbers return null. Org-ownership is enforced per call so a sibling sub-org sharing the tenant schema cannot read another sub-org’s regulator state. Read-only; scoped on numbers:read.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/regulator" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

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

package main

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

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

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/numbers/{id}/regulator')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/numbers/{id}/regulator');
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);

{
  "data": {
    "id": "string",
    "regulator": "IFT"
  },
  "meta": "string"
}

Get the carrier spam-label reputation for a number

GET /api/v1/numbers/{id}/reputation

Per-DID carrier spam-label reputation: how the carrier-analytics ecosystem (Hiya, TNS, First Orion, Free Caller Registry, Nomorobo) labels this tenant’s own outbound number, plus a registration / dispute remediation plan to clear a false “Spam Likely” or “Scam Likely” tag. Returns monitored: false / status: "unknown" until at least one provider observation has been recorded for the number. Distinct from /api/v1/numbers//health, which scores internal deliverability rather than the carrier-displayed label.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/reputation" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

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

package main

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

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

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/numbers/{id}/reputation')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/numbers/{id}/reputation');
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);

{
  "data": {
    "phone_number_id": "string",
    "phone_number": "string",
    "monitored": false,
    "status": "clear",
    "worst_label": "clear",
    "providers": [
      "string"
    ],
    "observations": [
      {
        "provider": "string",
        "label": "string",
        "rawLabel": "string",
        "observedAt": "string"
      }
    ],
    "remediation": [
      {
        "provider": "string",
        "provider_name": "string",
        "type": "register",
        "reason": "string",
        "url": "string"
      }
    ],
    "last_checked_at": "string"
  },
  "meta": "string"
}

Get the scheduled release for a number

GET /api/v1/numbers/{id}/scheduled-release

Read the pending future auto-release scheduled on a tenant-owned DID (Twilio / Bandwidth release_on parity). Returns scheduled_release: null when no release is scheduled. Org-ownership is enforced per call so a sibling sub-org sharing the tenant schema cannot read another sub-org’s schedule. Read-only; scoped on numbers:read.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/scheduled-release" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

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

package main

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

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

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/numbers/{id}/scheduled-release')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/numbers/{id}/scheduled-release');
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);

{
  "data": {
    "id": "string",
    "scheduled_release": "string"
  },
  "meta": "string"
}

Get SMS spam-complaint feedback loop for a number

GET /api/v1/numbers/{id}/sms-complaints

Per-DID SMS complaint rate, threshold level, and suppression hold (read-only).

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/sms-complaints" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

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

package main

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

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

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/numbers/{id}/sms-complaints')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/numbers/{id}/sms-complaints');
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);

{
  "data": {},
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Get the predictive spam-likelihood score for a number

GET /api/v1/numbers/{id}/spam-likelihood

Per-DID forward-looking spam-likelihood: a 0-100 score mapped to low / moderate / high / severe, a contributing-factor breakdown (failure rate, complaint rate, health-trend direction, anomaly) whose components sum to the score, and an ordered remediation playbook to act on before the carrier ecosystem publishes a spam label. A window with too little signal returns spam_likelihood_score: null with label unknown rather than a noisy small-sample number. Read-only over locally-stored rows.

string

required

—

string (enum: 7d|14d|30d)

Lookback window folded into the score

integer

Forecast horizon forwarded to the health-trend input

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/spam-likelihood" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

Python

import os, requests

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

package main

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

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

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/numbers/{id}/spam-likelihood')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/numbers/{id}/spam-likelihood');
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);

{
  "data": {
    "phone_number_id": "string",
    "phone_number": "string",
    "window": "7d",
    "window_start": "1970-01-01T00:00:00.000Z",
    "window_end": "1970-01-01T00:00:00.000Z",
    "spam_likelihood": {
      "spam_likelihood_score": 0,
      "spam_likelihood_label": "low",
      "contributing_factors": {
        "failure_rate": 0,
        "complaint_rate": 0,
        "trend": "string",
        "anomaly_detected": false,
        "failure_component": 0,
        "complaint_component": 0,
        "trend_component": 0,
        "anomaly_component": 0
      },
      "remediation_playbook": [
        {
          "step": 0,
          "action": "string",
          "guidance": "string"
        }
      ]
    },
    "trend": {
      "scored_periods": 0,
      "direction": "string"
    },
    "min_sample_size": 0
  },
  "meta": "string"
}

Get a toll-free number’s verification (TFV) status

GET /api/v1/numbers/{id}/tfv

Read the Toll-Free Verification (TFV) state for a single toll-free DID: the current status (not_submitted | pending | approved | rejected), submission and approval timestamps, any rejection reason, the submitted use case and sample messages, the carrier and provider submission id, the mandated business-identity fields (EIN / business registration number + country), and when the platform last observed a vendor update. Use it to render a DID’s verification card and pre-fill a resubmit. Org-ownership is enforced per call so a sibling sub-org sharing the tenant schema cannot read another org’s TFV identity attestation. Read-only; scoped on numbers:read.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "phoneNumberId": "string",
    "phoneNumber": "string",
    "numberType": "string",
    "tfvStatus": "not_submitted",
    "tfvSubmittedAt": "1970-01-01T00:00:00.000Z",
    "tfvApprovedAt": "1970-01-01T00:00:00.000Z",
    "tfvRejectionReason": "string",
    "tfvUseCase": "string",
    "tfvSampleMessages": [
      "string"
    ],
    "tfvProvider": "string",
    "tfvProviderSubmissionId": "string",
    "tfvEin": "string",
    "tfvBusinessRegistrationNumber": "string",
    "tfvBusinessRegistrationCountry": "string",
    "tfvLastVendorUpdate": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

Get per-number call and message usage

GET /api/v1/numbers/{id}/usage-analytics

Per-DID usage rollup over a configurable window — inbound / outbound / answered call counts with total and average duration, plus inbound / outbound / delivered / failed message counts and total segments — so operators managing large inventories can spot underused release candidates and over-pressured throttle candidates. Read-only aggregate over locally-stored call and message rows (no carrier round-trip). Org-ownership is enforced per call so a sibling sub-org sharing the tenant schema cannot read another org’s usage. Scoped on numbers:read.

string

required

—

string (enum: 24h|7d|30d|90d)

Rollup window length. Defaults to 30d.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/usage-analytics" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "phone_number_id": "string",
    "phone_number": "string",
    "window": "24h",
    "window_start": "1970-01-01T00:00:00.000Z",
    "window_end": "1970-01-01T00:00:00.000Z",
    "calls": {
      "inbound": 0,
      "outbound": 0,
      "answered": 0,
      "total_duration_seconds": 0,
      "avg_duration_seconds": 0
    },
    "messages": {
      "inbound": 0,
      "outbound": 0,
      "delivered": 0,
      "failed": 0,
      "total_segments": 0
    }
  },
  "meta": "string"
}

Get the 10DLC warming-tier state for a number

GET /api/v1/numbers/{id}/warming

Per-DID 10DLC warming state used to render the number’s ramp meter: the current daily_cap, the live current_day_count (read from Redis, not the once-a-day mirrored column), the warming_phase (initial | ramp | steady | verified), the trust_score, and when warming started. Returns null for non-10DLC numbers. Org-ownership is enforced per call so a sibling sub-org sharing the tenant schema cannot read another org’s warming state. Read-only; scoped on numbers:read.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/warming" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "phone_number_id": "string",
    "phone_number": "string",
    "trust_score": 0,
    "daily_cap": 0,
    "current_day_count": 0,
    "current_day_window_start": "1970-01-01T00:00:00.000Z",
    "warming_started_at": "1970-01-01T00:00:00.000Z",
    "warming_phase": "initial",
    "last_phase_advance_at": "1970-01-01T00:00:00.000Z",
    "days_warmed": 0
  },
  "meta": "string"
}

Get the number-warming progression forecast

GET /api/v1/numbers/{id}/warming/progression

Per-DID SMS warming progression for the FE growth chart: the warming_state (off | warming | warmed), when warming started, the configured warming_max_daily_sms ceiling, the live current_day_count, how many days the number has been warming, and a 15-day forecast of the daily-ceiling growth curve (day 0 through day 14). Distinct from the 10DLC warming-tier endpoint — this one drives the projection line. Org-ownership is enforced per call so a sibling sub-org sharing the tenant schema cannot read another org’s progression. Read-only; scoped on numbers:read.

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/{id}/warming/progression" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "phone_number_id": "string",
    "phone_number": "string",
    "warming_state": "off",
    "warming_started_at": "1970-01-01T00:00:00.000Z",
    "warming_max_daily_sms": 0,
    "current_day_count": 0,
    "days_warmed": 0,
    "forecast": [
      {
        "day": 0,
        "ceiling": 0
      }
    ]
  },
  "meta": "string"
}

List number applications

GET /api/v1/numbers/applications

List every number application (Twilio “Application” parity) for the organization. Each application is a reusable inbound-routing + ownership binding target for DIDs. Org-scoped — a sibling sub-account never sees another organization’s applications. Inbound routing only.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/applications" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": [
    "string"
  ],
  "meta": "string"
}

Fetch one number application

GET /api/v1/numbers/applications/{id}

Fetch a single number application by id, including its inbound-routing config and the DIDs currently bound to it. Org-scoped — an unknown or not-owned id returns 404 (no exists-but-not-yours enumeration leak).

string

required

Number-application id.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/applications/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": "string",
  "meta": "string"
}

Get a bulk reservation’s status and items

GET /api/v1/numbers/bulk-reserve/{id}

Fetch the current state of a bulk number reservation and its held items — status, requested-versus-reserved counts, cost, the 15-minute expires_at, and the per-item picks. Poll this while deciding whether to finalize or cancel; the row is inline-expired (status expired) once its hold window passes. Org-scoped — a reservation belonging to a sibling subaccount or an unknown id returns 404. Read-only; requires the numbers:read scope.

string

required

Reservation id returned by POST /numbers/bulk-reserve.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/bulk-reserve/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": "string",
  "meta": "string"
}

Fleet rollup across the SIM estate

GET /api/v1/numbers/connectivity/fleets

Roll the org’s SIMs up into fleets (grouped by fleetId, with SIMs that carry none collapsed under ungrouped).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/connectivity/fleets" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "fleets": [
      "string"
    ],
    "count": 0
  },
  "meta": "string"
}

List eSIM / IoT connectivity data-plans

GET /api/v1/numbers/connectivity/plans

Browse the read-only eSIM / IoT (M2M) data-plan catalog. Plans are DATA-ONLY (invariant #45) — every plan pins voice:false/sms:false; outbound MT voice/SMS exit only via the Devotel softswitch, never a cellular bearer.

string

Optional ISO 3166-1 alpha-2 coverage filter (case-insensitive).

string (enum: esim|iot-sim)

Optional SIM form-factor filter.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/connectivity/plans" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "plans": [
      "string"
    ],
    "count": 0
  },
  "meta": "string"
}

Fetch one connectivity plan

GET /api/v1/numbers/connectivity/plans/{id}

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/connectivity/plans/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "plan": "string"
  },
  "meta": "string"
}

Estimate connectivity plan usage cost

GET /api/v1/numbers/connectivity/plans/{id}/cost-estimate

Pure, side-effect-free cost estimate (whole cents, usage rounded to the nearest cent plus the monthly platform fee). Descriptive only — it neither moves money nor touches billing state.

string

required

—

number

Data volume in megabytes; non-positive / non-finite clamps to fee-only.

string

Optional coverage check — does the plan cover this country?

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/connectivity/plans/{id}/cost-estimate" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "plan_id": "string",
    "megabytes": 0,
    "estimated_cost_cents": 0,
    "covered": false
  },
  "meta": "string"
}

List provisioned SIMs

GET /api/v1/numbers/connectivity/sims

List the org’s provisioned eSIM / IoT SIMs, with optional filters.

string (enum: ordered|active|suspended|terminated)

—

string

—

string

—

string (enum: esim|iot-sim)

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "sims": [
      "string"
    ],
    "count": 0
  },
  "meta": "string"
}

Fetch one provisioned SIM

GET /api/v1/numbers/connectivity/sims/{iccid}

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims/{iccid}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": "string",
  "meta": "string"
}

Get SIM usage and recent sessions

GET /api/v1/numbers/connectivity/sims/{iccid}/usage

string

required

—

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims/{iccid}/usage" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "iccid": "string",
    "plan_id": "string",
    "state": "ordered",
    "usage_bytes": 0,
    "sessions": [
      "string"
    ]
  },
  "meta": "string"
}

Get available-number capabilities for a country

GET /api/v1/numbers/country-capabilities

Return a per-(line type × capability) inventory summary for one country so the buy-numbers picker can show real stock — how many mobile, local, and toll-free numbers are available, and which support SMS versus voice — before a search is run. Surfaces two_way_sms (send-and-receive only), a separate send-only toll_free_sms count, and a US-only local_sms_via_10dlc count so shoppers are not steered to a dead end (e.g. UK locals carry voice but not SMS). Counts are clamped at 100 (rendered “100+”) and cached for about five minutes. Read-only; requires the numbers:read scope.

string

required

ISO 3166-1 alpha-2 country code (e.g. GB, US).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/country-capabilities" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "country": "GB",
    "summary": {
      "mobile_sms": 100,
      "mobile_voice": 100,
      "local_sms": 0,
      "local_voice": 100,
      "toll_free": 42,
      "toll_free_sms": 0
    },
    "two_way_sms": 100,
    "us_uses_10dlc": false,
    "last_updated": "2026-08-11T12:00:00Z"
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-11T12:00:00Z"
  }
}

List dormant DID release candidates

GET /api/v1/numbers/dormancy-alerts

Org-scoped list of owned DIDs with no inbound/outbound calls or SMS for the dormancy window (default 30 days; override on the org or preview via ?days=). Each row carries the reclaimable monthly spend and a suggested_release flag so the dashboard can drive silent-number cost trimming. Companion read surface to the number.dormant webhook. Read-only; scoped on numbers:read.

string

Optional dormancy window override (integer 1–365). When omitted, the per-tenant org setting (or the platform default of 30) is used.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/dormancy-alerts" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {},
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Export the number inventory as CSV or JSON

GET /api/v1/numbers/export

Download the organization’s full owned-DID inventory as a single CSV (default) or JSON file for finance reconciliation and bulk auditing — the same rows the dashboard Numbers list shows, plus a trailing-30-day realised spend column per number. Use it to reconcile the monthly DID line without paging the list API. Filter with status, country_code, and search; CSV timestamps localise to the tz/locale you pass. Capped at 50,000 rows, with the X-Truncated header set when a larger inventory is truncated. Read-only; requires the numbers:read scope. Inbound DID provisioning only (invariant #45 untouched).

string (enum: csv|json)

Output format — a CSV attachment (default) or a JSON array.

string

Status filter (e.g. active); defaults to all so released/parked-but-still-billable rows are included.

string

ISO 3166-1 alpha-2 country filter.

string

Free-text match on the phone number or label.

string

IANA timezone for CSV timestamp columns (e.g. Europe/Istanbul); JSON stays canonical UTC.

string

BCP-47 locale for CSV date formatting (defaults to en-US).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/export" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

[
  {
    "msisdn": "+14155550100",
    "country_code": "US",
    "status": "active",
    "number_type": "local",
    "capabilities": "sms,voice",
    "monthly_cost": 1,
    "spend_30d": 3.45
  }
]

List hosted-messaging orders

GET /api/v1/numbers/hosted-messaging

List every hosted-messaging (“text-enable”) order for the authenticated organization. Use this to review the status of landline, toll-free, or mobile numbers whose inbound SMS is being enabled while their voice service stays with another carrier. Each order carries its lifecycle status (draft, loa_signed, submitted, active, rejected, cancelled), the number, the voice carrier of record, and the inbound-SMS route. Read-only; requires the numbers:read scope.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": [
    "string"
  ],
  "meta": "string"
}

Get a hosted-messaging order

GET /api/v1/numbers/hosted-messaging/{id}

Fetch a single hosted-messaging order by id, including its current lifecycle status, the number being text-enabled, the voice carrier of record, the inbound-SMS route, and any LOA signature details. Returns 404 when no order with that id exists for the organization. Read-only; requires the numbers:read scope.

string

required

Hosted-messaging order id.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": "string",
  "meta": "string"
}

List low-stock DID inventory alerts

GET /api/v1/numbers/inventory-alerts

Return live low-stock alerts for the organization’s owned DID inventory, grouped by (country_code, area_code_prefix). One alert row is emitted per bucket whose available count is below the tenant’s configured threshold (default 3; override on the org settings), so the dashboard can warn before a pool runs dry. Rows are sorted worst-first and capped by limit. Read-only; requires the numbers:read scope.

integer

Maximum number of worst-first alert buckets to return (top-N readout for the banner). Defaults to the platform default when omitted or invalid.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/inventory-alerts" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "alerts": [
      {
        "country_code": "string",
        "area_code_prefix": "string",
        "available_count": 0,
        "threshold": 0,
        "raised_at": "1970-01-01T00:00:00.000Z"
      }
    ],
    "total_alerts": 0,
    "limit": 0,
    "threshold": 0,
    "default_threshold": 0
  },
  "meta": "string"
}

Number-Intelligence lookup history & spend analytics

GET /api/v1/numbers/lookup-history

Number-Intelligence console analytics — a pure read over the finance ledger (public.credit_transactions) of every billed number lookup (single, by-number, trust-package, and bulk all debit the wallet via the number_lookup channel). Returns, scoped to the caller’s org: a daily lookup-count + spend series over the requested window, the configured per-tenant daily cost cap with today’s spend against it, and a recent-activity feed. No carrier call and no mutation. Read-only; scoped on numbers:read.

integer

Window length in days for the daily series (1–90, default 30).

integer

Number of entries in the recent-activity feed (1–100, default 25).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/lookup-history" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "window": {
      "days": 0,
      "from": "1970-01-01T00:00:00.000Z",
      "to": "1970-01-01T00:00:00.000Z"
    },
    "summary": {
      "total_lookups": 0,
      "total_spend_cents": 0,
      "currency": "string",
      "daily_cap_cents": 0,
      "today_spend_cents": 0,
      "cap_remaining_cents": 0
    },
    "daily": [
      {
        "date": "string",
        "lookups": 0,
        "spend_cents": 0
      }
    ],
    "recent": [
      {
        "id": "string",
        "occurred_at": "1970-01-01T00:00:00.000Z",
        "spend_cents": 0,
        "currency": "string"
      }
    ]
  },
  "meta": "string"
}

Full phone number intelligence lookup

GET /api/v1/numbers/lookup/{phoneNumber}

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 — explicitly flagged data.derived: true with data.confidence: low (not an operator-asserted flag; the paid Telnyx forwarding add-on is not contracted) and 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.

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.

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

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/lookup/{phoneNumber}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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())

{
  "data": {
    "phoneNumber": "string",
    "valid": false,
    "callingCountryCode": "string",
    "nationalFormat": "string",
    "carrier": {
      "name": "string",
      "type": "string",
      "mcc": "string",
      "mnc": "string"
    },
    "portability": {
      "ported": false,
      "portedDate": "1970-01-01T00:00:00.000Z",
      "mnp_original_carrier": null,
      "mnp_ported_at": null,
      "originalCarrier": null,
      "originalMnc": null
    },
    "simSwap": {
      "swapped": null,
      "lastSwapDate": null,
      "riskLevel": "low"
    },
    "roaming": {
      "roaming": null,
      "servingMcc": null,
      "homeMcc": null,
      "servingCountry": null
    },
    "liveStatus": "yes",
    "reachable": false,
    "cached": false,
    "cachedAt": "1970-01-01T00:00:00.000Z",
    "available": false,
    "message": "string",
    "dataPackages": {}
  },
  "meta": {
    "request_id": "string",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

{}

List bulk number-provisioning orders

GET /api/v1/numbers/orders

List the organization’s most-recent bulk number orders (summaries only). Each order is the pollable record of a POST /numbers/buy-bulk request, with its aggregate delivered/failed/partial outcome so customers can audit partial fulfillment after the fact (Twilio / Bandwidth OrderStatus parity). Org-scoped — a sibling subaccount under the same tenant schema never sees another org’s orders. Inbound DID provisioning only (invariant #45 untouched). Fetch /numbers/orders/{id} for per-line detail.

integer

Max orders to return, most-recent first (defaults to the server page size).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/orders" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "orders": [
      "string"
    ]
  },
  "meta": "string"
}

Fetch one bulk number-provisioning order

GET /api/v1/numbers/orders/{id}

Fetch a single bulk number order by id, including its per-line delivered/failed outcomes (E.164, country, capabilities, monthly cost, and any error). Org-scoped — an unknown or not-owned id returns 404 (no exists-but-not-yours enumeration leak). Inbound DID provisioning only (invariant #45 untouched).

string

required

Bulk-order record id (returned by /numbers/buy-bulk and /numbers/orders).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/orders/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": "string",
  "meta": "string"
}

List port-in requests

GET /api/v1/numbers/porting

List all number port-in requests for the authenticated organization. Each request carries the numbers being ported, the losing carrier, the carrier-side status (submitted, reviewing, approved, completed, rejected, supplement_submitted), the destination provider, and the Firm Order Confirmation (FOC) date once scheduled. Duplicate active rows for the same number set are collapsed in the response. Read-only; requires the numbers:read scope.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/porting" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": [
    "string"
  ],
  "meta": "string"
}

Get a port-in request’s status timeline

GET /api/v1/numbers/porting/{id}/timeline

Expand a port-in request’s flat status into a six-stage timeline (submitted, validating LoA, carrier review, FOC assigned, FOC scheduled, completed) with per-stage state and timestamps, the elapsed-days counter, the FOC date once assigned, and — on rejection — a plain-English explanation of the carrier’s reject code plus a recommended action. Pure read: it transforms the request you already have and makes no carrier call. Requires the numbers:read scope.

string

required

The port-in request id.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/porting/{id}/timeline" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "portingId": "port_01J9Z8ABCDEF",
    "status": "reviewing",
    "elapsedDays": 3,
    "focDate": null,
    "stages": [
      {
        "stage": "submitted",
        "enteredAt": "2026-08-11T09:30:00Z",
        "state": "completed",
        "label": "Submitted"
      },
      {
        "stage": "validating_loa",
        "enteredAt": "2026-08-11T10:05:00Z",
        "state": "completed",
        "label": "Validating LoA"
      },
      {
        "stage": "carrier_review",
        "enteredAt": "2026-08-12T08:00:00Z",
        "state": "current",
        "label": "Losing carrier review",
        "detail": "Expected: 5 days, elapsed: 3 days"
      },
      {
        "stage": "foc_assigned",
        "enteredAt": null,
        "state": "pending",
        "label": "FOC date assigned"
      },
      {
        "stage": "foc_scheduled",
        "enteredAt": null,
        "state": "pending",
        "label": "Scheduled for FOC"
      },
      {
        "stage": "completed",
        "enteredAt": null,
        "state": "pending",
        "label": "Port complete"
      }
    ]
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-14T12:00:00Z"
  }
}

List port-out requests

GET /api/v1/numbers/porting/out

List every number port-OUT request this organization has submitted to move its numbers away to another carrier. Each row carries the numbers, the destination carrier, the current lifecycle status, the hosting DID provider, and the Firm Order Confirmation (FOC) date once the carrier schedules it. Read-only; requires the numbers:read scope.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/porting/out" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": [
    {
      "id": "pout_01J9Z8ABCDEF",
      "numbers": [
        "+14155550123"
      ],
      "destinationCarrier": "Twilio",
      "status": "submitted",
      "provider": "telnyx",
      "submittedAt": "2026-08-12T09:30:00Z",
      "focDate": null,
      "rejectionReason": null
    }
  ],
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-14T12:00:00Z"
  }
}

List recoverable (snapback) numbers

GET /api/v1/numbers/recoverable

List the calling org’s recently-released numbers that are still recoverable via snapback — sitting in the post-release parking cooldown, not yet resold, and within the recovery window. Each row carries the id and recoverable_until deadline needed to drive POST /api/v1/numbers/{id}/reclaim. Keyset-paginated on the parking deadline so a telco-scale tenant with a large parked inventory never returns an unbounded list. Org-scoped; read-only on numbers:read.

integer

Recoverable numbers per page (default 25). Hard-capped server-side at 100 — larger values are silently clamped, not rejected.

string

Opaque keyset cursor from the previous page’s data.next_cursor (ordered by the parking deadline). Omit for the first page.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/recoverable" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "numbers": [
      {
        "id": "string",
        "phone_number": "string",
        "country_code": "string",
        "status": "string",
        "recoverable_until": "1970-01-01T00:00:00.000Z"
      }
    ],
    "total": 0,
    "has_more": false,
    "next_cursor": "string"
  },
  "meta": "string"
}

List carrier reputation alerts

GET /api/v1/numbers/reputation-alerts

Fleet-wide rollup of every monitored owned number (at least one carrier observation recorded) that still needs action — currently flagged, at risk, or missing branded-caller registration — and has no open tracked remediation submission covering it yet. A number drops off the list as soon as a tracked submission covers every flagged provider. The scan is capped at 500 monitored numbers per call; truncated: true means only the first 500 were scanned, so the counts are a lower bound.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/reputation-alerts" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": {
    "summary": {
      "monitored_count": 0,
      "needs_action_count": 0,
      "scam_likely_count": 0,
      "unregistered_count": 0
    },
    "alerts": [
      {
        "phone_number_id": "string",
        "phone_number": "string",
        "status": "clear",
        "worst_label": "clear",
        "flagged_providers": [
          {
            "provider": "string",
            "provider_name": "string"
          }
        ],
        "unregistered_providers": [
          {
            "provider": "string",
            "provider_name": "string"
          }
        ],
        "uncovered_providers": [
          {
            "provider": "string",
            "provider_name": "string"
          }
        ],
        "last_checked_at": "string"
      }
    ],
    "truncated": false
  },
  "meta": "string"
}

List tracking pools

GET /api/v1/numbers/tracking-pools

List every CXaaS call-tracking (Dynamic Number Insertion) pool for the organization. Org-scoped. Owner/admin/developer/viewer.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/tracking-pools" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": [
    "string"
  ],
  "meta": "string"
}

Fetch one tracking pool

GET /api/v1/numbers/tracking-pools/{id}

Fetch a single tracking pool by id. Org-scoped — an unknown or not-owned id returns 404. Owner/admin/developer/viewer.

string

required

Tracking-pool id.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/tracking-pools/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": "string",
  "meta": "string"
}

Preview the DNI swap number for a visitor

GET /api/v1/numbers/tracking-pools/resolve

Resolve the tracking DID a DNI snippet would display for the supplied UTM/referrer/session context (dashboard “test the swap” affordance and the server-side embed). Returns a null number when no pool matches, meaning the page keeps its default number. Registered ahead of /tracking-pools/{id} so the literal resolve segment is never swallowed by the :id param route. Owner/admin/developer/viewer.

string

—

string

—

string

—

string

—

string

—

string

—

string

Stable per-visitor key (session id / cookie) driving “sticky” picks.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/numbers/tracking-pools/resolve" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

import { Orbit } from '@devotel-orbit/node'

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

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

{
  "data": "string",
  "meta": "string"
}

Attach a compliance profile to a number

POST /api/v1/numbers/{id}/attach-compliance-profile

Attach an approved compliance profile (regulatory bundle) to a DID that landed at pending_compliance, re-submitting the bundle to the carrier for the pending order. The carrier’s verification webhook later flips the number to active once the bundle is accepted — use this to complete a regulated purchase that stalled awaiting documentation. Org-ownership is enforced; owner/admin/developer only.

string

required

The phone number record id.

string

required

Id of an approved tenant compliance profile to attach to the number.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/{id}/attach-compliance-profile" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "compliance_profile_id": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/attach-compliance-profile', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "compliance_profile_id": "string"
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Upload a document for a number’s requirement

POST /api/v1/numbers/{id}/documents/{docId}/upload

Upload the file that satisfies a specific regulatory requirement on a number (PDF, JPEG, PNG, or HEIC, up to 10 MB). The file is stored for audit and forwarded to the carrier; the response reports whether the carrier accepted it (submitted) or it is only staged locally pending a retry (uploaded).

string

required

—

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/{id}/documents/{docId}/upload" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/documents/{docId}/upload', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "status": "submitted",
    "fileUrl": "string",
    "providerDocumentId": "string",
    "rejectionReason": "string"
  },
  "meta": "string"
}

Refresh regulatory document statuses for a number

POST /api/v1/numbers/{id}/documents/refresh

Re-poll the number’s provider for the latest approval decision on every pending document requirement and return the refreshed list. Use it after uploading documents to pick up carrier approvals or rejections without waiting for the periodic background sync.

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/{id}/documents/refresh" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/documents/refresh', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": [
    {
      "id": "string",
      "requirement_type": "string",
      "status": "string",
      "rejection_reason": "string"
    }
  ],
  "meta": "string"
}

Verify the emergency (E911) address for a number

POST /api/v1/numbers/{id}/emergency-address/verify

Run the local structural dispatch-readiness check against the number’s registered emergency address and persist the verdict (valid or invalid) with any issues found. It validates required civic fields and postal-code format only; it does not call any provider address-verification service.

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/{id}/emergency-address/verify" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/emergency-address/verify', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "address": "string"
  },
  "meta": "string"
}

Submit a port-out request for a number

POST /api/v1/numbers/{id}/port-out

Start moving a number to another carrier without contacting support: the platform dispatches the port-out to the number’s current provider and, on success, records the carrier-confirmed order id and FOC date. Requires the losing-carrier account number, an authorized signatory, and the winning carrier’s OCN; include the port-out PIN when protection is enabled on the number.

string

required

—

string

required

Account number with the number’s current carrier.

string

required

Name of the LoA signatory authorizing the release.

string

required

Operating Company Number (OCN) of the winning carrier.

string

Required only when port-out PIN protection is enabled on the number (4-32 characters).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/{id}/port-out" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "losing_carrier_account_number": "string",
  "authorized_person": "string",
  "target_carrier_ocn": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/port-out', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "losing_carrier_account_number": "string",
  "authorized_person": "string",
  "target_carrier_ocn": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "phoneNumber": "string",
    "provider": "telnyx",
    "providerOrderId": "string",
    "providerStatus": "string",
    "focDate": "1970-01-01T00:00:00.000Z",
    "portStatus": "string"
  },
  "meta": "string"
}

Set or rotate the port-out PIN for a number

POST /api/v1/numbers/{id}/port-out-protection

Enable port-out PIN protection (or rotate the existing PIN) on a number by supplying a 4-32 character PIN. Once set, any port-out request must present the matching PIN before the carrier dispatch runs, closing the port-hijack attack class. The PIN is hashed at rest and never returned.

string

required

—

string

required

The port-out PIN (4-32 characters).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/{id}/port-out-protection" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "port_out_pin": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/port-out-protection', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "port_out_pin": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "enabled": false,
    "set_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

Reactivate a suspended number

POST /api/v1/numbers/{id}/reactivate

Restore a suspended number to active, re-enabling inbound routing and outbound use (the inverse of POST /api/v1/numbers/{id}/suspend). Only a number in suspended status can be reactivated; any other state returns 409. The row flips back to active, the suspension audit fields are cleared, and routing resumes immediately with no backfill. Org-ownership is enforced per call so a sibling sub-org sharing the tenant schema cannot un-pause a number it does not own. Scoped on numbers:write (owner / admin / developer).

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/{id}/reactivate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/reactivate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {},
  "meta": "string"
}

Reassign a number to a sibling subaccount

POST /api/v1/numbers/{id}/reassign

Move ownership of a purchased DID from the caller’s subaccount to a sibling subaccount under the same reseller parent, without releasing and re-buying it from the carrier (the DID parity to wallet transfer_to_subaccount). Because sibling subaccounts share one tenant schema, only the ownership pointer changes — the number’s config and history stay intact. The target org must be in the same tenant and org family, and the DID must be purchased inventory the caller owns, or the call returns 409. Org-ownership is enforced per call; invariant #45 is untouched (ownership-column write only). Scoped on numbers:write (owner / admin / developer).

string

required

—

string

required

Id of the sibling subaccount (same tenant + org family) to receive ownership of the number.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/{id}/reassign" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "target_org_id": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/reassign', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "target_org_id": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "phone_number": "string",
    "assigned_to_org_id": "string",
    "previous_assigned_to_org_id": "string"
  },
  "meta": "string"
}

Reclaim a parked number during its grace window

POST /api/v1/numbers/{id}/reclaim

Re-claim a number the org recently released while it is still parked in the post-release grace window (Twilio / Bandwidth snapback / winback), restoring it to active with no upstream re-purchase — the DID never left the account. Returns 409 when the number is not reclaimable (not parked, owned by a different org, or the parking window has already elapsed), in which case the caller should fall back to a fresh purchase from inventory. Use GET /api/v1/numbers/recoverable to discover which numbers are still reclaimable and until when. Scoped on numbers:write (owner / admin / developer).

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/{id}/reclaim" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/reclaim', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {},
  "meta": "string"
}

Repair a number’s partial provisioning

POST /api/v1/numbers/{id}/repair-provisioning

Re-run the post-purchase messaging-profile and voice-connection attachments for a number whose original purchase left them partial, so you can fix a DID that fails every send with “Invalid source number” without releasing and re-buying it (surfaced from the dashboard “Repair” badge). Returns which capabilities are now attached and their provider ids; a released number returns 400. Org-ownership is enforced per call so a sibling sub-org sharing the tenant schema cannot burn another org’s provider rate-limit budget. Scoped on numbers:write (owner / admin / developer).

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/{id}/repair-provisioning" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/repair-provisioning', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "messaging_profile_attached": false,
    "voice_connection_attached": false,
    "messaging_profile_id": "string",
    "voice_connection_id": "string"
  },
  "meta": "string"
}

Retry a failed number release

POST /api/v1/numbers/{id}/retry-release

Re-issue the upstream carrier release for a number whose previous release failed or is stuck pending (release_status='failed'), re-enqueueing the carrier DELETE instead of leaving the DID billing in limbo. The dashboard surfaces this as a “Retry release” action on the Active list when a failed release exists. Responds 202 Accepted — the retry is processed asynchronously. Org-ownership is enforced per call so a sibling sub-org sharing the tenant schema cannot force a release on a number it does not own. Scoped on numbers:write (owner / admin / developer).

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/{id}/retry-release" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/retry-release', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "retry_enqueued": false,
    "number_id": "string"
  },
  "meta": "string"
}

Ingest an SMS spam-complaint report for a number

POST /api/v1/numbers/{id}/sms-complaints/reports

Record a carrier/CTIA complaint report (counts per period) and recompute the rollup.

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/{id}/sms-complaints/reports" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/sms-complaints/reports', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {},
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Suspend an active number

POST /api/v1/numbers/{id}/suspend

Temporarily suspend an active number — stop inbound routing and outbound use WITHOUT releasing the DID back to inventory. Only a number in active status can be suspended; suspending a released / parked / pending number returns 409. The row flips to suspended and every inbound resolver + outbound from-number gate (which already whitelist status='active') stops routing immediately. Org-ownership is enforced per call so a sibling sub-org sharing the tenant schema cannot pause a number it does not own. The inverse of POST /api/v1/numbers/{id}/reactivate. Scoped on numbers:write (owner / admin / developer).

string

required

—

string

Optional free-text suspension note, persisted to the lifecycle audit fields.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/{id}/suspend" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/suspend', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {},
  "meta": "string"
}

Submit or resubmit a toll-free number for verification (TFV)

POST /api/v1/numbers/{id}/tfv-submit

Submit (or resubmit) the Toll-Free Verification form for a toll-free DID so the carrier can approve it for messaging — without an approved TFV, US / CA toll-free traffic is throttled or blocked with 30032 errors. Supply the messaging use case, a use-case summary, 1–5 sample messages, business identity (name, website, and either an EIN or a business registration number + ISO country), a contact email and E.164 phone, the opt-in type with 1–5 opt-in proof image URLs, and the expected monthly message volume. Samples are content-linted before submission, so disallowed-vertical content is rejected up front (422) instead of after a multi-day carrier review; political use cases additionally require a Campaign Verify token. Org-ownership is enforced per call so a sibling sub-org sharing the tenant schema cannot submit attestation against another org’s DID. Scoped on numbers:write (owner / admin).

string

required

—

string

required

Toll-free messaging use case (from the carrier-approved use-case list, e.g. Customer Care).

string

required

40–500 character description of how the number is used.

string[]

required

1–5 representative outbound messages the carrier will review.

string

required

—

string

required

—

string

US Employer Identification Number (xx-xxxxxxx). Supply this OR business_registration_number + business_registration_country.

string

—

string

ISO-3166 alpha-2 country of the business registration number.

string

required

—

string

required

E.164 contact phone (e.g. +14155550123).

string (enum: VERBAL|WEB_FORM|PAPER_FORM|VIA_TEXT|MOBILE_QR_CODE)

required

How subscribers opted in to messaging.

string[]

required

1–5 HTTPS URLs to opt-in proof screenshots.

string

required

Expected monthly message-volume band (e.g. “10,000”).

string

—

boolean

Set true for political messaging; requires cv_token.

string

Campaign Verify authorization token (required for political use cases).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv-submit" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "use_case": "string",
  "use_case_summary": "string",
  "sample_messages": [],
  "business_name": "string",
  "business_website": "https://example.com",
  "contact_email": "user@example.com",
  "contact_phone": "+14155552671",
  "opt_in_type": "VERBAL",
  "opt_in_image_urls": [],
  "message_volume": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/tfv-submit', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "use_case": "string",
  "use_case_summary": "string",
  "sample_messages": [],
  "business_name": "string",
  "business_website": "https://example.com",
  "contact_email": "user@example.com",
  "contact_phone": "+14155552671",
  "opt_in_type": "VERBAL",
  "opt_in_image_urls": [],
  "message_volume": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "phoneNumberId": "string",
    "phoneNumber": "string",
    "tfvStatus": "not_submitted",
    "tfvProvider": "string",
    "tfvProviderSubmissionId": "string",
    "tfvSubmittedAt": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

Create a number application

POST /api/v1/numbers/applications

Create a number application with an operator-facing label and optional inbound-routing handler URLs. Handler URLs are HTTPS-only and used for inbound routing only. Owner/admin/developer only.

string

required

—

string

—

any

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/applications" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "friendlyName": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/applications', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "friendlyName": "string"
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Bind (or move) a DID to a number application

POST /api/v1/numbers/applications/{id}/bind

Bind a DID (E.164) to an application. Verifies the caller’s org OWNS the number (cross-tenant gate) BEFORE the write. If the number is already bound to a DIFFERENT application it is atomically MOVED — the prior application loses it in the same transaction. Idempotent when the number is already bound to the same application. Inbound routing only. Owner/admin/developer only.

string

required

Number-application id.

string

required

The DID to bind, in E.164 (e.g. +14155550123).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/applications/{id}/bind" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/applications/{id}/bind', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "phoneNumber": "+14155552671"
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Unbind a DID from a number application

POST /api/v1/numbers/applications/{id}/unbind

Unbind a DID (E.164) from an application, reverting it to no application binding. Org-ownership gated. Owner/admin/developer only.

string

required

Number-application id.

string

required

The DID to unbind, in E.164 (e.g. +14155550123).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/applications/{id}/unbind" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/applications/{id}/unbind', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "phoneNumber": "+14155552671"
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Bulk HLR lookup for up to 100 numbers

POST /api/v1/numbers/bulk-lookup

Validate and enrich up to 100 phone numbers in one HLR (Home Location Register) lookup, returning line type, carrier/network, portability, and reachability for each number. Use it to scrub a list before a campaign — invalid or unreachable numbers surface per row so you can drop them ahead of send. Wallet balance is pre-checked for the whole batch and only successfully resolved rows are billed; a genuinely failed row is not charged. Rate-limited tighter than single lookup (5 requests per minute). Requires the numbers:read scope.

string[]

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/bulk-lookup" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "numbers": []
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/bulk-lookup', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "numbers": []
}),
})
console.log(await res.json())

{
  "data": {
    "results": [
      {
        "number": "+14155550100",
        "valid": true,
        "type": "mobile",
        "network": "Verizon",
        "ported": false,
        "present": "yes",
        "mcc": "310",
        "mnc": "004",
        "error_code": 0,
        "cached": false
      }
    ],
    "total": 1,
    "cached": 0,
    "queried": 1
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-11T12:00:00Z"
  }
}

Reserve a batch of numbers from a filter

POST /api/v1/numbers/bulk-reserve

Discover and hold up to 1000 DIDs matching a country / area-code / number-type / capability filter for 15 minutes, then either finalize (purchase, bill, and route) or cancel (release) the batch. Use this when you want the platform to find a block for you rather than posting a pre-built list of E.164s to /numbers/buy-bulk. It polls DIDWW and Telnyx (and platform inventory when provider is unset) and picks the cheapest N; partial holds are returned so you can compare reserved_count against the requested quantity. Inbound DID provisioning only (invariant #45 untouched). Requires the numbers:write scope.

string

required

ISO 3166-1 alpha-2 country code.

string

Optional area-code / prefix filter (2–5 digits).

string (enum: local|mobile|toll_free)

—

integer

required

—

string

Optional digit-only pattern to match within the number.

string (enum: contains|starts_with|ends_with)

—

string

Comma-separated capability filter (e.g. sms,voice).

string (enum: devotel|telnyx|didww)

—

string

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/bulk-reserve" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "country": "string",
  "quantity": 0
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/bulk-reserve', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "country": "string",
  "quantity": 0
}),
})
console.log(await res.json())

{
  "data": {
    "reservation_id": "numberReservation_01J9Z8ABCDEF",
    "status": "ready",
    "expires_at": "2026-08-11T12:15:00Z",
    "requested_quantity": 10,
    "reserved_count": 10,
    "total_cost_cents": 1000,
    "items": [
      {
        "id": "nri_01J9Z8ABCDEF",
        "phone_number": "+14155550100",
        "provider": "devotel",
        "country_code": "US",
        "monthly_cost_cents": 100,
        "status": "reserved"
      }
    ]
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-11T12:00:00Z"
  }
}

Cancel a bulk reservation (release held numbers)

POST /api/v1/numbers/bulk-reserve/{id}/cancel

Release every item held by a bulk reservation back to the carrier inventory pool without purchasing. No upstream carrier call is made (a reservation never placed an order) and nothing is billed. Use it to free a hold you no longer want before it expires. Returns 409 if the reservation has already been finalized, cancelled, or expired, and 404 for an unknown or not-owned id. No request body. Requires the numbers:write scope.

string

required

Reservation id returned by POST /numbers/bulk-reserve.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/bulk-reserve/{id}/cancel" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/bulk-reserve/{id}/cancel', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Finalize a bulk reservation (purchase held numbers)

POST /api/v1/numbers/bulk-reserve/{id}/finalize

Purchase, bill, and provision inbound routes for every item held by a bulk reservation, converting the 15-minute hold into owned numbers. It reuses the same wallet preflight, per-item compliance gate, and audit trail as /numbers/buy-bulk, so partial success is possible — the response carries succeeded_count, failed_count, debited_cents, and a final status of finalized, partial, or failed. Call it before the reservation’s expires_at; an expired or already-settled reservation is rejected. No request body. Inbound DID provisioning only (invariant #45 untouched). Requires the numbers:write scope.

string

required

Reservation id returned by POST /numbers/bulk-reserve.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/bulk-reserve/{id}/finalize" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/bulk-reserve/{id}/finalize', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Buy multiple phone numbers in one request

POST /api/v1/numbers/buy-bulk

Purchase up to 50 already-selected phone numbers in a single call, with an up-front wallet check against the summed per-number cost. Partial success is expected: provisioned numbers are returned in succeeded[] and per-row carrier failures in failed[] (a failed row is never charged), and the response is 200 even when every row fails — inspect succeeded to decide the UI state. The result is also persisted as a pollable order record (GET /numbers/orders/{id}) so partial fulfillment can be audited later. Inbound DID provisioning only (invariant #45 untouched). Requires the numbers:write scope.

object[]

required

—

string

Compliance profile applied to every item that needs one.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/buy-bulk" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "items": []
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/buy-bulk', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "items": []
}),
})
console.log(await res.json())

{
  "data": {
    "order_id": "numOrder_01J9Z8ABCDEF",
    "succeeded": [
      {
        "id": "num_01J9Z8ABCDEF",
        "phone_number": "+14155550100"
      }
    ],
    "failed": [
      {
        "phone_number": "+14155550101",
        "error": {
          "code": "CARRIER_UNAVAILABLE",
          "message": "Number no longer available"
        }
      }
    ],
    "total_cost_cents": 200,
    "debited_cents": 100
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-11T12:00:00Z"
  }
}

Claim a free trial number from the shared pool

POST /api/v1/numbers/claim-trial

Claim one free trial phone number from the shared pool for the authenticated organization, leased for 24 hours as a one-time lifetime claim (no renewal). Use it to test inbound calls and SMS before purchasing a dedicated number; to keep the number past expiry, convert it with POST /numbers/purchase-trial. Returns 409 if the organization already holds an active trial or already owns purchased numbers, and a pool error when no trial stock is available. No request body. Requires the numbers:write scope.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/claim-trial" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/claim-trial', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "pna_01J9Z8ABCDEF",
    "phoneNumber": "+14155550100",
    "organizationId": "org_01J9Z8ABCDEF",
    "assignedAt": "2026-08-11T12:00:00Z",
    "expiresAt": "2026-08-12T12:00:00Z",
    "numberType": "local",
    "country": "US"
  }
}

Order a SIM against a catalog plan

POST /api/v1/numbers/connectivity/sims

Provision (order) a new SIM in state ordered. The plan must be DATA-ONLY (invariant #45) — an MT-capable plan is rejected fail-closed. When iccid is omitted the server mints a synthetic 19-digit ICCID for the manual-mode flow. Requires the numbers:write scope (owner / admin / developer).

string

required

—

string

Aggregator-assigned ICCID; minted server-side when omitted.

string

—

string

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "planId": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "planId": "string"
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Activate a SIM

POST /api/v1/numbers/connectivity/sims/{iccid}/activate

Transition an ordered (or suspended) SIM to active. Returns 409 on an illegal transition. Requires the numbers:write scope.

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims/{iccid}/activate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims/{iccid}/activate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Apply or clear a SIM OTA profile

POST /api/v1/numbers/connectivity/sims/{iccid}/ota

Apply an OTA configuration profile to a SIM, or clear the applied profile by passing otaProfileId: null. Requires the numbers:write scope.

string

required

—

string

required

Profile id to apply, or null to clear the applied profile.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims/{iccid}/ota" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "otaProfileId": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims/{iccid}/ota', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "otaProfileId": "string"
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Resume a SIM

POST /api/v1/numbers/connectivity/sims/{iccid}/resume

Transition a suspended SIM back to active. Returns 409 on an illegal transition. Requires the numbers:write scope.

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims/{iccid}/resume" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims/{iccid}/resume', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Suspend a SIM

POST /api/v1/numbers/connectivity/sims/{iccid}/suspend

Transition an active SIM to suspended. Returns 409 on an illegal transition. Requires the numbers:write scope.

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims/{iccid}/suspend" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims/{iccid}/suspend', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Terminate a SIM

POST /api/v1/numbers/connectivity/sims/{iccid}/terminate

Permanently terminate a SIM (transition to the terminal terminated state). Returns 409 on an illegal transition. Requires the numbers:write scope.

string

required

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims/{iccid}/terminate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims/{iccid}/terminate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Record a SIM data session

POST /api/v1/numbers/connectivity/sims/{iccid}/usage

Record a metered data session against an active SIM. Advances the authoritative cumulative usageBytes meter and appends to the rolling session window. Descriptive only — it neither rates nor bills the usage. Requires the numbers:write scope.

string

required

—

number

required

Bytes consumed in this session (finite, non-negative).

string

—

string

ISO 3166-1 alpha-2 of the attached network.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims/{iccid}/usage" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "bytes": 0
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/connectivity/sims/{iccid}/usage', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "bytes": 0
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Open a hosted-messaging order

POST /api/v1/numbers/hosted-messaging

Open a new hosted-messaging order to text-enable an existing landline, toll-free, or mobile number without porting it — the number’s voice service stays with its current carrier. Supply the E.164 phoneNumber, the voiceCarrier of record, the numberType, and the inboundRoute that inbound SMS should be delivered to once the order is active. The order starts in draft; sign the LOA and submit it to progress. A second in-flight order for the same number is rejected. Requires the numbers:write scope.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Sign the hosted-messaging LOA

POST /api/v1/numbers/hosted-messaging/{id}/loa/sign

Record an in-platform Letter of Authorization (LOA) signature for a draft hosted-messaging order, transitioning it from draft to loa_signed. Supply the signer’s legal name and email, the verbatim acknowledgement text they accepted, and optionally a Devotel-issued signed URL of the signed LOA artefact. The carrier is not notified yet — this gives operators a buffer to revoke before submission. Requires the numbers:write scope.

string

required

Hosted-messaging order id.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging/{id}/loa/sign" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging/{id}/loa/sign', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Submit a hosted-messaging order

POST /api/v1/numbers/hosted-messaging/{id}/submit

Submit a signed hosted-messaging order to the hosting carrier, transitioning it from loa_signed to submitted. The signed LOA must already be recorded (otherwise the request is rejected) — the carrier then begins ownership verification before the number is activated for inbound SMS. Requires the numbers:write scope.

string

required

Hosted-messaging order id.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging/{id}/submit" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging/{id}/submit', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Look up phone number intelligence

POST /api/v1/numbers/lookup

Resolve carrier, line-type, portability, and live-status intelligence for a single E.164 number supplied in the request body — the POST companion to GET /api/v1/numbers/lookup/{phoneNumber}. Uses Devotel HLR as primary with a Telnyx fallback. Pass an optional Twilio-compatible fields selector to request add-on data packages (e.g. sim_swap, cnam, line_type_intelligence); the response then carries a dataPackages map. Each answered lookup is billed once via the number_lookup wallet channel (sandbox mode is free). Requires the numbers:write scope.

string

required

Phone number to look up, in E.164 format (e.g. +14155550123).

any

Optional Twilio-compatible data-package selector — a comma-separated string or a JSON array of field names (max 16).

Prior-express-consent date (YYYY-MM-DD) required to realise the reassigned_number data package; ignored otherwise.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/lookup" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+14155552671"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/lookup', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "phone": "+14155552671"
}),
})
console.log(await res.json())

{
  "data": {
    "phoneNumber": "string",
    "valid": false,
    "carrier": "string",
    "type": "string",
    "ported": false,
    "reachable": false,
    "dataPackages": {}
  },
  "meta": "string"
}

Bulk import port-in requests from CSV

POST /api/v1/numbers/port-in/bulk-csv

Import many port-in requests at once by uploading a single CSV file (multipart field file) with the columns phone_number, current_carrier_account_number, current_carrier_name, billing_name, billing_address — one row per number. Each valid row becomes its own manual-mode port-in request so ops can attach the LOA and country code afterwards; invalid rows are skipped and returned with a 1-indexed pointer. Capped at 1000 rows / 2 MB per request. Requires the numbers:write scope.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/port-in/bulk-csv" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/port-in/bulk-csv', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Submit a port-in request

POST /api/v1/numbers/porting

Submit a new port-in request to bring one or more numbers onto the platform from a losing carrier. Supply the E.164 numbers (a single string or an array), the currentCarrier, and — to dispatch to a destination provider automatically — the country (US/CA route to Telnyx, elsewhere to DIDWW) and a Devotel-issued signed loaFileUrl. Omitting the country stores the request in manual mode for ops to hand-process. Requires the numbers:write scope.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/porting" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/porting', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Upload a Letter of Authorization for a port-in

POST /api/v1/numbers/porting/{id}/loa

Upload the Letter of Authorization (LoA) for a port-in request as a single PDF, JPEG, PNG, or HEIC file (multipart field file, up to 10 MB). The file is stored privately, attached to the request, and its signature state moves to draft. Once the LoA is signed or submitted it can no longer be replaced — cancel and re-create the request to attach a different document. Requires the numbers:write scope.

string

required

The port-in request id.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/porting/{id}/loa" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/porting/{id}/loa', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Sign a port-in Letter of Authorization

POST /api/v1/numbers/porting/{id}/loa/sign

Capture an in-platform signature on an uploaded LoA: record the authorized signer’s name and email plus the verbatim acknowledgement text they agreed to, and move the signature state to signed. The request must already have a LoA in draft state; signing again returns 422. Requires the numbers:write scope.

string

required

The port-in request id.

string

required

Authorized signer’s full legal name, matching the losing carrier’s account.

string

required

—

string

required

Verbatim acknowledgement text the signer agreed to (stored for legal reconciliation).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/porting/{id}/loa/sign" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "signerName": "string",
  "signerEmail": "user@example.com",
  "acknowledgement": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/porting/{id}/loa/sign', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "signerName": "string",
  "signerEmail": "user@example.com",
  "acknowledgement": "string"
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Submit a signed port-in Letter of Authorization

POST /api/v1/numbers/porting/{id}/loa/submit

Forward a signed LoA to the losing carrier and move the signature state to submitted. Provider-dispatched requests send the document to the carrier; manual-mode requests transition locally so ops can hand off the signed PDF out of band. The LoA must already be in signed state. A carrier-side failure is logged but does not block the local transition — retry the carrier step via the refresh endpoint. Requires the numbers:write scope.

string

required

The port-in request id.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/porting/{id}/loa/submit" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/porting/{id}/loa/submit', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Refresh a port-in request’s carrier status

POST /api/v1/numbers/porting/{id}/refresh

Re-poll the destination provider for the latest carrier-side status of an in-flight port-in and store it on the local request — use it to pull the current stage and FOC date on demand instead of waiting for the next background sync. Manual-mode requests (no provider order attached at submit time) return 422 because there is nothing to poll. Requires the numbers:write scope.

string

required

The port-in request id.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/porting/{id}/refresh" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/porting/{id}/refresh', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Supplement a rejected port-in request

POST /api/v1/numbers/porting/{id}/supplement

Correct and re-submit a carrier-rejected port-in within the amend window (typically 7 days) without restarting the FOC clock — fix an address or name mismatch, a wrong account number or PIN, or replace a stale LoA. Send at least one field; account details and documents are forwarded to the carrier. Returns 422 when the request is not in a rejected/supplement state or the provider has no supplement API, and 409 when the carrier refuses (window expired). Requires the numbers:write scope.

string

required

The port-in request id.

string

Devotel-issued GCS signed URL for a replacement Letter of Authorization.

string

Devotel-issued GCS signed URL for an updated Customer Service Record.

string

—

object

—

string

—

string

—

string

Free-text note to the carrier explaining the correction.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/porting/{id}/supplement" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/porting/{id}/supplement', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Check port-in eligibility for a number

POST /api/v1/numbers/porting/check

Run a live pre-flight portability check on a single number before you submit a port-in, so a “not portable” answer comes back in seconds instead of after a 2-7 business-day carrier review. US and Canadian numbers are checked against the losing carrier’s database; numbers in other countries return check_status: check-not-supported because the upstream has no synchronous pre-check. Read-only — no LoA, no order, and no carrier state is created. Requires the numbers:read scope.

string

required

Number to check, in E.164 format (e.g. +14155550123).

string

Optional losing-carrier name, recorded for telemetry.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/porting/check" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/porting/check', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "phoneNumber": "+14155552671"
}),
})
console.log(await res.json())

{
  "data": {
    "eligible": true,
    "reasons": [
      "Number is portable."
    ],
    "splittable": false,
    "check_status": "checked",
    "provider": "telnyx"
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-14T12:00:00Z"
  }
}

Create a tracking pool

POST /api/v1/numbers/tracking-pools

Create a tracking pool binding a marketing source/campaign to a match rule set the DNI snippet uses to decide when to swap the displayed number. Newly created pools have no tracking DIDs — assign them separately. Owner/admin/developer only.

string

required

—

string

required

—

string

—

string

—

any

—

string (enum: sticky|fixed)

—

boolean

—

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/tracking-pools" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "string",
  "source": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/tracking-pools', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "label": "string",
  "source": "string"
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Assign (or move) a tracking DID to a pool

POST /api/v1/numbers/tracking-pools/{id}/assign

Assign a tracking DID to a pool after verifying the caller’s org owns the number (cross-tenant gate, 404 on miss — no exists-but-not-yours enumeration leak). A DID bound to at most one pool at a time — if already assigned to a different pool it is atomically MOVED. Idempotent when the DID is already on the target pool. Inbound termination only (Invariant #45). Owner/admin/developer only.

string

required

Tracking-pool id.

string

required

The DID to assign, in E.164 (e.g. +14155550123).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/tracking-pools/{id}/assign" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/tracking-pools/{id}/assign', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "phoneNumber": "+14155552671"
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Unassign a tracking DID from a pool

POST /api/v1/numbers/tracking-pools/{id}/unassign

Unassign a tracking DID from a pool, reverting it to unbound. Idempotent — a no-op if the DID is not currently on the pool. Owner/admin/developer only.

string

required

Tracking-pool id.

string

required

The DID to unassign, in E.164 (e.g. +14155550123).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/tracking-pools/{id}/unassign" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+14155552671"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/tracking-pools/{id}/unassign', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "phoneNumber": "+14155552671"
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Update a phone number

PUT /api/v1/numbers/{id}

Update an owned DID’s configuration. Only the fields you send are changed: operator label and tags, inbound webhook_url / forwarding_number / sms_forwarding, toggleable capabilities, the attached compliance_profile_id, and the per-number messaging_mps_cap and monthly_spend_cap_cents guardrails. Org-ownership is enforced; owner/admin/developer only.

string

required

The phone number record id.

string

—

string (enum: active|inactive)

—

string (enum: sms|mms|voice|fax)[]

—

string

E.164 number to forward inbound calls to, or an empty string to clear.

string

HTTPS inbound-event webhook for this DID, or null to clear.

string

E.164 number to forward inbound SMS to, or an empty string to clear.

string

Tenant compliance-profile id to attach, or an empty string / null to detach.

integer

Per-DID outbound messages-per-second ceiling, or null to clear.

integer

Per-DID monthly outbound SMS spend ceiling in US cents, or null to clear.

string[]

—

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/numbers/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Assign a number to a 10DLC campaign

PUT /api/v1/numbers/{id}/campaign-assignment

Record the 10DLC A2P campaign (and optional brand) a DID belongs to so US carrier throughput (TPS / daily caps) is segregated per campaign. The linkage is captured locally with status: pending; the org-level 10DLC service owns the carrier-side number→campaign assignment. Org-ownership is enforced; owner/admin/developer only.

string

required

The phone number record id.

string

required

TCR (or adapter) campaign id this DID is tied to for 10DLC A2P throughput segregation.

string

Optional TCR (or adapter) brand id recorded alongside the campaign for the dashboard readout.

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/numbers/{id}/campaign-assignment" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "campaign_id": "cmp_1a2b3c4d5e6f7081a2b3c4d5"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/campaign-assignment', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "campaign_id": "cmp_1a2b3c4d5e6f7081a2b3c4d5"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "assignment": "string"
  },
  "meta": "string"
}

Set a number’s CNAM registration

PUT /api/v1/numbers/{id}/cnam

Register or update the branded outbound Caller-Name (CNAM) for a DID. The display name is normalised (upper-cased, whitespace-collapsed, at most 15 characters per the CNAM/LIDB limit) and captured with status: pending; a separate dispatch step hands it to the Devotel wholesale CNAM/LIDB provisioning queue. Org-ownership is enforced; owner/admin only.

string

required

The phone number record id.

string

required

Desired branded caller name (letters, digits, spaces, and . , - ’ & only; normalised to upper-case, ≤ 15 chars).

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/numbers/{id}/cnam" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "display_name": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/cnam', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "display_name": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "cnam": "string"
  },
  "meta": "string"
}

Set the emergency (E911) address for a number

PUT /api/v1/numbers/{id}/emergency-address

Register or replace the E911 dispatchable civic address on a number so an emergency call from it can be routed to the correct PSAP. Saving resets the address to an unverified state, so call the verify endpoint afterwards to run the local dispatch-readiness check.

string

required

—

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/numbers/{id}/emergency-address" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/emergency-address', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "address": "string"
  },
  "meta": "string"
}

Set a Mexican number’s active telecom regulator

PUT /api/v1/numbers/{id}/regulator

Flip a Mexican (MX) number’s active regulator between IFT and CRT once the carrier confirms the telecom-regulator transition is in effect for that inventory. The target must be an MX number or the call returns 422; a value other than IFT / CRT is also rejected as 422. Org-ownership is enforced per call so a sibling sub-org sharing the tenant schema cannot re-stamp a number it does not own, and the change is written to the audit trail. Requires admin; scoped on numbers:write.

string

required

—

string (enum: IFT|CRT)

required

The regulator to set as active for this MX number.

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/numbers/{id}/regulator" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "regulator": "IFT"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/regulator', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "regulator": "IFT"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "regulator": "IFT"
  },
  "meta": "string"
}

Set the scheduled release for a number

PUT /api/v1/numbers/{id}/scheduled-release

Schedule (or replace) a FUTURE automatic release of a tenant-owned DID for cost / capacity planning. release_at must be a strictly-future ISO-8601 timestamp within 730 days; an out-of-range or past date returns 422. The number is NOT released on write — it is captured with status: scheduled and actioned later by the due-date sweeper. Org-ownership is enforced; scoped on numbers:write (owner / admin / developer).

string

required

—

string

required

Strictly-future ISO-8601 instant at which the held DID should auto-release back to inventory (within 730 days from now).

string

Optional operator capacity-planning note.

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/numbers/{id}/scheduled-release" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "release_at": "1970-01-01T00:00:00.000Z"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/scheduled-release', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "release_at": "1970-01-01T00:00:00.000Z"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "scheduled_release": "string"
  },
  "meta": "string"
}

Set a number’s auto-renewal preference

PATCH /api/v1/numbers/{id}/auto-renew

Toggle automatic recurring renewal for a held DID. When enabled the number is re-billed each cycle so it does not lapse at its next billing date; when disabled it is allowed to expire and release at the end of the current term. Org-ownership is enforced; owner/admin/developer only.

string

required

The phone number record id.

boolean

required

True to re-bill the number each cycle; false to let it lapse at term end.

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/numbers/{id}/auto-renew" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "auto_renew": false
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/auto-renew', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "auto_renew": false
}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Schedule or clear a number’s future auto-release

PATCH /api/v1/numbers/{id}/scheduled-release

Set or clear the future auto-release date on a held DID in a single PATCH (Twilio / Bandwidth release_on parity). Send release_at as a strictly-future ISO-8601 instant to arm the release, or release_at: null to clear it. The number is NOT released on write — the date is persisted to the row and a separate sweeper drives the existing release lifecycle when it arrives. This is the lightweight metadata toggle; the sibling GET / PUT / DELETE on this path expose the richer operator-set schedule object. Org-ownership is enforced per call so a sibling sub-org sharing the tenant schema cannot arm or clear a release on a number it does not own. Scoped on numbers:write (owner / admin / developer).

string

required

—

string

required

ISO-8601 timestamp at which the held DID should be automatically released back to inventory. Must be strictly in the future; pass null to clear an existing scheduled release.

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/numbers/{id}/scheduled-release" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "release_at": "1970-01-01T00:00:00.000Z"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/scheduled-release', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "release_at": "1970-01-01T00:00:00.000Z"
}),
})
console.log(await res.json())

{
  "data": {},
  "meta": "string"
}

Override the SMS complaint suppression hold

PATCH /api/v1/numbers/{id}/sms-complaints/suppression

Manually hold or lift the sending hold after remediation (mode=manual).

string

required

—

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/numbers/{id}/sms-complaints/suppression" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/sms-complaints/suppression', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {},
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Update a number application

PATCH /api/v1/numbers/applications/{id}

Edit an application’s label, description, and/or inbound-routing handler URLs. At least one field must be supplied. Handler URLs are HTTPS-only and used for inbound routing only. Owner/admin/developer only.

string

required

Number-application id.

string

—

string

—

any

—

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/numbers/applications/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/applications/{id}', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Update the hosted-messaging inbound route

PATCH /api/v1/numbers/hosted-messaging/{id}/route

Change where inbound SMS on a hosted number is delivered, for an order that has not yet activated. Once the order is active the route is locked (open a new order to change live routing) and once it is rejected or cancelled it cannot be edited. Supply the new inboundRoute; the updated order is returned. Requires the numbers:write scope.

string

required

Hosted-messaging order id.

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging/{id}/route" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging/{id}/route', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Update a tracking pool

PATCH /api/v1/numbers/tracking-pools/{id}

Edit a pool’s label/source/campaign/medium/match/swapStrategy/enabled. At least one field must be supplied. Tracking DIDs are managed via the assign/unassign endpoints, not this one. Owner/admin/developer only.

string

required

Tracking-pool id.

string

—

string

—

string

—

string

—

any

—

string (enum: sticky|fixed)

—

boolean

—

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/numbers/tracking-pools/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/tracking-pools/{id}', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Release a phone number

DELETE /api/v1/numbers/{id}

Release (soft-delete) an owned DID. The number is parked during the post-release grace window — recoverable via snapback (POST /api/v1/numbers/{id}/reclaim) before it returns to inventory — and billing for it stops. Org-ownership is enforced; an unknown or not-owned id returns 404. Owner/admin/developer only.

string

required

The phone number record id.

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/numbers/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Response: 204 No Content

Remove a number’s 10DLC campaign assignment

DELETE /api/v1/numbers/{id}/campaign-assignment

Clear the 10DLC campaign/brand linkage on a DID — for example before re-assigning it to a different campaign. Org-ownership is enforced; a local metadata write only. Owner/admin/developer only. Returns the record with assignment: null.

string

required

The phone number record id.

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/numbers/{id}/campaign-assignment" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/campaign-assignment', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "assignment": null
  },
  "meta": "string"
}

Remove a number’s CNAM registration

DELETE /api/v1/numbers/{id}/cnam

Clear the CNAM registration on a DID so the number reverts to the default carrier caller-name behaviour. Org-ownership is enforced; owner/admin only. Returns the record with cnam: null.

string

required

The phone number record id.

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/numbers/{id}/cnam" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/cnam', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "cnam": null
  },
  "meta": "string"
}

Remove the emergency (E911) address from a number

DELETE /api/v1/numbers/{id}/emergency-address

Delete the registered E911 dispatchable address from a number, clearing its civic location and any prior validation verdict. Use it when a number is decommissioned or reassigned; returns 404 when no address is registered so a delete on an un-registered number is an explicit miss.

string

required

—

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/numbers/{id}/emergency-address" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/emergency-address', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "address": null
  },
  "meta": "string"
}

Disable port-out PIN protection for a number

DELETE /api/v1/numbers/{id}/port-out-protection

Remove the port-out PIN protecting a number so future port-out requests no longer require the PIN. Use it to clear or reset protection; because the PIN is one-way hashed and never returned, a cleared PIN cannot be recovered and must be set again from scratch.

string

required

—

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/numbers/{id}/port-out-protection" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/port-out-protection', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "enabled": false,
    "set_at": "1970-01-01T00:00:00.000Z"
  },
  "meta": "string"
}

Cancel the scheduled release for a number

DELETE /api/v1/numbers/{id}/scheduled-release

Clear the pending future release on a tenant-owned DID (the operator cancels the planned release before the due date). Returns 404 when no release is scheduled, so a cancel on an un-scheduled number is an explicit miss rather than a silent no-op. Org-ownership is enforced; scoped on numbers:write (owner / admin / developer).

string

required

—

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/numbers/{id}/scheduled-release" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/{id}/scheduled-release', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string",
    "scheduled_release": null
  },
  "meta": "string"
}

Delete a number application

DELETE /api/v1/numbers/applications/{id}

Delete a number application. Refuses with 409 while any DIDs are still bound so routing is never silently orphaned — unbind or re-bind them first. Org-scoped — an unknown or not-owned id returns 404. Owner/admin/developer only.

string

required

Number-application id.

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/numbers/applications/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/applications/{id}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string"
  },
  "meta": "string"
}

Cancel a hosted-messaging order

DELETE /api/v1/numbers/hosted-messaging/{id}

Cancel a hosted-messaging order that has not yet reached a terminal state (draft, loa_signed, or submitted). The order transitions to cancelled and the updated record is returned. Use this to abandon a text-enable request before the hosting carrier activates it. Requires the numbers:write scope.

string

required

Hosted-messaging order id.

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging/{id}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Cancel a port-in request

DELETE /api/v1/numbers/porting/{id}

Cancel an in-flight port-in request that is still in submitted or reviewing state, withdrawing it from the losing carrier where a provider order was dispatched. Once the carrier has approved the port the request can no longer be cancelled here (409) — cancellation must then go through the losing carrier’s own flow. Requires the numbers:write scope.

string

required

The port-in request id.

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/numbers/porting/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/porting/{id}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": "string",
  "meta": "string"
}

Delete a tracking pool

DELETE /api/v1/numbers/tracking-pools/{id}

Delete a tracking pool. Org-scoped — an unknown or not-owned id returns 404. Owner/admin/developer only.

string

required

Tracking-pool id.

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/numbers/tracking-pools/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/numbers/tracking-pools/{id}', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "string"
  },
  "meta": "string"
}

​Numbers API

​Worked sequences

​Sequence 1 — rent a number

​Sequence 2 — port a number in

​Error samples

​List phone numbers

​Get a phone number

​Get per-DID branded-calling (Rich Call Data) answer-rate uplift

​Get a number’s 10DLC campaign assignment

​Get a number’s CNAM registration

​List regulatory documents for a number

​Get the emergency (E911) address for a number

​Get the deliverability health score for a number

​Get the deliverability health trend and forecast for a number

​Get port-out PIN protection status for a number

​Get a Mexican number’s active telecom regulator

​Get the carrier spam-label reputation for a number

​Get the scheduled release for a number

​Get SMS spam-complaint feedback loop for a number

​Get the predictive spam-likelihood score for a number

​Get a toll-free number’s verification (TFV) status

​Get per-number call and message usage

​Get the 10DLC warming-tier state for a number

​Get the number-warming progression forecast

​List number applications

​Fetch one number application

​Get a bulk reservation’s status and items

​Fleet rollup across the SIM estate

​List eSIM / IoT connectivity data-plans

​Fetch one connectivity plan

​Estimate connectivity plan usage cost

​List provisioned SIMs

​Fetch one provisioned SIM

​Get SIM usage and recent sessions

​Get available-number capabilities for a country

​List dormant DID release candidates

​Export the number inventory as CSV or JSON

​List hosted-messaging orders

​Get a hosted-messaging order

​List low-stock DID inventory alerts

​Number-Intelligence lookup history & spend analytics

​Full phone number intelligence lookup

​List bulk number-provisioning orders

​Fetch one bulk number-provisioning order

​List port-in requests

​Get a port-in request’s status timeline

​List port-out requests

​List recoverable (snapback) numbers

​List carrier reputation alerts

​List tracking pools

​Fetch one tracking pool

​Preview the DNI swap number for a visitor

​Attach a compliance profile to a number

​Upload a document for a number’s requirement

​Refresh regulatory document statuses for a number

​Verify the emergency (E911) address for a number

​Submit a port-out request for a number

​Set or rotate the port-out PIN for a number

​Reactivate a suspended number

​Reassign a number to a sibling subaccount

​Reclaim a parked number during its grace window

​Repair a number’s partial provisioning

​Retry a failed number release

​Ingest an SMS spam-complaint report for a number

​Suspend an active number

​Submit or resubmit a toll-free number for verification (TFV)

​Create a number application

​Bind (or move) a DID to a number application

​Unbind a DID from a number application

​Bulk HLR lookup for up to 100 numbers

​Reserve a batch of numbers from a filter

​Cancel a bulk reservation (release held numbers)

​Finalize a bulk reservation (purchase held numbers)

​Buy multiple phone numbers in one request

​Claim a free trial number from the shared pool

​Order a SIM against a catalog plan

​Activate a SIM

​Apply or clear a SIM OTA profile

​Resume a SIM

​Suspend a SIM

Numbers API

Worked sequences

Sequence 1 — rent a number

Sequence 2 — port a number in

Error samples

List phone numbers

Get a phone number

Get per-DID branded-calling (Rich Call Data) answer-rate uplift

Get a number’s 10DLC campaign assignment

Get a number’s CNAM registration

List regulatory documents for a number

Get the emergency (E911) address for a number

Get the deliverability health score for a number

Get the deliverability health trend and forecast for a number

Get port-out PIN protection status for a number

Get a Mexican number’s active telecom regulator

Get the carrier spam-label reputation for a number

Get the scheduled release for a number

Get SMS spam-complaint feedback loop for a number

Get the predictive spam-likelihood score for a number

Get a toll-free number’s verification (TFV) status

Get per-number call and message usage

Get the 10DLC warming-tier state for a number

Get the number-warming progression forecast

List number applications

Fetch one number application

Get a bulk reservation’s status and items

Fleet rollup across the SIM estate

List eSIM / IoT connectivity data-plans

Fetch one connectivity plan

Estimate connectivity plan usage cost

List provisioned SIMs

Fetch one provisioned SIM

Get SIM usage and recent sessions

Get available-number capabilities for a country

List dormant DID release candidates

Export the number inventory as CSV or JSON

List hosted-messaging orders

Get a hosted-messaging order

List low-stock DID inventory alerts

Number-Intelligence lookup history & spend analytics

Full phone number intelligence lookup

List bulk number-provisioning orders

Fetch one bulk number-provisioning order

List port-in requests

Get a port-in request’s status timeline

List port-out requests

List recoverable (snapback) numbers

List carrier reputation alerts

List tracking pools

Fetch one tracking pool

Preview the DNI swap number for a visitor

Attach a compliance profile to a number

Upload a document for a number’s requirement

Refresh regulatory document statuses for a number

Verify the emergency (E911) address for a number

Submit a port-out request for a number

Set or rotate the port-out PIN for a number

Reactivate a suspended number

Reassign a number to a sibling subaccount

Reclaim a parked number during its grace window

Repair a number’s partial provisioning

Retry a failed number release

Ingest an SMS spam-complaint report for a number

Suspend an active number

Submit or resubmit a toll-free number for verification (TFV)

Create a number application

Bind (or move) a DID to a number application

Unbind a DID from a number application

Bulk HLR lookup for up to 100 numbers

Reserve a batch of numbers from a filter

Cancel a bulk reservation (release held numbers)

Finalize a bulk reservation (purchase held numbers)

Buy multiple phone numbers in one request

Claim a free trial number from the shared pool

Order a SIM against a catalog plan

Activate a SIM

Apply or clear a SIM OTA profile

Resume a SIM

Suspend a SIM