Syncs

Syncs continuously replicate data from source applications into a data warehouse. A sync belongs to an integration and pairs a source connection with a destination database/schema; its datasets choose which tables and columns to replicate and how records are loaded. Use these endpoints to create and configure syncs and their datasets, discover the supported source and destination applications and their tables, review change history and schema-drift events, and track usage.

Sync and dataset schemas

List syncs

get

/v1/syncs

Returns all syncs in the account, sorted by name. Filter to one integration with the _integrationId query parameter (equivalent to GET /v1/integrations/{_integrationId}/syncs).

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

_integrationIdstring · objectIdOptional

Only return syncs that belong to this integration.

Example: 69f4ffd395ec28be9cb8c12e

limitinteger · min: 1 · max: 1000Optional

Maximum number of syncs to return per page.

Default: 1000Example: 100

afterstringOptional

Opaque pagination cursor for the next page. Take it from the after value in the Link response header's rel="next" URL rather than constructing it.

Example: WyIiLCI2OTdiZDAwNDFhMWJiMDdhZWY4NmRmNDciXQ

includestringOptional

Comma-separated list of fields to project into each returned record. Triggers summary projection: the response contains a minimal identity set (_id, name, plus resource-specific fields) with the requested fields added on top. Supports dot notation for nested fields. Mutually exclusive with exclude.

Example: _integrationId,disabled,lastModified

excludestringOptional

Comma-separated list of fields to strip from the default response. Unlike include, does not trigger summary projection — returns the full record with the named fields removed. Protected identity fields (e.g. name) cannot be stripped. Mutually exclusive with include.

Example: createdAt,lastModified

Responses

200

Array of sync objects.

application/json

204

No syncs exist in the account.

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

get/v1/syncs

GET /v1/syncs HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_id": "6a4b8bfb731a7a5cae9bd364",
    "_userId": "68c821306f5d848c881da205",
    "_integrationId": "69f4ffd395ec28be9cb8c12e",
    "name": "Salesforce Demo Sync",
    "disabled": false,
    "schedule": "? 0 */8 * * *",
    "timezone": "Asia/Calcutta",
    "historicDateTime": "2022-07-04T18:30:00.000Z",
    "source": {
      "_connectionId": "6a2a95909e994395f3c2a4e6"
    },
    "destination": {
      "_connectionId": "68d02dbe0839a514623c1d6d",
      "database": "ANALYTICS_DB",
      "schema": "salesforce_raw"
    },
    "driftPolicy": {
      "dataset": {
        "added": "automate",
        "removed": "automate"
      },
      "element": {
        "added": "automate",
        "objectAdded": "preserve",
        "arrayAdded": "preserve",
        "removed": "automate",
        "reduced": "automate",
        "expanded": "automate"
      }
    }
  },
  {
    "_id": "6966b5bd344490b470099978",
    "_userId": "68c821306f5d848c881da205",
    "_integrationId": "6966b587dfb77eaae13110c7",
    "name": "Order Analytics",
    "disabled": true,
    "historicDateTime": "1970-01-01T00:00:00.000Z",
    "source": {
      "_connectionId": "68db4afe97bf4f4942a3b92c"
    },
    "destination": {},
    "driftPolicy": {
      "dataset": {},
      "element": {}
    }
  }
]

Create a sync

post

/v1/syncs

Creates a sync inside an integration. Only _integrationId and source._connectionId are required — new syncs start as disabled drafts, so the destination, datasets, and schedule can be configured with later requests. Creating a sync also registers its connections for the platform's replication runtime.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Writable sync fields for POST /v1/syncs and PUT /v1/syncs/{_id}. Updates are full replacements: omitted optional fields (schedule, timezone, destination details, driftPolicy) are cleared, not preserved, so send the complete desired configuration on every PUT.

_integrationIdstring · objectIdOptional

Integration to create the sync in. Required on create; forbidden on update — the integration cannot be changed once assigned (400 sync_integration_id_update).

Example: 69f4ffd395ec28be9cb8c12e

namestring · max: 150Optional

Display name shown in the UI. Values over 150 characters fail with 422 size_limit_exceeded.

Example: Salesforce Demo Sync

descriptionstring · max: 5120Optional

Free-form notes about what the sync replicates and why.

Example: Replicates core CRM objects into the analytics warehouse.

disabledbooleanOptional

When true, the sync neither runs on schedule nor accepts on-demand runs. Set to false only once source, destination, datasets, and historicDateTime are all configured; enabling an incomplete sync fails with 422 sync_not_enabled.

Default: true

schedulestringOptional

Cron expression that controls automatic runs, e.g. ? 0 */6 * * * for every six hours. Send an empty string (or omit) for a sync that only runs on demand. Evaluated in timezone.

Example: ? 0 */6 * * *

timezonestringOptional

IANA time zone name (e.g. America/New_York) the schedule is evaluated in.

Example: America/New_York

historicDateTimestring · date-timeOptional

Earliest record timestamp to backfill from the source. Must be set before the sync can be enabled.

Example: 2022-07-04T18:30:00.000Z

Responses

201

Created sync.

application/json

A sync continuously replicates data from a source application into a data warehouse. New syncs start as disabled drafts; a sync can only be enabled once its source, destination, and datasets are fully configured.

_idstring · objectIdRead-onlyRequired

Unique identifier for the sync.

Example: 6a4b8bfb731a7a5cae9bd364

_userIdstring · objectIdRead-onlyRequired

Account owner the sync belongs to.

Example: 68c821306f5d848c881da205

_integrationIdstring · objectIdRequired

Integration the sync lives in. Required when creating; cannot be changed afterwards — sending it on an update fails with 400 sync_integration_id_update.

Example: 69f4ffd395ec28be9cb8c12e

namestring · max: 150Required

Display name shown in the UI. Defaults to an empty string when not provided at creation.

Example: Salesforce Demo Sync

descriptionstring · max: 5120Optional

Free-form notes about what the sync replicates and why.

Example: Replicates core CRM objects into the analytics warehouse.

disabledbooleanRequired

When true, the sync neither runs on schedule nor accepts on-demand runs. New syncs start disabled. Enabling requires a fully configured sync — source and destination connections plus a destination database and schema — and a historicDateTime; otherwise the update fails with 422 sync_not_enabled.

Default: true

schedulestringOptional

Cron expression that controls automatic runs, e.g. ? 0 */6 * * * for every six hours. Empty or omitted means the sync only runs on demand via POST /v1/syncs/{_syncId}/run. Evaluated in the sync's timezone.

Example: ? 0 */6 * * *

timezonestringOptional

IANA time zone name (e.g. America/New_York) the schedule is evaluated in.

Example: America/New_York

historicDateTimestring · date-timeOptional

Earliest record timestamp to backfill from the source. The first run extracts history from this point forward; later runs are incremental. Must be set before the sync can be enabled.

Example: 2022-07-04T18:30:00.000Z

400

Bad request. _integrationId is missing (missing_integration_id), the body contains _id or _userId (id_and_userId_in_request), or a connection reference is not a valid id.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

422

Validation failed. source._connectionId is missing (missing_source_connection), the destination duplicates another sync (duplicate_destination_host), the destination connector rejected the sync configuration (invalid_destination_sync_config), two enabled datasets resolve to the same destination table (conflicting_table_name), a field exceeds its size limit (size_limit_exceeded), or the drift policy is inconsistent (drift_policy_invalid_setup).

application/json

post/v1/syncs

POST /v1/syncs HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 99

{
  "_integrationId": "6966b587dfb77eaae13110c7",
  "source": {
    "_connectionId": "6a2a95909e994395f3c2a4e6"
  }
}

{
  "_id": "6a559b5185efa7502eefd439",
  "_userId": "68c821306f5d848c881da205",
  "_integrationId": "6966b587dfb77eaae13110c7",
  "name": "",
  "disabled": true,
  "source": {
    "_connectionId": "6a2a95909e994395f3c2a4e6"
  },
  "destination": {},
  "driftPolicy": {
    "dataset": {},
    "element": {}
  }
}

Get a sync

get

/v1/syncs/{_id}

Returns a single sync by ID.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Sync id.

Example: 6a4b8bfb731a7a5cae9bd364

Responses

200

Sync object.

application/json

A sync continuously replicates data from a source application into a data warehouse. New syncs start as disabled drafts; a sync can only be enabled once its source, destination, and datasets are fully configured.

_idstring · objectIdRead-onlyRequired

Unique identifier for the sync.

Example: 6a4b8bfb731a7a5cae9bd364

_userIdstring · objectIdRead-onlyRequired

Account owner the sync belongs to.

Example: 68c821306f5d848c881da205

_integrationIdstring · objectIdRequired

Integration the sync lives in. Required when creating; cannot be changed afterwards — sending it on an update fails with 400 sync_integration_id_update.

Example: 69f4ffd395ec28be9cb8c12e

namestring · max: 150Required

Display name shown in the UI. Defaults to an empty string when not provided at creation.

Example: Salesforce Demo Sync

descriptionstring · max: 5120Optional

Free-form notes about what the sync replicates and why.

Example: Replicates core CRM objects into the analytics warehouse.

disabledbooleanRequired

When true, the sync neither runs on schedule nor accepts on-demand runs. New syncs start disabled. Enabling requires a fully configured sync — source and destination connections plus a destination database and schema — and a historicDateTime; otherwise the update fails with 422 sync_not_enabled.

Default: true

schedulestringOptional

Cron expression that controls automatic runs, e.g. ? 0 */6 * * * for every six hours. Empty or omitted means the sync only runs on demand via POST /v1/syncs/{_syncId}/run. Evaluated in the sync's timezone.

Example: ? 0 */6 * * *

timezonestringOptional

IANA time zone name (e.g. America/New_York) the schedule is evaluated in.

Example: America/New_York

historicDateTimestring · date-timeOptional

Earliest record timestamp to backfill from the source. The first run extracts history from this point forward; later runs are incremental. Must be set before the sync can be enabled.

Example: 2022-07-04T18:30:00.000Z

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/syncs/{_id}

GET /v1/syncs/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_id": "6a4b8bfb731a7a5cae9bd364",
  "_userId": "68c821306f5d848c881da205",
  "_integrationId": "69f4ffd395ec28be9cb8c12e",
  "name": "Salesforce Demo Sync",
  "disabled": false,
  "schedule": "? 0 */8 * * *",
  "timezone": "Asia/Calcutta",
  "historicDateTime": "2022-07-04T18:30:00.000Z",
  "source": {
    "_connectionId": "6a2a95909e994395f3c2a4e6"
  },
  "destination": {
    "_connectionId": "68d02dbe0839a514623c1d6d",
    "database": "ANALYTICS_DB",
    "schema": "salesforce_raw"
  },
  "driftPolicy": {
    "dataset": {
      "added": "automate",
      "removed": "automate"
    },
    "element": {
      "added": "automate",
      "objectAdded": "preserve",
      "arrayAdded": "preserve",
      "removed": "automate",
      "reduced": "automate",
      "expanded": "automate"
    }
  }
}

Update a sync

put

/v1/syncs/{_id}

Replaces a sync's configuration. Send the complete desired state: omitted optional fields (schedule, timezone, destination details, driftPolicy) are cleared, not preserved. _integrationId cannot be sent — the integration is fixed at creation.

Set disabled: false to enable the sync once its source, destination, datasets, and historicDateTime are configured; enabling an incomplete sync fails with 422 sync_not_enabled.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Sync id.

Example: 6a4b8bfb731a7a5cae9bd364

Body

Writable sync fields for POST /v1/syncs and PUT /v1/syncs/{_id}. Updates are full replacements: omitted optional fields (schedule, timezone, destination details, driftPolicy) are cleared, not preserved, so send the complete desired configuration on every PUT.

_integrationIdstring · objectIdOptional

Integration to create the sync in. Required on create; forbidden on update — the integration cannot be changed once assigned (400 sync_integration_id_update).

Example: 69f4ffd395ec28be9cb8c12e

namestring · max: 150Optional

Display name shown in the UI. Values over 150 characters fail with 422 size_limit_exceeded.

Example: Salesforce Demo Sync

descriptionstring · max: 5120Optional

Free-form notes about what the sync replicates and why.

Example: Replicates core CRM objects into the analytics warehouse.

disabledbooleanOptional

When true, the sync neither runs on schedule nor accepts on-demand runs. Set to false only once source, destination, datasets, and historicDateTime are all configured; enabling an incomplete sync fails with 422 sync_not_enabled.

Default: true

schedulestringOptional

Cron expression that controls automatic runs, e.g. ? 0 */6 * * * for every six hours. Send an empty string (or omit) for a sync that only runs on demand. Evaluated in timezone.

Example: ? 0 */6 * * *

timezonestringOptional

IANA time zone name (e.g. America/New_York) the schedule is evaluated in.

Example: America/New_York

historicDateTimestring · date-timeOptional

Earliest record timestamp to backfill from the source. Must be set before the sync can be enabled.

Example: 2022-07-04T18:30:00.000Z

Responses

200

Updated sync.

application/json

A sync continuously replicates data from a source application into a data warehouse. New syncs start as disabled drafts; a sync can only be enabled once its source, destination, and datasets are fully configured.

_idstring · objectIdRead-onlyRequired

Unique identifier for the sync.

Example: 6a4b8bfb731a7a5cae9bd364

_userIdstring · objectIdRead-onlyRequired

Account owner the sync belongs to.

Example: 68c821306f5d848c881da205

_integrationIdstring · objectIdRequired

Integration the sync lives in. Required when creating; cannot be changed afterwards — sending it on an update fails with 400 sync_integration_id_update.

Example: 69f4ffd395ec28be9cb8c12e

namestring · max: 150Required

Display name shown in the UI. Defaults to an empty string when not provided at creation.

Example: Salesforce Demo Sync

descriptionstring · max: 5120Optional

Free-form notes about what the sync replicates and why.

Example: Replicates core CRM objects into the analytics warehouse.

disabledbooleanRequired

When true, the sync neither runs on schedule nor accepts on-demand runs. New syncs start disabled. Enabling requires a fully configured sync — source and destination connections plus a destination database and schema — and a historicDateTime; otherwise the update fails with 422 sync_not_enabled.

Default: true

schedulestringOptional

Cron expression that controls automatic runs, e.g. ? 0 */6 * * * for every six hours. Empty or omitted means the sync only runs on demand via POST /v1/syncs/{_syncId}/run. Evaluated in the sync's timezone.

Example: ? 0 */6 * * *

timezonestringOptional

IANA time zone name (e.g. America/New_York) the schedule is evaluated in.

Example: America/New_York

historicDateTimestring · date-timeOptional

Earliest record timestamp to backfill from the source. The first run extracts history from this point forward; later runs are incremental. Must be set before the sync can be enabled.

Example: 2022-07-04T18:30:00.000Z

400

Bad request. The body contains _integrationId (sync_integration_id_update) or _id/_userId (id_and_userId_in_request).

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Validation failed. source._connectionId is missing (missing_source_connection), the sync is not ready to enable (sync_not_enabled), the destination duplicates another sync (duplicate_destination_host), the destination connector rejected the sync configuration (invalid_destination_sync_config), two enabled datasets resolve to the same destination table (conflicting_table_name), a field exceeds its size limit (size_limit_exceeded), or the drift policy is inconsistent (drift_policy_invalid_setup).

application/json

put/v1/syncs/{_id}

PUT /v1/syncs/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 511

{
  "name": "Salesforce Demo Sync",
  "schedule": "? 0 */6 * * *",
  "timezone": "America/New_York",
  "historicDateTime": "2022-07-04T18:30:00.000Z",
  "source": {
    "_connectionId": "6a2a95909e994395f3c2a4e6"
  },
  "destination": {
    "_connectionId": "68d02dbe0839a514623c1d6d",
    "database": "ANALYTICS_DB",
    "schema": "salesforce_raw"
  },
  "driftPolicy": {
    "dataset": {
      "added": "automate",
      "removed": "automate"
    },
    "element": {
      "added": "automate",
      "objectAdded": "preserve",
      "arrayAdded": "preserve",
      "removed": "automate",
      "reduced": "automate",
      "expanded": "automate"
    }
  }
}

{
  "_id": "6a4b8bfb731a7a5cae9bd364",
  "_userId": "68c821306f5d848c881da205",
  "_integrationId": "69f4ffd395ec28be9cb8c12e",
  "name": "Salesforce Demo Sync",
  "disabled": true,
  "schedule": "? 0 */6 * * *",
  "timezone": "America/New_York",
  "historicDateTime": "2022-07-04T18:30:00.000Z",
  "source": {
    "_connectionId": "6a2a95909e994395f3c2a4e6"
  },
  "destination": {
    "_connectionId": "68d02dbe0839a514623c1d6d",
    "database": "ANALYTICS_DB",
    "schema": "salesforce_raw"
  },
  "driftPolicy": {
    "dataset": {
      "added": "automate",
      "removed": "automate"
    },
    "element": {
      "added": "automate",
      "objectAdded": "preserve",
      "arrayAdded": "preserve",
      "removed": "automate",
      "reduced": "automate",
      "expanded": "automate"
    }
  }
}

Delete a sync

delete

/v1/syncs/{_id}

Deletes a sync and tears down its replication resources, including its datasets. The sync must be disabled first — deleting an enabled sync fails with 400 sync_delete_not_allowed. Syncs are not recoverable through the recycle bin.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Sync id.

Example: 6a559b5185efa7502eefd439

Responses

204

Sync deleted.

No content

400

The sync is still enabled. Error code: sync_delete_not_allowed.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

delete/v1/syncs/{_id}

DELETE /v1/syncs/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List syncs in an integration

get

/v1/integrations/{_integrationId}/syncs

Returns the syncs that belong to one integration, sorted by name. Equivalent to GET /v1/syncs?_integrationId={_integrationId}.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_integrationIdstring · objectIdRequired

Integration id.

Example: 6966b587dfb77eaae13110c7

Query parameters

limitinteger · min: 1 · max: 1000Optional

Maximum number of syncs to return per page.

Default: 1000Example: 100

afterstringOptional

Opaque pagination cursor for the next page. Take it from the after value in the Link response header's rel="next" URL rather than constructing it.

Example: WyIiLCI2OTdiZDAwNDFhMWJiMDdhZWY4NmRmNDciXQ

includestringOptional

Comma-separated list of fields to project into each returned record. Triggers summary projection: the response contains a minimal identity set (_id, name, plus resource-specific fields) with the requested fields added on top. Supports dot notation for nested fields. Mutually exclusive with exclude.

Example: _integrationId,disabled,lastModified

excludestringOptional

Comma-separated list of fields to strip from the default response. Unlike include, does not trigger summary projection — returns the full record with the named fields removed. Protected identity fields (e.g. name) cannot be stripped. Mutually exclusive with include.

Example: createdAt,lastModified

Responses

200

Array of sync objects.

application/json

204

The integration has no syncs, or the integration does not exist.

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

get/v1/integrations/{_integrationId}/syncs

GET /v1/integrations/{_integrationId}/syncs HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_id": "6966b5bd344490b470099978",
    "_userId": "68c821306f5d848c881da205",
    "_integrationId": "6966b587dfb77eaae13110c7",
    "name": "Order Analytics",
    "disabled": true,
    "schedule": "? 0 */1 * * *",
    "timezone": "America/New_York",
    "historicDateTime": "1970-01-01T00:00:00.000Z",
    "source": {
      "_connectionId": "68db4afe97bf4f4942a3b92c"
    },
    "destination": {
      "_connectionId": "68d02dbe0839a514623c1d6d",
      "database": "ANALYTICS_DB",
      "schema": "orders_raw"
    },
    "driftPolicy": {
      "dataset": {},
      "element": {}
    }
  }
]

List datasets for a sync

get

/v1/syncs/{_syncId}/datasets

Returns the datasets configured on a sync — the tables/objects it replicates — sorted by name. Export-backed datasets whose export no longer uses the sync's source connection carry mismatchSyncConnection: true.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_syncIdstring · objectIdRequired

Sync id.

Example: 6a55970bdb54be366c858bc9

Query parameters

limitinteger · min: 1 · max: 1000Optional

Maximum number of datasets to return per page.

Default: 1000Example: 100

afterstringOptional

Opaque pagination cursor for the next page. Take it from the after value in the Link response header's rel="next" URL rather than constructing it.

Example: WyJBY2NvdW50IiwiNmE1NTk3MGM1Zjk0OThhMTc1OGEwYWQzIl0

includestringOptional

Comma-separated list of fields to project into each returned record. Triggers summary projection: the response contains a minimal identity set (_id, name, plus resource-specific fields) with the requested fields added on top. Supports dot notation for nested fields. Mutually exclusive with exclude.

Example: _integrationId,disabled,lastModified

excludestringOptional

Comma-separated list of fields to strip from the default response. Unlike include, does not trigger summary projection — returns the full record with the named fields removed. Protected identity fields (e.g. name) cannot be stripped. Mutually exclusive with include.

Example: createdAt,lastModified

Responses

200

Array of dataset objects.

application/json

204

The sync has no datasets, or the sync does not exist.

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

get/v1/syncs/{_syncId}/datasets

GET /v1/syncs/{_syncId}/datasets HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_id": "6a559b547885d8f93921c2ba",
    "_userId": "68c821306f5d848c881da205",
    "_syncId": "6a55970bdb54be366c858bc9",
    "name": "Account",
    "externalId": "Account",
    "enable": true,
    "enableAllDataElements": false,
    "ingestionMode": "merge",
    "userActionRequired": false,
    "exportProperties": {
      "type": "delta",
      "delta": {}
    },
    "driftPolicy": {
      "element": {}
    },
    "dataElements": [
      {
        "name": "Id",
        "enable": true,
        "mask": false,
        "isPrimaryKey": true,
        "children": []
      },
      {
        "name": "Name",
        "enable": true,
        "mask": false,
        "children": []
      }
    ]
  },
  {
    "_id": "6a55974edb54be366c858d26",
    "_userId": "68c821306f5d848c881da205",
    "_syncId": "6a55970bdb54be366c858bc9",
    "name": "Pull Salesforce Records",
    "externalId": "6a3e7c54c2387aaa87881b80",
    "enable": true,
    "enableAllDataElements": false,
    "ingestionMode": "merge",
    "tableName": "pull_salesforce_records",
    "isExport": true,
    "userActionRequired": false,
    "exportProperties": {
      "delta": {}
    },
    "driftPolicy": {
      "element": {}
    },
    "dataElements": [
      {
        "name": "Id",
        "enable": true,
        "mask": false,
        "isPrimaryKey": true,
        "children": []
      }
    ],
    "mismatchSyncConnection": true
  }
]

Create or update datasets for a sync

put

/v1/syncs/{_syncId}/datasets

Creates and updates a sync's datasets in one batch. Each array item either creates a dataset (identified by externalId) or updates one (identified by _id); a single request can mix both. Updates fully replace each dataset's writable fields. The response body is empty — read back the saved datasets with GET /v1/syncs/{_syncId}/datasets.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_syncIdstring · objectIdRequired

Sync id.

Example: 6a55970bdb54be366c858bc9

Bodyobject · DatasetUpsertItem[]

One dataset to create or update in a PUT /v1/syncs/{_syncId}/datasets batch. Send externalId (without _id) to create, or _id (without externalId) to update — providing both or neither fails with 400 dataset_externalId_id_required. Updates are full replacements of the writable fields.

_idstring · objectIdOptional

Dataset to update. The dataset must already belong to the sync in the request path. Omit when creating.

Example: 6a559b547885d8f93921c2ba

externalIdstringOptional

Identifier of the dataset in the source system — the table/object name from GET /v1/di/metadata/connections/{_connectionId}/datasets, or an export ID when isExport is true. Set when creating; immutable afterwards. A dataset with the same externalId must not already exist on the sync.

Example: Account

namestringOptional

Display name of the dataset, typically the source's human-readable label.

Example: Account

enablebooleanOptional

When true, the sync replicates this dataset on each run. Required (with an ingestionMode) to activate the dataset; datasets created with enable: false stay configured but skipped.

Example: true

ingestionModestring · enumOptional

How extracted records are written into the destination table. Required when enable is true. merge requires a primary key in dataElements.

Example: mergePossible values:

tableNamestringOptional

Destination table name override. Must be unique among the sync's datasets — duplicates within the batch or with existing datasets fail with 400 duplicate_dataset_table_names / 422 table_name_already_exists. Required when isExport is true.

Example: account

isExportbooleanOptional

When true, the dataset's records come from an existing export resource: externalId must be the export's ID, the export must use the sync's source connection (400 connection_mismatch), and the item must include tableName and dataElements but no exportProperties.

Responses

201

Datasets created/updated. The response has no body.

No content

400

Bad request. The body is not a non-empty array (INVALID_REQUEST_BODY / EMPTY_REQUEST_BODY), an item has both or neither of _id/externalId (dataset_externalId_id_required), an externalId already exists or an _id does not belong to the sync, tableName values collide (duplicate_dataset_table_names), or an export dataset's export uses a different connection than the sync (connection_mismatch).

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

422

Validation failed. An enabled dataset is missing ingestionMode (ingestion_mode_required_for_enabled_datasets), a merge dataset has no primary key, a tableName is already taken, two source columns sanitize to the same destination column name (duplicate_sanitized_column_names — rename or disable the conflicting source columns), or a data-element combination is invalid (e.g. transformMode without children, or isPrimaryKey with mask).

application/json

put/v1/syncs/{_syncId}/datasets

PUT /v1/syncs/{_syncId}/datasets HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 353

[
  {
    "name": "Account",
    "externalId": "Account",
    "enable": true,
    "ingestionMode": "merge",
    "exportProperties": {
      "type": "all"
    },
    "dataElements": [
      {
        "name": "Id",
        "enable": true,
        "mask": false,
        "isPrimaryKey": true
      },
      {
        "name": "Name",
        "enable": true,
        "mask": false
      }
    ]
  },
  {
    "name": "Contact",
    "externalId": "Contact",
    "enable": false,
    "ingestionMode": "merge",
    "exportProperties": {
      "type": "delta"
    }
  }
]

No content

Get a dataset

get

/v1/syncs/{_syncId}/datasets/{_id}

Returns a single dataset of a sync by ID.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_syncIdstring · objectIdRequired

Sync id.

Example: 6a55970bdb54be366c858bc9

_idstring · objectIdRequired

Dataset id.

Example: 6a559b547885d8f93921c2ba

Responses

200

Dataset object.

application/json

One table/object a sync replicates, with its per-column selections and load behavior. Datasets are scoped to a single sync and are created and updated in bulk via PUT /v1/syncs/{_syncId}/datasets.

_idstring · objectIdRead-onlyRequired

Unique identifier for the dataset.

Example: 6a559b547885d8f93921c2ba

_userIdstring · objectIdRead-onlyRequired

Account owner the dataset belongs to.

Example: 68c821306f5d848c881da205

_syncIdstring · objectIdRead-onlyRequired

Sync this dataset belongs to. Assigned from the request path at creation.

Example: 6a559b5185efa7502eefd439

namestringRequired

Display name of the dataset, typically the source's human-readable label (e.g. a Salesforce object's display name). Empty string when never set.

Example: Account

externalIdstringRequired

Identifier of the dataset in the source system — the table/object name for application sources, or the export ID when isExport is true. Immutable after creation.

Example: Account

enablebooleanRequired

When true, the sync replicates this dataset on each run. Disabled datasets stay configured but are skipped.

Example: true

enableAllDataElementsbooleanRead-onlyRequired

When true, every column in the source dataset is replicated. Computed by the platform: true while the dataset has no explicit dataElements selection, false once one is saved.

ingestionModestring · enumOptional

How each run's extracted records are written into the destination table. Required once the dataset is enabled (422 ingestion_mode_required_for_enabled_datasets). merge additionally requires a primary-key column in dataElements.

Example: mergePossible values:

tableNamestringOptional

Destination table name override. Must be unique among the sync's datasets (422 table_name_already_exists); required when isExport is true. Omit to let the platform derive the table name from the dataset.

Example: account

isExportbooleanOptional

When true, the dataset's records come from an existing export resource instead of a source table; externalId then holds the export ID, and the export must use the sync's source connection. Export datasets require tableName and an explicit dataElements selection, and do not accept exportProperties.

userActionRequiredbooleanRead-onlyRequired

When true, the platform detected a schema change that needs a user decision before the dataset can be modified or replicated again — typically drift the driftPolicy does not automate. Updates to the dataset are rejected until the conflict is resolved (in the UI) in the same save that clears the flag.

mismatchSyncConnectionbooleanRead-onlyOptional

Only present (as true) in list responses, on export-backed datasets whose export no longer uses the sync's source connection. Repoint the export or recreate the dataset to resume replicating it.

Example: true

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/syncs/{_syncId}/datasets/{_id}

GET /v1/syncs/{_syncId}/datasets/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_id": "6a559b547885d8f93921c2ba",
  "_userId": "68c821306f5d848c881da205",
  "_syncId": "6a55970bdb54be366c858bc9",
  "name": "Account",
  "externalId": "Account",
  "enable": true,
  "enableAllDataElements": false,
  "ingestionMode": "merge",
  "userActionRequired": false,
  "exportProperties": {
    "type": "delta",
    "delta": {}
  },
  "driftPolicy": {
    "element": {}
  },
  "dataElements": [
    {
      "name": "Id",
      "enable": true,
      "mask": false,
      "isPrimaryKey": true,
      "children": []
    },
    {
      "name": "Name",
      "enable": true,
      "mask": false,
      "children": []
    }
  ]
}

Get audit log for a sync

get

/v1/syncs/{_syncId}/audit

Returns the change history for a sync. Entries cover the sync itself and the related resources it depends on — its datasets (the tables being replicated) and the source and destination connections it uses — so a single response interleaves sync, dataset, and connection events. Read resourceType on each entry to tell them apart.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_syncIdstring · objectIdRequired

Sync id.

Example: 6a1889b0c7b977adc441bc0d

Query parameters

limitinteger · min: 1 · max: 1000Optional

Maximum number of audit entries to return per page.

Default: 1000Example: 100

afterstringOptional

Opaque pagination cursor for the next page. Take it from the after value in the Link response header's rel="next" URL rather than constructing it.

Example: W3siJGRhdGUiOiIyMDI2LTA1LTAxVDAwOjAwOjAwLjAwMFoifSwiNjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwIl0

fromstring · date-timeOptional

Only return entries at or after this timestamp.

Example: 2026-05-01T00:00:00.000Z

tostring · date-timeOptional

Only return entries at or before this timestamp.

Example: 2026-05-31T23:59:59.999Z

actionstring · enumOptional

Filter by the change type. Maps to the event field on each entry.

Example: updatePossible values:

sourcestring · enumOptional

Filter by how the change was initiated.

Example: uiPossible values:

_byUserIdstring · objectIdOptional

Filter to changes performed by a single user.

Example: 624cb0346309dc3a543733a2

resourceTypestring · enumOptional

Narrow the aggregated results to a single resource kind — e.g. sync for only the sync's own changes, excluding its datasets and connections.

Example: syncPossible values:

_resourceIdstring · objectIdOptional

Filter to a single resource's entries. Must be sent together with resourceType; sending it alone returns 400 invalid_id.

Example: 682094fa7eb7fc3e7ab7a4a0

Responses

200

Array of audit entries, newest first.

application/json

204

No audit entries match the query.

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

get/v1/syncs/{_syncId}/audit

GET /v1/syncs/{_syncId}/audit HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_id": "6a1889e4c7b977adc441cb3f",
    "resourceType": "sync",
    "_resourceId": "682094fa7eb7fc3e7ab7a4a0",
    "source": "ui",
    "event": "update",
    "time": "2026-05-28T18:31:00.861Z",
    "byUser": {
      "_id": "624cb0346309dc3a543733a2",
      "email": "[e-mail]",
      "name": "Tyler Lamparter"
    },
    "fieldChanges": [
      {
        "fieldPath": "name",
        "oldValue": "",
        "newValue": "Order Analytics"
      },
      {
        "fieldPath": "schedule",
        "newValue": "? 0 */1 * * *"
      },
      {
        "fieldPath": "timezone",
        "newValue": "Etc/UTC"
      }
    ]
  },
  {
    "_id": "6a1889c9c7b977adc441c27a",
    "resourceType": "connection",
    "_resourceId": "68c8213f8ece256d4c9fa351",
    "source": "system",
    "event": "update",
    "time": "2026-05-28T18:30:32.891Z",
    "byUser": {
      "_id": "624cb0346309dc3a543733a2",
      "email": "[e-mail]",
      "name": "Tyler Lamparter"
    },
    "fieldChanges": [
      {
        "fieldPath": "salesforce.refreshToken",
        "newValue": "********"
      }
    ]
  }
]

List events for a sync

get

/v1/di/resource/syncs/{_syncId}/events

Returns the events recorded for a sync across all of its runs — schema drift the platform detected or applied, and data-catalog activity — newest first. Events are retained per the account's data retention period; a time_lte older than the retention window returns an empty list.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_syncIdstring · objectIdRequired

Sync id.

Example: 6a4b8bfb731a7a5cae9bd364

Query parameters

limitinteger · min: 1 · max: 1000Optional

Maximum number of events to return per page.

Default: 100Example: 25

pageinteger · min: 1Optional

1-based page number. Combine with limit to page through results.

Default: 1Example: 2

time_ltestring · date-timeOptional

Only return events recorded at or before this timestamp.

Example: 2026-07-14T00:00:00.000Z

time_gtstring · date-timeOptional

Only return events recorded after this timestamp. Must not be in the future (422 future_time_gt_not_allowed).

Example: 2026-07-07T00:00:00.000Z

typestring · enumOptional

Only return events of one category.

Example: Schema DriftPossible values:

resourceNamestringOptional

Only return events for one source table/object.

Example: Account

flowExecutionGroupIdstringOptional

Only return events from one run. Use the flowExecutionGroupId returned by POST /v1/syncs/{_syncId}/run.

Example: d0f875a575bd4b8c944533da773f350a

Responses

200

Events matching the filters, newest first.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

The sync belongs to a different account owner.

application/json

404

Sync not found. Error code: invalid_ref.

application/json

422

Invalid filter. A timestamp value cannot be parsed, or time_gt is in the future (future_time_gt_not_allowed).

application/json

get/v1/di/resource/syncs/{_syncId}/events

GET /v1/di/resource/syncs/{_syncId}/events HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "events": [
    {
      "id": "80ba31fe-b66d-4777-9b12-3177c55aab13",
      "_syncId": "6a4b8bfb731a7a5cae9bd364",
      "_userId": "68c821306f5d848c881da205",
      "flowExecutionGroupId": "d0f875a575bd4b8c944533da773f350a",
      "resourceName": "RelatedListDefinition",
      "severity": "INFO",
      "eventTime": "2026-07-13T12:36:06.225Z",
      "type": "Schema Drift",
      "stage": "Extract",
      "metadata": {
        "action": "Table removed",
        "resourceType": "Table"
      }
    }
  ]
}

Get per-sync usage for the current month

get

/v1/syncs/usage

Returns the number of records each sync loaded during the current calendar month (UTC), for the current environment. Only syncs that ran this month appear. Requires account-administration permission (the same level that manages account users); accounts without a Data Ingestion entitlement get an empty usage array.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Per-sync loaded-record volumes for the current month.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/syncs/usage

GET /v1/syncs/usage HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "usage": [
    {
      "_id": "6a4b8bfb731a7a5cae9bd364",
      "name": "Salesforce Demo Sync",
      "source": {
        "_id": "6a2a95909e994395f3c2a4e6",
        "name": "Salesforce Production"
      },
      "destination": {
        "_id": "68d02dbe0839a514623c1d6d",
        "name": "Snowflake"
      },
      "volume": 1458
    }
  ]
}

Get monthly sync usage history

get

/v1/syncs/usage/summary

Returns account-wide sync usage by calendar month, newest first — the records loaded across all syncs and environments, alongside the account's Data Ingestion entitlement for each month. History reaches back at most 14 months. Requires account-administration permission (the same level that manages account users); accounts without a Data Ingestion entitlement get an empty array.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

fromstringOptional

First month to include, as YYYY-MM. Cannot be more than 14 months back (400 invalid_date_range). Defaults to 14 months before the current month.

Example: 2026-05Pattern: ^\d{4}-(0[1-9]|1[0-2])$

tostringOptional

Last month to include, as YYYY-MM. Cannot be in the future. Defaults to the current month.

Example: 2026-07Pattern: ^\d{4}-(0[1-9]|1[0-2])$

Responses

200

Monthly usage totals, newest month first.

application/json

One month's account-wide sync usage.

yearintegerRequired

Calendar year of the usage month.

Example: 2026

monthinteger · min: 1 · max: 12Required

Calendar month (1-12) of the usage.

Example: 7

volumestringRequired

Records loaded across all syncs that month, serialized as a string to avoid precision loss at high volumes.

Example: 292460

entitlementstringRequired

Records per month the account's Data Ingestion license allows, serialized as a string.

Example: 100000000

400

Invalid date range. from/to is malformed (invalid_date_format), or the range is older than 14 months, in the future, or reversed (invalid_date_range).

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/syncs/usage/summary

GET /v1/syncs/usage/summary HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "year": 2026,
    "month": 7,
    "volume": "1537",
    "entitlement": "100000000"
  },
  {
    "year": 2026,
    "month": 6,
    "volume": "292460",
    "entitlement": "100000000"
  },
  {
    "year": 2026,
    "month": 5,
    "volume": "127448244",
    "entitlement": "100000000"
  }
]

Get sync usage by environment

get

/v1/syncs/usage/environments

Returns the records loaded by syncs during the current calendar month (UTC), broken down by environment — production plus every additional environment in the account. Environments with no runs this month report a volume of 0. Requires account-administration permission (the same level that manages account users); accounts without a Data Ingestion entitlement get an empty usage array.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Per-environment loaded-record volumes for the current month.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/syncs/usage/environments

GET /v1/syncs/usage/environments HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "usage": [
    {
      "environment": {
        "_id": "68c821306f5d848c881da205",
        "name": "Production"
      },
      "volume": 1537
    },
    {
      "environment": {
        "_id": "69cc38111c25db1bb3468a62",
        "name": "Sandbox"
      },
      "volume": 0
    }
  ]
}

List supported sync source applications

get

/v1/di/metadata/sources

Returns the catalog of applications that can be used as the source of a sync — the system a sync extracts records from. Use the returned id as the source application when building a sync, and category to group the options in a picker.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Array of supported source applications.

application/json

A supported source application.

idstringRequired

Application identifier to use as the sync source.

Example: salesforce

categorystringOptional

Display grouping for the application in selection UIs. HTTP-connector-backed sources use the category HTTP Connector.

Example: Sales & Marketing

displayNamestringOptional

Human-readable application name. Present on HTTP-connector-backed sources.

Example: Stripe

sourcestringOptional

Where the source's metadata comes from. Present on HTTP-connector-backed sources with the value httpConnectorMetadata.

Example: httpConnectorMetadata

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/di/metadata/sources

GET /v1/di/metadata/sources HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "salesforce",
    "category": "Sales & Marketing"
  },
  {
    "id": "netsuite",
    "category": "Sales & Marketing"
  },
  {
    "id": "stripe",
    "category": "HTTP Connector",
    "displayName": "Stripe",
    "source": "httpConnectorMetadata",
    "httpConnector": {
      "_id": "63987132784a39b73aae63cd",
      "_apiId": null,
      "_versionId": "63987132784a39b73aae63ce"
    }
  }
]

List supported sync destination applications

get

/v1/di/metadata/destinations

Returns the catalog of applications that can be used as the destination of a sync — the data warehouse a sync loads records into. Use the returned id as the destination application when building a sync. Identifiers include snowflake (Snowflake), nsaw (NetSuite Analytics Warehouse), and bigquery (Google BigQuery).

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Array of supported destination applications.

application/json

A supported destination application.

idstringRequired

Application identifier to use as the sync destination.

Example: snowflake

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/di/metadata/destinations

GET /v1/di/metadata/destinations HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "snowflake"
  },
  {
    "id": "nsaw"
  }
]

List datasets available on a connection

get

/v1/di/metadata/connections/{_connectionId}/datasets

Returns the catalog of tables/objects a connection's application exposes for syncing, plus the connection's existing export resources that can back export-based datasets. Use the returned name values as externalId when creating datasets via PUT /v1/syncs/{_syncId}/datasets.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_connectionIdstring · objectIdRequired

Source connection id.

Example: 6a2a95909e994395f3c2a4e6

Query parameters

typestring · enumOptional

Restrict the response to one catalog. With datasets, only source tables/objects are returned; with exports, only export resources.

Default: allExample: datasetsPossible values:

refreshCachestring · enumOptional

When true, re-reads the catalog from the source application instead of serving the platform's cached copy. Slower; use after making schema changes in the source.

Example: truePossible values:

Responses

200

Dataset and/or export catalogs, keyed by type.

application/json

400

Bad request. The connection id is not a valid id, or type is not one of the allowed values.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

422

The catalog could not be fetched from the source application — e.g. the connection is offline or rejects the request. Error code: di_fetch_datasets_failure.

application/json

get/v1/di/metadata/connections/{_connectionId}/datasets

GET /v1/di/metadata/connections/{_connectionId}/datasets HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "datasets": [
    {
      "name": "Account",
      "displayName": "Account"
    },
    {
      "name": "Contact",
      "displayName": "Contact"
    }
  ],
  "exports": [
    {
      "name": "Pull Salesforce Records",
      "_id": "6a3e7c54c2387aaa87881b80",
      "type": "delta",
      "adaptorType": "SalesforceExport"
    }
  ]
}

Get column details for a dataset on a connection

get

/v1/di/metadata/connections/{_connectionId}/datasets/{datasetName}/details

Returns the full column/field catalog for one table/object on a connection, as read from the source application. Use it to build the dataElements selection before saving a dataset via PUT /v1/syncs/{_syncId}/datasets — each element's name here is the name to reference there.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_connectionIdstring · objectIdRequired

Source connection id.

Example: 6a2a95909e994395f3c2a4e6

datasetNamestringRequired

Table/object name from GET /v1/di/metadata/connections/{_connectionId}/datasets. When isExport is true, pass the export id instead.

Example: Account

Query parameters

isExportstring · enumOptional

Set to true when datasetName is an export id, to read the export's record structure instead of a source table.

Example: falsePossible values:

refreshCachestring · enumOptional

When true, re-reads the columns from the source application instead of the platform's cached copy. Use after making schema changes in the source.

Example: truePossible values:

recordTypestringOptional

NetSuite record type backing the dataset, for saved-search datasets. Omit for other sources.

Example: salesorder

displayNamestringOptional

NetSuite saved-search display name, sent together with recordType.

Example: Sales Orders

Responses

200

The dataset's column catalog.

application/json

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

422

The columns could not be fetched from the source application — e.g. the table/object does not exist or the connection rejects the request. Error code: di_fetch_data_elements_failure.

application/json

get/v1/di/metadata/connections/{_connectionId}/datasets/{datasetName}/details

GET /v1/di/metadata/connections/{_connectionId}/datasets/{datasetName}/details HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "dataset": {
    "name": "Account",
    "displayName": "Account",
    "platform": "salesforce",
    "dataSetType": "Regular",
    "href": "/services/data/v61.0/sobjects/Account",
    "nativeTerminology": {
      "dataset": "Object",
      "dataElements": "Fields",
      "description": "inlineHelpText"
    },
    "dataElements": [
      {
        "name": "Id",
        "displayName": "Account ID",
        "dataType": "String",
        "nativeDataType": "id",
        "dataLength": 18,
        "precision": 0,
        "scale": 0,
        "constraint": "PRIMARY_KEY",
        "isPrimaryKey": true,
        "fullyQualifiedName": "salesforce.00D30000000LHK8EAO.Account.Id",
        "appSpecificProperties": {
          "calculated": false
        },
        "children": null
      },
      {
        "name": "Name",
        "displayName": "Account Name",
        "dataType": "String",
        "nativeDataType": "string",
        "dataLength": 255,
        "precision": 0,
        "scale": 0,
        "fullyQualifiedName": "salesforce.00D30000000LHK8EAO.Account.Name",
        "appSpecificProperties": {
          "calculated": false
        },
        "children": null
      }
    ]
  }
}

List a connection's datasets merged with a sync's configuration

get

/v1/di/metadata/sync/{_syncId}/connections/{_connectionId}/datasets

Returns the connection's full dataset catalog with the sync's saved configuration merged in: catalog entries the sync already replicates carry their stored dataset fields (_id, enable, ingestionMode, …) plus computed totalFieldCount and selectedFieldCount, while unsaved entries appear with catalog fields only. dataElements arrays are stripped from every item to keep the payload small — read one item's columns with the sync-scoped details endpoint.

Use this to render or reconcile a sync's dataset selection; for just the saved datasets, GET /v1/syncs/{_syncId}/datasets is lighter.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_syncIdstring · objectIdRequired

Sync id.

Example: 6a55970bdb54be366c858bc9

_connectionIdstring · objectIdRequired

The sync's source connection id.

Example: 6a2a95909e994395f3c2a4e6

Query parameters

typestring · enumOptional

Restrict the response to one catalog. With datasets, only source tables/objects are returned; with exports, only export-backed entries.

Default: allExample: datasetsPossible values:

refreshCachestring · enumOptional

When true, re-reads the catalog from the source application instead of the platform's cached copy.

Example: truePossible values:

Responses

200

Merged dataset and/or export lists, keyed by type.

application/json

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

The sync or connection belongs to a different account owner.

application/json

422

The catalog could not be fetched or merged — e.g. the connection is offline or the sync/connection pair does not match.

application/json

get/v1/di/metadata/sync/{_syncId}/connections/{_connectionId}/datasets

GET /v1/di/metadata/sync/{_syncId}/connections/{_connectionId}/datasets HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "datasets": [
    {
      "name": "Account",
      "displayName": "Account",
      "externalId": "Account",
      "_id": "6a55970c5f9498a1758a0ad3",
      "enable": true,
      "enableAllDataElements": false,
      "ingestionMode": "append",
      "exportProperties": {
        "type": "all"
      },
      "userActionRequired": false,
      "totalFieldCount": 49,
      "selectedFieldCount": 35
    },
    {
      "name": "Contact",
      "displayName": "Contact",
      "exportProperties": {
        "type": "delta"
      }
    }
  ],
  "exports": [
    {
      "name": "Pull Salesforce Records",
      "externalId": "6a3e7c54c2387aaa87881b80",
      "_id": "6a55974edb54be366c858d26",
      "type": "delta",
      "adaptorType": "SalesforceExport",
      "tableName": "pull_salesforce_records",
      "enable": true,
      "ingestionMode": "merge",
      "isExport": true,
      "userActionRequired": false,
      "totalFieldCount": 16,
      "selectedFieldCount": 16
    }
  ]
}

Get column details for a dataset in a sync's context

get

/v1/di/metadata/sync/{_syncId}/connections/{_connectionId}/datasets/{datasetName}/details

Returns one table/object's full column catalog from the source, merged with the sync's saved dataset state — enablement, ingestionMode, exportProperties, drift policy, and per-column selections. Use it to edit a dataset's dataElements with the current source schema and saved selections in one payload.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_syncIdstring · objectIdRequired

Sync id.

Example: 6a55970bdb54be366c858bc9

_connectionIdstring · objectIdRequired

The sync's source connection id.

Example: 6a2a95909e994395f3c2a4e6

datasetNamestringRequired

Table/object name from the merged catalog. When isExport is true, pass the saved dataset's _id instead.

Example: Account

Query parameters

isExportstring · enumOptional

Set to true when datasetName identifies an export-backed dataset, to read the export's record structure instead of a source table.

Example: falsePossible values:

refreshCachestring · enumOptional

When true, re-reads the columns from the source application instead of the platform's cached copy.

Example: truePossible values:

recordTypestringOptional

NetSuite record type backing the dataset, for saved-search datasets. Omit for other sources.

Example: salesorder

displayNamestringOptional

NetSuite saved-search display name, sent together with recordType.

Example: Sales Orders

Responses

200

The dataset's column catalog merged with the sync's saved state.

application/json

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

The sync or connection belongs to a different account owner.

application/json

422

The columns could not be fetched or merged — e.g. the table/object does not exist in the source or the connection rejects the request. Error code: di_fetch_data_elements_failure.

application/json

get/v1/di/metadata/sync/{_syncId}/connections/{_connectionId}/datasets/{datasetName}/details

GET /v1/di/metadata/sync/{_syncId}/connections/{_connectionId}/datasets/{datasetName}/details HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "dataset": {
    "_id": "6a55970c5f9498a1758a0ad3",
    "name": "Account",
    "displayName": "Account",
    "platform": "salesforce",
    "enable": true,
    "isExport": false,
    "ingestionMode": "append",
    "exportProperties": {
      "type": "all"
    },
    "dataElements": [
      {
        "name": "Id",
        "displayName": "Account ID",
        "dataType": "String",
        "nativeDataType": "id",
        "dataLength": 18,
        "enable": true,
        "isPrimaryKey": true
      },
      {
        "name": "Name",
        "displayName": "Account Name",
        "dataType": "String",
        "nativeDataType": "string",
        "dataLength": 255,
        "enable": true
      }
    ]
  }
}