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
`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://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

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`, or `upsert`
`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

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

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`, or `upsert`
`schedule`	string	Cron expression
`config`	object	Additional configuration
`status`	string	`draft`, `active`, `paused`, or `error`
`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)