Open a short-code application
curl --request POST \
--url https://api.orbit.devotel.io/api/v1/numbers/short-codes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"countryCode": "US",
"leaseType": "dedicated",
"selection": "random",
"leaseTermMonths": 12,
"businessName": "Acme Inc",
"programBrief": {
"useCase": "2FA",
"description": "One-time passcodes for account sign-in and password resets.",
"sampleMessages": [
"Your Acme verification code is 481920. It expires in 10 minutes."
],
"messageFrequency": "1-3 messages per login attempt",
"optInDescription": "Subscribers opt in during sign-up by checking the SMS-verification box.",
"supportContact": "support@acme.example",
"privacyPolicyUrl": "https://acme.example/privacy",
"termsUrl": "https://acme.example/terms"
}
}
'import requests
url = "https://api.orbit.devotel.io/api/v1/numbers/short-codes"
payload = {
"countryCode": "US",
"leaseType": "dedicated",
"selection": "random",
"leaseTermMonths": 12,
"businessName": "Acme Inc",
"programBrief": {
"useCase": "2FA",
"description": "One-time passcodes for account sign-in and password resets.",
"sampleMessages": ["Your Acme verification code is 481920. It expires in 10 minutes."],
"messageFrequency": "1-3 messages per login attempt",
"optInDescription": "Subscribers opt in during sign-up by checking the SMS-verification box.",
"supportContact": "support@acme.example",
"privacyPolicyUrl": "https://acme.example/privacy",
"termsUrl": "https://acme.example/terms"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
countryCode: 'US',
leaseType: 'dedicated',
selection: 'random',
leaseTermMonths: 12,
businessName: 'Acme Inc',
programBrief: {
useCase: '2FA',
description: 'One-time passcodes for account sign-in and password resets.',
sampleMessages: ['Your Acme verification code is 481920. It expires in 10 minutes.'],
messageFrequency: '1-3 messages per login attempt',
optInDescription: 'Subscribers opt in during sign-up by checking the SMS-verification box.',
supportContact: 'support@acme.example',
privacyPolicyUrl: 'https://acme.example/privacy',
termsUrl: 'https://acme.example/terms'
}
})
};
fetch('https://api.orbit.devotel.io/api/v1/numbers/short-codes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.orbit.devotel.io/api/v1/numbers/short-codes",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'countryCode' => 'US',
'leaseType' => 'dedicated',
'selection' => 'random',
'leaseTermMonths' => 12,
'businessName' => 'Acme Inc',
'programBrief' => [
'useCase' => '2FA',
'description' => 'One-time passcodes for account sign-in and password resets.',
'sampleMessages' => [
'Your Acme verification code is 481920. It expires in 10 minutes.'
],
'messageFrequency' => '1-3 messages per login attempt',
'optInDescription' => 'Subscribers opt in during sign-up by checking the SMS-verification box.',
'supportContact' => 'support@acme.example',
'privacyPolicyUrl' => 'https://acme.example/privacy',
'termsUrl' => 'https://acme.example/terms'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.orbit.devotel.io/api/v1/numbers/short-codes"
payload := strings.NewReader("{\n \"countryCode\": \"US\",\n \"leaseType\": \"dedicated\",\n \"selection\": \"random\",\n \"leaseTermMonths\": 12,\n \"businessName\": \"Acme Inc\",\n \"programBrief\": {\n \"useCase\": \"2FA\",\n \"description\": \"One-time passcodes for account sign-in and password resets.\",\n \"sampleMessages\": [\n \"Your Acme verification code is 481920. It expires in 10 minutes.\"\n ],\n \"messageFrequency\": \"1-3 messages per login attempt\",\n \"optInDescription\": \"Subscribers opt in during sign-up by checking the SMS-verification box.\",\n \"supportContact\": \"support@acme.example\",\n \"privacyPolicyUrl\": \"https://acme.example/privacy\",\n \"termsUrl\": \"https://acme.example/terms\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.orbit.devotel.io/api/v1/numbers/short-codes")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"countryCode\": \"US\",\n \"leaseType\": \"dedicated\",\n \"selection\": \"random\",\n \"leaseTermMonths\": 12,\n \"businessName\": \"Acme Inc\",\n \"programBrief\": {\n \"useCase\": \"2FA\",\n \"description\": \"One-time passcodes for account sign-in and password resets.\",\n \"sampleMessages\": [\n \"Your Acme verification code is 481920. It expires in 10 minutes.\"\n ],\n \"messageFrequency\": \"1-3 messages per login attempt\",\n \"optInDescription\": \"Subscribers opt in during sign-up by checking the SMS-verification box.\",\n \"supportContact\": \"support@acme.example\",\n \"privacyPolicyUrl\": \"https://acme.example/privacy\",\n \"termsUrl\": \"https://acme.example/terms\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.orbit.devotel.io/api/v1/numbers/short-codes")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"countryCode\": \"US\",\n \"leaseType\": \"dedicated\",\n \"selection\": \"random\",\n \"leaseTermMonths\": 12,\n \"businessName\": \"Acme Inc\",\n \"programBrief\": {\n \"useCase\": \"2FA\",\n \"description\": \"One-time passcodes for account sign-in and password resets.\",\n \"sampleMessages\": [\n \"Your Acme verification code is 481920. It expires in 10 minutes.\"\n ],\n \"messageFrequency\": \"1-3 messages per login attempt\",\n \"optInDescription\": \"Subscribers opt in during sign-up by checking the SMS-verification box.\",\n \"supportContact\": \"support@acme.example\",\n \"privacyPolicyUrl\": \"https://acme.example/privacy\",\n \"termsUrl\": \"https://acme.example/terms\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "shortcode_01J9Z8ABCDEF",
"countryCode": "US",
"leaseType": "dedicated",
"selection": "random",
"requestedCode": null,
"assignedCode": null,
"leaseTermMonths": 12,
"status": "draft",
"businessName": "Acme Inc",
"createdAt": "2026-08-11T12:00:00.000Z",
"updatedAt": "2026-08-11T12:00:00.000Z"
},
"meta": {
"request_id": "req_01J9Z8ABCDEF",
"timestamp": "2026-08-11T12:00:00.000Z"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "<string>",
"status": 429,
"retry_after": 2
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}Numbers
Open a short-code application
Open a new SMS short-code leasing application (draft) for the organization, capturing the destination country, lease type and term, and the CTIA program brief. The application starts in draft, so the brief can still be edited with PATCH /numbers/short-codes/{id}/brief until it is submitted for carrier vetting; a vanity selection also requires requestedCode. Returns the created draft application. Provisioning lifecycle only — no outbound (MT) SMS path is created (invariant #45).
POST
/
api
/
v1
/
numbers
/
short-codes
Open a short-code application
curl --request POST \
--url https://api.orbit.devotel.io/api/v1/numbers/short-codes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"countryCode": "US",
"leaseType": "dedicated",
"selection": "random",
"leaseTermMonths": 12,
"businessName": "Acme Inc",
"programBrief": {
"useCase": "2FA",
"description": "One-time passcodes for account sign-in and password resets.",
"sampleMessages": [
"Your Acme verification code is 481920. It expires in 10 minutes."
],
"messageFrequency": "1-3 messages per login attempt",
"optInDescription": "Subscribers opt in during sign-up by checking the SMS-verification box.",
"supportContact": "support@acme.example",
"privacyPolicyUrl": "https://acme.example/privacy",
"termsUrl": "https://acme.example/terms"
}
}
'import requests
url = "https://api.orbit.devotel.io/api/v1/numbers/short-codes"
payload = {
"countryCode": "US",
"leaseType": "dedicated",
"selection": "random",
"leaseTermMonths": 12,
"businessName": "Acme Inc",
"programBrief": {
"useCase": "2FA",
"description": "One-time passcodes for account sign-in and password resets.",
"sampleMessages": ["Your Acme verification code is 481920. It expires in 10 minutes."],
"messageFrequency": "1-3 messages per login attempt",
"optInDescription": "Subscribers opt in during sign-up by checking the SMS-verification box.",
"supportContact": "support@acme.example",
"privacyPolicyUrl": "https://acme.example/privacy",
"termsUrl": "https://acme.example/terms"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
countryCode: 'US',
leaseType: 'dedicated',
selection: 'random',
leaseTermMonths: 12,
businessName: 'Acme Inc',
programBrief: {
useCase: '2FA',
description: 'One-time passcodes for account sign-in and password resets.',
sampleMessages: ['Your Acme verification code is 481920. It expires in 10 minutes.'],
messageFrequency: '1-3 messages per login attempt',
optInDescription: 'Subscribers opt in during sign-up by checking the SMS-verification box.',
supportContact: 'support@acme.example',
privacyPolicyUrl: 'https://acme.example/privacy',
termsUrl: 'https://acme.example/terms'
}
})
};
fetch('https://api.orbit.devotel.io/api/v1/numbers/short-codes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.orbit.devotel.io/api/v1/numbers/short-codes",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'countryCode' => 'US',
'leaseType' => 'dedicated',
'selection' => 'random',
'leaseTermMonths' => 12,
'businessName' => 'Acme Inc',
'programBrief' => [
'useCase' => '2FA',
'description' => 'One-time passcodes for account sign-in and password resets.',
'sampleMessages' => [
'Your Acme verification code is 481920. It expires in 10 minutes.'
],
'messageFrequency' => '1-3 messages per login attempt',
'optInDescription' => 'Subscribers opt in during sign-up by checking the SMS-verification box.',
'supportContact' => 'support@acme.example',
'privacyPolicyUrl' => 'https://acme.example/privacy',
'termsUrl' => 'https://acme.example/terms'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.orbit.devotel.io/api/v1/numbers/short-codes"
payload := strings.NewReader("{\n \"countryCode\": \"US\",\n \"leaseType\": \"dedicated\",\n \"selection\": \"random\",\n \"leaseTermMonths\": 12,\n \"businessName\": \"Acme Inc\",\n \"programBrief\": {\n \"useCase\": \"2FA\",\n \"description\": \"One-time passcodes for account sign-in and password resets.\",\n \"sampleMessages\": [\n \"Your Acme verification code is 481920. It expires in 10 minutes.\"\n ],\n \"messageFrequency\": \"1-3 messages per login attempt\",\n \"optInDescription\": \"Subscribers opt in during sign-up by checking the SMS-verification box.\",\n \"supportContact\": \"support@acme.example\",\n \"privacyPolicyUrl\": \"https://acme.example/privacy\",\n \"termsUrl\": \"https://acme.example/terms\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.orbit.devotel.io/api/v1/numbers/short-codes")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"countryCode\": \"US\",\n \"leaseType\": \"dedicated\",\n \"selection\": \"random\",\n \"leaseTermMonths\": 12,\n \"businessName\": \"Acme Inc\",\n \"programBrief\": {\n \"useCase\": \"2FA\",\n \"description\": \"One-time passcodes for account sign-in and password resets.\",\n \"sampleMessages\": [\n \"Your Acme verification code is 481920. It expires in 10 minutes.\"\n ],\n \"messageFrequency\": \"1-3 messages per login attempt\",\n \"optInDescription\": \"Subscribers opt in during sign-up by checking the SMS-verification box.\",\n \"supportContact\": \"support@acme.example\",\n \"privacyPolicyUrl\": \"https://acme.example/privacy\",\n \"termsUrl\": \"https://acme.example/terms\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.orbit.devotel.io/api/v1/numbers/short-codes")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"countryCode\": \"US\",\n \"leaseType\": \"dedicated\",\n \"selection\": \"random\",\n \"leaseTermMonths\": 12,\n \"businessName\": \"Acme Inc\",\n \"programBrief\": {\n \"useCase\": \"2FA\",\n \"description\": \"One-time passcodes for account sign-in and password resets.\",\n \"sampleMessages\": [\n \"Your Acme verification code is 481920. It expires in 10 minutes.\"\n ],\n \"messageFrequency\": \"1-3 messages per login attempt\",\n \"optInDescription\": \"Subscribers opt in during sign-up by checking the SMS-verification box.\",\n \"supportContact\": \"support@acme.example\",\n \"privacyPolicyUrl\": \"https://acme.example/privacy\",\n \"termsUrl\": \"https://acme.example/terms\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "shortcode_01J9Z8ABCDEF",
"countryCode": "US",
"leaseType": "dedicated",
"selection": "random",
"requestedCode": null,
"assignedCode": null,
"leaseTermMonths": 12,
"status": "draft",
"businessName": "Acme Inc",
"createdAt": "2026-08-11T12:00:00.000Z",
"updatedAt": "2026-08-11T12:00:00.000Z"
},
"meta": {
"request_id": "req_01J9Z8ABCDEF",
"timestamp": "2026-08-11T12:00:00.000Z"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "<string>",
"status": 429,
"retry_after": 2
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"status": 123,
"details": {}
},
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"docs_url": "<string>"
}
}Authorizations
BearerApiKey
Dashboard JWT token from Clerk
Headers
Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.
Required string length:
1 - 255Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
Available options:
true, false Body
application/json
The short-code lease request plus the CTIA program brief carriers vet.
The short-code lease request plus the CTIA program brief carriers vet.
ISO-3166 alpha-2 country to provision the code in.
dedicated leases the code to this program alone; shared pools it across programs.
random accepts any available code; vanity requests the specific requestedCode.
The requested vanity code (3-6 digits). Required when selection is vanity, ignored otherwise.
Lease term in months — one of 3, 6, or 12.
Legal business name carriers vet the program against.
The CTIA program brief carriers vet.
Show child attributes
Show child attributes