Integrations API

Connect third-party SaaS apps (Salesforce, HubSpot, Shopify, Pipedrive, Zendesk, Intercom, …) and pull their data into Orbit for use in flows, AI agents, and contact enrichment. Auth, token refresh, rate limiting, and provider-specific quirks are handled for you. Base path: /api/v1/integrations Authentication: API key (X-API-Key) or session JWT. Connect, disconnect, and sync are owner/admin-only writes; list, status, and data reads require the integrations:read scope, writes the integrations:write scope. Every response below is wrapped in the standard envelope: a data payload plus a meta block with request_id and timestamp. Errors use an error object with code, message, and status.

Using the SDKs

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

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

const res = await orbit.integrations.listCatalog();

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", "/integrations")

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.

Connections

Method	Path	Purpose
`GET`	`/api/v1/integrations`	List connected integrations
`POST`	`/api/v1/integrations/connect`	Initiate an OAuth connect flow
`GET`	`/api/v1/integrations/{id}/status`	Connection health + sync status
`DELETE`	`/api/v1/integrations/{id}/disconnect`	Disconnect (revokes provider tokens)

Sync & data

Method	Path	Purpose
`POST`	`/api/v1/integrations/{id}/sync`	Trigger a sync now
`GET`	`/api/v1/integrations/{id}/data`	Read synced records

The sections below walk one end-to-end HubSpot connection: list the catalog, start the OAuth flow, confirm the connection, trigger a sync, read records, and disconnect.

Inbound webhook

The integration server posts auth + sync events to POST /api/v1/integrations/webhooks/nango — internal only. You don’t call this directly.

List integrations

GET /api/v1/integrations Returns every integration available to your organization with a connected flag, its provider, category, and the syncs it offers, cursor-paginated (?limit= + ?cursor=). Add a ?fields= projection (comma-separated field names) when you only need a couple of fields per item. If the integration server is unreachable, the route serves the built-in catalog with connected: false instead of an error, so your settings page always renders.

curl "https://api.orbit.devotel.io/api/v1/integrations?limit=25" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "hubspot",
      "name": "HubSpot",
      "provider": "hubspot",
      "category": "crm",
      "connected": true,
      "syncs": ["contacts", "deals", "companies"]
    },
    {
      "id": "salesforce",
      "name": "Salesforce",
      "provider": "salesforce",
      "category": "crm",
      "connected": false,
      "syncs": ["contacts", "deals"]
    }
  ],
  "pagination": {
    "cursor": "salesforce",
    "has_more": true,
    "total": 14
  },
  "meta": {
    "request_id": "req_int_001",
    "timestamp": "2026-08-26T09:00:00Z"
  }
}

Start the OAuth connect flow

POST /api/v1/integrations/connect Initiates the OAuth authorization flow for one integration_id and returns the auth_url you redirect the operator to. Owner/admin only. A provider with no OAuth credentials set up yet returns 404; an integration-server outage returns 503. The narrative below uses HubSpot; swap the integration_id for any provider in the catalog.

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

{
  "data": {
    "auth_url": "https://app.hubspot.com/oauth/authorize?client_id=…&redirect_uri=…&scope=crm.objects.contacts.read"
  },
  "meta": {
    "request_id": "req_int_002",
    "timestamp": "2026-08-26T09:01:00Z"
  }
}

Redirect the operator to auth_url. After they consent on the provider’s page, they’re returned to Orbit and the connection is established — from here on, syncs can run.

Check connection status

GET /api/v1/integrations/{id}/status Returns whether the integration is connected for your organization plus the connection metadata and the per-sync status when connected. A never-connected or revoked integration resolves to connected: false with an empty sync list — not a 4xx — so you can render a disconnected state without special-casing errors.

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

{
  "data": {
    "connected": true,
    "connection_id": "b36e9147-…-8f2a",
    "provider": "hubspot",
    "created_at": "2026-08-20T14:11:00Z",
    "updated_at": "2026-08-26T08:58:00Z",
    "metadata": { "scopes": ["crm.objects.contacts.read", "crm.objects.deals.read"] },
    "syncs": [
      { "name": "contacts", "last_sync_at": "2026-08-26T08:55:00Z", "status": "idle" },
      { "name": "deals", "last_sync_at": "2026-08-26T08:55:12Z", "status": "idle" }
    ]
  },
  "meta": {
    "request_id": "req_int_003",
    "timestamp": "2026-08-26T09:02:00Z"
  }
}

Disconnected — whether it was never connected or the tokens were revoked — looks like this:

200

{
  "data": { "connected": false, "syncs": [] },
  "meta": { "request_id": "req_int_004", "timestamp": "2026-08-26T09:02:10Z" }
}

Trigger a sync

POST /api/v1/integrations/{id}/sync Runs one sync immediately instead of waiting for its scheduled cadence. The body names the sync — for HubSpot that’s contacts, deals, or companies from the catalog entry. Owner/admin only. A failed upstream trigger returns 502; there is no job handle to poll — watch the last_sync_at timestamps on the status endpoint to see the run complete.

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

{
  "data": {
    "status": "triggered",
    "integration_id": "hubspot",
    "sync_name": "contacts"
  },
  "meta": {
    "request_id": "req_int_005",
    "timestamp": "2026-08-26T09:03:00Z"
  }
}

Read synced records

GET /api/v1/integrations/{id}/data?model={name} Returns the records the integration has synced for one model. model is a required query parameter and names the model in the sync’s vocabulary (contacts, deals, companies for HubSpot). The response is the full record set — the route walks the integration server’s record cursor for you, so there is no pagination to manage on this endpoint. An unconfigured integration server returns an empty array; a failed upstream fetch returns 502.

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

{
  "data": [
    {
      "id": "hs-88412",
      "firstname": "Amara",
      "lastname": "Osei",
      "email": "amara@acme.example",
      "hs_lastmodifieddate": "2026-08-26T08:55:00Z"
    },
    {
      "id": "hs-88413",
      "firstname": "Jonas",
      "lastname": "Mikkelsen",
      "email": "jonas@globex.example",
      "hs_lastmodifieddate": "2026-08-26T08:55:01Z"
    }
  ],
  "meta": {
    "request_id": "req_int_006",
    "timestamp": "2026-08-26T09:04:00Z"
  }
}

Record fields are the provider’s own, passed through unchanged — the envelope is normalized, the record body is not. Map the provider fields you need; anything absent from a record stays absent.

Disconnect

DELETE /api/v1/integrations/{id}/disconnect Revokes the OAuth connection. Provider tokens stop working immediately and no further syncs run. Owner/admin only. A failed upstream revoke returns 502 — retry rather than assuming it went through.

curl -X DELETE https://api.orbit.devotel.io/api/v1/integrations/hubspot/disconnect \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "status": "disconnected",
    "integration_id": "hubspot"
  },
  "meta": {
    "request_id": "req_int_007",
    "timestamp": "2026-08-26T09:05:00Z"
  }
}

After the revoke, GET /{id}/status reports connected: false, and you can leave the revoked integration in your catalog or remove it from view entirely.

Same flow in Node `fetch`

No SDK required — plain Node 18+ fetch, dependency-free, walking the whole HubSpot narrative above.

const API_KEY = process.env.ORBIT_API_KEY;
const BASE = 'https://api.orbit.devotel.io/api/v1/integrations';

async function call(path, options = {}) {
  const res = await fetch(BASE + path, {
    ...options,
    headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json', ...options.headers },
  });
  const body = await res.json();
  if (!res.ok) throw new Error(`${res.status} ${body.error?.code}: ${body.error?.message}`);
  return body.data;
}

// 1. Start the OAuth flow and get the redirect URL.
const { auth_url } = await call('/connect', {
  method: 'POST',
  body: JSON.stringify({ integration_id: 'hubspot' }),
});
console.log('Send the operator to:', auth_url);

// 2. After consent, confirm the connection is live.
const status = await call('/hubspot/status');
if (!status.connected) throw new Error('HubSpot not connected yet');
console.log('Connected as', status.connection_id);

// 3. Trigger a contacts sync on demand.
await call('/hubspot/sync', {
  method: 'POST',
  body: JSON.stringify({ sync_name: 'contacts' }),
});

// 4. Read the synced contacts.
const records = await call('/hubspot/data?model=contacts');
console.log(`Synced ${records.length} contacts`);

// 5. Disconnect when you're done.
await call('/hubspot/disconnect', { method: 'DELETE' });

More task-shaped recipes in the same curl + Node style: REST API recipes.

Errors

Status	Condition	Error code
`401`	Missing or invalid API key, or the key lacks `integrations:read` / `integrations:write`	`UNAUTHORIZED`
`404`	Unknown `integration_id`, or the provider has no OAuth credentials set up	`INTEGRATION_NOT_CONFIGURED`
`409`	Duplicate connection — writing per-connection settings before connecting	`INTEGRATION_NOT_CONNECTED`
`502`	The sync trigger, record fetch, or disconnect failed upstream	`SYNC_TRIGGER_FAILED` / `SYNC_RECORDS_FAILED` / `DISCONNECT_FAILED`
`503`	Integration server not configured or unreachable	`NANGO_NOT_CONFIGURED` / `NANGO_UNAVAILABLE`

A disconnected integration is not an error — status and data reads stay 200 with connected: false / [] — so reserve error handling for the table above.

API Reference

All Endpoints

Integrations API: connect Salesforce, HubSpot, and more

Integrations API

Using the SDKs

Connections

Sync & data

Inbound webhook

List integrations

Start the OAuth connect flow

Check connection status

Trigger a sync

Read synced records

Disconnect

Same flow in Node `fetch`

Errors

See also

​Integrations API

​Using the SDKs

​Connections

​Sync & data

​Inbound webhook

​List integrations

​Start the OAuth connect flow

​Check connection status

​Trigger a sync

​Read synced records

​Disconnect

​Same flow in Node fetch

​Errors

​See also

Integrations API

Using the SDKs

Connections

Sync & data

Inbound webhook

List integrations

Start the OAuth connect flow

Check connection status

Trigger a sync

Read synced records

Disconnect

Same flow in Node `fetch`

Errors

See also