Syncs, sync runs, sync sequences and their triggers.
openapi: 3.0.0
info:
title: Hightouch Syncs API
description: Hightouch Public Rest API to access syncs, models, sources and destinations
version: 1.0.0
contact:
name: Hightouch
url: https://hightouch.com
x-harvested-from: https://api.hightouch.io/api/swagger.json
x-harvested-on: '2026-08-13'
x-source-document: openapi/_original/hightouch-api-openapi.json
servers:
- url: https://api.hightouch.com/api/v1
tags:
- name: Syncs
paths:
/syncs/{syncId}:
get:
operationId: GetSync
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/Sync'
examples:
Example 1:
value:
id: 1
slug: testsync
workspaceId: 1
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-02-16T21:37:58.510Z'
destinationId: 1
modelId: 1
configuration:
mode: upsert
object: contacts
mappings:
- to: email
from: email
type: standard
- to: phone
from: phone
type: standard
objectId: 0-1
externalIdMapping:
to: firstname
from: test_id
type: standard
associationMappings: []
schedule:
type: interval
schedule:
interval:
unit: day
quantity: 1
disabled: false
status: success
lastRunAt: '2022-02-16T21:37:58.510Z'
referencedColumns:
- email
- name
primaryKey: id
externalSegment: {}
tags:
foo: bar
'401':
description: Unauthorized
'404':
description: Not found
description: Retrieve sync from sync ID
summary: Get Sync
security:
- bearerAuth: []
parameters:
- description: The id of the sync
in: path
name: syncId
required: true
schema:
format: double
type: number
tags:
- Syncs
patch:
operationId: UpdateSync
responses:
'200':
description: Ok
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Sync'
- $ref: '#/components/schemas/ValidateErrorJSON'
- $ref: '#/components/schemas/InternalServerError'
examples:
Example 1:
value:
id: 1
slug: testsync3
workspaceId: 1
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-03-19T19:24:34.320Z'
destinationId: 1
modelId: 4
configuration:
mode: upsert
object: contacts
mappings:
- to: email
from: email
type: standard
objectId: 0-1
externalIdMapping:
to: firstname
from: test_id
type: standard
associationMappings: []
schedule:
type: interval
schedule:
interval:
unit: day
quantity: 1
status: success
disabled: true
lastRunAt: '2022-02-16T21:37:58.510Z'
referencedColumns:
- email
- name
primaryKey: id
externalSegment: {}
tags:
foo: bar
'401':
description: Unauthorized
'404':
description: Not found
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
'500':
description: Something went wrong
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
description: 'Update an existing sync
Patch a sync based on its Hightouch ID'
summary: Update Sync
security:
- bearerAuth: []
parameters:
- description: The sync's ID
in: path
name: syncId
required: true
schema:
format: double
type: number
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SyncUpdate'
example:
configuration:
mode: upsert
object: contacts
mappings:
- to: email
from: email
type: standard
objectId: 0-1
externalIdMapping:
to: firstname
from: test_id
type: standard
associationMappings: []
schedule: null
disabled: true
tags:
- Syncs
/syncs:
get:
operationId: ListSync
responses:
'200':
description: Ok
content:
application/json:
schema:
properties:
hasMore:
type: boolean
data:
items:
$ref: '#/components/schemas/Sync'
type: array
required:
- hasMore
- data
type: object
examples:
Example 1:
value:
hasMore: false
data:
- id: 1
slug: testsync
workspaceId: 1
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-02-16T21:37:58.510Z'
destinationId: 1
modelId: 1
configuration:
mode: upsert
object: contacts
mappings:
- to: email
from: email
type: standard
- to: phone
from: phone
type: standard
objectId: 0-1
externalIdMapping:
to: firstname
from: test_id
type: standard
associationMappings: []
schedule:
type: interval
schedule:
interval:
unit: day
quantity: 1
status: success
disabled: false
lastRunAt: '2022-02-16T21:37:58.510Z'
referencedColumns:
- email
- name
primaryKey: id
externalSegment: {}
tags:
foo: bar
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: List all the syncs in the current workspace
summary: List Syncs
security:
- bearerAuth: []
parameters:
- description: filter based on slug
in: query
name: slug
required: false
schema:
type: string
- description: filter based on modelId
in: query
name: modelId
required: false
schema:
format: double
type: number
- description: select syncs that were run after given ISO timestamp
in: query
name: after
required: false
schema:
format: date-time
type: string
- description: select syncs that were run before given ISO timestamp
in: query
name: before
required: false
schema:
format: date-time
type: string
- description: set the offset on results (for pagination)
in: query
name: offset
required: false
schema:
default: 0
format: double
type: number
- description: limit the number of objects returned (default is 100)
in: query
name: limit
required: false
schema:
default: 100
format: double
type: number
- description: specify the order
in: query
name: orderBy
required: false
schema:
default: id
type: string
enum:
- id
- name
- slug
- createdAt
- updatedAt
tags:
- Syncs
post:
operationId: CreateSync
responses:
'200':
description: Ok
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Sync'
- $ref: '#/components/schemas/ValidateErrorJSON'
- $ref: '#/components/schemas/InternalServerError'
examples:
Example 1:
value:
id: 1
slug: testsync3
workspaceId: 1
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-02-16T21:37:58.510Z'
destinationId: 1
modelId: 4
configuration:
mode: upsert
object: contacts
mappings:
- to: email
from: email
type: standard
objectId: 0-1
externalIdMapping:
to: firstname
from: test_id
type: standard
associationMappings: []
schedule:
type: interval
schedule:
interval:
unit: day
quantity: 1
status: success
disabled: false
lastRunAt: null
referencedColumns:
- email
- name
primaryKey: id
externalSegment: {}
tags:
foo: bar
'401':
description: Unauthorized
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
'500':
description: Something went wrong
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
description: Create a new sync
summary: Create Sync
security:
- bearerAuth: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SyncCreate'
example:
slug: testsync3
destinationId: '1'
modelId: '4'
configuration:
mode: upsert
object: contacts
mappings:
- to: email
from: email
type: standard
objectId: 0-1
externalIdMapping:
to: firstname
from: test_id
type: standard
associationMappings: []
schedule: null
disabled: false
tags:
- Syncs
/syncs/{syncId}/runs:
get:
operationId: ListSyncRuns
responses:
'200':
description: Ok
content:
application/json:
schema:
properties:
hasMore:
type: boolean
data:
items:
$ref: '#/components/schemas/SyncRun'
type: array
required:
- hasMore
- data
type: object
examples:
Example 1:
value:
data:
- id: 42
startedAt: '2022-02-08T16:11:04.712Z'
createdAt: '2022-02-08T16:11:04.712Z'
finishedAt: '2022-02-08T16:11:11.698Z'
querySize: 773
status: success
completionRatio: 0.54
plannedRows:
addedCount: 773
changedCount: 0
removedCount: 0
successfulRows:
addedCount: 773
changedCount: 0
removedCount: 0
failedRows:
addedCount: 0
changedCount: 0
removedCount: 0
error: null
- id: 43
startedAt: '2022-02-08T16:11:04.712Z'
createdAt: '2022-02-08T17:44:05.198Z'
finishedAt: '2022-02-08T17:44:25.366Z'
querySize: 773
status: success
completionRatio: 0.54
plannedRows:
addedCount: 0
changedCount: 765
removedCount: 0
successfulRows:
addedCount: 0
changedCount: 765
removedCount: 0
failedRows:
addedCount: 0
changedCount: 0
removedCount: 0
error: null
hasMore: false
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: List all sync runs under a sync
summary: List Sync Runs
security:
- bearerAuth: []
parameters:
- in: path
name: syncId
required: true
schema:
format: double
type: number
- description: query for specific run id
in: query
name: runId
required: false
schema:
format: double
type: number
- description: select sync runs that are started after given ISO timestamp
in: query
name: after
required: false
schema:
format: date-time
type: string
- description: select sync runs that are started before certain ISO timestamp
in: query
name: before
required: false
schema:
format: date-time
type: string
- description: select sync runs that are started within last given minutes
in: query
name: within
required: false
schema:
format: double
type: number
- description: set the offset on results (for pagination)
in: query
name: offset
required: false
schema:
default: 0
format: double
type: number
- description: limit the number of objects returned (default is 100)
in: query
name: limit
required: false
schema:
default: 100
format: double
type: number
- description: specify the order
in: query
name: orderBy
required: false
schema:
default: id
type: string
enum:
- id
- createdAt
- startedAt
- finishedAt
tags:
- Syncs
/syncs/{syncId}/trigger:
post:
operationId: TriggerRun
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerRunOutput'
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: 'Trigger a new run for the given sync.
If a run is already in progress, this queues a sync run that will get
executed immediately after the current run completes.'
summary: Trigger Sync
security:
- bearerAuth: []
parameters:
- description: The id of the sync to trigger a run
in: path
name: syncId
required: true
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerRunInput'
tags:
- Syncs
/syncs/trigger:
post:
operationId: TriggerRunCustom
responses:
'200':
description: Ok
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/TriggerRunOutput'
- $ref: '#/components/schemas/ValidateErrorJSON'
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: 'Trigger a new run globally based on sync id or sync slug
If a run is already in progress, this queues a sync run that will get
executed immediately after the current run completes.'
summary: Trigger Sync From ID or Slug
security:
- bearerAuth: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerRunCustomInput'
tags:
- Syncs
/sync-sequences/{syncSequenceId}/trigger:
post:
operationId: TriggerSequenceRun
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerSequenceRunOutput'
examples:
Example 1:
value:
id: 0cb7da35-1fff-4d4a-bf1b-6534d515e5b5
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: 'Trigger a new run for the given sync sequence.
A sequence never runs concurrently with itself. If a run is already in
progress, then where run queueing is enabled for the workspace, a single
follow-up run is queued and starts after the current run completes
(repeated triggers return the same queued run); otherwise the id of the
run already in progress is returned.'
summary: Trigger Sync sequence
security:
- bearerAuth: []
parameters:
- description: The id of the sync sequence to trigger a run
in: path
name: syncSequenceId
required: true
schema:
type: string
tags:
- Syncs
/sync-sequences/runs/{syncSequenceRunId}:
get:
operationId: GetSyncSequenceRun
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/SyncSequenceStatusOutput'
examples:
Example 1:
value:
id: 0cb7da35-1fff-4d4a-bf1b-6534d515e5b5
status: done
syncRuns:
- syncId: 3093
status: success
finishedAt: '2023-10-17T11:06:01.713+00:00'
syncRunId: 6134
- syncId: 1960
status: warning
finishedAt: '2023-10-17T11:06:10.567+00:00'
syncRunId: 6148
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: Get the status of a sync sequence run.
summary: Sync sequence status
security:
- bearerAuth: []
parameters:
- description: The id of the sync sequence run
in: path
name: syncSequenceRunId
required: true
schema:
type: string
tags:
- Syncs
components:
schemas:
CronSchedule:
properties:
expression:
type: string
required:
- expression
type: object
additionalProperties: false
DBTSchedule:
properties:
account:
properties:
id:
type: string
required:
- id
type: object
job:
properties:
id:
type: string
required:
- id
type: object
required:
- account
- job
type: object
additionalProperties: false
InternalServerError:
type: string
enum:
- Internal Server Error
nullable: false
Interval:
properties:
unit:
$ref: '#/components/schemas/IntervalUnit'
quantity:
type: number
format: double
required:
- unit
- quantity
type: object
additionalProperties: false
IntervalSchedule:
properties:
interval:
$ref: '#/components/schemas/Interval'
required:
- interval
type: object
additionalProperties: false
IntervalUnit:
enum:
- minute
- hour
- day
- week
type: string
Record_Day.boolean-or-undefined_:
properties:
monday:
type: boolean
tuesday:
type: boolean
wednesday:
type: boolean
thursday:
type: boolean
friday:
type: boolean
saturday:
type: boolean
sunday:
type: boolean
type: object
description: Construct a type with a set of properties K of type T
Sync:
description: 'Syncs define how data from models are mapped to destinations. Each time a
sync runs, Hightouch calculates the rows that have changed since the last
run, and syncs them to Sync''s destination.'
properties:
id:
type: number
format: double
description: The sync's id
slug:
type: string
description: The sync's slug
workspaceId:
type: number
format: double
description: The id of the workspace that the sync belongs to
createdAt:
type: string
format: date-time
description: The timestamp when the sync was created
updatedAt:
type: string
format: date-time
description: The timestamp when the sync was last updated
destinationId:
type: number
format: double
description: The id of the Destination that sync is connected to
modelId:
type: number
format: double
description: The id of the Model that sync is connected to
configuration:
properties: {}
additionalProperties: {}
type: object
description: 'The sync''s configuration. This specifies how data is mapped, among other
configuration.
The schema depends on the destination type.
Consumers should NOT make assumptions on the contents of the
configuration. It may change as Hightouch updates its internal code.'
schedule:
properties:
schedule:
anyOf:
- $ref: '#/components/schemas/IntervalSchedule'
- $ref: '#/components/schemas/CronSchedule'
- $ref: '#/components/schemas/VisualCronSchedule'
- $ref: '#/components/schemas/DBTSchedule'
type:
type: string
required:
- schedule
- type
type: object
nullable: true
description: 'The scheduling configuration. It can be triggered based on several ways:
Interval: the sync will be triggered based on certain interval(minutes/hours/days/weeks)
Cron: the sync will be triggered based on cron expression https://en.wikipedia.org/wiki/Cron.
Visual: the sync will be triggered based a visual cron configuration on UI
DBT-cloud: the sync will be triggered based on a dbt cloud job'
status:
$ref: '#/components/schemas/SyncStatus'
description: The overall status of the sync
disabled:
type: boolean
description: Whether the sync has been disabled by the user.
lastRunAt:
type: string
format: date-time
nullable: true
description: The timestamp of the last sync run
referencedColumns:
items:
type: string
type: array
description: The reference column that sync depends on to sync data from source
primaryKey:
type: string
description: The primary key that sync uses to identify data from source
externalSegment:
properties:
id:
type: string
type: object
description: The user facing ID for any created lists or audiences in the sync destination
tags:
properties: {}
additionalProperties:
type: string
type: object
description: The tags of the sync
required:
- id
- slug
- workspaceId
- createdAt
- updatedAt
- destinationId
- modelId
- configuration
- schedule
- status
- disabled
- lastRunAt
- referencedColumns
- primaryKey
- externalSegment
- tags
type: object
additionalProperties: false
SyncCreate:
description: The input for creating a Sync
properties:
slug:
type: string
description: The sync's slug
configuration:
properties: {}
additionalProperties: {}
type: object
description: 'The sync''s configuration. This specifies how data is mapped, among other
configuration.
The schema depends on the destination type.
Consumers should NOT make assumptions on the contents of the
configuration. It may change as Hightouch updates its internal code.'
destinationId:
type: number
format: double
description: The id of the Destination that sync is connected to
modelId:
type: number
format: double
description: The id of the Model that sync is connected to
schedule:
properties:
schedule:
anyOf:
- $ref: '#/components/schemas/IntervalSchedule'
- $ref: '#/components/schemas/CronSchedule'
- $ref: '#/components/schemas/VisualCronSchedule'
- $ref: '#/components/schemas/DBTSchedule'
type:
type: string
required:
- schedule
- type
type: object
nullable: true
description: 'The scheduling configuration. It can be triggered based on several ways:
Interval: the sync will be triggered based on certain interval(minutes/hours/days/weeks)
Cron: the sync will be triggered based on cron expression https://en.wikipedia.org/wiki/Cron.
Visual: the sync will be triggered based a visual cron configuration on UI
DBT-cloud: the sync will be triggered based on a dbt cloud job'
disabled:
type: boolean
description: Whether the sync has been disabled by the user.
required:
- slug
- configuration
- destinationId
- modelId
- schedule
- disabled
type: object
additionalProperties: false
SyncRun:
properties:
id:
type: number
format: double
description: The sync run's id
createdAt:
type: string
format: date-time
description: 'The timestamp when sync run was created. In most cases this will be
equivalent to `startedAt`, but it may be earlier if the sync was triggered
while a run was already in progress, and the new run didn''t start for
a while.'
startedAt:
type: string
format: date-time
description: The timestamp when the sync run started
finishedAt:
type: string
format: date-time
description: The timestamp when the sync run finished
querySize:
type: number
format: double
description: The number of rows in the query.
status:
$ref: '#/components/schemas/SyncRunStatus'
description: The status of sync run
completionRatio:
type: number
format: double
description: The completion ratio of sync run, showing the progress of a sync run
plannedRows:
properties:
removedCount:
type: number
format: double
description: The number of removed rows.
changedCount:
type: number
format: double
description: The number of changed rows.
addedCount:
type: number
format: double
description: The number of added rows.
required:
- removedCount
- changedCount
- addedCount
type: object
description: 'The number of planned rows that this sync run was supposed to execute.
Note that the counts for `successfulRows` and `failedRows` may not add up
to `plannedRows` if the sync was cancelled.'
successfulRows:
properties:
removedCount:
type: number
format:
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hightouch/refs/heads/main/openapi/hightouch-syncs-api-openapi.yml