Integrations Rail

Integrations Rail

External connectors, sync jobs, and data feeds.

Overview

The Integrations Rail provides endpoints for managing external system integrations, data synchronization, and export feeds.

Base URL

/api/v1/integrations

Endpoints

List Connectors

GET /api/v1/integrations/connectors

List available integration connectors.

Response:

{
  "data": [
    {
      "connectorId": "stripe",
      "name": "Stripe",
      "category": "PAYMENTS",
      "status": "AVAILABLE",
      "features": ["payments", "subscriptions", "invoices"]
    },
    {
      "connectorId": "quickbooks",
      "name": "QuickBooks",
      "category": "ACCOUNTING",
      "status": "AVAILABLE",
      "features": ["invoices", "expenses", "reports"]
    }
  ]
}

Create Connection

POST /api/v1/integrations/connections

Create an integration connection.

Request Body:

{
  "connectorId": "stripe",
  "name": "Production Stripe",
  "credentials": {
    "apiKey": "${IOF_CONNECTOR_API_KEY}",
    "webhookSecret": "${IOF_CONNECTOR_WEBHOOK_SECRET}"
  },
  "config": {
    "syncInterval": "15m",
    "autoSync": true
  }
}

Response:

{
  "data": {
    "connectionId": "conn_abc123",
    "connectorId": "stripe",
    "name": "Production Stripe",
    "status": "ACTIVE",
    "lastSyncAt": null,
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

List Connections

GET /api/v1/integrations/connections

List active connections.

Get Connection

GET /api/v1/integrations/connections/:connectionId

Get connection details.

Update Connection

PATCH /api/v1/integrations/connections/:connectionId

Update connection settings.

Test Connection

POST /api/v1/integrations/connections/:connectionId/test

Test connection health.

Response:

{
  "data": {
    "success": true,
    "latency": 120,
    "version": "2023-10-16",
    "permissions": ["read", "write"]
  }
}

Sync Data

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

Trigger data synchronization.

Request Body:

{
  "entities": ["customers", "invoices"],
  "mode": "INCREMENTAL",
  "dateRange": {
    "from": "2025-01-01",
    "to": "2025-01-15"
  }
}

Get Sync Status

GET /api/v1/integrations/connections/:connectionId/sync/:syncId

Get sync job status.

Response:

{
  "data": {
    "syncId": "sync_xyz",
    "status": "COMPLETED",
    "startedAt": "2025-01-15T10:00:00Z",
    "completedAt": "2025-01-15T10:05:00Z",
    "stats": {
      "customers": { "created": 50, "updated": 120, "errors": 2 },
      "invoices": { "created": 200, "updated": 0, "errors": 0 }
    }
  }
}

Create Export

POST /api/v1/integrations/exports

Create a data export.

Request Body:

{
  "name": "Monthly Contract Export",
  "format": "CSV",
  "entities": ["contracts"],
  "filter": {
    "status": "ACTIVE",
    "createdAt": { "gte": "2025-01-01" }
  },
  "schedule": {
    "frequency": "MONTHLY",
    "day": 1,
    "time": "02:00"
  },
  "destination": {
    "type": "S3",
    "bucket": "exports-bucket",
    "path": "/contracts/"
  }
}

List Exports

GET /api/v1/integrations/exports

List configured exports.

Trigger Export

POST /api/v1/integrations/exports/:exportId/run

Manually trigger an export.

Connector Categories

Category	Examples
PAYMENTS	Stripe, PayPal
ACCOUNTING	QuickBooks, Xero
CRM	Salesforce, HubSpot
BANKING	Plaid, Tink
COMPLIANCE	ComplyAdvantage
STORAGE	S3, Azure Blob

Sync Modes

Mode	Description
FULL	Full data sync
INCREMENTAL	Only changes since last sync
SNAPSHOT	Point-in-time snapshot

Export Formats

Format	Description
CSV	Comma-separated values
JSON	JSON format
PARQUET	Apache Parquet
XML	XML format

Events

Event	Description
integration.connected	Connection established
integration.sync.started	Sync started
integration.sync.completed	Sync completed
integration.sync.failed	Sync failed
integration.export.completed	Export completed

See Also

• Webhooks Rail - Webhook delivery
• Events Rail - Event distribution