Settings API

Everything that shows up under the dashboard’s Settings tab — the organization profile, user preferences, in-app notifications, team & invites, API keys, sender IDs, single sign-on (SAML & SCIM), HIPAA controls, privacy, compliance policies, and keyword / opt-out rules. Base path: /api/v1/settings Authentication: Session JWT (most operations are admin/owner-gated).

Using the SDKs

import { Orbit } from "@devotel-orbit/node";

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

const res = await orbit.settings.get();

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/settings")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

Organization

Method	Path	Purpose
`GET`	`/api/v1/settings/organization`	Read org profile
`GET`	`/api/v1/settings/general`	General settings
`PUT`	`/api/v1/settings/general`	Update general settings

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

{
  "data": {
    "id": "org_a41f3c2b9d",
    "name": "Acme Logistics",
    "plan": "growth",
    "credits": 124000,
    "created_at": "2026-03-12T09:30:00Z"
  },
  "meta": {
    "request_id": "req_org_001",
    "timestamp": "2026-08-25T10:00:00Z"
  }
}

User preferences

Method	Path	Purpose
`GET`	`/api/v1/settings/preferences`	Read the calling user’s preferences
`PUT`	`/api/v1/settings/preferences`	Update preferences (theme, language, timezone)

PUT /api/v1/settings/preferences is a partial update — send only what changes:

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/preferences" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "theme": "dark", "language": "en", "timezone": "Europe/Berlin" }'

Notifications

Method	Path	Purpose
`GET`	`/api/v1/settings/notifications`	List all notifications (read and unread)
`DELETE`	`/api/v1/settings/notifications`	Permanently delete all notifications (irreversible — this does not mark them as read)
`PUT`	`/api/v1/settings/notifications/{id}/read`	Mark one as read

cURL

curl "https://api.orbit.devotel.io/api/v1/settings/notifications" \
  -H "Authorization: Bearer $SESSION_JWT"

Node

const { data } = await orbit.request("GET", "/settings/notifications");
// data — one entry per notification

{
  "data": [
    {
      "id": "ntf_5c2e7a91",
      "type": "info",
      "title": "New team member joined",
      "message": "ops@example-corp.com joined as developer.",
      "read": false,
      "createdAt": "2026-08-25T09:58:00Z"
    },
    {
      "id": "ntf_9d4f1b26",
      "type": "success",
      "title": "Sender ID approved",
      "message": "Sender ID ACME is now sendable.",
      "read": true,
      "createdAt": "2026-08-24T16:12:00Z"
    }
  ],
  "meta": {
    "request_id": "req_notif_001",
    "timestamp": "2026-08-25T10:00:00Z"
  }
}

Mark a single notification as read:

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/notifications/ntf_5c2e7a91/read" \
  -H "Authorization: Bearer $SESSION_JWT"

Node

await orbit.request("PUT", "/settings/notifications/ntf_5c2e7a91/read");

{
  "data": {
    "id": "ntf_5c2e7a91",
    "read": true
  },
  "meta": {
    "request_id": "req_notif_002",
    "timestamp": "2026-08-25T10:00:10Z"
  }
}

DELETE /api/v1/settings/notifications clears the org’s notification list and returns 204 No Content.

Team

Method	Path	Purpose
`GET`	`/api/v1/settings/team`	List team members
`GET`	`/api/v1/settings/team/activity`	Recent team activity
`POST`	`/api/v1/settings/team/invite`	Invite a new member
`PUT`	`/api/v1/settings/team/{userId}`	Change role
`DELETE`	`/api/v1/settings/team/{userId}`	Remove a member
`GET`	`/api/v1/settings/team/invites`	List pending invites
`DELETE`	`/api/v1/settings/team/invites/{email}`	Cancel an invite
`POST`	`/api/v1/settings/team/invites/{email}/resend`	Resend an invite
`POST`	`/api/v1/settings/team/accept-invite`	Accept an invite (invited user calls this)

Invite a member by assigning one of the assignable roles (admin, supervisor, developer, viewer, billing):

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/settings/team/invite" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ops@example-corp.com", "role": "developer" }'

Node

const { data } = await orbit.request("POST", "/settings/team/invite", {
  email: "ops@example-corp.com",
  role: "developer",
});

{
  "data": {
    "email": "ops@example-corp.com",
    "role": "developer",
    "invitedAt": "2026-08-25T10:01:00Z",
    "email_sent": true
  },
  "meta": {
    "request_id": "req_team_invite_001",
    "timestamp": "2026-08-25T10:01:00Z"
  }
}

List current members and their roles:

cURL

curl "https://api.orbit.devotel.io/api/v1/settings/team" \
  -H "Authorization: Bearer $SESSION_JWT"

Node

const { data, meta } = await orbit.request("GET", "/settings/team");
// data — one entry per member; meta.pagination drives the pager

{
  "data": [
    {
      "id": "usr_2c9e4a71",
      "email": "owner@example-corp.com",
      "name": "Alex Rivera",
      "role": "owner",
      "skills": [],
      "lastActiveAt": "2026-08-25T09:30:00Z",
      "createdAt": "2026-03-12T09:30:00Z",
      "seat_type": "full"
    },
    {
      "id": "usr_7f1b8d32",
      "email": "ops@example-corp.com",
      "name": "Sam Okafor",
      "role": "developer",
      "skills": ["inbound-sms"],
      "lastActiveAt": "2026-08-24T17:40:00Z",
      "createdAt": "2026-08-25T10:06:00Z",
      "seat_type": "light"
    }
  ],
  "meta": {
    "request_id": "req_team_list_001",
    "timestamp": "2026-08-25T10:01:30Z",
    "pagination": {
      "cursor": null,
      "has_more": false,
      "total": 2
    }
  }
}

Change a member’s role to one of the assignable roles:

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/team/usr_7f1b8d32" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'

Node

await orbit.request("PUT", "/settings/team/usr_7f1b8d32", {
  role: "admin",
});

{
  "data": {
    "userId": "usr_7f1b8d32",
    "role": "admin"
  },
  "meta": {
    "request_id": "req_team_role_001",
    "timestamp": "2026-08-25T10:02:00Z"
  }
}

List pending invites:

cURL

curl "https://api.orbit.devotel.io/api/v1/settings/team/invites" \
  -H "Authorization: Bearer $SESSION_JWT"

Node

const { data } = await orbit.request("GET", "/settings/team/invites");

{
  "data": [
    {
      "email": "ops@example-corp.com",
      "role": "developer",
      "invitedBy": "owner@example-corp.com",
      "invitedAt": "2026-08-25T10:01:00Z"
    }
  ],
  "meta": {
    "request_id": "req_team_invites_001",
    "timestamp": "2026-08-25T10:02:30Z"
  }
}

DELETE /api/v1/settings/team/{userId} removes a member, and DELETE/POST .../resend on /team/invites/{email} cancels or re-sends a pending invite; all three return 204 No Content. The invited user accepts the invite with the token from the invitation email (presented on the accept-invite page):

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/settings/team/accept-invite" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "token": "<invitation token from the invitation email>" }'

Node

const { data } = await orbit.request("POST", "/settings/team/accept-invite", {
  token: invitationToken,
});

{
  "data": {
    "email": "ops@example-corp.com",
    "role": "developer",
    "organizationId": "org_a41f3c2b9d"
  },
  "meta": {
    "request_id": "req_team_accept_001",
    "timestamp": "2026-08-25T10:05:00Z"
  }
}

API keys

Method	Path	Purpose
`GET`	`/api/v1/settings/api-keys`	List API keys
`POST`	`/api/v1/settings/api-keys`	Issue a new API key
`DELETE`	`/api/v1/settings/api-keys/{id}`	Revoke immediately
`POST`	`/api/v1/settings/api-keys/{id}/rotate`	Rotate (issues new + revokes old)
`POST`	`/api/v1/settings/api-keys/{id}/schedule-revoke`	Schedule revocation in the future (for safe rotation)
`POST`	`/api/v1/settings/api-keys/{id}/cancel-revoke`	Cancel a scheduled revoke

POST /api/v1/settings/api-keys returns the plaintext key once — stored with a _warning because it is never readable again. expiresIn accepts never, 30d, 90d, or 1y; allowed_ips accepts bare IPs or CIDRs (empty = unrestricted). mode: "test" activates sandbox mode (no delivery, no charges).

curl -X POST "https://api.orbit.devotel.io/api/v1/settings/api-keys" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend SMS sender",
    "type": "secret",
    "mode": "live",
    "expiresIn": "90d",
    "scopes": ["messaging.send"],
    "allowed_ips": ["203.0.113.10"]
  }'

{
  "data": {
    "id": "key_0u9k2x5m4z",
    "name": "Backend SMS sender",
    "key": "dv_live_sk_3f6c2a19d57e4b90ac12",
    "type": "secret",
    "mode": "live",
    "active": true,
    "created_at": "2026-08-25T10:02:00Z",
    "_warning": "Store this key securely. It will not be shown again."
  },
  "meta": {
    "request_id": "req_apikey_001",
    "timestamp": "2026-08-25T10:02:00Z"
  }
}

Rotate a key without taking integrations down — by default the old key keeps authenticating for a grace period (1–168 hours) while you swap it everywhere; mode: "immediate" revokes at once:

curl -X POST "https://api.orbit.devotel.io/api/v1/settings/api-keys/key_0u9k2x5m4z/rotate" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "grace_period_hours": 24 }'

The response carries the new key’s plaintext (shown once) plus the old key’s revocation cutoff. Cancel a scheduled cutoff any time before it fires with POST /api/v1/settings/api-keys/{id}/cancel-revoke.

Sender IDs

Method	Path	Purpose
`GET`	`/api/v1/settings/sender-ids`	List sender IDs
`POST`	`/api/v1/settings/sender-ids`	Register a new sender ID

Many countries require sender ID pre-registration before alpha-numeric sender IDs can be used. The full list of operations (including delete + status checks) is in the auto-generated reference below. Register an alphanumeric sender ID for SMS (≤ 11 characters on that channel) — it starts pending and becomes sendable when the destination registry approves it:

curl -X POST "https://api.orbit.devotel.io/api/v1/settings/sender-ids" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "senderId": "ACME",
    "channel": "sms",
    "country": "GB",
    "description": "Delivery notifications sender"
  }'

{
  "data": {
    "id": "sid_0k7d2p4v8m",
    "senderId": "ACME",
    "channel": "sms",
    "country": "GB",
    "status": "pending",
    "description": "Delivery notifications sender",
    "createdAt": "2026-08-25T10:03:00Z"
  },
  "meta": {
    "request_id": "req_sid_001",
    "timestamp": "2026-08-25T10:03:00Z"
  }
}

Single sign-on (SAML & SCIM)

Configure enterprise SSO and directory provisioning for the org. These endpoints manage the configuration; the login and provisioning flows your identity provider calls live on the public /auth/saml/* and /scim/v2/* paths documented under Authentication.

Method	Path	Purpose
`GET`	`/api/v1/settings/saml`	Read the current SAML config (returns the certificate fingerprint, never the raw certificate)
`PATCH`	`/api/v1/settings/saml`	Upsert SAML config — SSO URL, entity ID, attribute mappings, `enabled`, `enforced`. Owner only
`POST`	`/api/v1/settings/saml/test-connection`	Probe an IdP metadata URL and suggest the SSO URL / entity ID
`GET`	`/api/v1/settings/scim`	Read the current SCIM config (returns `hasToken`, never the token)
`POST`	`/api/v1/settings/scim/generate-token`	Generate or rotate the SCIM bearer token — shown once. Owner only
`PATCH`	`/api/v1/settings/scim`	Update SCIM `enabled`, default role, and group-to-role mapping. Owner only

The SSO URL and metadata URL are validated to block requests to internal or private addresses. When you configure SAML for the first time, PATCH /api/v1/settings/saml requires an x509Cert; once one is stored, omit the field to change other settings without re-uploading it.

curl -X PATCH "https://api.orbit.devotel.io/api/v1/settings/saml" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "ssoUrl": "https://idp.example-corp.com/sso",
    "entityId": "urn:example-corp:orbit",
    "attrEmail": "mail",
    "attrName": "displayName",
    "enabled": true,
    "enforced": false
  }'

First-time setup additionally sends x509Cert (the IdP’s PEM signing certificate). The response echoes the saved configuration with cert_fingerprint_sha256 — never the raw certificate.

HIPAA controls

Manage covered-entity mode, the Business Associate Agreement (BAA) record, and the PHI access log. Reads require an admin; enabling, disabling, and BAA changes are owner only.

Method	Path	Purpose
`GET`	`/api/v1/settings/hipaa`	Read HIPAA status and configuration
`PUT`	`/api/v1/settings/hipaa`	Enable or disable HIPAA mode and set the data-retention window (30–3650 days)
`POST`	`/api/v1/settings/hipaa/reauth-challenge`	Mint a 5-minute re-auth challenge required to disable HIPAA mode. Owner only
`GET`	`/api/v1/settings/hipaa/phi-access-log`	List the PHI access log (paginated)
`PUT`	`/api/v1/settings/hipaa/baa`	Record BAA signed status, signing date, and document URL. Owner only

Disabling HIPAA mode is protected. PUT /api/v1/settings/hipaa with enabled: false returns 401 REAUTH_REQUIRED unless you first call POST /api/v1/settings/hipaa/reauth-challenge and replay the returned token in an X-Reauth-Challenge header within 5 minutes. Enabling HIPAA and retention-only updates do not require re-auth. See HIPAA compliance for the full covered-entity guide. Enable covered-entity mode and set the data-retention window; reads come back with your BAA state so you can confirm what applies before you record a signed BAA:

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/hipaa" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "data_retention_days": 365 }'

{
  "data": {
    "enabled": true,
    "data_retention_days": 365,
    "baa_signed": true,
    "baa_signed_at": "2026-07-01T00:00:00Z",
    "baa_document_url": "https://contracts.example.com/acme-baa.pdf",
    "updated_at": "2026-08-25T10:04:00Z"
  },
  "meta": {
    "request_id": "req_hipaa_001",
    "timestamp": "2026-08-25T10:04:00Z"
  }
}

To disable (owner only), first mint a re-auth challenge, then replay it in the header within 5 minutes:

RECHALLENGE=$(curl -s -X POST "https://api.orbit.devotel.io/api/v1/settings/hipaa/reauth-challenge" \
  -H "Authorization: Bearer $SESSION_JWT" | jq -r .data.token)

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/hipaa" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "X-Reauth-Challenge: $RECHALLENGE" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Privacy

Control PII redaction and transcript retention for the org. Reads are available to any member; updates are owner/admin only.

Method	Path	Purpose
`GET`	`/api/v1/settings/privacy`	Read privacy settings
`PUT`	`/api/v1/settings/privacy`	Update privacy settings

The body of PUT /api/v1/settings/privacy accepts:

pii_redaction_enabled (boolean) — mask phone numbers and email addresses on screen for viewer-tier operators. Display only; dial targets and outbound payloads still carry raw E.164.
pii_redaction_in_transcripts (boolean) — scrub PII from agent conversation turns at write time. Applies to new turns only; existing turns are not back-redacted.
transcript_retention_days (integer 1–3650, or null for no deletion) — the nightly retention job deletes agent conversations and messages older than this window.

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/privacy" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "pii_redaction_enabled": true,
    "pii_redaction_in_transcripts": true,
    "transcript_retention_days": 90
  }'

{
  "data": {
    "pii_redaction_enabled": true,
    "pii_redaction_in_transcripts": true,
    "transcript_retention_days": 90,
    "updated_at": "2026-08-25T10:05:00Z"
  },
  "meta": {
    "request_id": "req_privacy_001",
    "timestamp": "2026-08-25T10:05:00Z"
  }
}

Compliance

Per-org compliance and outbound-safety policies enforced on the send path. Each resource exposes a read (available to any member) and a write (owner only).

Method	Path	Purpose
`GET` / `PATCH`	`/api/v1/settings/compliance/policy-scan-mode`	Pre-send policy scanner mode (`strict`, `warn`, `off`)
`GET` / `PATCH`	`/api/v1/settings/compliance/unknown-marketing-policy`	Marketing-send policy for contacts whose consent state is unknown
`GET` / `PATCH`	`/api/v1/settings/compliance/consent-default-policy`	Default consent policy applied when a contact has no explicit consent record
`GET` / `PUT`	`/api/v1/settings/compliance/country-allowlist`	Outbound destination-country allowlist and the allow-all override
`GET` / `PUT`	`/api/v1/settings/compliance/fraud-caps`	Per-channel velocity and daily-spend caps, with the platform floor per channel
`GET` / `PUT`	`/api/v1/settings/compliance/channel-rate-overrides`	Per-channel outbound rate-limit overrides
`GET` / `PUT`	`/api/v1/settings/compliance/ai-turn-audit`	Toggle AI-turn audit logging
`GET` / `PATCH`	`/api/v1/settings/compliance/inbox-ai-privacy`	Toggle inbox AI auto-categorize / auto-summarize and set the spam-handling action

The country allowlist is tenant-scoped — it constrains only your own org’s outbound traffic, never another tenant’s. The work below is self-serve tenant configuration; compliance topics document tenant-owned controls only. Pair a read (GET) with a write (PATCH or PUT, owner/admin) so callers hold the current value before updating it. Policy scan mode — set the pre-send policy scanner:

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/settings/compliance/policy-scan-mode" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "strict" }'

Node

const { data } = await orbit.request("PATCH", "/settings/compliance/policy-scan-mode", {
  mode: "strict",
});

{
  "data": {
    "mode": "strict",
    "updated_at": "2026-08-25T10:06:00Z"
  },
  "meta": {
    "request_id": "req_comp_scan_001",
    "timestamp": "2026-08-25T10:06:00Z"
  }
}

Country allowlist — the full countries array replaces the previous list; sending an empty array with allow_all: false blocks every destination until reconfigured:

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/compliance/country-allowlist" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "countries": ["US", "CA", "GB"], "allow_all": false }'

Node

const { data } = await orbit.request("PUT", "/settings/compliance/country-allowlist", {
  countries: ["US", "CA", "GB"],
  allow_all: false,
});

{
  "data": {
    "countries": ["US", "CA", "GB"],
    "allow_all": false,
    "updated_at": "2026-08-25T10:06:30Z"
  },
  "meta": {
    "request_id": "req_comp_countries_001",
    "timestamp": "2026-08-25T10:06:30Z"
  }
}

Fraud caps — values below a channel’s platform floor are clamped to the floor:

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/compliance/fraud-caps" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "max_per_minute": 100,
    "max_daily_spend_cents": 50000
  }'

Node

const { data } = await orbit.request("PUT", "/settings/compliance/fraud-caps", {
  channel: "sms",
  max_per_minute: 100,
  max_daily_spend_cents: 50000,
});

{
  "data": {
    "channel": "sms",
    "max_per_minute": 100,
    "max_daily_spend_cents": 50000,
    "updated_at": "2026-08-25T10:07:00Z"
  },
  "meta": {
    "request_id": "req_comp_fraud_001",
    "timestamp": "2026-08-25T10:07:00Z"
  }
}

Channel rate overrides — override a channel’s default outbound rate limit:

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/compliance/channel-rate-overrides" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "sms", "max_per_second": 10 }'

Node

const { data } = await orbit.request("PUT", "/settings/compliance/channel-rate-overrides", {
  channel: "sms",
  max_per_second: 10,
});

{
  "data": {
    "channel": "sms",
    "max_per_second": 10,
    "updated_at": "2026-08-25T10:07:30Z"
  },
  "meta": {
    "request_id": "req_comp_rate_001",
    "timestamp": "2026-08-25T10:07:30Z"
  }
}

AI-turn audit — toggle audit logging of AI agent conversation turns:

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/compliance/ai-turn-audit" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

Node

const { data } = await orbit.request("PUT", "/settings/compliance/ai-turn-audit", {
  enabled: true,
});

{
  "data": {
    "enabled": true,
    "updated_at": "2026-08-25T10:08:00Z"
  },
  "meta": {
    "request_id": "req_comp_aiaudit_001",
    "timestamp": "2026-08-25T10:08:00Z"
  }
}

Inbox AI privacy — set the inbox AI classification features and the spam-handling action (folder or suppress):

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/settings/compliance/inbox-ai-privacy" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_categorize": true,
    "auto_summarize": false,
    "spam_action": "folder"
  }'

Node

const { data } = await orbit.request("PATCH", "/settings/compliance/inbox-ai-privacy", {
  auto_categorize: true,
  auto_summarize: false,
  spam_action: "folder",
});

{
  "data": {
    "auto_categorize": true,
    "auto_summarize": false,
    "spam_action": "folder",
    "updated_at": "2026-08-25T10:08:30Z"
  },
  "meta": {
    "request_id": "req_comp_inbox_001",
    "timestamp": "2026-08-25T10:08:30Z"
  }
}

The pair GET / PATCH on unknown-marketing-policy and consent-default-policy, and the consent-audit posture read (GET /api/v1/settings/compliance/consent-audit — no write counterpart, so it is read-only), all use the same envelope. For every compliance resource, a plain GET returns the saved value in the same envelope shape.

Keyword & opt-out rules

Automated inbound-keyword handling and STOP/START opt-out management. Keyword-rule writes require the developer role or higher; opt-out-rule writes require an admin. Both list endpoints are paginated.

Keyword rules

Method	Path	Purpose
`GET`	`/api/v1/settings/keyword-rules`	List keyword rules
`POST`	`/api/v1/settings/keyword-rules`	Create a keyword rule
`PUT`	`/api/v1/settings/keyword-rules/{id}`	Update a keyword rule
`DELETE`	`/api/v1/settings/keyword-rules/{id}`	Delete a keyword rule

A rule matches an inbound keyword on a channel (sms, whatsapp, rcs, viber, email) with a match_type of exact, contains, starts_with, or regex, then runs an action: reply with response_text, forward to an agent_id, trigger a flow_id, or opt the contact out / back in.

Opt-out rules

Method	Path	Purpose
`GET`	`/api/v1/settings/opt-out-rules`	List opt-out / opt-in rules
`POST`	`/api/v1/settings/opt-out-rules`	Create an opt-out or opt-in rule
`PUT`	`/api/v1/settings/opt-out-rules`	Bulk update opt-out / opt-in rules (up to 100 per request)
`DELETE`	`/api/v1/settings/opt-out-rules/{id}`	Delete an opt-out / opt-in rule

Opt-out rules are keyword rules whose action is opt-out or opt-in (for example STOP and START). Set auto_reply_text to confirm the change back to the contact. See Opt-outs & suppression for how suppression is enforced at send time.

Worked sequences

The walk-through below covers the keyword-rule and opt-out-rule surfaces end to end in the order an integration typically drives them: create, list, update, then delete. Keyword-rule bodies are snake_case; responses return the stored rule in camelCase. Step 1 — create a keyword rule

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/settings/keyword-rules" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "HOURS",
    "channel": "sms",
    "match_type": "exact",
    "action": "reply",
    "response_text": "We are open Mon–Sat 9–6. Reply MENU for options."
  }'

Node

const { data } = await orbit.request("POST", "/settings/keyword-rules", {
  keyword: "HOURS",
  channel: "sms",
  match_type: "exact",
  action: "reply",
  response_text: "We are open Mon–Sat 9–6. Reply MENU for options.",
});

Python

import os, requests

r = requests.post(
    "https://api.orbit.devotel.io/api/v1/settings/keyword-rules",
    headers={
        "Authorization": f"Bearer {os.environ['SESSION_JWT']}",
        "Content-Type": "application/json",
    },
    json={
        "keyword": "HOURS",
        "channel": "sms",
        "match_type": "exact",
        "action": "reply",
        "response_text": "We are open Mon–Sat 9–6. Reply MENU for options.",
    },
)
print(r.json()["data"]["id"])

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]string{
		"keyword":       "HOURS",
		"channel":       "sms",
		"match_type":    "exact",
		"action":        "reply",
		"response_text": "We are open Mon–Sat 9–6. Reply MENU for options.",
	})
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/settings/keyword-rules",
		bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SESSION_JWT"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	fmt.Println("status:", resp.StatusCode)
}

Ruby

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/settings/keyword-rules")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV['SESSION_JWT']}"
req["Content-Type"] = "application/json"
req.body = {
  keyword: "HOURS",
  channel: "sms",
  match_type: "exact",
  action: "reply",
  response_text: "We are open Mon–Sat 9–6. Reply MENU for options.",
}.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/settings/keyword-rules");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("SESSION_JWT"),
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "keyword" => "HOURS",
    "channel" => "sms",
    "match_type" => "exact",
    "action" => "reply",
    "response_text" => "We are open Mon–Sat 9–6. Reply MENU for options.",
]));

echo curl_exec($ch);

{
  "data": {
    "id": "kw_4v8p3d2x",
    "keyword": "HOURS",
    "channel": "sms",
    "matchType": "exact",
    "action": "reply",
    "responseText": "We are open Mon–Sat 9–6. Reply MENU for options.",
    "agentId": null,
    "flowId": null,
    "active": true,
    "createdAt": "2026-08-25T10:10:00Z"
  },
  "meta": {
    "request_id": "req_kw_create_001",
    "timestamp": "2026-08-25T10:10:00Z"
  }
}

Step 2 — create an opt-out rule

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/settings/opt-out-rules" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "STOP",
    "channel": "sms",
    "action": "opt-out",
    "auto_reply_text": "You have been unsubscribed. Reply START to resume."
  }'

Node

const { data } = await orbit.request("POST", "/settings/opt-out-rules", {
  keyword: "STOP",
  channel: "sms",
  action: "opt-out",
  auto_reply_text: "You have been unsubscribed. Reply START to resume.",
});

Python

import os, requests

r = requests.post(
    "https://api.orbit.devotel.io/api/v1/settings/opt-out-rules",
    headers={
        "Authorization": f"Bearer {os.environ['SESSION_JWT']}",
        "Content-Type": "application/json",
    },
    json={
        "keyword": "STOP",
        "channel": "sms",
        "action": "opt-out",
        "auto_reply_text": "You have been unsubscribed. Reply START to resume.",
    },
)
print(r.json()["data"]["id"])

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]string{
		"keyword":         "STOP",
		"channel":         "sms",
		"action":          "opt-out",
		"auto_reply_text": "You have been unsubscribed. Reply START to resume.",
	})
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/settings/opt-out-rules",
		bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SESSION_JWT"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	fmt.Println("status:", resp.StatusCode)
}

Ruby

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/settings/opt-out-rules")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV['SESSION_JWT']}"
req["Content-Type"] = "application/json"
req.body = {
  keyword: "STOP",
  channel: "sms",
  action: "opt-out",
  auto_reply_text: "You have been unsubscribed. Reply START to resume.",
}.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/settings/opt-out-rules");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("SESSION_JWT"),
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "keyword" => "STOP",
    "channel" => "sms",
    "action" => "opt-out",
    "auto_reply_text" => "You have been unsubscribed. Reply START to resume.",
]));

echo curl_exec($ch);

{
  "data": {
    "id": "oor_2m6q9t4w",
    "keyword": "STOP",
    "channel": "sms",
    "matchType": "exact",
    "action": "opt-out",
    "responseText": "You have been unsubscribed. Reply START to resume.",
    "active": true,
    "createdAt": "2026-08-25T10:11:00Z"
  },
  "meta": {
    "request_id": "req_oor_create_001",
    "timestamp": "2026-08-25T10:11:00Z"
  }
}

Step 3 — list rules GET /api/v1/settings/keyword-rules returns all rules; GET /api/v1/settings/opt-out-rules narrows to the opt-out/opt-in subset. Both are cursor-paginated — follow meta.pagination.cursor while has_more is true:

cURL

curl "https://api.orbit.devotel.io/api/v1/settings/opt-out-rules?limit=20" \
  -H "Authorization: Bearer $SESSION_JWT"

Node

const { data, meta } = await orbit.request("GET", "/settings/opt-out-rules?limit=20");
// meta.pagination.cursor feeds the next page while meta.pagination.has_more is true

Python

import os, requests

r = requests.get(
    "https://api.orbit.devotel.io/api/v1/settings/opt-out-rules?limit=20",
    headers={"Authorization": f"Bearer {os.environ['SESSION_JWT']}"},
)
page = r.json()
# page["meta"]["pagination"]["cursor"] feeds the next page
# while page["meta"]["pagination"]["has_more"] is true
print(len(page["data"]))

package main

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

func main() {
	req, _ := http.NewRequest("GET",
		"https://api.orbit.devotel.io/api/v1/settings/opt-out-rules?limit=20",
		nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SESSION_JWT"))
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	// follow meta.pagination.cursor while meta.pagination.has_more is true
	fmt.Println("status:", resp.StatusCode)
}

Ruby

require "net/http"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/settings/opt-out-rules?limit=20")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{ENV['SESSION_JWT']}"

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/settings/opt-out-rules?limit=20"
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("SESSION_JWT"),
]);

echo curl_exec($ch);

{
  "data": [
    {
      "id": "oor_2m6q9t4w",
      "keyword": "STOP",
      "channel": "sms",
      "matchType": "exact",
      "action": "opt-out",
      "responseText": "You have been unsubscribed. Reply START to resume.",
      "active": true,
      "createdAt": "2026-08-25T10:11:00Z"
    },
    {
      "id": "oor_7r3k8cx1",
      "keyword": "START",
      "channel": "sms",
      "matchType": "exact",
      "action": "opt-in",
      "responseText": "You are re-subscribed. Reply STOP to opt out.",
      "active": true,
      "createdAt": "2026-08-25T10:11:20Z"
    }
  ],
  "meta": {
    "request_id": "req_oor_list_001",
    "timestamp": "2026-08-25T10:12:00Z",
    "pagination": {
      "cursor": null,
      "has_more": false,
      "total": 2
    }
  }
}

Step 4 — update a keyword rule PUT /api/v1/settings/keyword-rules/{id} is a partial update — send only the fields to change; it returns the updated rule id (fetch the full record with GET if you need it):

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/keyword-rules/kw_4v8p3d2x" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

Node

await orbit.request("PUT", "/settings/keyword-rules/kw_4v8p3d2x", {
  active: false,
});

Python

import os, requests

r = requests.put(
    "https://api.orbit.devotel.io/api/v1/settings/keyword-rules/kw_4v8p3d2x",
    headers={
        "Authorization": f"Bearer {os.environ['SESSION_JWT']}",
        "Content-Type": "application/json",
    },
    json={"active": False},
)
print(r.json()["data"]["id"])

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]bool{"active": false})
	req, _ := http.NewRequest("PUT",
		"https://api.orbit.devotel.io/api/v1/settings/keyword-rules/kw_4v8p3d2x",
		bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SESSION_JWT"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	fmt.Println("status:", resp.StatusCode)
}

Ruby

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/settings/keyword-rules/kw_4v8p3d2x")
req = Net::HTTP::Put.new(uri)
req["Authorization"] = "Bearer #{ENV['SESSION_JWT']}"
req["Content-Type"] = "application/json"
req.body = { active: false }.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/settings/keyword-rules/kw_4v8p3d2x"
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("SESSION_JWT"),
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["active" => false]));

echo curl_exec($ch);

{
  "data": {
    "id": "kw_4v8p3d2x"
  },
  "meta": {
    "request_id": "req_kw_update_001",
    "timestamp": "2026-08-25T10:13:00Z"
  }
}

Step 5 — bulk-update opt-out rules PUT /api/v1/settings/opt-out-rules updates up to 100 rules in one call — the dashboard bulk-edit save. Each entry names the rule id plus the fields to change (keyword, channel, action, auto_reply_text, or active to toggle without deleting):

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/settings/opt-out-rules" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      { "id": "oor_2m6q9t4w", "active": true },
      { "id": "oor_7r3k8cx1", "auto_reply_text": "Welcome back." }
    ]
  }'

Node

const { data } = await orbit.request("PUT", "/settings/opt-out-rules", {
  rules: [
    { id: "oor_2m6q9t4w", active: true },
    { id: "oor_7r3k8cx1", auto_reply_text: "Welcome back." },
  ],
});

Python

import os, requests

r = requests.put(
    "https://api.orbit.devotel.io/api/v1/settings/opt-out-rules",
    headers={
        "Authorization": f"Bearer {os.environ['SESSION_JWT']}",
        "Content-Type": "application/json",
    },
    json={
        "rules": [
            {"id": "oor_2m6q9t4w", "active": True},
            {"id": "oor_7r3k8cx1", "auto_reply_text": "Welcome back."},
        ],
    },
)
print(r.json()["data"]["updated"])

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]interface{}{
		"rules": []map[string]interface{}{
			{"id": "oor_2m6q9t4w", "active": true},
			{"id": "oor_7r3k8cx1", "auto_reply_text": "Welcome back."},
		},
	})
	req, _ := http.NewRequest("PUT",
		"https://api.orbit.devotel.io/api/v1/settings/opt-out-rules",
		bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SESSION_JWT"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	fmt.Println("status:", resp.StatusCode)
}

Ruby

require "net/http"
require "json"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/settings/opt-out-rules")
req = Net::HTTP::Put.new(uri)
req["Authorization"] = "Bearer #{ENV['SESSION_JWT']}"
req["Content-Type"] = "application/json"
req.body = {
  rules: [
    { id: "oor_2m6q9t4w", active: true },
    { id: "oor_7r3k8cx1", auto_reply_text: "Welcome back." },
  ],
}.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/settings/opt-out-rules");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("SESSION_JWT"),
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "rules" => [
        ["id" => "oor_2m6q9t4w", "active" => true],
        ["id" => "oor_7r3k8cx1", "auto_reply_text" => "Welcome back."],
    ],
]));

echo curl_exec($ch);

{
  "data": {
    "updated": ["oor_2m6q9t4w", "oor_7r3k8cx1"],
    "count": 2
  },
  "meta": {
    "request_id": "req_oor_bulk_001",
    "timestamp": "2026-08-25T10:14:00Z"
  }
}

Step 6 — delete rules DELETE /api/v1/settings/keyword-rules/{id} and DELETE /api/v1/settings/opt-out-rules/{id} both return the deleted id:

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/settings/opt-out-rules/oor_7r3k8cx1" \
  -H "Authorization: Bearer $SESSION_JWT"

Node

await orbit.request("DELETE", "/settings/opt-out-rules/oor_7r3k8cx1");

Python

import os, requests

r = requests.delete(
    "https://api.orbit.devotel.io/api/v1/settings/opt-out-rules/oor_7r3k8cx1",
    headers={"Authorization": f"Bearer {os.environ['SESSION_JWT']}"},
)
print(r.json()["data"]["deleted"])

package main

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

func main() {
	req, _ := http.NewRequest("DELETE",
		"https://api.orbit.devotel.io/api/v1/settings/opt-out-rules/oor_7r3k8cx1",
		nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SESSION_JWT"))
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	fmt.Println("status:", resp.StatusCode)
}

Ruby

require "net/http"
require "uri"

uri = URI("https://api.orbit.devotel.io/api/v1/settings/opt-out-rules/oor_7r3k8cx1")
req = Net::HTTP::Delete.new(uri)
req["Authorization"] = "Bearer #{ENV['SESSION_JWT']}"

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/settings/opt-out-rules/oor_7r3k8cx1"
);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . getenv("SESSION_JWT"),
]);

echo curl_exec($ch);

{
  "data": {
    "deleted": "oor_7r3k8cx1"
  },
  "meta": {
    "request_id": "req_oor_delete_001",
    "timestamp": "2026-08-25T10:15:00Z"
  }
}

API Reference

All Endpoints

Settings API overview: org, users, keys, and SSO

Settings API

Using the SDKs

Organization

User preferences

Notifications

Team

API keys

Sender IDs

Single sign-on (SAML & SCIM)

HIPAA controls

Privacy

Compliance

Keyword & opt-out rules

Keyword rules

Opt-out rules

Worked sequences

See also

​Settings API

​Using the SDKs

​Organization

​User preferences

​Notifications

​Team

​API keys

​Sender IDs

​Single sign-on (SAML & SCIM)

​HIPAA controls

​Privacy

​Compliance

​Keyword & opt-out rules

​Keyword rules

​Opt-out rules

​Worked sequences

​See also

Settings API

Using the SDKs

Organization

User preferences

Notifications

Team

API keys

Sender IDs

Single sign-on (SAML & SCIM)

HIPAA controls

Privacy

Compliance

Keyword & opt-out rules

Keyword rules

Opt-out rules

Worked sequences

See also