Search documentation...

K

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.
Your API key provides read/write access to sensitive Hightouch resources and should be kept secure. If you believe your API key may have been compromised, be sure to revoke it immediately.
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 available:

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
  }
}

    Need help?

    Our team is relentlessly focused on your success. We're ready to jump on a call to help unblock you.

    • Connection issues with your data warehouse?
    • Confusing API responses from destination systems?
    • Unsupported destination objects or modes?
    • Help with complex SQL queries?

    or

    Feature Requests?

    If you see something that's missing from our app, let us know and we'll work with you to build it!

    We want to hear your suggestions for new sources, destinations, and other features that would help you activate your data.

On this page

The Hightouch REST APIAuthorizationEndpointsStart a new sync runGet the status of a sync run

Was this page helpful?