Syncs API

Syncs (formerly “audience syncs”) activate audiences by sending their members to destinations. Unlike Reverse ETL pipelines (which sync model data), syncs are driven by audience membership — they send the set of users who match an audience’s filter criteria to a destination like a CRM, ad platform, or marketing tool. The API path remains audience-syncs for backwards compatibility.

Endpoints

List Syncs

GET /api/v1/workspaces/{id}/audience-syncs

Returns all syncs in the workspace.

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspace_id": "660e8400-e29b-41d4-a716-446655440000",
    "audience_id": "770e8400-e29b-41d4-a716-446655440000",
    "destination_id": "880e8400-e29b-41d4-a716-446655440000",
    "name": "High-Value Customers to Google Ads",
    "description": "Sync high-value audience to Google Ads customer match",
    "field_mapping": [
      {"source_column": "email", "destination_field": "hashedEmail"},
      {"source_column": "phone", "destination_field": "hashedPhoneNumber"}
    ],
    "sync_mode": "mirror",
    "schedule": "0 */4 * * *",
    "config": {},
    "status": "active",
    "status_error": "",
    "created_by": "990e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z",
    "last_synced_at": "2024-01-15T16:00:00Z",
    "last_run_id": "aae8400-e29b-41d4-a716-446655440000",
    "split_group_id": null
  }
]

Example

curl -X GET https://composable.zeotap.com/api/v1/workspaces/{id}/audience-syncs \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

Create Sync

POST /api/v1/workspaces/{id}/audience-syncs

Creates a new sync to activate an audience to a destination.

Request Body

Sync Modes

Snapshot mode

snapshot delivers the complete current audience membership on every run, with no delta. Every other mode is incremental: each run diffs the membership against the previous run and sends only who joined, changed, or left.

Restricted to file-based destinations — gcs, s3, azure_blob, minio, sftp, box, dropbox, google_drive, microsoft_onedrive, microsoft_sharepoint, liveramp, acxiom, infosum, tableau. A file drop can carry the entire dataset as one artifact, with no per-row operation column; a per-row API destination has no equivalent and would simply re-send every record on every run. Requesting it elsewhere returns 400:

{
  "error": "sync_mode \"snapshot\" is not supported by destination type \"braze\"; supported modes: [add remove mirror upsert]"
}

What differs from mirror on the same destination:

• Output files carry no _operation column. Mirror labels each row added / changed / removed; a snapshot file is the whole membership, so per-row operations do not apply.
• Departed records are simply absent from the next file rather than delivered tagged removed. Treat each drop as authoritative and replace the prior copy rather than merging into it.
• Run stats report every row under rows_added; rows_updated and rows_deleted stay 0.

Example

curl -X POST https://composable.zeotap.com/api/v1/workspaces/{id}/audience-syncs \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-Value Customers to Google Ads",
    "audience_id": "770e8400-e29b-41d4-a716-446655440000",
    "destination_id": "880e8400-e29b-41d4-a716-446655440000",
    "field_mapping": [
      {"source_column": "email", "destination_field": "hashedEmail"}
    ],
    "sync_mode": "mirror",
    "schedule": "0 */4 * * *"
  }'

Get Sync

GET /api/v1/workspaces/{id}/audience-syncs/{audienceSyncId}

Returns a single sync by ID.

Update Sync

PUT /api/v1/workspaces/{id}/audience-syncs/{audienceSyncId}

Updates an existing sync.

Request Body

Same fields as create. Only include fields you want to change.

Delete Sync

DELETE /api/v1/workspaces/{id}/audience-syncs/{audienceSyncId}

Deletes a sync.

Response

{
  "status": "deleted"
}

Trigger Sync Run

POST /api/v1/workspaces/{id}/audience-syncs/{audienceSyncId}/trigger

Manually triggers a sync run.

Response

Returns the created sync run object with status 201 Created.

List Sync Runs

GET /api/v1/workspaces/{id}/audience-syncs/{audienceSyncId}/runs

Returns the execution history for a sync.

Get Sync Run

GET /api/v1/workspaces/{id}/audience-syncs/{audienceSyncId}/runs/{runId}

Returns details of a specific sync run.

List Syncs by Audience

GET /api/v1/workspaces/{id}/audiences/{audId}/syncs

Returns all syncs that activate a specific audience.

Sync Object