Numbers

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.

API Reference

All Endpoints

Worked sequences

Sequence 1 — rent a number

Sequence 2 — port a number in

Error samples

​Worked sequences

​Sequence 1 — rent a number

​Sequence 2 — port a number in

​Error samples

Worked sequences

Sequence 1 — rent a number

Sequence 2 — port a number in

Error samples