Worked request and response samples

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

{
  "data": {
    "integrations": [
      {
        "unique_key": "hubspot",
        "provider": "hubspot",
        "display_name": "HubSpot",
        "logo_url": "https://nango.example.com/logos/hubspot.svg",
        "status": "available",
        "syncs": ["contacts", "companies", "deals"],
        "actions": ["create-contact", "log-call"]
      },
      {
        "unique_key": "salesforce",
        "provider": "salesforce",
        "display_name": "Salesforce",
        "logo_url": null,
        "status": "available",
        "syncs": ["contacts", "accounts"],
        "actions": ["create-contact"]
      },
      {
        "unique_key": "pipedrive",
        "provider": "pipedrive",
        "display_name": "Pipedrive",
        "logo_url": null,
        "status": "available",
        "syncs": ["contacts"],
        "actions": []
      }
    ]
  },
  "meta": {
    "request_id": "req_integrations_catalog_01",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

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

{
  "data": {
    "integrations": [
      {
        "unique_key": "hubspot",
        "provider": "hubspot",
        "display_name": "HubSpot",
        "logo_url": "https://nango.example.com/logos/hubspot.svg",
        "status": "available",
        "syncs": ["contacts", "companies", "deals"],
        "actions": ["create-contact", "log-call"]
      },
      {
        "unique_key": "salesforce",
        "provider": "salesforce",
        "display_name": "Salesforce",
        "logo_url": null,
        "status": "available",
        "syncs": ["contacts", "accounts"],
        "actions": ["create-contact"]
      },
      {
        "unique_key": "pipedrive",
        "provider": "pipedrive",
        "display_name": "Pipedrive",
        "logo_url": null,
        "status": "available",
        "syncs": ["contacts"],
        "actions": []
      }
    ]
  },
  "meta": {
    "request_id": "req_integrations_catalog_01",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Copy a request as written, substitute your own ids, and compare the response envelope. Successful reads and writes return { data, meta }; failures return the { error, meta } envelope, and the retry-vs-surface matrix for every class sits at the bottom of this page. The four calls below are the chain every third-party CRM connection walks: discover what the catalogue offers, start the OAuth handshake, confirm the connection stuck and data is flowing, then trim the capabilities the connection exposes. HubSpot, Salesforce and Pipedrive ride the same rails — pick whichever the customer runs. A hidden catch-up sync exists too: POST /:id/sync with { "sync_name": … } forces a re-pull, and GET /:id/data?model=contacts reads back the synced records. Both are in the generated operation list below; the chain spans them.

1. Discover the catalogue

GET /api/v1/integrations/catalog

Every provider tile the Integrations grid offers is answered here — each row carries the provider’s key, the syncs and actions it advertises, and a status flag so you can gate a roadmap row before you send an operator into an OAuth flow. ?coming_soon= on the dashboard merges preview rows; the plain list covers the live set. Request

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

Response

{
  "data": {
    "integrations": [
      {
        "unique_key": "hubspot",
        "provider": "hubspot",
        "display_name": "HubSpot",
        "logo_url": "https://nango.example.com/logos/hubspot.svg",
        "status": "available",
        "syncs": ["contacts", "companies", "deals"],
        "actions": ["create-contact", "log-call"]
      },
      {
        "unique_key": "salesforce",
        "provider": "salesforce",
        "display_name": "Salesforce",
        "logo_url": null,
        "status": "available",
        "syncs": ["contacts", "accounts"],
        "actions": ["create-contact"]
      },
      {
        "unique_key": "pipedrive",
        "provider": "pipedrive",
        "display_name": "Pipedrive",
        "logo_url": null,
        "status": "available",
        "syncs": ["contacts"],
        "actions": []
      }
    ]
  },
  "meta": {
    "request_id": "req_integrations_catalog_01",
    "timestamp": "2026-09-08T12:00:00Z"
  }
}

Row-level badges come from a different call — GET /api/v1/integrations pages the same providers with the org’s connected flag folded in. Treat status: "coming_soon" as un-connectable and skip the OAuth kickoff for it.

2. Start the OAuth handshake

POST /api/v1/integrations/connect

Starts the connect flow for a catalogue key and returns the provider authorization URL your operator should be sent to. The handler resolves the provider’s own authorize endpoint — there is no connection record to create beforehand; the kickoff is one POST. Owner/admin role plus the integrations:write scope; a one-time audit event records who started the flow. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/integrations/connect" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_id": "hubspot"
  }'

Response

{
  "data": {
    "auth_url": "https://app.hubspot.com/oauth/authorize?client_id=hs_client_8a2f&redirect_uri=https%3A%2F%2Forbit.devotel.io%2Foauth%2Fcallback&scope=contacts%20crm.objects.companies.read"
  },
  "meta": {
    "request_id": "req_integrations_connect_01",
    "timestamp": "2026-09-08T12:00:01Z"
  }
}

Redirect the operator’s browser to data.auth_url. When the provider callback returns, the connection registers and the next poll of GET /api/v1/integrations/{id}/status flips connected to true — re-fetch with GET /api/v1/integrations/connections?fresh=1 if your page caches connection state.

3. Confirm the connection — scopes and last sync

GET /api/v1/integrations/{id}/status

Reads the connection back after the OAuth redirect: granted provider scopes sit under metadata, and each sync plus its last heartbeat carries the timestamp your data-freshness banner renders. A never-connected or revoked key returns connected: false with an empty syncs list rather than an error, so poll it freely. Request

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

Response

{
  "data": {
    "connected": true,
    "connection_id": "3f8a1c2b9d4e5f60718293a4b5c6d7e8",
    "provider": "hubspot",
    "created_at": "2026-09-08T12:01:44Z",
    "metadata": {
      "scopes": "contacts crm.objects.companies.read"
    },
    "syncs": [
      {
        "name": "contacts",
        "status": "SUCCESS",
        "last_synced_at": "2026-09-08T12:24:10Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_integrations_status_01",
    "timestamp": "2026-09-08T12:24:11Z"
  }
}

A PAUSED, STOPPED, ERROR or FAILED status on any sync marks the connection as errored at the fan-out layer (GET /api/v1/integrations/connections), and the dashboard card flips to a warning state — rely on the same classification when you build your own health probe.

4. Tune what the connection exposes

PATCH /api/v1/integrations/{id}/features

Per-tenant capability flags on the connection: audience (list building), crm_context (agent CRM tools), agent_tools, engagement, automation. Unknown keys are rejected with a 422; a disconnected integration returns 409 instead of silently saving a dead override. GET /:id/features returns the same object with every flag defaulted to true before any save. Request

curl -X PATCH "https://api.orbit.devotel.io/api/v1/integrations/hubspot/features" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "engagement": false,
    "automation": false
  }'

Response

{
  "data": {
    "audience": true,
    "crm_context": true,
    "agent_tools": true,
    "engagement": false,
    "automation": false
  },
  "meta": {
    "request_id": "req_integrations_features_01",
    "timestamp": "2026-09-08T12:25:02Z"
  }
}

Rotate a connected connection off the same way: DELETE /:id/disconnect, or key-scoped DELETE /connections/{uniqueKey} — for Slack it also flushes the per-tenant bot token before the upstream revoke so no stale events keep landing.

5. Force a sync, then read the records back

POST /api/v1/integrations/{id}/sync

The scheduled cadence is usually enough, but after a big import on the provider side you can force the named sync to run now instead of waiting. The call returns as soon as the run is queued, not when it finishes: poll section 3 for the outcome. Owner/admin role plus the integrations:write scope; a failed upstream trigger answers 502 SYNC_TRIGGER_FAILED. Request

curl -X POST "https://api.orbit.devotel.io/api/v1/integrations/hubspot/sync" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sync_name": "contacts"
  }'

Response

{
  "data": {
    "status": "triggered",
    "integration_id": "hubspot",
    "sync_name": "contacts"
  },
  "meta": {
    "request_id": "req_integrations_sync_01",
    "timestamp": "2026-09-08T12:26:40Z"
  }
}

Once that run lands, pull the synced records for one model yourself. The read walks the full record set, not a first page, so the array is the model’s complete current copy.

GET /api/v1/integrations/{id}/data?model=contacts

Request

curl -X GET "https://api.orbit.devotel.io/api/v1/integrations/hubspot/data?model=contacts" \
  -H "X-API-Key: $ORBIT_API_KEY"

Response

{
  "data": [
    {
      "id": "rec_8fk2m1q0pv",
      "email": "ada.lovelace@example.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "phone": "+14155550134",
      "updated_at": "2026-09-08T12:24:10Z"
    }
  ],
  "meta": {
    "request_id": "req_integrations_data_01",
    "timestamp": "2026-09-08T12:26:52Z"
  }
}

model is required and is one of the sync names GET /catalog lists for the provider (for HubSpot: contacts, companies, deals). A model the connection does not sync answers 422 VALIDATION_ERROR with error.details.field: "model", the same envelope as the 422 branch in the matrix below; the new 502 SYNC_RECORDS_FAILED class means the integration server failed mid-fetch, so back off and retry rather than treating it as “no records”. If the integration server is not configured the endpoint returns data: [], which reads exactly like a model that has not synced yet — disambiguate with GET /{id}/status.

6. Take the integration further than the API — blueprints and Postman

Every GET below is authenticated with the same X-API-Key and answers application/json with a per-org Content-Disposition filename (for an org slug of acme-corp, orbit-acme-corp.…), so save the body straight to that file. The blueprints are pre-wired to your tenant’s API host: triggers subscribe to the Orbit webhook event catalog and actions call the existing message, contact and verify endpoints.

GET /api/v1/developers/connector/zapier · GET /api/v1/developers/connector/make · GET /api/v1/developers/connector/n8n

Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/connector/zapier" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -o orbit-acme-corp.zapier-app.json

Response

HTTP/2 200
content-type: application/json; charset=utf-8
content-disposition: attachment; filename="orbit-acme-corp.zapier-app.json"
cache-control: no-store

{ "version": 1, "platform": "zapier", "triggers": ["conversation.created", "contact.updated"], "actions": ["send-sms", "create-contact"] }

/connector/make and /connector/n8n serve the same download for Make (orbit-acme-corp.make-app.json) and n8n (orbit-acme-corp.n8n-nodes.json); import the file into the tool rather than coding against it. Need the machine-readable trigger/action summary without downloading all three? GET /api/v1/developers/connector/catalog is the one inline { data, meta } read of the set. For Postman, the pair is a tenant-scoped collection plus its environment:

GET /api/v1/developers/postman-collection · GET /api/v1/developers/postman-environment

Request

curl -X GET "https://api.orbit.devotel.io/api/v1/developers/postman-collection" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -o orbit-acme-corp.postman_collection.json

Response

HTTP/2 200
content-type: application/json; charset=utf-8
content-disposition: attachment; filename="orbit-acme-corp.postman_collection.json"
cache-control: no-store

{ "info": { "name": "Devotel Orbit — acme-corp", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [] }

Import the collection and the environment together; the environment carries the base URL and scopes the collection’s requests to your org.

7. Sync states worth polling

The status values GET /{id}/status returns per sync, and what to do with each while you poll:

Status	Means	Your poll loop
`SUCCESS`	the most recent run finished and records landed	stop polling; read `GET /{id}/data?model=` for the model’s current copy
`RUNNING`	a run is in flight (initial backfill or incremental)	keep polling at backoff; `last_synced_at` advances when it completes
`ERROR` / `FAILED`	the latest run failed upstream	stop polling and surface; a retry is `POST /{id}/sync` with the same `sync_name`
`PAUSED` / `STOPPED`	the connection is flagged errored at the fan-out layer (`GET /connections`), data is not flowing	surface the reconnect flow; polling never heals it

A never-run sync reports last_synced_at: null; the connections fan-out mirrors the same classification in its errored flag, so a health probe of your own can branch on the identical set.

Errors worth branching on

These failures cover the chain above. Each block is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface for the same classes. For the platform-wide decision table these branches plug into, see the error handling guide.

401 — Unauthorized

  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "The API key is invalid, expired, or lacks the required scope.",
      "status": 401
    },
    "meta": {
      "request_id": "req_integrata1",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 401 on this page is the bearer key failing before the route ran — it never means the resource is wrong. Rotate the key or re-mint the scoped token; retrying the same request changes nothing.

403 — Forbidden

  {
    "error": {
      "code": "FORBIDDEN",
      "message": "The key is valid but does not have the scope this operation requires.",
      "status": 403
    },
    "meta": {
      "request_id": "req_integrata1f",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 403 means the key authenticated but the operation is gated by scope — check the key’s scopes on the developer page; a 403 is never a data-not-found shape. The connect, feature-flag and disconnect writes additionally require an owner or admin role.

422 — validation or connection-state mismatch

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": { "field": "integration_id", "value": "hubstp", "expected": "a catalogue key from GET /catalog" }
    },
    "meta": {
      "request_id": "req_integratb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and resend with one of the keys GET /catalog returns instead of blind-retrying the same body. On the features PATCH the validator rejects any key outside audience | crm_context | agent_tools | engagement | automation the same way, and re-saving a feature override the catalogue no longer lists surfaces as a 409 with code INTEGRATION_NOT_CONNECTED (see below) — connect first, then re-apply.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_integratc3",
      "timestamp": "2026-09-03T12:00:00Z",
      "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
    }
  }

The Retry-After header and error.details.retry_after are both set on every 429 — resend the SAME request after the lower of the two.

409 — the connection was not there yet

  {
    "error": {
      "code": "INTEGRATION_NOT_CONNECTED",
      "message": "Feature preferences can only be saved when the integration is connected. Connect first, then adjust capabilities.",
      "status": 409
    },
    "meta": {
      "request_id": "req_integratd4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

The features PATCH refuses to store an override for a key with no live connection — send the operator through the connect flow (section 2), then re-apply the override. GET /{id}/status tells you whether that has happened without erroring on a false.

60-second retry matrix

Class	Meaning	Branch response
401 `UNAUTHORIZED`	the bearer key itself fails	Surface. Rotate the key or re-mint the scoped token; do not retry the same request.
403 `FORBIDDEN`	the key lacks this operation’s scope	Surface. Fix the key’s scope set; a retry with the same key never heals it. Connect / features / disconnect writes also need an owner or admin role.
422 `VALIDATION_ERROR`	the payload does not match the schema	Fix, then resend intentionally. Branch on `error.details.field`; a blind retry repeats the same 422.
409 `INTEGRATION_NOT_CONNECTED`	a write needs a live connection	Surface the connect flow. Re-apply the feature override after OAuth completes.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.

8. Connect Intercom — OAuth install and the inbound receiver

Intercom rides the same rails as sections 1–5, with one structural difference: Orbit registers the event subscriptions on the Intercom side itself during the connect handshake, so there is no per-topic registration call for you to make. Start the install. GET /api/v1/integrations/intercom/oauth/start answers, in the standard envelope, with the Intercom authorization URL for your app. Hand that URL to a workspace admin; the install only completes once an admin approves it on the Intercom side. The redirect back. Intercom sends the admin’s browser to GET /api/v1/integrations/intercom/oauth/callback, which verifies the signed state, exchanges the code for a workspace token, registers the webhook topics, and stores the connection:

200

{
  "data": {
    "connected": true,
    "workspace_id": "ws_a1b2c3d4",
    "topics_subscribed": [
      "contact.created",
      "contact.updated",
      "conversation.user.replied"
    ]
  },
  "meta": {
    "request_id": "req_intercom_cb01",
    "timestamp": "2026-09-30T14:02:11Z"
  }
}

A declined install answers 400 with the standard error envelope; re-run the start call to retry. The inbound receiver. Once connected, Intercom delivers workspace events to POST /api/v1/integrations/webhooks/intercom — the URL Orbit registered during the handshake. Your integration never calls this endpoint; it is documented so you can recognize it in access logs and allow-list it. Every delivery authenticates with X-Hub-Signature: sha1=<hex>, an HMAC-SHA1 over the raw body, and re-deliveries (Intercom retries a notification up to 30 times) no-op on the (topic, notification_id) dedupe — a 200 from the receiver always means “recorded exactly once.” Read-back and re-pull. GET /api/v1/integrations/intercom/status reads the connection back exactly like section 3 (connected, per-sync last_synced_at); POST /api/v1/integrations/intercom/sync forces a re-pull after a big import on the Intercom side instead of waiting for the scheduled cadence. Any write against a workspace that has not completed the handshake answers 409 INTEGRATION_NOT_CONNECTED (matrix above) — connect first, then re-apply.

API Reference

All Endpoints

Worked request and response samples