POST
/
syncs
curl --request POST \
  --url https://app.getcensus.com/api/v1/syncs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "label": "New Signups to Leads",
  "operation": "mirror",
  "source_attributes": {
    "connection_id": 12,
    "object": {
      "type": "model",
      "name": "test_ads"
    }
  },
  "destination_attributes": {
    "connection_id": 15,
    "object": "user_data"
  },
  "alert_attributes": [
    {
      "type": "FailureAlertConfiguration",
      "send_for": "first_time",
      "should_send_recovery": true,
      "options": null
    },
    {
      "type": "InvalidRecordPercentAlertConfiguration",
      "send_for": "every_time",
      "should_send_recovery": false,
      "options": {
        "threshold": 10
      }
    }
  ],
  "mappings": [
    {
      "from": {
        "type": "column",
        "data": "hashed_email"
      },
      "to": "user_identifier.hashed_email_PREHASHED",
      "is_primary_identifier": true
    },
    {
      "from": {
        "type": "column",
        "data": "list_id"
      },
      "to": "list_id",
      "lookup_object": "user_list",
      "lookup_field": "name"
    },
    {
      "from": {
        "type": "constant_value",
        "data": {
          "value": "cohort_1",
          "basic_type": "text"
        }
      },
      "to": "cohort"
    }
  ],
  "advanced_configuration": {
    "data_source_country": "US, GB",
    "bulk_id_lookup": true
  },
  "mode": {
    "type": "triggered",
    "triggers": {
      "schedule": {
        "frequency": "daily",
        "hour": 10,
        "minute": 30
      }
    }
  },
  "paused": false,
  "field_behavior": "sync_all_properties",
  "field_normalization": "snake_case",
  "field_order": "alphabetical_column_name",
  "high_water_mark_attributes": {
    "use_high_water_mark_diff_type": true,
    "column_name": "updated_at"
  },
  "validate_only": true,
  "failed_run_notifications_enabled": false,
  "failed_record_notifications_enabled": false,
  "failed_record_notifications_threshold_percent": 10
}'
{
  "status": "created",
  "data": {
    "sync_id": 4545
  }
}

Authorizations

​
Authorization
string
header
required

Bearer token for the current workspace. Can be retrieved from the Workspace's settings page.

Body

application/json
​
operation
enum<string>
required

How records are synced to the destination.

Available options:
append,
insert,
mirror,
update,
upsert
Example:

"mirror"

​
source_attributes
object
required

Attributes used to identify the data source for this sync.

​
destination_attributes
object
required
​
mappings
object[]
required
Example:
[
  {
    "from": { "type": "column", "data": "hashed_email" },
    "to": "user_identifier.hashed_email_PREHASHED",
    "is_primary_identifier": true
  },
  {
    "from": { "type": "column", "data": "list_id" },
    "to": "list_id",
    "lookup_object": "user_list",
    "lookup_field": "name"
  },
  {
    "from": {
      "type": "constant_value",
      "data": { "value": "cohort_1", "basic_type": "text" }
    },
    "to": "cohort"
  }
]
​
label
string

A label to give to this sync.

Example:

"New Signups to Leads"

​
alert_attributes
object[]
Example:
[
  {
    "type": "FailureAlertConfiguration",
    "send_for": "first_time",
    "should_send_recovery": true,
    "options": null
  },
  {
    "type": "InvalidRecordPercentAlertConfiguration",
    "send_for": "every_time",
    "should_send_recovery": false,
    "options": { "threshold": 10 }
  }
]
​
advanced_configuration
object

Set of key-value pairs that describe advanced configuration options for specific destination object types. See the specific destination's documentation for more information on available options.

Example:
{
  "data_source_country": "US, GB",
  "bulk_id_lookup": true
}
​
mode
object

Specify run mode for the sync.

​
paused
boolean

Whether or not this sync should be paused.

Example:

false

​
field_behavior
enum<string>

Specify "sync_all_properties" to automatically update mappings.

Available options:
sync_all_properties,
specific_properties
​
field_normalization
enum<string>

If field_behavior is set to "sync_all_properties", specify how automatic mappings should be named.

Available options:
start_case,
lower_case,
upper_case,
camel_case,
snake_case,
match_source_names
Example:

"snake_case"

​
field_order
enum<string>

Specify how the destination fields should be ordered. The default behavior is alphabetically by column name. Only allowed to be set on syncs with destination objects that allow field ordering. Refer to GET /destinations/{destination_id}/objects to see if the supports_field_ordering is present on your destination object.

Available options:
alphabetical_column_name,
mapping_order
Example:

"alphabetical_column_name"

​
high_water_mark_attributes
object

The high water mark diffing strategy will allow append syncs to use a timestamp column when identifying new records instead of the default Census diff engine (using primary keys).

​
validate_only
boolean
default:false

When true, checks if the given payload is valid to configure a sync. Does not create the sync.

Example:

true

​
failed_run_notifications_enabled
boolean
default:true
deprecated

When true, will email all workspace users with email notifications enabled and all workspace additional emails when the sync fails and recovers. DEPRECATION WARNING -- This field will soon be deprecated in favor of the alert_attributes object. If both this field and the alert_attributes object are present, the alert_attributes object will take precedence.

Example:

false

​
failed_record_notifications_enabled
boolean
default:true
deprecated

When true, will email all workspace users with email notifications enabled and all workspace additional emails when the sync has more than failed_record_notifications_threshold_percent rejected or invalid records in the source or destination. DEPRECATION WARNING -- This field will soon be deprecated in favor of the alert_attributes object. If both this field and the alert_attributes object are present, the alert_attributes object will take precedence.

Example:

false

​
failed_record_notifications_threshold_percent
integer
default:75
deprecated

The percentage of rejected and invalid records for which failed record emails will be triggered. DEPRECATION WARNING -- This field will soon be deprecated in favor of the alert_attributes object. If both this field and the alert_attributes object are present, the alert_attributes object will take precedence.

Required range: 0 <= x <= 100
Example:

10

Response

201 - application/json
Sync created successfully
​
status
enum<string>

Outcome of the operation.

Available options:
success,
updated,
created,
not_found,
error
Example:

"created"

​
data
object

Was this page helpful?

Raise issue
List SyncsFetch sync