Organization API

Your own organization — read and update its profile, run KYC (“know your customer”) verification, check account status, set default business hours, and manage own-org branding and custom domains. For cross-org admin, see the Admin Organizations API (parent-child) or contact support for platform-level operations. Base path: /api/v1/organization Authentication: API key (X-API-Key) or session JWT. Read endpoints are available to any org member; endpoints marked admin require the owner or admin role.

Using the SDKs

Prefer the typed client, but this page’s endpoint has no helper yet — the generic request() keeps auth/retries and the { data, meta } envelope identical:

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

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

const { data } = await orbit.request<unknown>(
  "POST",
  "/organization",
  {}
);

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("POST", "/organization", {})

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. Raw curl in the body of this page works identically. Full SDK index at SDK quickstart.

Profile

Method	Path	Purpose
`GET`	`/api/v1/organization/`	Get the calling org’s profile
`PUT`	`/api/v1/organization/`	Update the org’s name and general settings — admin

PUT /api/v1/organization/ is the same operation as PUT /api/v1/settings/general — it renames the org and updates its general settings, accepting the same fields and applying the same validation. Use whichever path fits your integration.

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

{
  "data": {
    "id": "org_9f2e_acme",
    "name": "Acme Logistics",
    "slug": "acme-logistics",
    "plan": "business",
    "tenantId": "tenant_4Qx3Hv",
    "balance": 241500,
    "maxTeamMembers": 25,
    "rateLimitPerSecond": 50,
    "isSubaccount": false,
    "billing_currency": "USD",
    "createdAt": "2026-01-14T09:00:00Z",
    "updatedAt": "2026-08-25T10:00:00Z"
  },
  "meta": {
    "request_id": "req_org_001",
    "timestamp": "2026-08-25T10:00:00Z"
  }
}

Rename the org or update general settings with a PUT — the call requires the owner or admin role and accepts the same body as PUT /api/v1/settings/general:

curl -X PUT "https://api.orbit.devotel.io/api/v1/organization/" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Logistics International",
    "monthly_budget_cents": 250000
  }'

{
  "data": {
    "id": "org_9f2e_acme",
    "name": "Acme Logistics International",
    "settings": {},
    "monthly_budget_cents": 250000
  },
  "meta": {
    "request_id": "req_orgupd_001",
    "timestamp": "2026-08-25T10:00:30Z"
  }
}

KYC & verification

Method	Path	Purpose
`POST`	`/api/v1/organization/kyc/submit`	Submit KYC documents
`GET`	`/api/v1/organization/kyc/status`	Check KYC verification status
`POST`	`/api/v1/organization/kyc/idv/session`	Start a hosted ID-document + selfie-liveness (IDV) session
`GET`	`/api/v1/organization/kyc/idv/status`	Poll the IDV verification result

KYC is required to send messages on certain channels (10DLC SMS in the US, registered sender IDs in some countries, WhatsApp Business verification). Statuses are not_started (no KYC on file), pending, pending_review (submitted, awaiting review), approved, and rejected. The IDV endpoints add hosted document capture with selfie liveness. POST /kyc/idv/session returns a session you send the user to; GET /kyc/idv/status polls the normalized result. These return 503 IDV_NOT_CONFIGURED until an IDV provider is provisioned for your account. An IDV pass is a verification signal reviewed alongside your KYC submission — it does not approve KYC on its own.

Submit KYC, then poll the status

POST /api/v1/organization/kyc/submit records the form and stamps the org pending_review — the review is operator-run, not instant, so poll GET /api/v1/organization/kyc/status until it resolves to approved or rejected. Re-submitting an already-approved org returns 409 ALREADY_VERIFIED.

curl -X POST "https://api.orbit.devotel.io/api/v1/organization/kyc/submit" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Logistics Ltd",
    "company_website": "https://acme-logistics.example",
    "country": "US",
    "industry": "Freight and logistics",
    "use_case": "Delivery status SMS and WhatsApp notifications to end customers who booked on our platform.",
    "estimated_monthly_volume": 40000,
    "registration_number": "DE-2004-0317"
  }'

{
  "data": {
    "status": "pending_review",
    "submitted_at": "2026-08-25T10:00:00Z"
  },
  "meta": {
    "request_id": "req_kyc_001",
    "timestamp": "2026-08-25T10:00:00Z"
  }
}

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

{
  "data": {
    "status": "pending_review",
    "use_case": "Delivery status SMS and WhatsApp notifications to end customers who booked on our platform.",
    "submitted_at": "2026-08-25T10:00:00Z"
  },
  "meta": {
    "request_id": "req_kycstatus_001",
    "timestamp": "2026-08-25T10:05:00Z"
  }
}

Legacy SDK builds (pre-2026-06-09) read verification state from the bare GET /api/v1/organization/kyc, which returns the same result as /kyc/status. New integrations should call /kyc/status.

AI provider selection

Every tenant runs its AI features on Orbit’s curated provider lineup — you pick the tier; Orbit runs the model, the keys, and the metering behind it.

Method	Path	Purpose
`GET`	`/api/v1/organization/llm-provider`	List the provider tiers your org can pick, plus your recorded selection and the provider that resolves for your org — admin
`PUT`	`/api/v1/organization/llm-provider`	Record (or clear) your org’s provider selection — admin
`GET`	`/api/v1/organization/llm-provider/resolve`	The resolution only, without the catalog — admin

Two tiers are selectable today: the Devotel LLM free base tier (devotel — zero vendor cost, the default every tenant starts from) and premium Anthropic Claude (anthropic). Recording a selection is a whitelabel-parent / root-organization capability: a subaccount can read the catalog and resolution but always gets 403 on the PUT. Additional third-party models join the lineup only after passing a measured quality, latency, and cost evaluation — a provider still being evaluated is never returned as selectable and never resolves, so no stale or unvetted id can ever be recorded or honored. If your org has never recorded a selection the resolution falls back to the platform default (premium Claude), so this API changes nothing until you opt in. PUT accepts { "provider": "devotel" | "anthropic" | null }; passing null clears the selection back to the platform default.

curl -X PUT "https://api.orbit.devotel.io/api/v1/organization/llm-provider" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "devotel" }'

{
  "data": {
    "provider": "devotel",
    "source": "stored",
    "catalog": {
      "provider": "devotel",
      "label": "Devotel LLM — Free base tier",
      "tier": "free_base",
      "evaluationState": "curated",
      "defaultModel": "devotel-llm",
      "transportAvailable": false
    }
  },
  "meta": {
    "request_id": "req_llmprov_001",
    "timestamp": "2026-08-25T10:08:00Z"
  }
}

Account status

Method	Path	Purpose
`GET`	`/api/v1/organization/account-status`	Get account restriction status, reason codes, and remediation steps

GET /api/v1/organization/account-status is the self-serve answer to “why is my account restricted and how do I fix it?” It reports any active restriction (outbound pause, dunning, subscription state, or pending KYC) with reason codes, the steps to clear it, and where to appeal — so an account is never silently suspended.

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

{
  "data": {
    "state": "restricted",
    "restrictions": [
      {
        "code": "outbound_paused_dunning",
        "severity": "pause",
        "scope": "outbound",
        "summary": "Outbound messages are paused because payment failed three times.",
        "reason": "The last three Stripe payment attempts failed (payment-method issue); outbound is paused until billing recovers.",
        "remediation": {
          "action": "update_payment_method",
          "self_serve": true,
          "steps": [
            "Open Billing in the dashboard and update the payment method.",
            "Retry the failed invoice — outbound resumes automatically."
          ]
        },
        "appeal": {
          "available": true,
          "channel": "self_serve"
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_acctstatus_001",
    "timestamp": "2026-08-25T10:06:00Z"
  }
}

When there is no active restriction the response is { "state": "active", "restrictions": [] }.

Business hours

Method	Path	Purpose
`GET`	`/api/v1/organization/business-hours`	Get the org-wide default business hours and holiday calendar
`PUT`	`/api/v1/organization/business-hours`	Set the org-wide default business hours and holiday calendar — admin

Org business hours are the company-wide default schedule. Every ACD queue, inbound route, and auto-attendant that hasn’t set its own schedule inherits these hours, so you configure them once instead of per route. The body is diff-submit: an omitted field is untouched, holiday_calendar_id set to null clears the calendar link, and a set value must reference a holiday calendar owned by your org.

curl -X PUT "https://api.orbit.devotel.io/api/v1/organization/business-hours" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_hours": {
      "mon": [{ "start": "09:00", "end": "17:00" }],
      "tue": [{ "start": "09:00", "end": "17:00" }],
      "wed": [{ "start": "09:00", "end": "17:00" }],
      "thu": [{ "start": "09:00", "end": "17:00" }],
      "fri": [{ "start": "09:00", "end": "15:00" }]
    },
    "holiday_calendar_id": "hc_us_federal"
  }'

{
  "data": {
    "business_hours": {
      "mon": [{ "start": "09:00", "end": "17:00" }],
      "tue": [{ "start": "09:00", "end": "17:00" }],
      "wed": [{ "start": "09:00", "end": "17:00" }],
      "thu": [{ "start": "09:00", "end": "17:00" }],
      "fri": [{ "start": "09:00", "end": "15:00" }]
    },
    "holiday_calendar_id": "hc_us_federal"
  },
  "meta": {
    "request_id": "req_hours_001",
    "timestamp": "2026-08-25T10:07:00Z"
  }
}

Branding

An own-org shortcut for the branding CRUD that also lives at /api/v1/subaccounts/{id}/branding — manage your own org’s branding without needing to know your org id ahead of time. To read the resolved effective branding for the current tenant, see the Branding API.

Method	Path	Purpose
`GET`	`/api/v1/organization/branding`	Get the org’s branding — admin
`PUT`	`/api/v1/organization/branding`	Update logo, colors, and brand name — admin
`POST`	`/api/v1/organization/branding/reset`	Reset branding back to platform defaults — admin

curl -X PUT "https://api.orbit.devotel.io/api/v1/organization/branding" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dashboard_name": "Acme Support Desk",
    "primary_color": "#4F46E5",
    "accent_color": "#06B6D4",
    "logo_url": "https://acme.example/assets/logo.png",
    "support_email": "help@acme.example"
  }'

{
  "data": {
    "dashboard_name": "Acme Support Desk",
    "primary_color": "#4F46E5",
    "accent_color": "#06B6D4",
    "logo_url": "https://acme.example/assets/logo.png",
    "support_email": "help@acme.example"
  },
  "meta": {
    "request_id": "req_brand_001",
    "timestamp": "2026-08-25T10:02:00Z"
  }
}

The body is a partial JSONB merge — send only the fields you change; explicit null clears a field; omitted fields stay untouched. Six-digit hex colours, http(s) logo URLs (public, non-private hosts), dashboard_name up to 50 characters. Read the current branding with GET /api/v1/organization/branding (same role gate), or fall back to the platform defaults by resetting explicitly:

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

Custom domains

An own-org shortcut for the custom-domain CRUD at /api/v1/subaccounts/{id}/domains. Add a vanity domain for your dashboard; each domain is CNAME-verified before it goes live.

Method	Path	Purpose
`GET`	`/api/v1/organization/domains`	List custom domains
`POST`	`/api/v1/organization/domains`	Claim a custom domain (CNAME-verified) — admin
`DELETE`	`/api/v1/organization/domains/{domainId}`	Remove a custom domain — admin
`POST`	`/api/v1/organization/domains/{domainId}/verify`	Trigger DNS re-verification — admin

Claim a domain first — the response carries the domain row and the canonical CNAME target you must point your hostname at:

curl -X POST "https://api.orbit.devotel.io/api/v1/organization/domains" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "desk.acme.example" }'

{
  "data": {
    "id": "d_dom_check_me",
    "organization_id": "org_9f2e_acme",
    "domain": "desk.acme.example",
    "status": "pending",
    "cname_target": "orbit.devotel.io",
    "cname_verified_at": null,
    "ssl_cert_provisioned_at": null,
    "error": null,
    "created_at": "2026-08-25T10:03:00Z",
    "updated_at": "2026-08-25T10:03:00Z"
  },
  "meta": {
    "request_id": "req_domain_001",
    "timestamp": "2026-08-25T10:03:00Z"
  }
}

In your DNS provider, create a CNAME on desk.acme.example pointing at the cname_target above and wait for it to propagate — no A record. GET /api/v1/subaccounts/{id}/domains/cname-target returns the same canonical target server-side if you render DNS instructions in your own portal. After the record resolves, trigger re-verification; the DNS check re-runs so a fresh record turns your domain live, and the TLS certificate provisions asynchronously after verify succeeds:

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

{
  "data": {
    "id": "d_dom_check_me",
    "organization_id": "org_9f2e_acme",
    "domain": "desk.acme.example",
    "status": "verified",
    "cname_target": "orbit.devotel.io",
    "cname_verified_at": "2026-08-25T10:04:00Z",
    "ssl_cert_provisioned_at": null,
    "error": null
  },
  "meta": {
    "request_id": "req_domainverify_001",
    "timestamp": "2026-08-25T10:04:00Z"
  }
}

List the claimed domains with GET /api/v1/organization/domains and remove one with DELETE /api/v1/organization/domains/{domainId} — both respond on the same { data, meta } envelope; the delete returns { "deleted": true }.

Members & invites

Own-org aliases for the team surface in Settings — manage seats and pending invitations without knowing the canonical /api/v1/settings/* paths.

Method	Path	Purpose
`GET`	`/api/v1/organization/members`	List team members
`PUT`	`/api/v1/organization/members/{id}`	Change a member’s role — admin
`DELETE`	`/api/v1/organization/members/{id}`	Remove a member — owner
`GET`	`/api/v1/organization/invites`	List pending invites
`POST`	`/api/v1/organization/invites`	Send an invite — admin
`POST`	`/api/v1/organization/invites/{email}/resend`	Resend an invite — admin
`DELETE`	`/api/v1/organization/invites/{email}`	Revoke an invite — admin

API keys

Issue, rotate, and revoke API keys for your own organization. These are aliases of the Settings security surface; SDKs and hand-rolled integrations can treat /organization/api-keys as the canonical path.

Method	Path	Purpose
`GET`	`/api/v1/organization/api-keys`	List the org’s API keys — owner, admin, or developer
`POST`	`/api/v1/organization/api-keys`	Create a key with scoped permissions — owner, admin, or developer
`POST`	`/api/v1/organization/api-keys/{id}/rotate`	Rotate a key (grace-period rollover by default, `mode: "immediate"` for a panic revoke) — owner, admin, or developer
`DELETE`	`/api/v1/organization/api-keys/{id}`	Revoke a key — owner, admin, or developer

Create a key with an explicit scopes set — the response returns the plaintext key exactly once, store it before you leave the response:

curl -X POST "https://api.orbit.devotel.io/api/v1/organization/api-keys" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing sync",
    "type": "secret",
    "scopes": ["billing:read", "messages:write"]
  }'

{
  "data": {
    "id": "apikey_4Qt2Hb",
    "key": "dv_live_sk_7Fnb2kP9v4QxJmLrTyW8zHcNq3a",
    "keyPrefix": "dv_live_sk_",
    "lastFourChars": "W8Hc",
    "name": "Billing sync",
    "type": "secret",
    "mode": "live"
  },
  "meta": {
    "request_id": "req_apikey_001",
    "timestamp": "2026-08-25T10:05:00Z"
  }
}

Scopes are validated against a closed catalog (messages:read / messages:write, contacts:*, billing:*, voice:*, video:*, numbers:*, campaigns:*, analytics:read, webhooks:*, and siblings) — an unknown scope is a 422 VALIDATION_ERROR, and minting a wildcard * key requires the owner role. A public key (embeddable in client code) can only hold read-only scopes; write scopes on a public key are rejected. List the keys currently active on the org:

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

{
  "data": [
    {
      "id": "apikey_4Qt2Hb",
      "name": "Billing sync",
      "keyPrefix": "dv_live_sk_",
      "lastFourChars": "W8Hc",
      "type": "secret",
      "scopes": ["billing:read", "messages:write"],
      "active": true,
      "expiresAt": null,
      "createdAt": "2026-08-25T10:05:00Z"
    }
  ],
  "meta": {
    "request_id": "req_apikeys_001",
    "timestamp": "2026-08-25T10:05:30Z"
  }
}

Rotate drops a fresh key while keeping the old one valid for a grace period (1–168 hours, 24 by default) so running processes finish before flip-down — pass { "mode": "immediate" } on a compromised key instead. Revoke ends a key outright:

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

{
  "data": {
    "id": "apikey_9Nxx21",
    "key": "dv_live_sk_QjK1vR7dPmXsLf12YwZtCq9a",
    "keyPrefix": "dv_live_sk_",
    "lastFourChars": "Yq9a",
    "name": "Billing sync",
    "type": "secret",
    "mode": "live"
  },
  "meta": {
    "request_id": "req_apikeyrot_001",
    "timestamp": "2026-08-25T10:06:00Z"
  }
}

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

API Reference

All Endpoints

Organization API: profile, KYC, and custom domains

Organization API

Using the SDKs

Profile

KYC & verification

Submit KYC, then poll the status

AI provider selection

Account status

Business hours

Branding

Custom domains

Members & invites

API keys

See also

​Organization API

​Using the SDKs

​Profile

​KYC & verification

​Submit KYC, then poll the status

​AI provider selection

​Account status

​Business hours

​Branding

​Custom domains

​Members & invites

​API keys

​See also

Organization API

Using the SDKs

Profile

KYC & verification

Submit KYC, then poll the status

AI provider selection

Account status

Business hours

Branding

Custom domains

Members & invites

API keys

See also