Worked onboarding reads

The onboarding endpoints are read-mostly state probes — the account estate a new tenant works through in its first session is easiest to learn as one chain: poll the provisioning panel → drive the checklist → override the steps that don’t auto-detect → confirm channel readiness → watch where verification is stuck. The samples below walk that chain end to end and show the full { data, meta } envelope at each step. Scope of this overlay: the samples show cURL and Node — the two most-requested languages. Python, Go, Ruby, and PHP tabs appear on the operation blocks themselves. The quickstart (quickstart) chains the same steps with dashboard screenshots; this overlay stays envelope-accurate against the API.

1. Poll the provisioning panel

Right after signup, poll GET /api/v1/onboarding/provisioning-status at ~2s intervals until allReady is true. emailVerified, tenantSchemaReady, and apiKeySeeded are the three blocking signals — the first API key (dv_live_sk_* / dv_test_sk_*) is seeded by the workspace itself during provisioning, so this read is also how you confirm you can start signing API calls. trialCreditsGranted is reported for information but never blocks.

curl "https://api.orbit.devotel.io/api/v1/onboarding/provisioning-status" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/onboarding/provisioning-status",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
const { data } = await res.json();
// Advance one panel row per boolean; stop polling when data.allReady flips.
console.log(data.readyCount, data.allReady);

200

{
  "data": {
    "emailVerified": true,
    "tenantSchemaReady": true,
    "trialCreditsGranted": false,
    "apiKeySeeded": true,
    "readyCount": 3,
    "allReady": true
  },
  "meta": {
    "request_id": "req_7c2e91ab",
    "timestamp": "2026-09-09T10:00:04.000Z"
  }
}

Once allReady is true, stop polling this endpoint — the 5s cache exists for the provisioning window only.

2. Drive the bootstrap chain off the checklist

GET /api/v1/onboarding/status returns the nine-step getting-started checklist with every satisfaction probe already resolved server-side. Each step carries an id, a dashboard deep link (ctaUrl), a completed flag, and completedBy — system when the platform’s own probe saw the signal, user when an operator marked or skipped it. Branch your integration on nextIncompleteStep instead of diffing the steps client-side.

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

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/onboarding/status",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
const { data } = await res.json();
// Resume banner reads the first incomplete step directly.
console.log(data.nextIncompleteStep?.id, data.overallPct);

200

{
  "data": {
    "steps": [
      {
        "id": "email_verified",
        "label": "Verify your email",
        "description": "Confirm your email address to unlock account recovery and security alerts.",
        "ctaUrl": "/settings/profile",
        "completed": true,
        "completedAt": "2026-09-09T09:41:12.000Z",
        "completedBy": "system"
      },
      {
        "id": "org_created",
        "label": "Create your workspace",
        "description": "Set up a workspace so you can invite teammates and keep data scoped per tenant.",
        "ctaUrl": "/settings/general",
        "completed": true,
        "completedAt": "2026-09-09T09:47:30.000Z",
        "completedBy": "system"
      },
      {
        "id": "org_named",
        "label": "Name your workspace",
        "description": "Rename your workspace from 'Personal' so teammates recognise it in their org switcher.",
        "ctaUrl": "/settings/general",
        "completed": true,
        "completedAt": "2026-09-09T09:48:05.000Z",
        "completedBy": "system"
      },
      {
        "id": "payment_method_added",
        "label": "Add a payment method",
        "description": "Attach a card or bank account so live-mode messages and number purchases can settle.",
        "ctaUrl": "/billing/payment",
        "completed": false,
        "completedAt": null,
        "completedBy": null
      },
      {
        "id": "trial_credit_granted",
        "label": "Receive your trial credit",
        "description": "KYC submitted — under review (usually < 24h).",
        "ctaUrl": "/settings/kyc",
        "completed": false,
        "completedAt": null,
        "completedBy": null
      }
    ],
    "totalCount": 9,
    "completedCount": 3,
    "complete": false,
    "completedAt": null,
    "overallPct": 33,
    "nextIncompleteStep": {
      "id": "payment_method_added",
      "label": "Add a payment method",
      "ctaUrl": "/billing/payment"
    }
  },
  "meta": {
    "request_id": "req_7c2e920c",
    "timestamp": "2026-09-09T10:01:02.000Z"
  }
}

Three contract notes callers branch on:

trial_credit_granted is the wallet confirmation. It flips only after account verification (KYC) is approved and the trial credit lands; until verification is approved the step is hidden from steps[] entirely, and totalCount drops to 8 — compute progress from completedCount / totalCount, never from a hard-coded nine.
payment_method_added is the plan-credit attachment step — it flips the moment a default card or bank account exists for billing, and live traffic and number purchases settle against it.
A backend blip degrades, never errors. When the platform probes are briefly unavailable the endpoint still returns 200 with every step reading incomplete (the response is not cached, so the next poll recovers the true state). Treat an all-incomplete payload as “ask again in a minute”, not as a failed call — and keep your poll cadence at or above the 60s cache.

3. Mark or skip the steps that don’t auto-detect

Steps that resolve outside the platform’s reach need a manual nudge. POST /api/v1/onboarding/complete-step and /skip-step store a per-user override that the checklist derivation merges on top of its probes — the step then reports completed: true with completedBy: "user". Both writes are restricted to the owner and admin roles and are audit-logged; send an Idempotency-Key so a retried click never double-writes.

curl -X POST "https://api.orbit.devotel.io/api/v1/onboarding/complete-step" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Idempotency-Key: onboarding-complete-payment-method" \
  -H "Content-Type: application/json" \
  -d '{ "stepId": "payment_method_added" }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/onboarding/complete-step",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Idempotency-Key": "onboarding-complete-payment-method",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ stepId: "payment_method_added" }),
  },
);
console.log(await res.json());

200

{
  "data": {
    "stepId": "payment_method_added",
    "action": "manual_complete"
  },
  "meta": {
    "request_id": "req_7c2e93d1",
    "timestamp": "2026-09-09T10:02:11.000Z"
  }
}

Use the same body for /skip-step; its echo carries "action": "skipped". Skip is the right call for steps that genuinely don’t apply — for example a sandbox-only workspace that never adds a payment method. A step id outside the nine canonical values is rejected:

422

{
  "error": {
    "code": "INVALID_REQUEST",
    "status": 422,
    "message": "Invalid onboarding step id. Allowed: email_verified, org_created, org_named, payment_method_added, trial_credit_granted, first_number_purchased, first_message_sent, first_contact_created, first_agent_or_campaign_or_team_invite"
  },
  "meta": {
    "request_id": "req_7c2e94e2",
    "timestamp": "2026-09-09T10:02:14.000Z"
  }
}

4. Confirm SMS readiness in one read

For the SMS surface specifically, GET /api/v1/onboarding/sms-checklist collapses five readiness probes — API key, purchased number, approved SMS sender ID, first sent message, active webhook — into one round-trip. It is the fast path to gate a “you can send real traffic now” state without hitting five endpoints.

curl "https://api.orbit.devotel.io/api/v1/onboarding/sms-checklist" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/onboarding/sms-checklist",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
const { data } = await res.json();
// "4/5 complete" header without re-counting client-side.
console.log(`${data.completedCount}/5 complete`);

200

{
  "data": {
    "hasApiKey": true,
    "hasNumber": true,
    "hasSenderId": true,
    "hasSentMessage": true,
    "hasWebhook": false,
    "completedCount": 4
  },
  "meta": {
    "request_id": "req_7c2e95f3",
    "timestamp": "2026-09-09T10:03:22.000Z"
  }
}

Note hasSenderId counts only an approved SMS sender — a registration still pending provider approval reads false.

5. See where verification is stuck

Once traffic is moving, the remaining onboarding risk is verification lag. GET /api/v1/onboarding/status-timeline folds account KYC, US 10DLC brand and campaign registration, per-country compliance profiles, and per-number compliance state into one ordered timeline — each row carries its folded state, the current blocker line, and a deep-link resolveUrl to fix it.

curl "https://api.orbit.devotel.io/api/v1/onboarding/status-timeline" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/onboarding/status-timeline",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
const { data } = await res.json();
// Render one "where verification is stuck" view from the folded states.
for (const step of data.steps) {
  if (step.state === "rejected" || step.blocker) {
    console.log(step.id, step.state, step.blocker, step.resolveUrl);
  }
}

200

{
  "data": {
    "steps": [
      {
        "id": "kyc:account",
        "kind": "kyc",
        "label": "Account verification",
        "state": "in_review",
        "submittedAt": "2026-09-08T14:12:00.000Z",
        "updatedAt": "2026-09-09T09:41:00.000Z",
        "sla": { "hours": 24, "label": "24h" },
        "etaAt": "2026-09-09T14:12:00.000Z",
        "blocker": null,
        "resolveUrl": "/settings/kyc",
        "reviewer": null
      },
      {
        "id": "10dlc:brand",
        "kind": "us_10dlc",
        "label": "US 10DLC brand",
        "state": "pending",
        "submittedAt": "2026-09-08T15:01:00.000Z",
        "updatedAt": "2026-09-08T15:01:00.000Z",
        "sla": null,
        "etaAt": null,
        "blocker": "Brand registration is waiting on the campaign submission.",
        "resolveUrl": "/compliance/senders",
        "reviewer": null
      }
    ],
    "counts": {
      "total": 2,
      "approved": 0,
      "in_review": 1,
      "rejected": 0,
      "pending": 1
    },
    "computedAt": "2026-09-09T10:04:01.000Z"
  },
  "meta": {
    "request_id": "req_7c2e9604",
    "timestamp": "2026-09-09T10:04:01.000Z"
  }
}

Poll this at or above its 60s cache cadence — a row that sits in in_review past its etaAt is the one to surface, not to re-fetch faster.

API Reference

All Endpoints

Worked onboarding reads