Create a new SIP credential

curl --request POST \
  --url https://api.orbit.devotel.io/api/v1/sip-credentials \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "label": "front-desk",
  "extensionNumber": "101",
  "outboundEnabled": true,
  "outboundCallerIdMode": "fixed",
  "defaultCallerIdE164": "+14155550123",
  "concurrentCallCap": 2,
  "allowedIpCidrs": [
    "203.0.113.0/24"
  ],
  "notes": "Lobby desk phone, Yealink T54W"
}
'

import requests

url = "https://api.orbit.devotel.io/api/v1/sip-credentials"

payload = {
    "label": "front-desk",
    "extensionNumber": "101",
    "outboundEnabled": True,
    "outboundCallerIdMode": "fixed",
    "defaultCallerIdE164": "+14155550123",
    "concurrentCallCap": 2,
    "allowedIpCidrs": ["203.0.113.0/24"],
    "notes": "Lobby desk phone, Yealink T54W"
}
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({
    label: 'front-desk',
    extensionNumber: '101',
    outboundEnabled: true,
    outboundCallerIdMode: 'fixed',
    defaultCallerIdE164: '+14155550123',
    concurrentCallCap: 2,
    allowedIpCidrs: ['203.0.113.0/24'],
    notes: 'Lobby desk phone, Yealink T54W'
  })
};

fetch('https://api.orbit.devotel.io/api/v1/sip-credentials', 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/sip-credentials",
  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([
    'label' => 'front-desk',
    'extensionNumber' => '101',
    'outboundEnabled' => true,
    'outboundCallerIdMode' => 'fixed',
    'defaultCallerIdE164' => '+14155550123',
    'concurrentCallCap' => 2,
    'allowedIpCidrs' => [
        '203.0.113.0/24'
    ],
    'notes' => 'Lobby desk phone, Yealink T54W'
  ]),
  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/sip-credentials"

	payload := strings.NewReader("{\n  \"label\": \"front-desk\",\n  \"extensionNumber\": \"101\",\n  \"outboundEnabled\": true,\n  \"outboundCallerIdMode\": \"fixed\",\n  \"defaultCallerIdE164\": \"+14155550123\",\n  \"concurrentCallCap\": 2,\n  \"allowedIpCidrs\": [\n    \"203.0.113.0/24\"\n  ],\n  \"notes\": \"Lobby desk phone, Yealink T54W\"\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/sip-credentials")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"label\": \"front-desk\",\n  \"extensionNumber\": \"101\",\n  \"outboundEnabled\": true,\n  \"outboundCallerIdMode\": \"fixed\",\n  \"defaultCallerIdE164\": \"+14155550123\",\n  \"concurrentCallCap\": 2,\n  \"allowedIpCidrs\": [\n    \"203.0.113.0/24\"\n  ],\n  \"notes\": \"Lobby desk phone, Yealink T54W\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.orbit.devotel.io/api/v1/sip-credentials")

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  \"label\": \"front-desk\",\n  \"extensionNumber\": \"101\",\n  \"outboundEnabled\": true,\n  \"outboundCallerIdMode\": \"fixed\",\n  \"defaultCallerIdE164\": \"+14155550123\",\n  \"concurrentCallCap\": 2,\n  \"allowedIpCidrs\": [\n    \"203.0.113.0/24\"\n  ],\n  \"notes\": \"Lobby desk phone, Yealink T54W\"\n}"

response = http.request(request)
puts response.read_body

{}

{
  "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>"
  }
}

POST

api

sip-credentials

Create a new SIP credential

curl --request POST \
  --url https://api.orbit.devotel.io/api/v1/sip-credentials \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "label": "front-desk",
  "extensionNumber": "101",
  "outboundEnabled": true,
  "outboundCallerIdMode": "fixed",
  "defaultCallerIdE164": "+14155550123",
  "concurrentCallCap": 2,
  "allowedIpCidrs": [
    "203.0.113.0/24"
  ],
  "notes": "Lobby desk phone, Yealink T54W"
}
'

import requests

url = "https://api.orbit.devotel.io/api/v1/sip-credentials"

payload = {
    "label": "front-desk",
    "extensionNumber": "101",
    "outboundEnabled": True,
    "outboundCallerIdMode": "fixed",
    "defaultCallerIdE164": "+14155550123",
    "concurrentCallCap": 2,
    "allowedIpCidrs": ["203.0.113.0/24"],
    "notes": "Lobby desk phone, Yealink T54W"
}
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({
    label: 'front-desk',
    extensionNumber: '101',
    outboundEnabled: true,
    outboundCallerIdMode: 'fixed',
    defaultCallerIdE164: '+14155550123',
    concurrentCallCap: 2,
    allowedIpCidrs: ['203.0.113.0/24'],
    notes: 'Lobby desk phone, Yealink T54W'
  })
};

fetch('https://api.orbit.devotel.io/api/v1/sip-credentials', 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/sip-credentials",
  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([
    'label' => 'front-desk',
    'extensionNumber' => '101',
    'outboundEnabled' => true,
    'outboundCallerIdMode' => 'fixed',
    'defaultCallerIdE164' => '+14155550123',
    'concurrentCallCap' => 2,
    'allowedIpCidrs' => [
        '203.0.113.0/24'
    ],
    'notes' => 'Lobby desk phone, Yealink T54W'
  ]),
  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/sip-credentials"

	payload := strings.NewReader("{\n  \"label\": \"front-desk\",\n  \"extensionNumber\": \"101\",\n  \"outboundEnabled\": true,\n  \"outboundCallerIdMode\": \"fixed\",\n  \"defaultCallerIdE164\": \"+14155550123\",\n  \"concurrentCallCap\": 2,\n  \"allowedIpCidrs\": [\n    \"203.0.113.0/24\"\n  ],\n  \"notes\": \"Lobby desk phone, Yealink T54W\"\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/sip-credentials")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"label\": \"front-desk\",\n  \"extensionNumber\": \"101\",\n  \"outboundEnabled\": true,\n  \"outboundCallerIdMode\": \"fixed\",\n  \"defaultCallerIdE164\": \"+14155550123\",\n  \"concurrentCallCap\": 2,\n  \"allowedIpCidrs\": [\n    \"203.0.113.0/24\"\n  ],\n  \"notes\": \"Lobby desk phone, Yealink T54W\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.orbit.devotel.io/api/v1/sip-credentials")

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  \"label\": \"front-desk\",\n  \"extensionNumber\": \"101\",\n  \"outboundEnabled\": true,\n  \"outboundCallerIdMode\": \"fixed\",\n  \"defaultCallerIdE164\": \"+14155550123\",\n  \"concurrentCallCap\": 2,\n  \"allowedIpCidrs\": [\n    \"203.0.113.0/24\"\n  ],\n  \"notes\": \"Lobby desk phone, Yealink T54W\"\n}"

response = http.request(request)
puts response.read_body

{}

{
  "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

Authorization

string

header

required

Dashboard JWT token from Clerk

Headers

Idempotency-Key

string

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 - 255

X-Test-Mode

enum<string>

Sandbox 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

Credential settings. label is the only required field — everything else has a platform default. Bounds are validated by the endpoint and reported as a 422 naming the field.

label

string

Required. Device label, 1-32 characters. Lowercased and slugified into the SIP username (<org-prefix>-<label>), which stays stable across password rotations.

extensionNumber

string

Internal extension, 2-8 characters of digits, * or #. Unique per organization.

outboundEnabled

boolean

Whether the device may place outbound calls. Defaults to true.

outboundCallerIdMode

enum<string>

How the From: number is chosen on outbound calls: fixed always uses defaultCallerIdE164, pick_from_owned lets the device send any number you own, inherit_org uses the organization default. Defaults to fixed.

Available options:

fixed,

pick_from_owned,

inherit_org

defaultCallerIdE164

string

E.164 number presented as the caller ID, for example +14155550123. Must be a number your organization owns, otherwise the request is rejected with 403.

outboundDailySpendCapCents

integer

Daily outbound spend ceiling for this device, in cents (0-100000). Omit for no cap.

outboundBlockedCountries

string[]

ISO 3166-1 alpha-2 country codes this device may not dial, for example RU or KP. Up to 50 entries.

concurrentCallCap

integer

Maximum simultaneous calls for this device (1-100). Omit for no cap.

expiresAt

string

ISO 8601 timestamp after which the credential stops authenticating, for example 2027-01-31T00:00:00Z. Useful for contractor or seasonal devices.

dnd

boolean

Create the device in do-not-disturb, so inbound calls skip it. Defaults to false.

forceCodec

enum<string>

Pin media to a single codec instead of negotiating. Leave unset unless the handset misbehaves during negotiation.

Available options:

PCMU,

PCMA,

OPUS,

G722,

AMR-WB

forceRecordInbound

boolean

Always record inbound calls to this device.

forceRecordOutbound

boolean

Always record outbound calls from this device.

forwardBusyToUsername

string

SIP username in the same organization that inbound calls ring when this device is busy.

forwardNoAnswerToUsername

string

SIP username in the same organization that inbound calls ring when this device does not answer.

forwardUnavailableToUsername

string

SIP username in the same organization that inbound calls ring when this device is not registered.

allowedIpCidrs

string[]

Source IP allow-list in CIDR notation, up to 20 entries. Omit to accept registrations from any address.

allowedUserAgent

string

Lock the credential to one SIP User-Agent string, for example Bria 6. Registrations from any other client are refused.

voicemailPin

string

4-8 digit passcode the handset must key in on the *97 voicemail dial-in. Stored hashed and never returned; the read endpoints only report whether one is set.

notes

string

Free-text note kept with the credential, up to 1000 characters.

Response

The created credential with the plaintext password (shown once), connection details (sip_server, sip_realm, sip_port_tls, sip_port_tcp), and metadata inside the standard { data, meta } envelope.

API Reference

All Endpoints

Create a new SIP credential

Authorizations

Headers

Body

Response