Integrations API

Connect external services via OAuth, sync email and calendar, and manage document storage.

All endpoints prefixed with /api/v1/integrations

OAuth

OAuth provider authorization and management.

GET /api/v1/integrations/oauth/providers

Get list of available OAuth providers and their configuration status.

Auth: Bearer token

GET /api/v1/integrations/oauth/:provider/authorize

Initiate OAuth flow — redirects to provider's consent screen.

Auth: Bearer token

GET /api/v1/integrations/oauth/:provider/callback

Handle OAuth callback from provider.

Auth: None (OAuth redirect)

DELETE /api/v1/integrations/oauth/:provider

Disconnect an OAuth provider.

Auth: Bearer token

Connections

Manage OAuth connections and sync operations.

GET /api/v1/integrations/connections

List all OAuth connections for the current user.

Auth: Bearer token

GET /api/v1/integrations/connections/:id/status

Get detailed status of a specific connection.

Auth: Bearer token

POST /api/v1/integrations/connections/:id/sync

Trigger manual sync for a connection (email, calendar, or all).

Auth: Bearer token

Request Body
json 
{
  "type": "email"
}
POST /api/v1/integrations/connections/:id/refresh

Manually refresh OAuth token.

Auth: Bearer token

Email

Email integration — inbox, send, thread tracking, and entity matching.

GET /api/v1/integrations/email/inbox

Paginated inbox with folder, search, and unread filters.

Auth: Bearer token

Query Parameters
Parameter Type Description
folder string Folder name (inbox, sent, archive)
q string Search query
unread boolean Filter unread only
page number Page number
limit number Items per page
GET /api/v1/integrations/email/folders/counts

Get aggregate email counts per folder.

Auth: Bearer token

PATCH /api/v1/integrations/email/:id/read

Toggle email read status.

Auth: Bearer token

PATCH /api/v1/integrations/email/:id/star

Toggle email star status.

Auth: Bearer token

PATCH /api/v1/integrations/email/:id/archive

Toggle email archive status.

Auth: Bearer token

POST /api/v1/integrations/email/send

Send an email via the user's OAuth connection.

Auth: Bearer token

Request Body
json 
{
  "to": ["recipient@company.com"],
  "subject": "Follow up",
  "body": "...",
  "cc": [],
  "bcc": []
}
GET /api/v1/integrations/email/threads/:entityType/:entityId

Get email threads linked to a CRM entity.

Auth: Bearer token

GET /api/v1/integrations/email/thread/:threadId

Get all emails in a thread.

Auth: Bearer token

POST /api/v1/integrations/email/match

Manually match an email address to a CRM entity.

Auth: Bearer token

Request Body
json 
{
  "emailAddress": "contact@company.com",
  "entityType": "contact",
  "entityId": 42
}
POST /api/v1/integrations/email/sync

Trigger manual email sync.

Auth: Bearer token

Calendar

Calendar integration — events, CRM linking, and sync.

GET /api/v1/integrations/calendar/events

Get calendar events in a date range.

Auth: Bearer token

Query Parameters
Parameter Type Description
start string Start date (ISO)
end string End date (ISO)
GET /api/v1/integrations/calendar/events/:id

Get a single calendar event.

Auth: Bearer token

POST /api/v1/integrations/calendar/events

Create a new calendar event.

Auth: Bearer token

Request Body
json 
{
  "title": "Client Meeting",
  "start": "2026-07-01T14:00:00Z",
  "end": "2026-07-01T15:00:00Z",
  "description": "Quarterly review",
  "attendees": ["contact@company.com"]
}
PUT /api/v1/integrations/calendar/events/:id

Update a calendar event.

Auth: Bearer token

DELETE /api/v1/integrations/calendar/events/:id

Delete a calendar event.

Auth: Bearer token

GET /api/v1/integrations/calendar/events/entity/:entityType/:entityId

Get calendar events linked to a CRM entity.

Auth: Bearer token

POST /api/v1/integrations/calendar/sync

Trigger manual calendar sync.

Auth: Bearer token

Documents

Document storage with upload, download, and entity linking.

GET /api/v1/integrations/documents/config

Get document storage configuration status.

Auth: Bearer token

POST /api/v1/integrations/documents/upload

Initiate a document upload (returns presigned URL).

Auth: Bearer token

Request Body
json 
{
  "fileName": "contract.pdf",
  "contentType": "application/pdf",
  "entityType": "account",
  "entityId": 1
}
POST /api/v1/integrations/documents/:id/confirm

Confirm that upload has completed.

Auth: Bearer token

GET /api/v1/integrations/documents

List documents with pagination and filtering.

Auth: Bearer token

GET /api/v1/integrations/documents/entity/:entityType/:entityId

Get documents for a specific CRM entity.

Auth: Bearer token

GET /api/v1/integrations/documents/:id

Get a specific document.

Auth: Bearer token

GET /api/v1/integrations/documents/:id/download

Get download URL for a document.

Auth: Bearer token

DELETE /api/v1/integrations/documents/:id

Delete a document.

Auth: Bearer token

POST /api/v1/integrations/documents/:id/archive

Archive a document.

Auth: Bearer token