Connector API

The connector router manages data source integrations including Salesforce, Customer.io, Delivr.ai, O365, and Fathom.video. It handles OAuth authentication, sync operations, and connection status monitoring.

Router namespace: connector

Source: src/server/trpc/routers/connector.ts

Procedures

Procedure	Type	Access	Description
list	query	tenant	List all registered connectors with status
getStatus	query	tenant	Get detailed status for a specific connector
getAuthUrl	mutation	admin	Generate Salesforce OAuth authorization URL
disconnect	mutation	admin	Disconnect a connector
getSyncHistory	query	tenant	Get sync log history for a connector
getEntityCounts	query	tenant	Get entity counts synced from a connector
triggerSync	mutation	admin	Trigger a data sync for a connector

---

list

Returns all registered connectors with their current connection status, merging the connector registry with database records.

connector.list.queryOptions()

Input

None.

Response

[
  {
    "id": "salesforce",
    "name": "Salesforce",
    "version": "1.0.0",
    "status": "connected",
    "lastSyncAt": "2026-03-05T08:00:00.000Z",
    "lastSyncError": null
  },
  {
    "id": "customerio",
    "name": "Customer.io",
    "version": "1.0.0",
    "status": "disconnected",
    "lastSyncAt": null,
    "lastSyncError": null
  }
]

Connector Statuses

Status	Description
disconnected	Not configured or explicitly disconnected
pending_auth	OAuth flow initiated, awaiting callback
connected	Authenticated and ready for sync
syncing	Sync currently in progress
error	Last sync failed

---

getStatus

Returns detailed status for a specific connector including latest sync statistics.

connector.getStatus.queryOptions(input)

Input

Field	Type	Required	Description
connectorId	string	Yes	Connector identifier (e.g., "salesforce")

Response

{
  "id": "salesforce",
  "name": "Salesforce",
  "version": "1.0.0",
  "status": "connected",
  "config": { "instanceUrl": "https://example.my.salesforce.com" },
  "lastSyncAt": "2026-03-05T08:00:00.000Z",
  "lastSyncError": null,
  "latestSync": {
    "recordsCreated": 150,
    "recordsUpdated": 42,
    "recordsFailed": 0,
    "syncType": "incremental"
  }
}

---

getAuthUrl

Generates a Salesforce OAuth 2.0 authorization URL. Creates or reuses the Salesforce connector record and returns the URL to redirect the user to Salesforce for consent.

connector.getAuthUrl.mutationOptions(options)

Access: Admin only

Input

None.

Response

{
  "authUrl": "https://login.salesforce.com/services/oauth2/authorize?client_id=...&redirect_uri=..."
}

OAuth Flow

1. Client calls connector.getAuthUrl
2. Client redirects user to authUrl
3. User authorizes in Salesforce
4. Salesforce redirects to callback URL with auth code
5. Server exchanges code for tokens (encrypted at rest)
6. Connector status updates to "connected"

Security

OAuth tokens are encrypted at rest using AES-256-GCM. The CONNECTOR_ENCRYPTION_KEY environment variable must be set. Never log or expose raw tokens.

---

disconnect

Disconnects a connector by clearing its credentials and resetting its status.

connector.disconnect.mutationOptions(options)

Access: Admin only

Input

Field	Type	Required	Description
connectorId	string	Yes	Database ID of the connector to disconnect

Response

{
  "disconnected": true
}

---

getSyncHistory

Returns paginated sync log entries for a connector, ordered by most recent first.

connector.getSyncHistory.queryOptions(input)

Input

Field	Type	Required	Default	Description
connectorId	string	Yes	--	Database ID of the connector
limit	number (1-100)	No	20	Maximum log entries to return

Response

[
  {
    "id": "sync_abc123",
    "connectorId": "conn_456",
    "tenantId": "tenant_789",
    "syncType": "incremental",
    "status": "completed",
    "recordsCreated": 150,
    "recordsUpdated": 42,
    "recordsFailed": 0,
    "startedAt": "2026-03-05T08:00:00.000Z",
    "completedAt": "2026-03-05T08:02:30.000Z"
  }
]

---

getEntityCounts

Returns the number of entities (accounts, people, opportunities) synced from a specific connector source.

connector.getEntityCounts.queryOptions(input)

Input

Field	Type	Required	Description
connectorId	string	Yes	Connector ID

Response

{
  "accounts": 340,
  "people": 1250,
  "opportunities": 89
}

---

triggerSync

Initiates a data sync for a connector. The sync runs asynchronously via Temporal workflows.

connector.triggerSync.mutationOptions(options)

Access: Admin only

Input

Field	Type	Required	Default	Description
connectorId	string	Yes	--	Database ID of the connector
fullSync	boolean	No	false	Force full sync instead of incremental

Response

{
  "queued": true,
  "connectorId": "conn_456",
  "fullSync": false
}

Incremental vs Full Sync

By default, syncs are incremental (only changed records). Set fullSync: true to re-sync all records from the source. Full syncs take longer but resolve data drift.

Example

const trpc = useTRPC();
const queryClient = useQueryClient();

const syncMutation = useMutation(
  trpc.connector.triggerSync.mutationOptions({
    onSuccess: () => {
      queryClient.invalidateQueries({
        queryKey: trpc.connector.getStatus.queryKey(),
      });
    },
  })
);

syncMutation.mutate({ connectorId: "conn_456", fullSync: false });

Related Pages

• Field Mappings API -- Configure source-to-canonical field mappings
• Writeback API -- Push scores back to Salesforce
• Authentication -- OAuth security and admin access