ht
Documentation
WelcomeConcepts

Get Started

OverviewCreate a sourceCreate a modelCreate a destinationCreate a sync

Integrations

AWSdbt Clouddbt ModelsGit SyncAirflowHTTP APIPagerDuty
Documentation/Integrations/Api
ht
Documentation

HTTP API

Table of Contents
The Hightouch REST API
The Hightouch HTTP API allows you to trigger syncs and view their status using simple HTTP requests to our API

The Hightouch REST API

The Hightouch REST API can be used to trigger syncs and to get the status of a sync run. We are working on expanding the capabilities of the API to expose a variety of additional information on models, destinations, sources, and other objects as well. Let us know if there's any functionality you're interested in!

Authorization

Every request to the API must provide an Authorization Bearer token. This token is attached to a particular workspace.Create an API Token in your workspace settings. Once you click the Create API Key button, you'll be prompted for a name and presented with an API key.
This API Token should be kept secure. You can always revoke it and create a new one as needed.
To send a request, include Authorization: Bearer <token> in your HTTP header. For example
API_KEY=abcdefg-my-api-key
# Using curl
curl https://api.hightouch.io/api/v2/rest/sync/123 -H "Authorization: Bearer $API_KEY"
# Use httpie
http https://api.hightouch.io/api/v2/rest/sync/123 "Authorization: Bearer $API_KEY"

Endpoints

The following endpoints are defined

Start a new Sync Run

This requests that a sync run be initiated. The request to start a run occurs separate from the job being picked up by the worker. If you need to know the status of the run triggered by this sync, the latest_sync_run_id from the response can be used with the /api/v2/rest/sync/ endpoint described below.POST https://api.hightouch.io/api/v2/rest/run/:sync_id

Examples

curl -X POST https://api.hightouch.io/api/v2/rest/run/123 -H "Authorization: Bearer $API_KEY"

Parameters

  • No http parameters are accepted

Response Types

  • 200: Successful started a sync
  • 400: No sync ID provided.
  • 403: Unauthorized. Invalid API Key for the given sync.
  • 404: Sync ID provided does not exist, or does not exist for the given workspace.

Response

  • sync_id: (int) The ID of the sync that was started
  • message: (string) The string "Sync has been queued"
  • latest_sync_run_id: (int) The most recent run id before the sync request was queued for a new run.
{
"latest_sync_run_id": 12345,
"message": "Sync has been queued",
"sync_id": "123"
}

Get the status of a sync run

This requests the current status of a sync, along with additional sync metadata.You may specify the status of a particular run, otherwise the API will return the status of the most recent run. For example, if you triggered a run via the /run/ endpoint you can use the latest_sync_run_id returned from that run to get the status of the run invoked by your call.GET https://api.hightouch.io/api/v2/rest/sync/:sync_id

Examples

curl https://api.hightouch.io/api/v2/rest/sync/123 -H "Authorization: Bearer $API_KEY"
curl https://api.hightouch.io/api/v2/rest/sync/123?latest_sync_run_id=12345 -H "Authorization: Bearer $API_KEY"

Parameters

  • latest_sync_run_id: If provided, fetches the status of the run following the sync run provided.

Response Types

  • 200: Successful started a sync.
  • 400: No sync ID provided.
  • 403: Unauthorized. Invalid API Key for the given sync.
  • 404: Sync ID provided does not exist, or does not exist for the given workspace.

Response

  • id: (int) The ID of the sync that was started
  • modelid: the ID of the model associated with this sync
  • destination_id: The ID of the destiantion associated with this sync
  • sync: An object containing additional sync information.
  • sync.sync_id: The id of the sync that was started
  • sync.sync_paused: Boolean, whether the sync is paused
  • sync.sync_created_at: The date the sync was created
  • sync.sync_created_by: The user id of the user who created this sync
  • sync.sync_schedule: The sync's schedule, if any.
  • sync.sync_status: The status of the sync, for a given sync run id (if provided) or for the latest run.
  • sync.last_run_at: The timestamp of when the sync was last run.
  • last_sync_run: An object containing additional sync run information.
  • last_sync_run.sync_run_id: The id of the sync run which determines the status of the response provided
  • last_sync_run.sync_run_created_at: Timestamp of when the the last run was started.
  • last_sync_run.sync_run_finished_at: Timestamp of when the last run was completed. The duration of the sync is the difference between finished_at and created_at
  • last_sync_run.sync_run_error: The error, if any, associated with this run.
{
"id": 12345,
"model_id": 123,
"destination_id": 456,
"sync": {
"sync_id": 12345,
"sync_paused": false,
"sync_created_at": "2021-06-08T21:36:55.017905+00:00",
"sync_created_by": 443322,
"sync_schedule": null,
"sync_status": "success",
"last_run_at": "2021-07-06T21:45:04.152+00:00"
},
"last_sync_run": {
"sync_run_id": 42069,
"sync_run_created_at": "2021-07-06T21:44:11.106691+00:00",
"sync_run_finished_at": "2021-07-06T21:44:12.288+00:00",
"sync_run_error": null
}
}