{
  "data": {
    "rules": [
      {
        "match_kind": "pstn",
        "match_value": "+442071234567",
        "pattern": "vip",
        "label": "Front desk"
      },
      {
        "match_kind": "prefix",
        "match_value": "+1800",
        "pattern": "priority",
        "label": "Toll-free callers"
      }
    ],
    "patterns": [
      { "id": "standard", "label": "Standard ring", "alertInfo": null, "priority": false },
      { "id": "priority", "label": "Priority alert", "alertInfo": "info=alert-priority", "priority": true },
      { "id": "urgent", "label": "Urgent alert", "alertInfo": "info=alert-urgent", "priority": true },
      { "id": "vip", "label": "VIP ring", "alertInfo": "info=alert-vip", "priority": true },
      { "id": "internal", "label": "Internal ring", "alertInfo": "info=alert-internal", "priority": false },
      { "id": "external", "label": "External ring", "alertInfo": "info=alert-external", "priority": false }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

{
  "data": {
    "rules": [
      {
        "match_kind": "pstn",
        "match_value": "+442071234567",
        "pattern": "vip",
        "label": "Front desk"
      },
      {
        "match_kind": "prefix",
        "match_value": "+1800",
        "pattern": "priority",
        "label": "Toll-free callers"
      }
    ],
    "patterns": [
      { "id": "standard", "label": "Standard ring", "alertInfo": null, "priority": false },
      { "id": "priority", "label": "Priority alert", "alertInfo": "info=alert-priority", "priority": true },
      { "id": "urgent", "label": "Urgent alert", "alertInfo": "info=alert-urgent", "priority": true },
      { "id": "vip", "label": "VIP ring", "alertInfo": "info=alert-vip", "priority": true },
      { "id": "internal", "label": "Internal ring", "alertInfo": "info=alert-internal", "priority": false },
      { "id": "external", "label": "External ring", "alertInfo": "info=alert-external", "priority": false }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Me API

Me endpoints exposed by the Devotel CPaaS API Base path: /api/v1/me Endpoint count: 14

Working with this group

Every operation under /me reads or writes only the authenticated caller’s own resources: profile preferences, speed-dial favorites, saved campaign drafts, report history, recommendation drafts, and ring rules. The credential on the request determines the tenant: an API key (dv_live_sk_* or dv_test_sk_*) resolves to the organization that owns the key, while a dashboard session resolves to the organization the signed-in user is currently working in.

First call: the identity probe

GET /api/v1/me is the first call every SDK quick start makes: it proves the credential works and returns the identity, organization id, and plan that every later request acts under. Authorization is role-based, so the response carries the caller’s role on the user object and per organization; there is no per-call scope list to request.

cURL

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

200

{
  "data": {
    "user": {
      "id": "user_01J9VKD3Q8N2XW7R4T6YB5E0M1",
      "email": "ada@example.com",
      "name": "Ada Okafor",
      "image": null,
      "role": "admin",
      "emailVerified": true,
      "twoFactorEnabled": true,
      "softphone_layout": "compact_bottom_bar",
      "voicemail_to_email_enabled": false,
      "voicemail_to_email_address": null,
      "inbox_signature": "Ada Okafor\nExample Coffee Roasters",
      "inbox_show_archived_tags": false
    },
    "tenant": {
      "id": "org_01J9Z2H4K5P8Q1S3T6V9W2X4Y7",
      "name": "Example Coffee Roasters",
      "slug": "example-coffee",
      "plan": "growth",
      "logoUrl": null
    },
    "organizations": [
      {
        "id": "org_01J9Z2H4K5P8Q1S3T6V9W2X4Y7",
        "name": "Example Coffee Roasters",
        "slug": "example-coffee",
        "logoUrl": null,
        "role": "admin"
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX9T2K8V5N3J6D1M4A7B0C",
    "timestamp": "2026-10-15T09:12:44.000Z"
  }
}

List saved campaign drafts from any SDK

GET /api/v1/me/campaign-drafts returns the caller’s saved AI campaign drafts in data.drafts. The history is capped at 50 drafts, so the full list arrives in one response and there is no cursor to follow; meta carries the correlation fields only. The same call in four styles:

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

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

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

const res = await orbit.request('GET', '/me/campaign-drafts')
console.log(res.data.drafts)

import os
from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/me/campaign-drafts")
print(res["data"]["drafts"])

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

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

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

200

{
  "data": {
    "drafts": [
      {
        "id": "draft_7f3a91c2e4b0",
        "name": "Spring re-engagement",
        "brief": "Win back customers inactive for 90 days with a 15% comeback offer.",
        "draft": {
          "headline": "We miss you — here's 15% off your next order",
          "sms": "Example Co.: your 15% comeback offer is ready. Reply STOP to opt out.",
          "email": "Hi {{first_name}}, it's been a while — enjoy 15% off this week."
        },
        "channels": ["sms", "email"],
        "createdAt": 1791936000000,
        "updatedAt": 1792022400000
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Correlating a request

Every response on this page repeats meta.request_id, a server-generated id for exactly one request. Quote it when reporting a failed call or reading your request logs: support and diagnostics resolve it to the same request across services. meta.timestamp is the server time the response was produced.

title: “Worked identity and org-context samples” description: “The startup introspection chain — call GET /me, read identity + tenant + memberships, decide on the caller’s role — plus a worked sweep of the per-user me/* resources (ring rules, favorites, campaign drafts, generated reports) and the authentication failures this probe surfaces first.”

Worked identity and org-context samples

Bootstrap the session, then decide: call GET /api/v1/me at startup before touching any resource operation, read data.user, data.tenant, and data.organizations out of the same envelope, and branch on the caller’s role before you call a write path. Every signed-in client resolves identity through this probe — the dashboard’s org picker and the mobile client both bootstrap from it. Cache the response per session, keep meta.request_id for support correlation, and re-fetch only on org switch or role change.

Worked sequence: dashboard-adjacent operator reads

The me/* GETs below are the per-user state the dashboard piles onto the post-login bootstrap: distinctive-ring rules, speed-dial favorites, saved AI campaign drafts, and generated-report history. Chain them in this order so a mobile or API client can render the operator’s own resources in one sweep; a drafted campaign row travels as one entry of data.drafts[] with the brief, the generated copy, and the target channels.

// 1. Ring rules — distinctive ringing on inbound callers.
const ring = await fetch("https://api.orbit.devotel.io/api/v1/me/ring-rules", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
}).then((r) => r.json());
// ring.data.rules → the caller's rules; ring.data.patterns → picker catalog.

// 2. Favorites — one-tap dial targets on the dialpad.
const favorites = await fetch(
  "https://api.orbit.devotel.io/api/v1/me/favorites",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
).then((r) => r.json());
// favorites.data.favorites → ordered one-tap targets.

// 3. Campaign drafts — the AI Studio draft history.
const drafts = await fetch(
  "https://api.orbit.devotel.io/api/v1/me/campaign-drafts",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
).then((r) => r.json());
// drafts.data.drafts → one entry per saved draft ({ id, name, brief, draft, channels }).

// 4. Generated reports — the Insights → Reports run history (metadata only).
const reports = await fetch(
  "https://api.orbit.devotel.io/api/v1/me/generated-reports",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
).then((r) => r.json());
// reports.data.reports → metadata rows; row-level content stays client-side.

A drafted campaign row — one entry of data.drafts[] from the third call above (the generated blueprint is null when the row was saved brief-only):

{
  "id": "draft_8b0d2f4a6c8e0b2d4f6a",
  "name": "Q4 re-engagement — lapsed SMS",
  "brief": "Win back lapsed SMS customers with a 10% offer before holiday spend starts",
  "draft": {
    "sms_headline": "Come back for 10% off",
    "sms_body": "We miss you — 10% off your next order, ends Saturday."
  },
  "channels": ["sms"],
  "createdAt": 1755860400125,
  "updatedAt": 1755860400125
}

Each sweep is scoped to the signed-in operator only — a leaked row id from another user never resolves. Empty state is an empty array (or data.draft: null on the Recommendations tester), so render your empty-view CTA rather than a table skeleton.

Worked reads — ring rules and favorites

Each per-user read below is the second leg of the worked sequence: the GET the bootstrap chain fires, paired with the envelope it answers. Chain them after GET /me resolves the caller.

Ring rules — the caller’s distinctive-ring rules

GET /api/v1/me/ring-rules

Distinctive-ring rules map an inbound-caller match to the ring pattern the softphone plays; data.patterns is the picker catalog the dashboard renders for the rule editor. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/ring-rules" \
  -H "X-API-Key: $ORBIT_API_KEY"

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/me/ring-rules", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
console.log(await res.json());

Response

{
  "data": {
    "rules": [
      {
        "match_kind": "pstn",
        "match_value": "+442071234567",
        "pattern": "vip",
        "label": "Front desk"
      },
      {
        "match_kind": "prefix",
        "match_value": "+1800",
        "pattern": "priority",
        "label": "Toll-free callers"
      }
    ],
    "patterns": [
      { "id": "standard", "label": "Standard ring", "alertInfo": null, "priority": false },
      { "id": "priority", "label": "Priority alert", "alertInfo": "info=alert-priority", "priority": true },
      { "id": "urgent", "label": "Urgent alert", "alertInfo": "info=alert-urgent", "priority": true },
      { "id": "vip", "label": "VIP ring", "alertInfo": "info=alert-vip", "priority": true },
      { "id": "internal", "label": "Internal ring", "alertInfo": "info=alert-internal", "priority": false },
      { "id": "external", "label": "External ring", "alertInfo": "info=alert-external", "priority": false }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Favorites — one-tap dial targets

GET /api/v1/me/favorites

Speed-dial favorites ordered by sort_order then creation time — the dialpad’s one-tap call surface. label is null when the caller never named the target. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/favorites" \
  -H "X-API-Key: $ORBIT_API_KEY"

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/me/favorites", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
console.log(await res.json());

Response

{
  "data": {
    "favorites": [
      {
        "id": "favorite_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3",
        "target_kind": "pstn",
        "target_value": "+14155552671",
        "label": "Front desk",
        "sort_order": 0,
        "created_at": "2026-08-26T10:00:00.000Z"
      },
      {
        "id": "favorite_3a9e4c2b1d8f4a6e9c7b5d2e4f6a8c1",
        "target_kind": "sip",
        "target_value": "sip:support@pbx.example.com",
        "label": null,
        "sort_order": 10,
        "created_at": "2026-08-26T10:05:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Campaign drafts — the AI Studio draft history

GET /api/v1/me/campaign-drafts

One entry per saved AI Studio draft; draft is null when the row was saved brief-only, so gate the preview panel on its presence. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/campaign-drafts" \
  -H "X-API-Key: $ORBIT_API_KEY"

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/me/campaign-drafts", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
console.log(await res.json());

Response

{
  "data": {
    "drafts": [
      {
        "id": "draft_8b0d2f4a6c8e0b2d4f6a",
        "name": "Q4 re-engagement — lapsed SMS",
        "brief": "Win back lapsed SMS customers with a 10% offer before holiday spend starts",
        "draft": {
          "sms_headline": "Come back for 10% off",
          "sms_body": "We miss you — 10% off your next order, ends Saturday."
        },
        "channels": ["sms"],
        "createdAt": 1755860400125,
        "updatedAt": 1755860400125
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Read the authenticated caller

GET /api/v1/me

Returns the caller’s identity, the active tenant, and every organization the caller belongs to in one envelope. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me" \
  -H "X-API-Key: $ORBIT_API_KEY"

Node.js

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

Response

{
  "data": {
    "user": {
      "id": "usr_9f2a4c6e1b7d3e8f5012a4b6c8d0e2f4",
      "email": "jane@acme.example",
      "name": "Jane Cooper",
      "image": null,
      "role": "admin",
      "emailVerified": true,
      "twoFactorEnabled": false,
      "softphone_layout": "compact_bottom_bar",
      "voicemail_to_email_enabled": false,
      "voicemail_to_email_address": null,
      "inbox_signature": null,
      "inbox_show_archived_tags": false
    },
    "tenant": {
      "id": "ten_4c8d1e6a9b2f4d8c0e2a4c6e8b0d2f4a",
      "name": "Acme Logistics",
      "slug": "acme-logistics",
      "plan": "scale",
      "logoUrl": null
    },
    "organizations": [
      {
        "id": "org_2b6c8e0a4d6f8b0c2e4a6c8d0e2f4a6c",
        "name": "Acme Logistics",
        "slug": "acme-logistics",
        "logoUrl": null,
        "role": "admin"
      },
      {
        "id": "org_7d0e2a4c6e8b0d2f4a6c8e0a2c4e6a8b",
        "name": "Acme Retail",
        "slug": "acme-retail",
        "logoUrl": "https://cdn.orbit.devotel.io/org-logos/acme-retail.png",
        "role": "member"
      }
    ]
  },
  "meta": {
    "request_id": "req_me_bootstrap_01",
    "timestamp": "2026-09-11T08:12:44.310Z"
  }
}

The three data keys always arrive together: user carries the identity fields above plus the caller’s per-user preferences (softphone layout, voicemail-to-email opt-in, inbox signature), tenant is the organization context every subsequent request runs in, and organizations lists every membership with the caller’s role in each.

Preflight: decide on the caller’s role

Branch on data.user.role / membership role before calling a write path

The identity probe answers three startup questions in one call: who is calling (data.user), which organization the key is bound to (data.tenant.slug), and whether the caller’s role in that org justifies the call you are about to make (data.organizations[].role). A workspace-scoped key resolves to exactly one tenant; multi-org dashboard (Clerk-session) callers receive every membership in data.organizations. An admin-of-one-org membership appears alongside the rest — treat the per-org role as the decision input and the org-scoped endpoint’s own verdict as authoritative.

const res = await fetch("https://api.orbit.devotel.io/api/v1/me", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const { data } = await res.json();

// Branch on the caller's role before any write path.
const membership = data.organizations.find((o) => o.slug === data.tenant.slug);
const role = membership?.role ?? "member";
if (role !== "admin" && role !== "owner") {
  console.warn(`Role "${role}" cannot manage this resource — expect 403 on write paths`);
}

import os, requests

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

# Branch on the caller's role before any write path.
membership = next(
    (o for o in data["organizations"] if o["slug"] == data["tenant"]["slug"]),
    None,
)
role = membership["role"] if membership else "member"
if role not in ("admin", "owner"):
    print(f'Role "{role}" cannot manage this resource — expect 403 on write paths')

using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-API-Key", Environment.GetEnvironmentVariable("ORBIT_API_KEY"));
var me = await http.GetFromJsonAsync<JsonElement>("https://api.orbit.devotel.io/api/v1/me");
var data = me.GetProperty("data");

// Branch on the caller's role before any write path.
var role = data.GetProperty("user").GetProperty("role").GetString() ?? "member";
if (role is not ("admin" or "owner"))
{
    Console.WriteLine($"Role \"{role}\" cannot manage this resource — expect 403 on write paths");
}

The decision table for the role you read:

Caller state	`GET /me`	Role-less write that follows
Credential valid; role carries the write path’s grant	`200` — full envelope	`200` / `201` — operation succeeds
Credential valid; role lacks the grant	`200` — full envelope	`403 FORBIDDEN` — surface, rotating retry never heals
Credential missing or invalid	`401` — see below	no downstream call is reached

A 200 on /me tells you the credential is good — it never tells you a write will succeed. Read the role, decide, and treat the operation’s own 403 as the authoritative verdict when the table disagrees with your role map.

Org-context and capability probes in the me surface

The me surface resolves the caller’s active organization context and capability footprint. Use these probes to hide unsupported actions, decide whether an organization area should surface in the dashboard, and map each caller to the operations they can drive. The GET /me envelope is the org-context probe: it resolves the active tenant and memberships in one round trip. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me" \
  -H "X-API-Key: $ORBIT_API_KEY"

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/me", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const { data } = await res.json();
console.log(data.tenant, data.organizations);

Response

{
  "data": {
    "tenant": {
      "id": "ten_4c8d1e6a9b2f4d8c0e2a4c6e8b0d2f4a",
      "name": "Acme Logistics",
      "slug": "acme-logistics",
      "plan": "scale",
      "logoUrl": null
    },
    "organizations": [
      {
        "id": "org_2b6c8e0a4d6f8b0c2e4a6c8d0e2f4a6c",
        "name": "Acme Logistics",
        "slug": "acme-logistics",
        "role": "admin"
      }
    ]
  }
}

The data.tenant block carries the active organization footprint (id, name, slug, plan) every subsequent request runs against; data.organizations lists every membership with the caller’s role. Prefer this single envelope over a second call — there is no separate GET /me/org or GET /me/memberships path; the memberships guard lives on this envelope.

Membership / role guard

Resolve the caller’s membership in the active organization before any write path and gate on its role — the same guard the dashboard applies when opening an organization area.

ROLE=$(curl -s -X GET "https://api.orbit.devotel.io/api/v1/me" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  | jq -r '.data.organizations[] | select(.slug == "acme-logistics") | .role')
echo "caller role: $ROLE"

const res = await fetch("https://api.orbit.devotel.io/api/v1/me", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const { data } = await res.json();

const membership = data.organizations.find(
  (o: { slug: string; role: string }) => o.slug === data.tenant.slug,
);
const role = membership?.role ?? "member";
console.log(`caller role: ${role}`);

The guard answers “does this caller belong to the active org, and with what role” without a dedicated memberships call. Membership role is the only role input the me surface honors — org-scoped endpoints refuse operations the role does not carry.

Feature-gate probe — predictive activation schedule

GET /api/v1/me/predictive-activation-schedule

GET /api/v1/me/predictive-activation-schedule is the capability probe for the predictive-models panel: it returns the caller’s per-model auto-activation schedule intent, or data.schedule: null when no schedule is saved. SDK helpers use null to hide the panel and non-null to render it, so the probe doubles as the feature gate. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/predictive-activation-schedule" \
  -H "X-API-Key: $ORBIT_API_KEY"

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/me/predictive-activation-schedule",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
const { data } = await res.json();
const scheduleEnabled = data.schedule !== null;
console.log("predictive schedule saved:", scheduleEnabled);

Response with a saved schedule

{
  "data": {
    "schedule": {
      "churn_propensity": {
        "enabled": true,
        "cadence": "daily",
        "topN": 100,
        "nameTemplate": "Churn – {date}"
      }
    }
  },
  "meta": {}
}

Response with no schedule saved

{
  "data": { "schedule": null },
  "meta": {}
}

Build the features map your SDK helpers consume from the probe: featuresEnabled.predictiveSchedule = data.schedule !== null, and each model key that survives the server registry (churn_propensity, conversion_intent, lifetime_value, engagement_fatigue) marks its panel as enabled. A PUT on the same path toggles the intent — treat the read as the probe and the write as the setter, never cache the write’s response as the gate.

Chain — authenticated caller → memberships → capabilities

The standard bootstrap chain the me surface supports: (1) call GET /me to resolve identity, (2) guard on data.organizations membership for the active organization, and (3) probe GET /me/predictive-activation-schedule so unsupported actions stay hidden.

// 1. Resolve the authenticated caller.
const meRes = await fetch("https://api.orbit.devotel.io/api/v1/me", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const { data: me } = await meRes.json();

// 2. Guard on membership for the active organization.
const membership = me.organizations.find(
  (o: { slug: string; role: string }) => o.slug === me.tenant.slug,
);
const role = membership?.role ?? "member";

// 3. Probe capabilities before rendering the panel.
const capRes = await fetch(
  "https://api.orbit.devotel.io/api/v1/me/predictive-activation-schedule",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
const { data: cap } = await capRes.json();
const featuresEnabled = { predictiveSchedule: cap.schedule !== null };

console.log({ user: me.user.email, role, featuresEnabled });

Each probe is idempotent, so cache the envelope per session and re-fetch only on org switch or role change. Treat the chain as the only sequence that establishes org context before touching a resource operation.

Errors worth branching on

This probe is where an invalid credential surfaces first — an integration that skips the bootstrap re-discovers the same 401 on every later call. The mechanics of the envelope (error.code / message / status / details, the meta.docs_url trail) are owned by the error handling guide; only the /me-specific branch is hers.

401 — the credential itself fails

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key is missing, invalid, or has been revoked.",
    "status": 401
  },
  "meta": {
    "request_id": "req_me_auth_01",
    "timestamp": "2026-09-11T08:12:45.120Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/INVALID_API_KEY"
  }
}

A 401 on this probe means the X-API-Key header value itself fails — it never means the identity payload moved. The failure precedes tenant resolution, so there is no data envelope to fall back to. Read meta.docs_url for the code’s remedy anchor; rotate the key or mint a new one, because retrying the same header re-fails identically.

Retry matrix

Class	Meaning	Branch response
401 `INVALID_API_KEY`	the credential itself is missing, invalid, or revoked	Surface. Rotate or mint a key; retrying the same value re-fails identically. Follow `meta.docs_url` to the code’s remedy.
403 `FORBIDDEN`	the credential is valid but the caller’s role lacks the operation’s grant	Surface on the operation, not here. `/me` itself returns `200`; the write path you preflighted against the role table answers `403`. Fix the role or the scope — a retry with the same credential never heals it.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request. Cache the `200` payload per session so a retry storm is unnecessary.
5xx transient	a backing lookup failed	Retry with backoff. The startup probe is idempotent; serve your last cached envelope while you retry rather than failing the session.

The platform-wide retry-vs-terminal decision table lives in the error handling guide.

List campaign-drafts

GET /api/v1/me/campaign-drafts

string (enum: true|false)

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.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/campaign-drafts" \
  -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/me/campaign-drafts', {
  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/me/campaign-drafts", 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/me/campaign-drafts", 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/me/campaign-drafts')
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/me/campaign-drafts');
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"
  }
}

List favorites

GET /api/v1/me/favorites

List the authenticated caller’s pinned dial targets (speed-dial favorites) ordered by sort_order then creation time — the dialpad’s one-tap call surface. Use it to populate the Favorites tab on a softphone or mobile dialer. Scoped strictly to the signed-in user; a row id leaked from another user never resolves here.

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/favorites" \
  -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/me/favorites', {
  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/me/favorites", 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/me/favorites", 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/me/favorites')
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/me/favorites');
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": {
    "favorites": [
      {
        "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
        "target_kind": "pstn",
        "target_value": "string",
        "label": null,
        "sort_order": 0,
        "created_at": "1970-01-01T00:00:00.000Z"
      }
    ]
  },
  "meta": {}
}

List generated-reports

GET /api/v1/me/generated-reports

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/generated-reports" \
  -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/me/generated-reports', {
  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/me/generated-reports", 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/me/generated-reports", 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/me/generated-reports')
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/me/generated-reports');
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 predictive-activation schedule

GET /api/v1/me/predictive-activation-schedule

Return the caller’s per-model auto-activation schedule intent for the CDP Predictive Models panel — which predictive models re-materialise their ranked population into a campaign segment on a cadence (hourly/daily/weekly), how many top-ranked profiles per run, and the segment-name template. Scoped strictly to the signed-in user (data.schedule is null when no schedule has been saved).

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/predictive-activation-schedule" \
  -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/me/predictive-activation-schedule', {
  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/me/predictive-activation-schedule", 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/me/predictive-activation-schedule", 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/me/predictive-activation-schedule')
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/me/predictive-activation-schedule');
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": {
    "schedule": "string"
  },
  "meta": {}
}

List recommendations-draft

GET /api/v1/me/recommendations-draft

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/recommendations-draft" \
  -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/me/recommendations-draft', {
  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/me/recommendations-draft", 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/me/recommendations-draft", 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/me/recommendations-draft')
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/me/recommendations-draft');
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"
  }
}

List ring-rules

GET /api/v1/me/ring-rules

string (enum: true|false)

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/ring-rules" \
  -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/me/ring-rules', {
  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/me/ring-rules", 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/me/ring-rules", 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/me/ring-rules')
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/me/ring-rules');
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"
  }
}

Create a favorite

POST /api/v1/me/favorites

Pin a new dial target to the caller’s favorites so it renders as a one-tap entry on the softphone/dialpad. Caps each user at 50 pins (409 FAVORITE_LIMIT_REACHED when full) and rejects a duplicate target (409 FAVORITE_ALREADY_EXISTS). The target format is checked against target_kind: pstn values must be E.164 and sip values must start with sip: (422 otherwise). Favorites store dial INTENT only — placing a call to a pinned target routes through the normal outbound calling surface.

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.

string (enum: true|false)

string (enum: pstn|extension|contact_id|sip)

required

What the pinned dial target is: pstn (a public E.164 phone number, e.g. +442071234567), extension (a short internal extension), contact_id (a CRM/directory reference), or sip (a SIP URI beginning sip:). Drives validation of target_value.

string

required

The dial target itself. Format must match target_kind: E.164 for pstn (422 otherwise), a sip:-prefixed URI for sip, free-form for extension and contact_id.

string | null

Display label the dialpad shows for this pin (≤ 64 chars). Omit or pass null to render the target itself.

integer

Position in the favorites list — lower sorts first. Defaults to 0 (top).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/me/favorites" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "target_kind": "pstn",
  "target_value": "+14155552671",
  "label": "Front desk",
  "sort_order": 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/me/favorites', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "target_kind": "pstn",
  "target_value": "+14155552671",
  "label": "Front desk",
  "sort_order": 0
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/me/favorites", headers=headers, json={
  "target_kind": "pstn",
  "target_value": "+14155552671",
  "label": "Front desk",
  "sort_order": 0
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/me/favorites", bytes.NewBuffer([]byte(`{
  "target_kind": "pstn",
  "target_value": "+14155552671",
  "label": "Front desk",
  "sort_order": 0
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/me/favorites')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "target_kind": "pstn",
  "target_value": "+14155552671",
  "label": "Front desk",
  "sort_order": 0
}.to_json
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/me/favorites');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "target_kind": "pstn",
  "target_value": "+14155552671",
  "label": "Front desk",
  "sort_order": 0
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "favorite": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "target_kind": "pstn",
      "target_value": "string",
      "label": null,
      "sort_order": 0,
      "created_at": "1970-01-01T00:00:00.000Z"
    }
  },
  "meta": {}
}

Update campaign-drafts

PUT /api/v1/me/campaign-drafts

string

string (enum: true|false)

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/me/campaign-drafts" \
  -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/me/campaign-drafts', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.put("https://api.orbit.devotel.io/api/v1/me/campaign-drafts", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("PUT", "https://api.orbit.devotel.io/api/v1/me/campaign-drafts", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/me/campaign-drafts')
req = Net::HTTP::Put.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
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/me/campaign-drafts');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

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

Update generated-reports

PUT /api/v1/me/generated-reports

string

string (enum: true|false)

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/me/generated-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/me/generated-reports', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.put("https://api.orbit.devotel.io/api/v1/me/generated-reports", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("PUT", "https://api.orbit.devotel.io/api/v1/me/generated-reports", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/me/generated-reports')
req = Net::HTTP::Put.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
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/me/generated-reports');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

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

Replace predictive-activation schedule

PUT /api/v1/me/predictive-activation-schedule

Replace the caller’s per-model auto-activation schedule intent wholesale — the dashboard sends its full validated map on every settled change, so a replace is the natural verb. Each entry pins enabled (an explicit OFF survives), the cadence, the per-run topN (1–500), and a human-readable nameTemplate rendered into the new segment’s name. Accepted model keys mirror the server-owned registry (churn_propensity, conversion_intent, lifetime_value, engagement_fatigue); any other key is a 400. Merged into the caller’s preferences without clobbering siblings.

string

string (enum: true|false)

object

required

Per-model schedule intent map (partial record — only toggled models).

cURL

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

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/me/predictive-activation-schedule', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "schedule": {}
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.put("https://api.orbit.devotel.io/api/v1/me/predictive-activation-schedule", headers=headers, json={
  "schedule": {}
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("PUT", "https://api.orbit.devotel.io/api/v1/me/predictive-activation-schedule", bytes.NewBuffer([]byte(`{
  "schedule": {}
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/me/predictive-activation-schedule')
req = Net::HTTP::Put.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "schedule": {}
}.to_json
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/me/predictive-activation-schedule');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "schedule": {}
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "updated": false,
    "schedule": {}
  },
  "meta": {}
}

Update recommendations-draft

PUT /api/v1/me/recommendations-draft

string

string (enum: true|false)

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/me/recommendations-draft" \
  -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/me/recommendations-draft', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.put("https://api.orbit.devotel.io/api/v1/me/recommendations-draft", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("PUT", "https://api.orbit.devotel.io/api/v1/me/recommendations-draft", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/me/recommendations-draft')
req = Net::HTTP::Put.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
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/me/recommendations-draft');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

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

Update ring-rules

PUT /api/v1/me/ring-rules

string

string (enum: true|false)

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/me/ring-rules" \
  -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/me/ring-rules', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.put("https://api.orbit.devotel.io/api/v1/me/ring-rules", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("PUT", "https://api.orbit.devotel.io/api/v1/me/ring-rules", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/me/ring-rules')
req = Net::HTTP::Put.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
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/me/ring-rules');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

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

Update a favorite

PATCH /api/v1/me/favorites/{id}

Relabel or reorder one of the caller’s favorites. Only label and sort_order are mutable — the dial target itself is fixed at creation; delete and re-pin to change it. Fields omitted from the body are left untouched, and a body with no recognised field returns 200 with data.updated: false. Returns 404 when the id does not belong to the caller (cross-user ids resolve to not-found, never another user’s row).

string

required

Favorite id (favorite_ + suffix), as returned by create or list.

string (enum: true|false)

string | null

Replacement display label (≤ 64 chars), or null to clear the label.

integer

New position in the favorites list — lower sorts first.

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/me/favorites/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Front desk",
  "sort_order": 1
}'

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/me/favorites/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "label": "Front desk",
  "sort_order": 1
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.patch("https://api.orbit.devotel.io/api/v1/me/favorites/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers, json={
  "label": "Front desk",
  "sort_order": 1
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("PATCH", "https://api.orbit.devotel.io/api/v1/me/favorites/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", bytes.NewBuffer([]byte(`{
  "label": "Front desk",
  "sort_order": 1
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/me/favorites/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Patch.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "label": "Front desk",
  "sort_order": 1
}.to_json
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/me/favorites/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "label": "Front desk",
  "sort_order": 1
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "updated": false,
    "favorite": {
      "id": "msg_3f6a81c2d4e5471a9b0c2d5e",
      "target_kind": "pstn",
      "target_value": "string",
      "label": null,
      "sort_order": 0,
      "created_at": "1970-01-01T00:00:00.000Z"
    }
  },
  "meta": {}
}

Delete a favorite

DELETE /api/v1/me/favorites/{id}

Remove one of the caller’s pinned favorites so it no longer renders on the dialpad Favorites tab. Returns 404 when the id does not belong to the caller — a row id leaked from another user can never be deleted through this operation.

string

required

Favorite id (favorite_ + suffix), as returned by create or list.

string (enum: true|false)

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/me/favorites/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -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/me/favorites/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.delete("https://api.orbit.devotel.io/api/v1/me/favorites/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.orbit.devotel.io/api/v1/me/favorites/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/me/favorites/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Delete.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
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/me/favorites/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "deleted": false,
    "id": "msg_3f6a81c2d4e5471a9b0c2d5e"
  },
  "meta": {}
}

API Reference

All Endpoints

Me API

Me API

Working with this group

First call: the identity probe

List saved campaign drafts from any SDK

Correlating a request

Worked identity and org-context samples

Worked sequence: dashboard-adjacent operator reads

Worked reads — ring rules and favorites

Ring rules — the caller’s distinctive-ring rules

Favorites — one-tap dial targets

Campaign drafts — the AI Studio draft history

Read the authenticated caller

Preflight: decide on the caller’s role

Org-context and capability probes in the me surface

Membership / role guard

Feature-gate probe — predictive activation schedule

Chain — authenticated caller → memberships → capabilities

Errors worth branching on

401 — the credential itself fails

Retry matrix

List campaign-drafts

List favorites

List generated-reports

Get predictive-activation schedule

List recommendations-draft

List ring-rules

Create a favorite

Update campaign-drafts

Update generated-reports

Replace predictive-activation schedule

Update recommendations-draft

Update ring-rules

Update a favorite

Delete a favorite

​Me API

​Working with this group

​First call: the identity probe

​List saved campaign drafts from any SDK

​Correlating a request

​Worked identity and org-context samples

​Worked sequence: dashboard-adjacent operator reads

​Worked reads — ring rules and favorites

​Ring rules — the caller’s distinctive-ring rules

​Favorites — one-tap dial targets

​Campaign drafts — the AI Studio draft history

​Read the authenticated caller

​Preflight: decide on the caller’s role

​Org-context and capability probes in the me surface

​Membership / role guard

​Feature-gate probe — predictive activation schedule

​Chain — authenticated caller → memberships → capabilities

​Errors worth branching on

​401 — the credential itself fails

​Retry matrix

​List campaign-drafts

​List favorites

​List generated-reports

​Get predictive-activation schedule

​List recommendations-draft

​List ring-rules

​Create a favorite

​Update campaign-drafts

​Update generated-reports

​Replace predictive-activation schedule

​Update recommendations-draft

​Update ring-rules

​Update a favorite

​Delete a favorite

Me API

Working with this group

First call: the identity probe

List saved campaign drafts from any SDK

Correlating a request

Worked identity and org-context samples

Worked sequence: dashboard-adjacent operator reads

Worked reads — ring rules and favorites

Ring rules — the caller’s distinctive-ring rules

Favorites — one-tap dial targets

Campaign drafts — the AI Studio draft history

Read the authenticated caller

Preflight: decide on the caller’s role

Org-context and capability probes in the me surface

Membership / role guard

Feature-gate probe — predictive activation schedule

Chain — authenticated caller → memberships → capabilities

Errors worth branching on

401 — the credential itself fails

Retry matrix

List campaign-drafts

List favorites

List generated-reports

Get predictive-activation schedule

List recommendations-draft

List ring-rules

Create a favorite

Update campaign-drafts

Update generated-reports

Replace predictive-activation schedule

Update recommendations-draft

Update ring-rules

Update a favorite

Delete a favorite