Destinations API

Destinations are the tools and platforms where SignalSmith sends your data. Destinations receive data from syncs and audience syncs, and support a wide range of types including CRM platforms, advertising networks, marketing tools, warehouses, and webhooks.

Endpoints

Method	Path	Description
`GET`	`/api/v1/workspaces/{id}/destinations`	List all destinations
`POST`	`/api/v1/workspaces/{id}/destinations`	Create 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/test`	Test a new connection (SSE)
`POST`	`/api/v1/workspaces/{id}/destinations/{destId}/test`	Test an existing connection (SSE)
`GET`	`/api/v1/workspaces/{id}/destinations/{destId}/fields`	Describe destination fields
`GET`	`/api/v1/workspaces/{id}/destinations/{destId}/permissions`	Get destination permissions

List Destinations

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

Returns all destinations in the workspace.

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://your-instance.signalsmith.io/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

Field	Type	Required	Description
`name`	string	Yes	Display name
`destination_type`	string	Yes	Destination connector type
`config`	object	Yes	Connection configuration (varies by type)
`connection_id`	string	No	Shared connection ID

Supported Destination Types

Type	Description
`salesforce`	Salesforce CRM
`hubspot`	HubSpot CRM
`google_ads`	Google Ads
`facebook_ads`	Facebook/Meta Ads
`linkedin_ads`	LinkedIn Ads
`the_trade_desk`	The Trade Desk
`braze`	Braze
`iterable`	Iterable
`klaviyo`	Klaviyo
`mailchimp`	Mailchimp
`snowflake`	Snowflake (as destination)
`bigquery`	BigQuery (as destination)
`databricks`	Databricks (as destination)
`webhook`	Custom webhook
`s3`	Amazon S3
`gcs`	Google 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://your-instance.signalsmith.io/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://your-instance.signalsmith.io/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.

Request Body

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

Example

curl -X PUT https://your-instance.signalsmith.io/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 syncs reference it.

Response

{
  "status": "deleted"
}

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

Field	Type	Required	Description
`destination_type`	string	Yes	Destination connector type
`config`	object	Yes	Connection 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 sync configuration. The structure varies by destination type.

Example

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

Get Permissions

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

Returns the role-based permission settings for a destination.

Response

[
  {
    "destination_id": "550e8400-e29b-41d4-a716-446655440000",
    "role": "admin",
    "trigger_syncs": true,
    "configure_models_syncs": true,
    "manage_destination": true
  },
  {
    "destination_id": "550e8400-e29b-41d4-a716-446655440000",
    "role": "member",
    "trigger_syncs": true,
    "configure_models_syncs": false,
    "manage_destination": false
  }
]

Destination Object

Field	Type	Description
`id`	string (UUID)	Unique identifier
`workspace_id`	string (UUID)	Owning workspace
`connection_id`	string (UUID) or null	Shared connection reference
`name`	string	Display name
`destination_type`	string	Connector type
`config`	object	Connection configuration
`status`	string	`pending`, `connected`, or `error`
`status_error`	string	Error message when status is `error`
`created_by`	string (UUID)	Account that created the destination
`created_at`	string (ISO 8601)	Creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp

Models Syncs