Create Sync

curl --request POST \
  --url https://api.hightouch.com/api/v1/syncs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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
}
'

import requests

url = "https://api.hightouch.com/api/v1/syncs"

payload = {
    "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": None,
    "disabled": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://api.hightouch.com/api/v1/syncs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hightouch.com/api/v1/syncs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hightouch.com/api/v1/syncs"

	payload := strings.NewReader("{\n  \"slug\": \"testsync3\",\n  \"destinationId\": \"1\",\n  \"modelId\": \"4\",\n  \"configuration\": {\n    \"mode\": \"upsert\",\n    \"object\": \"contacts\",\n    \"mappings\": [\n      {\n        \"to\": \"email\",\n        \"from\": \"email\",\n        \"type\": \"standard\"\n      }\n    ],\n    \"objectId\": \"0-1\",\n    \"externalIdMapping\": {\n      \"to\": \"firstname\",\n      \"from\": \"test_id\",\n      \"type\": \"standard\"\n    },\n    \"associationMappings\": []\n  },\n  \"schedule\": null,\n  \"disabled\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hightouch.com/api/v1/syncs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"slug\": \"testsync3\",\n  \"destinationId\": \"1\",\n  \"modelId\": \"4\",\n  \"configuration\": {\n    \"mode\": \"upsert\",\n    \"object\": \"contacts\",\n    \"mappings\": [\n      {\n        \"to\": \"email\",\n        \"from\": \"email\",\n        \"type\": \"standard\"\n      }\n    ],\n    \"objectId\": \"0-1\",\n    \"externalIdMapping\": {\n      \"to\": \"firstname\",\n      \"from\": \"test_id\",\n      \"type\": \"standard\"\n    },\n    \"associationMappings\": []\n  },\n  \"schedule\": null,\n  \"disabled\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hightouch.com/api/v1/syncs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"slug\": \"testsync3\",\n  \"destinationId\": \"1\",\n  \"modelId\": \"4\",\n  \"configuration\": {\n    \"mode\": \"upsert\",\n    \"object\": \"contacts\",\n    \"mappings\": [\n      {\n        \"to\": \"email\",\n        \"from\": \"email\",\n        \"type\": \"standard\"\n      }\n    ],\n    \"objectId\": \"0-1\",\n    \"externalIdMapping\": {\n      \"to\": \"firstname\",\n      \"from\": \"test_id\",\n      \"type\": \"standard\"\n    },\n    \"associationMappings\": []\n  },\n  \"schedule\": null,\n  \"disabled\": false\n}"

response = http.request(request)
puts response.read_body

{
  "id": 1,
  "slug": "testsync3",
  "workspaceId": 1,
  "createdAt": "2022-02-16T21:37:58.510Z",
  "updatedAt": "2022-02-16T21:37:58.510Z",
  "createdBy": {
    "id": 1,
    "name": "Jane Doe",
    "email": "jane.doe@example.com"
  },
  "updatedBy": {
    "id": 1,
    "name": "Jane Doe",
    "email": "jane.doe@example.com"
  },
  "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"
  },
  "syncTemplateId": null,
  "syncTemplateOverrides": null
}

{
  "message": "Validation failed",
  "details": {}
}

{
  "message": "Validation failed",
  "details": {}
}

"Internal Server Error"

Syncs

Create Sync

Create a new sync

A sync either owns its configuration (destinationId and configuration) or is created from a sync template (syncTemplateId). A sync created from a template uses the template’s destination and configuration, and may set the fields the template’s overrideConfig marks as overridable through syncTemplateOverrides. The effective configuration is validated for the destination either way, and configuration.<field> errors on a template sync refer to that merged configuration. In a workspace that requires sync templates for audience activation, a sync on an audience must be created from a sync template.

POST

syncs

Create Sync

curl --request POST \
  --url https://api.hightouch.com/api/v1/syncs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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
}
'

import requests

url = "https://api.hightouch.com/api/v1/syncs"

payload = {
    "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": None,
    "disabled": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://api.hightouch.com/api/v1/syncs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hightouch.com/api/v1/syncs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hightouch.com/api/v1/syncs"

	payload := strings.NewReader("{\n  \"slug\": \"testsync3\",\n  \"destinationId\": \"1\",\n  \"modelId\": \"4\",\n  \"configuration\": {\n    \"mode\": \"upsert\",\n    \"object\": \"contacts\",\n    \"mappings\": [\n      {\n        \"to\": \"email\",\n        \"from\": \"email\",\n        \"type\": \"standard\"\n      }\n    ],\n    \"objectId\": \"0-1\",\n    \"externalIdMapping\": {\n      \"to\": \"firstname\",\n      \"from\": \"test_id\",\n      \"type\": \"standard\"\n    },\n    \"associationMappings\": []\n  },\n  \"schedule\": null,\n  \"disabled\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hightouch.com/api/v1/syncs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"slug\": \"testsync3\",\n  \"destinationId\": \"1\",\n  \"modelId\": \"4\",\n  \"configuration\": {\n    \"mode\": \"upsert\",\n    \"object\": \"contacts\",\n    \"mappings\": [\n      {\n        \"to\": \"email\",\n        \"from\": \"email\",\n        \"type\": \"standard\"\n      }\n    ],\n    \"objectId\": \"0-1\",\n    \"externalIdMapping\": {\n      \"to\": \"firstname\",\n      \"from\": \"test_id\",\n      \"type\": \"standard\"\n    },\n    \"associationMappings\": []\n  },\n  \"schedule\": null,\n  \"disabled\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hightouch.com/api/v1/syncs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"slug\": \"testsync3\",\n  \"destinationId\": \"1\",\n  \"modelId\": \"4\",\n  \"configuration\": {\n    \"mode\": \"upsert\",\n    \"object\": \"contacts\",\n    \"mappings\": [\n      {\n        \"to\": \"email\",\n        \"from\": \"email\",\n        \"type\": \"standard\"\n      }\n    ],\n    \"objectId\": \"0-1\",\n    \"externalIdMapping\": {\n      \"to\": \"firstname\",\n      \"from\": \"test_id\",\n      \"type\": \"standard\"\n    },\n    \"associationMappings\": []\n  },\n  \"schedule\": null,\n  \"disabled\": false\n}"

response = http.request(request)
puts response.read_body

{
  "id": 1,
  "slug": "testsync3",
  "workspaceId": 1,
  "createdAt": "2022-02-16T21:37:58.510Z",
  "updatedAt": "2022-02-16T21:37:58.510Z",
  "createdBy": {
    "id": 1,
    "name": "Jane Doe",
    "email": "jane.doe@example.com"
  },
  "updatedBy": {
    "id": 1,
    "name": "Jane Doe",
    "email": "jane.doe@example.com"
  },
  "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"
  },
  "syncTemplateId": null,
  "syncTemplateOverrides": null
}

{
  "message": "Validation failed",
  "details": {}
}

{
  "message": "Validation failed",
  "details": {}
}

"Internal Server Error"

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

The input for creating a Sync.

A sync either owns its configuration (destinationId and configuration are required) or is created from a sync template (syncTemplateId is required, configuration must be omitted and this sync's own values go in syncTemplateOverrides).

slug

string

required

The sync's slug

modelId

number<double>

required

The id of the Model that sync is connected to

schedule

object | null

required

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

Match Booster (type "match_booster"): the sync will be triggered after each Match Booster enrichment run of its model completes. Requires the model to have Match Booster enabled, and takes no inner schedule payload.

Show child attributes

disabled

boolean

required

Whether the sync has been disabled by the user.

destinationId

number<double>

The id of the Destination that sync is connected to. Required unless syncTemplateId is provided: a sync created from a sync template always uses the template's destination, and this field, when provided, must match it.

configuration

object

The sync's configuration. This specifies how data is mapped, among other configuration. The schema depends on the destination type.

Required unless syncTemplateId is provided, in which case it must be omitted: the template provides the configuration and this sync's own values go in syncTemplateOverrides.

Show child attributes

syncTemplateId

number<double>

The id of the Sync Template to create the sync from. The sync inherits the template's destination and configuration and follows later changes to the template. A null schedule inherits the template's schedule; a schedule given here belongs to the sync. modelId must be the template's model or an audience built on it.

syncTemplateOverrides

object

Values this sync sets for the template's overridable fields, keyed by configuration field path (for example "externalIdMapping" or "target.schema"). Only fields the template's overrideConfig marks as overridable are accepted. Requires syncTemplateId.

Show child attributes

Response

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.

number<double>

required

The sync's id

slug

string

required

The sync's slug

workspaceId

number<double>

required

The id of the workspace that the sync belongs to

createdAt

string<date-time>

required

The timestamp when the sync was created

updatedAt

string<date-time>

required

The timestamp when the sync was last updated

createdBy

object | null

required

The user who created the sync, or null if no user was recorded

Show child attributes

updatedBy

object | null

required

The user who last updated the sync, or null if no user was recorded

Show child attributes

destinationId

number<double>

required

The id of the Destination that sync is connected to

modelId

number<double>

required

The id of the Model that sync is connected to

configuration

object

required

The sync's configuration. This specifies how data is mapped, among other configuration.

The schema depends on the destination type.

For a sync bound to a sync template this is the effective configuration: the template's configuration with this sync's syncTemplateOverrides applied.

Consumers should NOT make assumptions on the contents of the configuration. It may change as Hightouch updates its internal code.

Show child attributes

schedule

object | null

required

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

Show child attributes

status

enum<string>

required

The overall status of the sync

Available options:

disabled,

pending,

cancelled,

failed,

queued,

success,

warning,

querying,

processing,

reporting,

interrupted

disabled

boolean

required

Whether the sync has been disabled by the user.

lastRunAt

string<date-time> | null

required

The timestamp of the last sync run

referencedColumns

string[]

required

The reference column that sync depends on to sync data from source

primaryKey

string

required

The primary key that sync uses to identify data from source

externalSegment

object

required

The user facing ID for any created lists or audiences in the sync destination

Show child attributes

Get started

Audiences

AI Decisioning

Destinations

Events

Lineage

Match Booster

Sources

Models

Sync templates

Sync drafts

Syncs

Sync sequences

Create Sync

Authorizations

Body

Response