Skip to content

Connectors API ​

Overview ​

The Connectors API manages SaaS tool integrations: OAuth flows, sync operations, record queries, webhook ingestion, entity resolution, and admin oversight. All endpoints require authentication (session cookie or API key) and the saas_connectors feature flag unless noted otherwise.

Base path: /api/connectors


Connector catalog ​

List available connectors ​

GET /api/connectors/

Returns all registered connectors with categories and connection status.

Response ​

json
{
  "connectors": [
    {
      "id": "rippling",
      "display_name": "Rippling",
      "category": "hris",
      "description": "Sync employee directory, departments, and teams",
      "supported_entities": ["employee", "company"],
      "supports_webhooks": true,
      "icon_url": "/connector-logos/rippling.svg",
      "connected": true,
      "connection_id": "conn_abc123"
    },
    {
      "id": "merge_hris",
      "display_name": "Merge HRIS",
      "category": "hris",
      "description": "Connect 50+ HRIS platforms via unified API",
      "supported_entities": ["employee", "team", "employment", "location"],
      "supports_webhooks": false,
      "icon_url": "/connector-logos/merge.svg",
      "connected": false,
      "connection_id": null
    }
  ]
}

OAuth flow ​

Start OAuth flow ​

GET /api/connectors/{connector_id}/connect

Redirects the user to the SaaS provider’s OAuth authorization page. A cryptographic state parameter is generated and stored server-side (5-minute TTL) for CSRF protection.

ParameterTypeDescription
connector_idpathConnector identifier (for example, rippling)

Response ​

302 Redirect to the provider’s OAuth consent page.

OAuth callback ​

GET /api/connectors/{connector_id}/callback

Handles the OAuth callback from the SaaS provider. Exchanges the authorization code for access and refresh tokens, encrypts them with AES-256-GCM, and creates the connection.

ParameterTypeDescription
connector_idpathConnector identifier
codequeryAuthorization code from provider
statequeryCSRF state token (validated server-side)

Response ​

HTML page that sends postMessage to the opener window and auto-closes.


Connection management ​

List connections ​

GET /api/connectors/connections

Returns the authenticated user’s active connections.

Response ​

json
{
  "connections": [
    {
      "id": "conn_abc123",
      "connector_id": "rippling",
      "status": "active",
      "health_status": "healthy",
      "provider_account_name": "Acme Corp",
      "last_synced_at": "2026-03-29T10:00:00Z",
      "record_count": 127,
      "visibility_scope": "cloud",
      "visibility_scope_id": null,
      "created_at": "2026-03-28T14:30:00Z"
    }
  ]
}

Connection detail ​

GET /api/connectors/connections/{id}

Returns full detail for a single connection, including health information.

ParameterTypeDescription
idpathConnection ID

Response ​

json
{
  "id": "conn_abc123",
  "connector_id": "rippling",
  "display_name": "Rippling",
  "status": "active",
  "health_status": "healthy",
  "health_checked_at": "2026-03-29T10:15:00Z",
  "provider_account_name": "Acme Corp",
  "last_synced_at": "2026-03-29T10:00:00Z",
  "record_count": 127,
  "visibility_scope": "cloud",
  "visibility_scope_id": null,
  "consent_accepted_at": "2026-03-28T14:30:00Z",
  "created_at": "2026-03-28T14:30:00Z",
  "updated_at": "2026-03-29T10:00:00Z"
}

Disconnect ​

DELETE /api/connectors/connections/{id}

Revokes the connection and cascade-deletes all associated records and memories.

ParameterTypeDescription
idpathConnection ID

Response ​

json
{
  "status": "revoked",
  "records_deleted": 127,
  "memories_deleted": 127,
  "webhooks_disabled": 1
}

Set visibility scope ​

PUT /api/connectors/connections/{id}/visibility

Admin-only. Sets who can see data from this connection.

ParameterTypeDescription
idpathConnection ID

Request ​

json
{
  "visibility_scope": "group",
  "visibility_scope_id": "grp_leadership"
}
FieldTypeRequiredDescription
visibility_scopestringYescloud, group, or user
visibility_scope_idstringWhen scope is groupGroup ID for group-restricted scope

Response ​

json
{
  "id": "conn_abc123",
  "visibility_scope": "group",
  "visibility_scope_id": "grp_leadership",
  "updated_at": "2026-03-29T11:00:00Z"
}

Sync operations ​

Trigger sync ​

POST /api/connectors/connections/{id}/sync

Triggers a manual sync for the connection. Returns immediately; sync runs as a background task.

ParameterTypeDescription
idpathConnection ID

Response ​

json
{
  "sync_job_id": "sync_xyz789",
  "status": "pending",
  "trigger": "manual",
  "created_at": "2026-03-29T11:05:00Z"
}

List sync jobs ​

GET /api/connectors/connections/{id}/sync-jobs

Returns sync job history for a connection.

ParameterTypeDescription
idpathConnection ID

Query parameters ​

ParameterTypeDefaultDescription
limitint20Maximum results
offsetint0Pagination offset

Response ​

json
{
  "sync_jobs": [
    {
      "id": "sync_xyz789",
      "status": "completed",
      "trigger": "scheduled",
      "entity_types": "employee",
      "records_synced": 127,
      "records_total": 127,
      "errors": null,
      "started_at": "2026-03-29T10:00:00Z",
      "completed_at": "2026-03-29T10:00:08Z",
      "duration_ms": 8200
    }
  ],
  "total": 15
}

Push to memory ​

POST /api/connectors/connections/{id}/memory-sync

Pushes synced records through the MemoryBridge to create or update AI memories. Usually triggered automatically after sync; this endpoint allows manual re-bridging.

ParameterTypeDescription
idpathConnection ID

Response ​

json
{
  "memories_created": 12,
  "memories_updated": 115,
  "memories_unchanged": 0,
  "pii_fields_filtered": 889
}

Record queries ​

Query synced records ​

GET /api/connectors/connections/{id}/records

Returns synced records for a connection. Respects visibility scope.

ParameterTypeDescription
idpathConnection ID

Query parameters ​

ParameterTypeDefaultDescription
entity_typestringallFilter by entity type (for example, employee)
searchstring—Search by name or email
limitint50Maximum results
offsetint0Pagination offset

Response ​

json
{
  "records": [
    {
      "id": "rec_001",
      "entity_type": "employee",
      "external_id": "emp_12345",
      "record_kind": "data",
      "data": {
        "name": "Alice Smith",
        "email": "alice@acme.com",
        "department": "Engineering",
        "title": "Senior Engineer",
        "team": "Platform",
        "manager": "Bob Jones",
        "work_location": "San Francisco",
        "employment_type": "Full-time",
        "start_date": "2024-01-15",
        "status": "Active"
      },
      "synced_at": "2026-03-29T10:00:05Z",
      "memory_id": "mem_abc123"
    }
  ],
  "total": 127
}

Webhooks ​

Inbound webhook ​

POST /api/connectors/webhooks/{connector_id}/{webhook_secret}

Public endpoint — no cookie or API key required. Authenticated via connector-specific signature verification on the request headers and body.

This is the URL that SaaS tools POST events to. Each connection gets a unique webhook_secret in the URL.

The endpoint:

  1. Validates the connector-specific signature (for example, Rippling HMAC).
  2. Checks timestamp freshness (rejects payloads older than 5 minutes when available).
  3. Parses events into normalized records.
  4. Upserts records and triggers MemoryBridge.
ParameterTypeDescription
connector_idpathConnector identifier
webhook_secretpathPer-connection webhook secret

Response ​

200 OK with:

json
{
  "status": "accepted",
  "records_upserted": 1
}

Rate limit: 100 requests per minute per webhook_secret. Excess traffic returns 429 Too Many Requests.


Entity resolution ​

Requires the saas_connector_entities feature flag for endpoints in this section.

List resolved entities ​

GET /api/connectors/entities

Returns cross-connector resolved entities for the organization.

Query parameters ​

ParameterTypeDefaultDescription
entity_typestringallperson, company, or team
searchstring—Search by name or identifier
limitint50Maximum results

Response ​

json
{
  "entities": [
    {
      "id": "ent_alice",
      "entity_type": "person",
      "primary_identifier": "alice@acme.com",
      "display_name": "Alice Smith",
      "source_count": 2,
      "sources": ["rippling", "salesforce"],
      "updated_at": "2026-03-29T10:00:05Z"
    }
  ],
  "total": 89
}

Entity profile ​

GET /api/connectors/entities/{id}

Returns the unified profile for a resolved entity with merged fields. Use Entity source records for per-connector rows.

ParameterTypeDescription
idpathEntity ID

Response ​

json
{
  "id": "ent_alice",
  "entity_type": "person",
  "primary_identifier": "alice@acme.com",
  "display_name": "Alice Smith",
  "merged_data": {
    "name": "Alice Smith",
    "email": "alice@acme.com",
    "department": "Engineering",
    "title": "Senior Engineer",
    "team": "Platform",
    "work_location": "San Francisco"
  },
  "source_count": 2,
  "first_seen_at": "2026-03-28T14:30:00Z",
  "updated_at": "2026-03-29T10:00:05Z"
}

Entity source records ​

GET /api/connectors/entities/{id}/records

Returns all source records that resolved to this entity.

ParameterTypeDescription
idpathEntity ID

Response ​

json
{
  "records": [
    {
      "id": "rec_001",
      "connector_id": "rippling",
      "entity_type": "employee",
      "external_id": "emp_12345",
      "data": {
        "name": "Alice Smith",
        "department": "Engineering"
      },
      "synced_at": "2026-03-29T10:00:05Z"
    }
  ]
}

Admin endpoints ​

Admin-only unless noted. Operates across the whole organization.

All organization connections ​

GET /api/connectors/admin/connections

Returns every connection in the organization. Response shape matches List connections, with user_id and user_email on each item.

Response ​

json
{
  "connections": [
    {
      "id": "conn_abc123",
      "connector_id": "rippling",
      "status": "active",
      "health_status": "healthy",
      "provider_account_name": "Acme Corp",
      "last_synced_at": "2026-03-29T10:00:00Z",
      "record_count": 127,
      "visibility_scope": "cloud",
      "visibility_scope_id": null,
      "created_at": "2026-03-28T14:30:00Z",
      "user_id": "usr_admin01",
      "user_email": "admin@acme.com"
    },
    {
      "id": "conn_def456",
      "connector_id": "merge_hris",
      "status": "active",
      "health_status": "warning",
      "provider_account_name": "Acme Corp — BambooHR",
      "last_synced_at": "2026-03-28T22:00:00Z",
      "record_count": 412,
      "visibility_scope": "group",
      "visibility_scope_id": "grp_hr_ops",
      "created_at": "2026-03-20T09:00:00Z",
      "user_id": "usr_hr_lead",
      "user_email": "hr.lead@acme.com"
    }
  ]
}

Organization health overview ​

GET /api/connectors/admin/health

Returns a health summary for all organization connections.

Response ​

json
{
  "total_connections": 3,
  "healthy": 2,
  "warning": 1,
  "error": 0,
  "expired": 0,
  "connections": [
    {
      "id": "conn_abc123",
      "connector_id": "rippling",
      "health_status": "healthy",
      "health_checked_at": "2026-03-29T10:15:00Z",
      "provider_account_name": "Acme Corp",
      "user_email": "admin@acme.com"
    }
  ]
}

Authentication ​

All endpoints except the inbound webhook require authentication via session cookie or API key header:

Authorization: Bearer <api_key>

The inbound webhook endpoint authenticates via connector-specific signature verification on the request body (and headers, where applicable).


Feature flags ​

FlagRequired forTier
saas_connectorsAll connector endpointsPersonal+
saas_connector_webhooksWebhook processingBusiness+
saas_connector_actionsAction executionBusiness+
saas_connector_entitiesEntity resolution endpointsBusiness+
saas_connector_unified_apiMerge and unified API connectorsEnterprise

Error responses ​

Standard error format:

json
{
  "detail": "Connection not found",
  "status_code": 404
}
StatusMeaning
400Invalid request parameters
401Not authenticated
403Insufficient permissions or feature unavailable for tier
404Connection or entity not found
429Rate limit exceeded (webhooks)
500Internal server error

SOC 2 Type II Certified | BAA Available | HIPAA-Ready