Skip to Content
API ReferenceDestinations

Destinations API

Destinations are the tools and platforms where Zeotap sends your data. Destinations receive data from Reverse ETL pipelines and audience-driven Syncs, and support a wide range of types including CRM platforms, advertising networks, marketing tools, warehouses, and webhooks.

Endpoints

MethodPathDescription
GET/api/v1/workspaces/{id}/destinationsList all destinations
POST/api/v1/workspaces/{id}/destinationsCreate a destination
GET/api/v1/workspaces/{id}/destinations/{destId}Get a destination
PUT/api/v1/workspaces/{id}/destinations/{destId}Update a destination
DELETE/api/v1/workspaces/{id}/destinations/{destId}Delete a destination
POST/api/v1/workspaces/{id}/destinations/testTest a new connection (SSE)
POST/api/v1/workspaces/{id}/destinations/{destId}/testTest an existing connection (SSE)
GET/api/v1/workspaces/{id}/destinations/{destId}/fieldsDescribe destination fields
PUT/api/v1/workspaces/{id}/delivery/connections/{destId}Update a delivery setup connection

List Destinations

GET /api/v1/workspaces/{id}/destinations

Returns all destinations in the workspace, except the system destinations delivery setup creates for the Engagement module.

Query Parameters

ParameterTypeDescription
include_systembooleantrue, 1 or yes also returns system destinations. Any other value, or none, leaves them out.
ownedbooleantrue returns only destinations this workspace owns, leaving out those a parent workspace shares with it.

Response

[ { "id": "550e8400-e29b-41d4-a716-446655440000", "workspace_id": "660e8400-e29b-41d4-a716-446655440000", "connection_id": null, "name": "Salesforce Production", "destination_type": "salesforce", "config": { "instance_url": "https://mycompany.salesforce.com", "api_version": "58.0", "object": "Contact" }, "status": "connected", "status_error": "", "created_by": "770e8400-e29b-41d4-a716-446655440000", "created_at": "2024-01-15T09:30:00Z", "updated_at": "2024-01-15T09:30:00Z" } ]

Example

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

Create Destination

POST /api/v1/workspaces/{id}/destinations

Creates a new destination connection.

Request Body

FieldTypeRequiredDescription
namestringYesDisplay name
destination_typestringYesDestination connector type
configobjectYesConnection configuration (varies by type)
connection_idstringNoShared connection ID

Supported Destination Types

TypeDescription
salesforceSalesforce CRM
hubspotHubSpot CRM
google_adsGoogle Ads
facebook_adsFacebook/Meta Ads
linkedin_adsLinkedIn Ads
the_trade_deskThe Trade Desk
brazeBraze
iterableIterable
klaviyoKlaviyo
mailchimpMailchimp
snowflakeSnowflake (as destination)
bigqueryBigQuery (as destination)
databricksDatabricks (as destination)
webhookCustom webhook
s3Amazon S3
gcsGoogle Cloud Storage

Webhook Config Example

{ "name": "Custom Webhook", "destination_type": "webhook", "config": { "url": "https://api.example.com/webhook", "method": "POST", "headers": { "X-API-Key": "your-api-key" } } }

Response

Returns the created destination with status 201 Created.

Example

curl -X POST https://agentic.zeotap.com/api/v1/workspaces/{id}/destinations \ -H "Authorization: Bearer <token>" \ -H "X-Workspace-ID: <workspace-id>" \ -H "Content-Type: application/json" \ -d '{ "name": "Salesforce Production", "destination_type": "salesforce", "config": { "instance_url": "https://mycompany.salesforce.com", "api_version": "58.0" } }'

Get Destination

GET /api/v1/workspaces/{id}/destinations/{destId}

Returns a single destination by ID.

Example

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

Update Destination

PUT /api/v1/workspaces/{id}/destinations/{destId}

Updates an existing destination. A system destination created by delivery setup cannot be updated here: the request is refused with 409 and a system_owned error. Use Update a delivery setup connection instead.

Request Body

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

Errors

StatusErrorWhen
409system_ownedThe destination was created by delivery setup.

Example

curl -X PUT https://agentic.zeotap.com/api/v1/workspaces/{id}/destinations/{destId} \ -H "Authorization: Bearer <token>" \ -H "X-Workspace-ID: <workspace-id>" \ -H "Content-Type: application/json" \ -d '{ "name": "Salesforce Production (Updated)" }'

Delete Destination

DELETE /api/v1/workspaces/{id}/destinations/{destId}

Deletes a destination. Cannot be deleted if active Reverse ETL pipelines or Syncs reference it. A system destination created by delivery setup cannot be deleted here, with or without force.

Response

{ "status": "deleted" }

Errors

StatusErrorWhen
409system_ownedThe destination was created by delivery setup.

Update a Delivery Setup Connection

PUT /api/v1/workspaces/{id}/delivery/connections/{destId}

Updates a destination created by delivery setup: its name, its configuration or its API key. Requires the destinations.write permission. The change is recorded in the workspace audit log.

Request Body

FieldTypeDescription
namestringOptional. The new name. Omit it to keep the current name.
configobjectOptional. Merged over the stored configuration.
credentialsobjectOptional. Merged over the stored credentials. Omit it to keep the stored key.
verifybooleanOptional. Test the connection before saving.

Errors

StatusErrorWhen
403permission deniedThe caller does not hold destinations.write.
404delivery_connection_not_foundThe destination was not created by delivery setup, or is in another workspace.

Example

curl -X PUT https://agentic.zeotap.com/api/v1/workspaces/{id}/delivery/connections/{destId} \ -H "Authorization: Bearer <token>" \ -H "X-Workspace-ID: <workspace-id>" \ -H "Content-Type: application/json" \ -d '{ "credentials": { "api_key": "SG.new-key" } }'

Test New Connection

POST /api/v1/workspaces/{id}/destinations/test

Tests a destination connection using provided credentials. Response is streamed via Server-Sent Events (SSE).

Request Body

FieldTypeRequiredDescription
destination_typestringYesDestination connector type
configobjectYesConnection configuration

Response (SSE Stream)

event: step data: {"name":"connectivity","status":"passed","message":"Successfully connected"} event: step data: {"name":"authentication","status":"passed","message":"OAuth token valid"} event: done data: {"success":true,"steps":[...]}

Test Existing Connection

POST /api/v1/workspaces/{id}/destinations/{destId}/test

Tests an existing destination’s connection. On completion, the destination’s status is updated.

Response (SSE Stream)

event: step data: {"name":"connectivity","status":"passed","message":"Connected successfully"} event: done data: {"success":true,"destination":{...},"steps":[...]}

Describe Fields

GET /api/v1/workspaces/{id}/destinations/{destId}/fields

Returns the available fields in the destination that can be mapped to during Reverse ETL or Sync configuration. The structure varies by destination type.

Example

curl -X GET https://agentic.zeotap.com/api/v1/workspaces/{id}/destinations/{destId}/fields \ -H "Authorization: Bearer <token>" \ -H "X-Workspace-ID: <workspace-id>"

Destination Object

FieldTypeDescription
idstring (UUID)Unique identifier
workspace_idstring (UUID)Owning workspace
connection_idstring (UUID) or nullShared connection reference
namestringDisplay name
destination_typestringConnector type
configobjectConnection configuration
statusstringpending, connected, error, or auth_expired
status_errorstringError message when status is error
created_bystring (UUID)Account that created the destination
created_atstring (ISO 8601)Creation timestamp
updated_atstring (ISO 8601)Last update timestamp
Last updated on