Imports API

The one-click migration importer pulls your existing configuration and audience out of another provider and maps it onto Orbit. It runs as a five-step wizard: connect a source account, preview what will be imported (a dry run), run the import as a background job, watch its progress live, and reconcile any conflicts. Every credential you supply is used only to read your source account — phone numbers, messaging profiles, templates, contacts, conversations, and audiences. Orbit never sends messages or places calls through your old provider as a result of an import: outbound traffic always exits through Orbit. The credential is encrypted the moment you submit it, handed forward as an opaque envelope string, and removed from the job record once the import finishes. Base path: /api/v1/imports Authentication: Clerk session (Authorization: Bearer <token>) or API key (X-API-Key). Every endpoint requires an authenticated tenant.

Supported sources

The {source} path segment on the dry-run and run endpoints is one of:

Source	Value	Connect method
Twilio	`twilio`	Twilio Connect OAuth, or a manual Account SID + Auth Token
Telnyx	`telnyx`	Manual V2 API key
Klaviyo	`klaviyo`	Manual private API key (`pk_…`)
MessageBird (Bird)	`messagebird`	Manual access key
Front	`front`	Connected during onboarding

Entity kinds

Each import selects a subset of entity kinds to pull. Every source advertises the kinds it supports; ask for between 1 and 10 per import. phone_numbers, messaging_services, templates, contacts, conversations, channels, flows, inboxes, tags, teammates, lists, segments

Step 1 — connect a source

The connect step exchanges your source credentials for an opaque, encrypted envelope string. You pass that envelope to the dry-run and run steps; it is never stored in the browser and the raw secret is never echoed back.

Start the Twilio Connect authorization

GET /api/v1/imports/twilio/connect

Begins the Twilio Connect OAuth flow. Returns a Twilio authorization URL for the wizard to open in a popup, plus a state value to match against on the callback.

cURL

curl "https://api.orbit.devotel.io/api/v1/imports/twilio/connect" \
  -H "X-API-Key: dv_live_sk_your_key_here"

200 OK

{
  "data": {
    "authorizeUrl": "https://www.twilio.com/authorize?response_type=code&client_id=CN…&state=twoa_…&code_challenge=…&code_challenge_method=S256",
    "state": "twoa_1a2b3c4d5e6f"
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-08-13T12:00:00Z" }
}

Returns 503 TWILIO_CONNECT_NOT_CONFIGURED when Twilio Connect is not enabled on the environment — fall back to Submit Twilio credentials manually below.

Complete the Twilio Connect authorization

GET /api/v1/imports/twilio/callback

Twilio redirects the browser here after the user approves access. It validates the returned state, exchanges the authorization code for credentials, encrypts them, and issues a 302 redirect back into the import wizard with the envelope attached to the URL. You do not call this endpoint yourself — Twilio invokes it, and the raw access token is never returned to the browser. Returns 400 when the authorization was denied or the code/state is missing or invalid.

Submit Twilio credentials manually

POST /api/v1/imports/twilio/manual-credentials

Use this when the OAuth flow is unavailable (for example, a self-hosted subaccount). Returns the encrypted envelope directly.

string

required

Twilio Account SID — starts with AC followed by 32 hex characters.

string

required

Twilio Auth Token, 8–256 characters.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/imports/twilio/manual-credentials" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "accountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "authToken": "your_auth_token" }'

200 OK

{
  "data": {
    "envelope": "enc:…opaque…",
    "accountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-08-13T12:00:00Z" }
}

Submit Telnyx / Klaviyo / MessageBird credentials manually

POST /api/v1/imports/telnyx/manual-credentials
POST /api/v1/imports/klaviyo/manual-credentials
POST /api/v1/imports/messagebird/manual-credentials

These providers don’t publish an OAuth delegation flow, so you supply an API key directly. All three take the same body and return the same envelope shape.

string

required

The provider API key. Telnyx V2 keys start with KEY; Klaviyo private keys start with pk_; MessageBird access keys are alphanumeric (optionally prefixed live_ or test_).

string

Optional display-only label shown in the wizard’s “Connected as” line. Up to 128 characters.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/imports/telnyx/manual-credentials" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "apiKey": "KEYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "accountId": "Acme Corp" }'

200 OK

{
  "data": { "envelope": "enc:…opaque…", "accountId": "Acme Corp" },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-08-13T12:00:00Z" }
}

Returns 422 VALIDATION_ERROR when the key doesn’t match the provider’s format.

Step 2 — preview (dry run)

POST /api/v1/imports/{source}/dry-run

Counts the upstream entities and detects conflicts with data already in Orbit, so you can show an accurate row count and estimated duration before committing. Nothing is written.

string

required

The encrypted credentials envelope from step 1.

array

required

1–10 entity kinds to preview (see Entity kinds).

integer

Twilio only — how many days of conversation history to include, 1–90. Twilio exposes at most 90 days of message history without an Insights subscription, so values above 90 are rejected.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/imports/twilio/dry-run" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "envelope": "enc:…opaque…",
    "entities": ["phone_numbers", "contacts", "conversations"],
    "conversationDays": 30
  }'

200 OK

{
  "data": {
    "source": "twilio",
    "entities": [
      { "kind": "phone_numbers", "estimatedCount": 12, "knownConflicts": 1 },
      { "kind": "contacts", "estimatedCount": 8421, "knownConflicts": 0 },
      { "kind": "conversations", "estimatedCount": 15230, "knownConflicts": 0 }
    ],
    "etaSeconds": 540,
    "generatedAt": "2026-08-13T12:00:00Z"
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-08-13T12:00:00Z" }
}

Step 3 — run the import

POST /api/v1/imports/{source}/run

Queues a background import job and returns its jobId. Submit the same envelope and entities you previewed, optionally with a per-entity conflictPolicy.

string

required

The encrypted credentials envelope from step 1.

array

required

1–10 entity kinds to import.

integer

Twilio only — conversation lookback window, 1–90 days.

object

Optional map of entity kind → how to resolve a collision: skip, overwrite, or merge. Kinds you omit fall back to skipping conflicting rows.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/imports/twilio/run" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "envelope": "enc:…opaque…",
    "entities": ["phone_numbers", "contacts", "conversations"],
    "conversationDays": 30,
    "conflictPolicy": { "contacts": "merge" }
  }'

202 Accepted

{
  "data": { "jobId": "imp_9s2h1k4m7p", "status": "pending" },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-08-13T12:00:00Z" }
}

Open the progress stream for jobId to watch it run.

Step 4 — track progress

Stream import job progress

GET /api/v1/imports/{jobId}/progress

A Server-Sent Events stream of the job’s per-entity counts and status transitions. The first frame is a snapshot of the current state, so a page that subscribes late renders immediately; keepalive comments arrive every 15 seconds and the stream closes automatically after one hour. A job that has already finished replays its final end frame and closes. Frame events: snapshot, progress, status, end.

cURL

curl -N "https://api.orbit.devotel.io/api/v1/imports/imp_9s2h1k4m7p/progress" \
  -H "X-API-Key: dv_live_sk_your_key_here"

event: snapshot
data: {"jobId":"imp_9s2h1k4m7p","status":"running","source":"twilio","progress":[…]}

event: progress
data: {"type":"progress","kind":"contacts","imported":4200,"total":8421}

event: end
data: {"status":"succeeded"}

Returns 403 when the request origin isn’t allowed, or 404 when no such job exists for your tenant.

Get an import job

GET /api/v1/imports/{jobId}

A point-in-time snapshot of a single job — its source, status, and per-entity progress. Poll this if you don’t need the live stream.

cURL

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

200 OK

{
  "data": {
    "id": "imp_9s2h1k4m7p",
    "source": "twilio",
    "status": "running",
    "progress": [
      { "kind": "contacts", "total": 8421, "imported": 4200, "skipped": 0, "failed": 0 }
    ]
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-08-13T12:00:00Z" }
}

List recent import jobs

GET /api/v1/imports

Returns your organization’s recent import jobs, each with its source and status — used to render the import history table.

cURL

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

200 OK

{
  "data": {
    "jobs": [
      { "id": "imp_9s2h1k4m7p", "source": "twilio", "status": "running" },
      { "id": "imp_7a1b2c3d4e", "source": "telnyx", "status": "succeeded" }
    ]
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-08-13T12:00:00Z" }
}

Step 5 — cancel or roll back

Cancel a running import job

POST /api/v1/imports/{jobId}/cancel

Requests cancellation of an in-flight job. The status flips to cancelled and the worker stops between pages on its next check. Only a job that is still pending or running can be cancelled.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/imports/imp_9s2h1k4m7p/cancel" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Returns 404 NOT_FOUND when the job doesn’t exist, or 409 IMPORT_NOT_CANCELLABLE (with the current status in details.current_status) when the job has already reached a terminal state.

Roll back a completed import

POST /api/v1/imports/{jobId}/rollback

Deletes every contact created by this import batch in a single transaction and records the rollback on the job. This is destructive and is restricted to owner or admin roles. Roll back only after the job has finished or been cancelled.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/imports/imp_9s2h1k4m7p/rollback" \
  -H "X-API-Key: dv_live_sk_your_key_here"

200 OK

{
  "data": { "rolledBack": true, "deletedCount": 8421 },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-08-13T12:00:00Z" }
}

Returns 403 FORBIDDEN for a non-owner/admin caller, 404 NOT_FOUND when the job doesn’t exist, and 409 when the job is still running (IMPORT_STILL_RUNNING) or has already been rolled back (ALREADY_ROLLED_BACK).

Errors

Status	`error.code`	Cause
`400`	`INVALID_ENVELOPE`	The credentials `envelope` couldn’t be decrypted — restart from step 1.
`400`	`TWILIO_OAUTH_DENIED` / `VALIDATION_ERROR`	The Twilio callback was denied, or `code`/`state` was missing.
`403`	`FORBIDDEN`	Only `owner` or `admin` may roll back an import.
`403`	`OAUTH_STATE_MISMATCH`	The OAuth `state` doesn’t match the current session.
`404`	`UNKNOWN_IMPORT_SOURCE`	The `{source}` segment isn’t a supported provider.
`404`	`NOT_FOUND`	No import job with that id exists for your tenant.
`409`	`IMPORT_NOT_CANCELLABLE`	The job already reached a terminal status.
`409`	`IMPORT_STILL_RUNNING` / `ALREADY_ROLLED_BACK`	Cancel before rolling back, or the job was already rolled back.
`422`	`VALIDATION_ERROR`	The request body failed validation (bad key format, empty `entities`, or more than 10 kinds).
`503`	`TWILIO_CONNECT_NOT_CONFIGURED`	Twilio Connect isn’t enabled — use manual credentials.

API Reference

All Endpoints

Imports API: one-click migration from another provider

Imports API

Supported sources

Entity kinds

Step 1 — connect a source

Start the Twilio Connect authorization

Complete the Twilio Connect authorization

Submit Twilio credentials manually

Submit Telnyx / Klaviyo / MessageBird credentials manually

Step 2 — preview (dry run)

Step 3 — run the import

Step 4 — track progress

Stream import job progress

Get an import job

List recent import jobs

Step 5 — cancel or roll back

Cancel a running import job

Roll back a completed import

Errors

See also

​Imports API

​Supported sources

​Entity kinds

​Step 1 — connect a source

​Start the Twilio Connect authorization

​Complete the Twilio Connect authorization

​Submit Twilio credentials manually

​Submit Telnyx / Klaviyo / MessageBird credentials manually

​Step 2 — preview (dry run)

​Step 3 — run the import

​Step 4 — track progress

​Stream import job progress

​Get an import job

​List recent import jobs

​Step 5 — cancel or roll back

​Cancel a running import job

​Roll back a completed import

​Errors

​See also

Imports API

Supported sources

Entity kinds

Step 1 — connect a source

Start the Twilio Connect authorization

Complete the Twilio Connect authorization

Submit Twilio credentials manually

Submit Telnyx / Klaviyo / MessageBird credentials manually

Step 2 — preview (dry run)

Step 3 — run the import

Step 4 — track progress

Stream import job progress

Get an import job

List recent import jobs

Step 5 — cancel or roll back

Cancel a running import job

Roll back a completed import

Errors

See also