Integrations

Integrations define automated data flows between sources and destinations. They specify what data to move, how to transform it, and when to sync.

List Integrations

Retrieve all integrations for your account.


GET /api/v1/integrations

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of items to return (default: 20, max: 100)
`offset`	integer	Number of items to skip (default: 0)
`sort`	string	Sort field and order (e.g., `created_at:desc`, `last_sync_at:desc`)
`state`	string	Filter by state: `active`, `inactive`
`status`	string	Filter by status: `pending`, `running`, `completed`, `errored`
`source_app_id`	string	Filter by source app
`destination_app_id`	string	Filter by destination app
`data_type`	string	Filter by data type

Example Request


curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.vendodata.com/api/v1/integrations?state=active&status=completed"

Example Response


{
  "data": [
    {
      "id": "dd0e8400-e29b-41d4-a716-446655440008",
      "accountId": "123e4567-e89b-12d3-a456-426614174000",
      "sourceAppId": "550e8400-e29b-41d4-a716-446655440000",
      "sourceAppName": "My Shopify Store",
      "sourceAppType": "shopify",
      "destinationAppId": "bb0e8400-e29b-41d4-a716-446655440006",
      "destinationAppName": "Mixpanel Production",
      "destinationAppType": "mixpanel",
      "dataType": "events",
      "state": "active",
      "status": "completed",
      "isActive": true,
      "lastSyncAt": "2024-03-04T10:30:00Z",
      "consecutiveFailures": 0,
      "latestJobId": "job_54321",
      "createdAt": "2024-01-25T11:00:00Z",
      "updatedAt": "2024-03-04T10:30:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "limit": 20,
      "offset": 0,
      "hasMore": false
    }
  }
}

Get Integration Details

Retrieve details for a specific integration.


GET /api/v1/integrations/{integrationId}

Path Parameters

Parameter	Type	Description
`integrationId`	string (UUID)	The integration’s unique identifier

Example Request


curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.vendodata.com/api/v1/integrations/dd0e8400-e29b-41d4-a716-446655440008

Example Response


{
  "data": {
    "id": "dd0e8400-e29b-41d4-a716-446655440008",
    "accountId": "123e4567-e89b-12d3-a456-426614174000",
    "sourceAppId": "550e8400-e29b-41d4-a716-446655440000",
    "sourceAppName": "My Shopify Store",
    "sourceAppType": "shopify",
    "destinationAppId": "bb0e8400-e29b-41d4-a716-446655440006",
    "destinationAppName": "Mixpanel Production",
    "destinationAppType": "mixpanel",
    "dataType": "events",
    "config": {
      "global": {
        "include_refunds": true
      },
      "tasks": [
        {
          "task_type": "track_events",
          "event_mapping": {
            "order_completed": "Purchase"
          }
        }
      ]
    },
    "schedule": {
      "frequency_value": 1,
      "frequency_unit": "hours",
      "rolling_window_days": 7
    },
    "state": "active",
    "status": "completed",
    "isActive": true,
    "lastSyncAt": "2024-03-04T10:30:00Z",
    "lastError": null,
    "consecutiveFailures": 0,
    "importDependencyStatus": "ready",
    "latestJobId": "job_54321",
    "createdAt": "2024-01-25T11:00:00Z",
    "updatedAt": "2024-03-04T10:30:00Z"
  }
}

Create Integration

Create a new integration between a source and destination.


POST /api/v1/integrations

Request Body

Field	Type	Required	Description
`sourceAppId`	string (UUID)	No	Source app (optional for some integrations)
`destinationAppId`	string (UUID)	Yes	Destination app
`dataType`	string	Yes	Type of data to sync
`config`	object	Yes	Integration configuration with tasks
`schedule`	object	Yes	Sync schedule
`historicalSyncStartDate`	string (datetime)	No	Start date for historical data

Data Types

Data Type	Description
`events`	Track events and page views
`user_properties`	User profile attributes
`group_properties`	Company/group attributes
`conversions`	Conversion events for ad platforms
`ad_data`	Ad performance metrics
`audiences`	Audience segments

Config Object


{
  "global": {
    // Global settings applied to all tasks
  },
  "tasks": [
    {
      "task_type": "track_events",
      // Task-specific configuration
    }
  ]
}

Schedule Object

Field	Type	Description
`frequencyValue`	integer	Sync frequency (1, 2, 6, etc.)
`frequencyUnit`	string	`hours`, `days`, `weeks`, `months`
`rollingWindowDays`	integer	Days of data to include (default: 0)
`oneOff`	boolean	Run once only
`runNow`	boolean	Trigger immediate sync on creation

Example Request


curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceAppId": "550e8400-e29b-41d4-a716-446655440000",
    "destinationAppId": "bb0e8400-e29b-41d4-a716-446655440006",
    "dataType": "events",
    "config": {
      "global": {},
      "tasks": [
        {
          "task_type": "track_events",
          "include_anonymous": false
        }
      ]
    },
    "schedule": {
      "frequencyValue": 1,
      "frequencyUnit": "hours",
      "rollingWindowDays": 7,
      "runNow": true
    }
  }' \
  https://app.vendodata.com/api/v1/integrations

Example Response


{
  "data": {
    "id": "ee0e8400-e29b-41d4-a716-446655440009",
    "accountId": "123e4567-e89b-12d3-a456-426614174000",
    "sourceAppId": "550e8400-e29b-41d4-a716-446655440000",
    "destinationAppId": "bb0e8400-e29b-41d4-a716-446655440006",
    "dataType": "events",
    "state": "active",
    "status": "pending",
    "createdAt": "2024-03-04T15:00:00Z"
  }
}

Update Integration

Update an existing integration.


PATCH /api/v1/integrations/{integrationId}

Request Body

Field	Type	Description
`config`	object	Updated configuration
`schedule`	object	Updated schedule

Example Request


curl -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": {
      "frequencyValue": 6,
      "frequencyUnit": "hours"
    }
  }' \
  https://app.vendodata.com/api/v1/integrations/dd0e8400-e29b-41d4-a716-446655440008

Delete Integration

Soft-delete an integration.


DELETE /api/v1/integrations/{integrationId}

Example Request


curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.vendodata.com/api/v1/integrations/ee0e8400-e29b-41d4-a716-446655440009

Trigger Sync

Manually trigger a sync for an integration.


POST /api/v1/integrations/{integrationId}/sync

Example Request


curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.vendodata.com/api/v1/integrations/dd0e8400-e29b-41d4-a716-446655440008/sync

Example Response


{
  "data": {
    "jobId": "job_98765",
    "status": "dispatched",
    "message": "Sync job has been dispatched"
  }
}

Error: Inactive Integration


{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Cannot trigger sync for an inactive integration. Resume the integration first."
  }
}

Import Dependency Status

Integrations that depend on source data track import readiness:

Status	Description
`ready`	Source data is available, can sync
`checking`	Checking if source data is ready
`waiting`	Waiting for source import to complete
`error`	Source import failed

The importDependencyStatus field indicates whether the integration can proceed with export.