Skip to content

Data Connectors API

Connect external systems, store connection metadata, and enqueue syncs.

Base URL

BASE_URL = "https://api.fermi.dev/public/v1"

Public prefixes:

Prefix
/connect/integrations/*
/sync/*
/gmail/*
/database/*
/connectors/*
/webhooks/*

Authentication

Authorization: Bearer <service-actor-token>

Required Scopes:

  • connectors:read
  • connectors:write
  • connectors:sync

Shared connect flow

Most OAuth connectors use the same session API.

POST /connect/integrations/connect-session

{
  "integration": "google-mail"
}

Response:

{
  "sessionToken": "session-token-abc123"
}

Pass sessionToken to the connect UI / frontend SDK to finish OAuth. The response includes sessionToken only (no connectUrl).

Credential connectors (SQL, MongoDB, Snowflake, Custom REST basic/bearer, ProSoft XP) use providerConfigKey plus credentials instead of integration. See each connector page. WhatsApp uses pairing under /connectors/whatsapp/*, not credential connect-session.

After the connection exists:

  1. GET /connect/integrations/connections?providerConfigKey={key} → { connections, total }
  2. POST /connect/integrations/connection-metadata with { connectionId, providerConfigKey, metadata }
  3. POST /sync/enqueue with { connectionId, providerKey } (providerKey matches providerConfigKey)

Reconnect: send connectionId with integration on connect-session.

Connection id required

connectionId on metadata, sync, user-info, Gmail profile, Drive files, sheet preview, and SharePoint site/folder APIs must be an existing connection from the list endpoint. A fake or missing id returns 400, 404, 500 wrapping 404, or 502. GET connection-metadata requires connectionId in the query; omitting it does not return a clean 404.

Disconnect

DELETE /connect/integrations/connection/{connectionId} currently returns 502 on the public path. Do not treat a success JSON as live behavior. Remove connections in the Fermi app until this is fixed.

Catalog

Connectable connectors (full pages):

Catalog id Connect with Page
google-sheets integration: google-drive Google Sheets
google-drive integration: google-drive-files Google Drive
gmail integration: google-mail Gmail
outlook integration: outlook Outlook
salesforce integration: salesforce Salesforce
dynamics-365 integration: microsoft-oauth2-cc Dynamics 365
sharepoint integration: sharepoint-online SharePoint
microsoft-teams integration: microsoft-teams Microsoft Teams
mongodb providerConfigKey: mongodb MongoDB
postgresql providerConfigKey: postgresql SQL Databases
mysql providerConfigKey: mysql SQL Databases
mssql providerConfigKey: mssql SQL Databases
mariadb providerConfigKey: mariadb SQL Databases
oracle providerConfigKey: oracle SQL Databases
snowflake providerConfigKey: snowflake-jwt Snowflake
custom-rest-api Connect: private-api-basic or private-api-bearer. Webhooks: custom-rest-api Custom REST
prosoft-xp providerConfigKey: prosoft-xprest ProSoft XP
whatsapp Pairing: /connectors/whatsapp/pairing-session WhatsApp
documents providerConfigKey: documents Documents

custom-rest-api is a catalog / webhook providerConfigKey. Do not send it as integration or as connect-session providerConfigKey (live 400).

Listed in the product catalog but not connectable (no connect API):

Catalog id Status
sap-success-factors connectDisabled
sap-concur hidden, coming_soon

Inbound webhooks (callbacks)

These URLs are for Google, WhatsApp, and Custom REST to call Fermi. Partners do not POST them with a dashboard API key or as a substitute for connect-session.

  • POST /webhooks/gmail-push
  • POST /webhooks/whatsapp/{connectionId}
  • POST /webhooks/api-connector/receive/{connectionId} — Custom REST uses Authorization: Bearer <apiKey> from generate-webhook

Partner POSTs without provider auth receive 401.

Next Steps