Resolve rotations and plan escalations

On-call tooling and the incident driver both live behind these two endpoints — the call resolves who is accountable at a given instant, and the plan flattens the escalation ladder you would walk when an incident refuses an ACK. Both are pure compute: nothing is persisted, no pages are sent, and no state changes. An incident driver (the webhook-worker escalation scheduler) still fires pages through the notify channel downstream. Resolve a rotation. POST /api/v1/oncall/resolve answers “who is on call now” — a rotation is a fixed-length shift schedule anchored to an absolute start (anchor), with members rotating through it in order.

{
  "data": {
    "rotation_name": "core-rotation",
    "at": "2026-08-01T12:00:00.000Z",
    "on_call": "+14155552671",
    "shift_index": 12,
    "shift_start": "2026-07-31T12:00:00.000Z",
    "shift_end": "2026-08-01T12:00:00.000Z",
    "next_on_call": "+14155559900",
    "next_handoff_at": "2026-08-01T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_resolve",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Plan an escalation. POST /api/v1/oncall/escalation/plan flattens the policy into the ordered pages timeline: each step names a target (a live rotation resolved at the page’s fire instant, or a static member list), the channels paged, and the escalate_after_seconds window before the next step. Each layer of the walk fires at a cumulative offsetSeconds from the incident start; policy.repeat loops the whole policy that many extra times if no step is ever acknowledged.

{
  "data": {
    "policy_name": "core-support",
    "start_at": "2026-08-01T12:00:00.000Z",
    "total_pages": 4,
    "pages": [
      {
        "round": 0,
        "step": 0,
        "offset_seconds": 0,
        "fire_at": "2026-08-01T12:00:00.000Z",
        "targets": ["+14155552671"],
        "channels": ["sms"]
      },
      {
        "round": 0,
        "step": 1,
        "offset_seconds": 300,
        "fire_at": "2026-08-01T12:05:00.000Z",
        "targets": ["oncall-secondary"],
        "channels": ["voice", "sms"]
      }
    ]
  },
  "meta": {
    "request_id": "req_plan",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Rotation targets resolve at each page’s fire instant, so a hand-off that lands mid-escalation reaches the right human.

Sandbox-mode request quickstart

The two calls below authenticate the way a test-mode client call should — set ORBIT_API_KEY to your dv_test_sk_… value and every curl/SDK sample on this page runs against the sandbox with no carrier spend. The key prefix decides the mode: with API-key auth the X-Test-Mode header is not consulted (only a session-authenticated dashboard call honors it), and a live-prefixed key (dv_live_sk_…) always runs live. For voice recipients in a page-down or skip-rank drill, aim at a sandbox magic number so the routing is deterministic instead of hitting a live handset. The full routing matrix (session auth vs key auth vs sandbox orgs) is in Sandbox and test mode, and the Quality endpoint overlay carries the same per-request pattern worked against a read endpoint — copy either form and your key handling stays sandbox-safe.

SDK surface bridge — List the on-call rotation and take a live skip-rank claim — both read (or mutate) through the SDK escape hatch with the tenant’s live key.

These three tabs mirror SDK status and coverage. Python fronts client.request, Go fronts client.Request, and TS fronts fetch-TS — each with the live key.

List the on-call rotation

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/telephony/carriers/oncall" \
  -H "X-API-Key: ORBIT_API_KEY"

fetch-TS (Node SDK style)

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

client.request

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

client.Request

package main

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

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

Claim the next slot (skip cycle)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/telephony/carriers/oncall/skip-rank" \
  -H "X-API-Key: ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "cycle": "next"
}'

fetch-TS (Node SDK style)

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

client.request

r = requests.post("https://api.orbit.devotel.io/api/v1/telephony/carriers/oncall/skip-rank", json={
  "cycle": "next"
}, headers={ "X-API-Key": os.environ["ORBIT_API_KEY"] })
print(r.json())

client.Request

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/telephony/carriers/oncall/skip-rank", bytes.NewBuffer([]byte(`{
  "cycle": "next"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

API Reference

All Endpoints

Resolve rotations and plan escalations