Syncs API

Syncs define how data moves from a model to a destination. Each sync specifies the source model, target destination, field mappings, sync mode, and schedule.

Endpoints

Method	Path	Description
`GET`	`/api/v1/workspaces/{id}/syncs`	List all syncs
`POST`	`/api/v1/workspaces/{id}/syncs`	Create a sync
`GET`	`/api/v1/workspaces/{id}/syncs/{syncId}`	Get a sync
`PUT`	`/api/v1/workspaces/{id}/syncs/{syncId}`	Update a sync
`DELETE`	`/api/v1/workspaces/{id}/syncs/{syncId}`	Delete a sync
`POST`	`/api/v1/workspaces/{id}/syncs/{syncId}/trigger`	Trigger a sync run
`GET`	`/api/v1/workspaces/{id}/syncs/{syncId}/runs`	List sync runs
`GET`	`/api/v1/workspaces/{id}/syncs/{syncId}/runs/{runId}`	Get a sync run

List Syncs

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

Returns all syncs in the workspace.

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspace_id": "660e8400-e29b-41d4-a716-446655440000",
    "model_id": "770e8400-e29b-41d4-a716-446655440000",
    "destination_id": "880e8400-e29b-41d4-a716-446655440000",
    "name": "Customers to Salesforce",
    "description": "Sync active customers to Salesforce contacts",
    "field_mapping": [
      {"source_column": "email", "destination_field": "Email"},
      {"source_column": "first_name", "destination_field": "FirstName"},
      {"source_column": "last_name", "destination_field": "LastName"}
    ],
    "sync_mode": "upsert",
    "schedule": "0 */6 * * *",
    "config": {},
    "primary_key": "customer_id",
    "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-15T15:00:00Z",
    "last_run_id": "aae8400-e29b-41d4-a716-446655440000"
  }
]

Example

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

Create Sync

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

Creates a new sync between a model and a destination.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Display name
`description`	string	No	Description
`model_id`	string (UUID)	Yes	Source model ID
`destination_id`	string (UUID)	Yes	Target destination ID
`field_mapping`	array	Yes	Column-to-field mappings
`sync_mode`	string	Yes	`upsert`, `insert`, `update`, or `mirror`
`schedule`	string	No	Cron expression for scheduling (e.g., `0 /6 * *`)
`primary_key`	string	Yes	Column used as the unique identifier for upsert/mirror
`config`	object	No	Additional sync-specific configuration

Sync Modes

Mode	Description
`upsert`	Creates new records and updates existing ones based on the primary key
`insert`	Only creates new records; ignores existing ones
`update`	Only updates existing records; does not create new ones
`mirror`	Full sync: creates, updates, and deletes records to match the source exactly

Field Mapping

{
  "field_mapping": [
    {
      "source_column": "email",
      "destination_field": "Email"
    },
    {
      "source_column": "revenue",
      "destination_field": "Annual_Revenue",
      "type_cast": "number"
    }
  ]
}

Field	Type	Required	Description
`source_column`	string	Yes	Column name from the model
`destination_field`	string	Yes	Field name in the destination
`type_cast`	string	No	Type conversion to apply

Example

curl -X POST https://your-instance.signalsmith.io/api/v1/workspaces/{id}/syncs \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customers to Salesforce",
    "model_id": "770e8400-e29b-41d4-a716-446655440000",
    "destination_id": "880e8400-e29b-41d4-a716-446655440000",
    "field_mapping": [
      {"source_column": "email", "destination_field": "Email"},
      {"source_column": "first_name", "destination_field": "FirstName"}
    ],
    "sync_mode": "upsert",
    "primary_key": "customer_id",
    "schedule": "0 */6 * * *"
  }'

Get Sync

GET /api/v1/workspaces/{id}/syncs/{syncId}

Returns a single sync by ID.

Example

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

Update Sync

PUT /api/v1/workspaces/{id}/syncs/{syncId}

Updates an existing sync configuration.

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}/syncs/{syncId} \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "0 */12 * * *",
    "status": "paused"
  }'

Delete Sync

DELETE /api/v1/workspaces/{id}/syncs/{syncId}

Deletes a sync.

Response

{
  "status": "deleted"
}

Trigger Sync Run

POST /api/v1/workspaces/{id}/syncs/{syncId}/trigger

Manually triggers a sync run outside of the configured schedule.

Response

Returns the created sync run object with status 201 Created.

{
  "id": "bbe8400-e29b-41d4-a716-446655440000",
  "sync_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "660e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "started_at": "2024-01-15T15:00:00Z",
  "rows_synced": 0,
  "rows_failed": 0,
  "triggered_by": "990e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T15:00:00Z"
}

Example

curl -X POST https://your-instance.signalsmith.io/api/v1/workspaces/{id}/syncs/{syncId}/trigger \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

List Sync Runs

GET /api/v1/workspaces/{id}/syncs/{syncId}/runs

Returns the execution history for a sync.

Response

[
  {
    "id": "bbe8400-e29b-41d4-a716-446655440000",
    "sync_id": "550e8400-e29b-41d4-a716-446655440000",
    "workspace_id": "660e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "started_at": "2024-01-15T15:00:00Z",
    "completed_at": "2024-01-15T15:02:30Z",
    "rows_synced": 5420,
    "rows_failed": 3,
    "error_message": "",
    "triggered_by": "990e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-15T15:00:00Z"
  }
]

Sync Run Statuses

Status	Description
`pending`	Run is queued
`running`	Run is in progress
`completed`	Run finished successfully
`failed`	Run failed with an error
`cancelled`	Run was manually cancelled

Get Sync Run

GET /api/v1/workspaces/{id}/syncs/{syncId}/runs/{runId}

Returns details of a specific sync run.

Example

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

Sync Object

Field	Type	Description
`id`	string (UUID)	Unique identifier
`workspace_id`	string (UUID)	Owning workspace
`model_id`	string (UUID)	Source model
`destination_id`	string (UUID)	Target destination
`name`	string	Display name
`description`	string	Description
`field_mapping`	array	Column-to-field mappings
`sync_mode`	string	`upsert`, `insert`, `update`, or `mirror`
`schedule`	string	Cron expression
`config`	object	Additional configuration
`primary_key`	string	Primary key column
`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

Destinations Traits