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
| Method | Path | Description |
|---|---|---|
GET | /api/v1/workspaces/{id}/audience-syncs | List all syncs |
POST | /api/v1/workspaces/{id}/audience-syncs | Create a sync |
GET | /api/v1/workspaces/{id}/audience-syncs/{audienceSyncId} | Get a sync |
PUT | /api/v1/workspaces/{id}/audience-syncs/{audienceSyncId} | Update a sync |
DELETE | /api/v1/workspaces/{id}/audience-syncs/{audienceSyncId} | Delete a sync |
POST | /api/v1/workspaces/{id}/audience-syncs/{audienceSyncId}/trigger | Trigger a sync run |
POST | /api/v1/workspaces/{id}/audience-syncs/{audienceSyncId}/pause | Pause a sync |
POST | /api/v1/workspaces/{id}/audience-syncs/{audienceSyncId}/resume | Resume a paused sync and reset its failure count |
GET | /api/v1/workspaces/{id}/audience-syncs/{audienceSyncId}/runs | List sync runs |
GET | /api/v1/workspaces/{id}/audience-syncs/{audienceSyncId}/runs/{runId} | Get a sync run |
GET | /api/v1/workspaces/{id}/audiences/{audId}/syncs | List syncs by audience |
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://agentic.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
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name |
description | string | No | Description |
audience_id | string (UUID) | Yes | Audience to sync |
destination_id | string (UUID) | Yes | Target destination |
field_mapping | array | Yes | Column-to-field mappings |
sync_mode | string | Yes | add, remove, mirror, upsert, or snapshot |
schedule | string | No | Cron expression for scheduling |
config | object | No | Additional sync-specific configuration |
split_group_id | string (UUID) | No | A/B test group to sync (instead of the full audience) |
Sync Modes
| Mode | Description |
|---|---|
add | Only add new audience members to the destination |
remove | Only remove members who exited the audience |
mirror | Add new members and remove exited members to keep destination in sync |
upsert | Add new members and update existing records |
snapshot | Delivers the complete current membership on every run with no delta. File-based destinations only — see Snapshot mode |
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
_operationcolumn. Mirror labels each rowadded/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_updatedandrows_deletedstay0.
Example
curl -X POST https://agentic.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: a field you leave out keeps its saved value. That includes description (send "" to clear it) and min_confidence (send null to clear it).
A destination field the destination declares is saved in the destination’s own spelling. For example, EMAIL for Meta’s email is saved as email.
The field mapping and config are checked against the destination’s rules only when the request changes the field mapping, the config or the sync mode. A rename, a new description or a schedule change saves even if the saved mapping would not pass a rule added since it was created.
Pause Sync
POST /api/v1/workspaces/{id}/audience-syncs/{audienceSyncId}/pause
Stops a sync from running. Scheduled runs are skipped and manual runs are refused until it is resumed. Only the status changes. The field mapping, config, description, schedule and failure count stay as they are, and nothing is re-validated, so any active or failing sync can be paused. Pausing a paused sync does nothing. A draft or broken sync cannot be paused (409 invalid_status_transition).
Requires audiences.write and syncs.write, and edit access to the audience’s folder and the destination. Returns the sync object.
Resume Sync
POST /api/v1/workspaces/{id}/audience-syncs/{audienceSyncId}/resume
Puts a paused sync back to active and resets its failure count, whether a person paused it or it was paused automatically after repeated failures (auto_paused: true). Only the status and the failure count change. Resuming an active sync changes nothing. A draft, error or broken sync cannot be resumed (409 invalid_status_transition); a broken sync is restored by editing it.
Requires audiences.write and syncs.write, and edit access to the audience’s folder and the destination. Returns the sync object.
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
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Unique identifier |
workspace_id | string (UUID) | Owning workspace |
audience_id | string (UUID) | Source audience |
destination_id | string (UUID) | Target destination |
name | string | Display name |
description | string | Description |
field_mapping | array | Column-to-field mappings |
sync_mode | string | add, remove, mirror, upsert, or snapshot |
schedule | string | Cron expression |
config | object | Additional configuration |
status | string | draft, active, paused, error, or broken |
broken_reason | object or null | Present while status is broken: what was lost, and why |
status_error | string | Error message when status is error |
created_by | string (UUID) | Account that created the sync |
created_at | string (ISO 8601) | Creation timestamp |
updated_at | string (ISO 8601) | Last update timestamp |
last_synced_at | string (ISO 8601) or null | Last successful sync time |
last_run_id | string (UUID) or null | ID of the most recent run |
split_group_id | string (UUID) or null | A/B test group (if applicable) |
consecutive_failures | integer | Runs that have failed in a row; reset by a successful run or a resume |
auto_paused | boolean | true when the sync is paused because of repeated failures rather than by a person |