Links

Syncs

GET /syncs

This endpoint returns a list of your syncs.
See Pagination for standard URL parameters and response data.
Request
Response
curl 'https://app.getcensus.com/api/v1/syncs' \
--header 'Authorization: Bearer [API_TOKEN]'
{
"status": "success",
"data": [
{
"id": 61,
"label": null,
"schedule_frequency": "never",
"schedule_day": null,
"schedule_hour": null,
"schedule_minute": null,
"cron_expression": null,
"created_at": "2021-10-22T00:40:11.246Z",
"updated_at": "2021-10-22T00:43:44.173Z",
"operation": "upsert",
"paused": false,
"status": "Ready",
"lead_union_insert_to": null,
"field_behavior": "specific_properties",
"field_normalization": null,
"mirror_strategy": null,
"failed_run_notifications_enabled": true,
"failed_record_notifications_enabled": true,
"failed_record_notifications_threshold_percent": 75
"source_attributes": {
"connection_id": 4,
"object": {
"type": "model",
"id": 15,
"name": "braze_test",
"created_at": "2021-10-11T20:52:58.293Z",
"updated_at": "2021-10-14T23:15:18.508Z",
"query": "select cast('[email protected]' as VARCHAR(2000)) as email, cast('random' as VARCHAR(2000)) as random_prop"
}
},
"destination_attributes": {
"connection_id": 15,
"object": "user"
},
"triggers": {
"dbt_cloud": {
"project_id": "12345",
"job_id": "123456"
},
"fivetran": {
"job_id": "test_job_id",
"job_name": "test_job_name"
}
},
"mappings": [
{
"from": {
"type": "column",
"data": "EMAIL"
},
"to": "external_id",
"is_primary_identifier": true,
"generate_field": false,
"preserve_values": false,
"operation": null
},
{
"from": {
"type": "constant_value",
"data": {
"value": "test",
"basic_type": "text"
}
},
"to": "first_name",
"is_primary_identifier": false,
"generate_field": false,
"preserve_values": false,
"operation": null
}
]
},
{
"id": 60,
"label": null,
"schedule_frequency": "never",
"schedule_day": null,
"schedule_hour": null,
"schedule_minute": null,
"cron_expression": null,
"created_at": "2021-10-22T00:38:32.191Z",
"updated_at": "2021-10-22T00:43:47.858Z",
"operation": "upsert",
"paused": false,
"status": "Ready",
"lead_union_insert_to": null,
"field_behavior": "specific_properties",
"field_normalization": null,
"mirror_strategy": null,
"failed_run_notifications_enabled": true,
"failed_record_notifications_enabled": true,
"failed_record_notifications_threshold_percent": 75
"source_attributes": {
"connection_id": 4,
"object": {
"type": "model",
"id": 15,
"name": "braze_test",
"created_at": "2021-10-11T20:52:58.293Z",
"updated_at": "2021-10-14T23:15:18.508Z",
"query": "select cast('[email protected]' as VARCHAR(2000)) as email, cast('random' as VARCHAR(2000)) as random_prop"
}
},
"destination_attributes": {
"connection_id": 15,
"object": "user"
},
"mappings": [
{
"from": {
"type": "column",
"data": "EMAIL"
},
"to": "external_id",
"is_primary_identifier": true,
"generate_field": false,
"preserve_values": false,
"operation": null
},
{
"from": {
"type": "constant_value",
"data": {
"value": "usa",
"basic_type": "text"
}
},
"to": "country",
"is_primary_identifier": false,
"generate_field": false,
"preserve_values": false,
"operation": null
}
]
}
],
"next": "https://app.getcensus.com/api/v1/syncs?page=2&per_page=2",
"pagination": {
"total_records": 4,
"per_page": 2,
"prev_page": null,
"page": 1,
"next_page": 2,
"last_page": 2
}
}
Data Property
Description
A list of syncs
A list of your syncs. The properties of a sync are expanded on below in the POST /syncs endpoint.
Along with the properties mentioned above, this endpoint returns an id, created_at, updated_at, and status for each sync. Possible values for the status property: - "Ready": no sync history
- "Up to Date": last sync completed - "Failing": last sync failed

GET /syncs/[ID]

This endpoint returns information on a specific sync.
Request
Response
curl 'https://app.getcensus.com/api/v1/syncs/[ID]' \
--header 'Authorization: Bearer [API_TOKEN]'
{
"status": "success",
"data": {
"id": 61,
"label": null,
"schedule_frequency": "never",
"schedule_day": null,
"schedule_hour": null,
"schedule_minute": null,
"cron_expression": null,
"created_at": "2021-10-22T00:40:11.246Z",
"updated_at": "2021-10-22T00:43:44.173Z",
"operation": "upsert",
"paused": false,
"status": "Ready",
"lead_union_insert_to": null,
"field_behavior": "specific_properties",
"field_normalization": null,
"mirror_strategy": null,
"failed_run_notifications_enabled": true,
"failed_record_notifications_enabled": true,
"failed_record_notifications_threshold_percent": 75
"source_attributes": {
"connection_id": 4,
"object": {
"type": "model",
"id": 15,
"name": "braze_test",
"created_at": "2021-10-11T20:52:58.293Z",
"updated_at": "2021-10-14T23:15:18.508Z",
"query": "select cast('[email protected]' as VARCHAR(2000)) as email, cast('random' as VARCHAR(2000)) as random_prop"
}
},
"destination_attributes": {
"connection_id": 15,
"object": "user"
},
"triggers": {
"dbt_cloud": {
"project_id": "12345",
"job_id": "123456"
},
"fivetran": {
"job_id": "test_job_id",
"job_name": "test_job_name"
}
},
"mappings": [
{
"from": {
"type": "column",
"data": "EMAIL"
},
"to": "external_id",
"is_primary_identifier": true,
"generate_field": false,
"preserve_values": false,
"operation": null
},
{
"from": {
"type": "constant_value",
"data": {
"value": "test",
"basic_type": "text"
}
},
"to": "first_name",
"is_primary_identifier": false,
"generate_field": false,
"preserve_values": false,
"operation": null
}
]
}
}
Data Property
Description
A sync
Information on a sync. The properties of a sync are expanded on below in the POST /syncs endpoint.
Along with the properties mentioned above, this endpoint returns an id, created_at, updated_at, and status for the sync. Possible values for the status property: - "Ready": no sync history
- "Up to Date": last sync completed - "Failing": last sync failed

POST /syncs

This endpoint creates a sync with the given data.
Request
Response
curl --location --request POST 'https://app.getcensus.com/api/v1/syncs' \
--header 'Authorization: Bearer [API_TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
"label": "TEST 1",
"operation": "mirror",
"schedule_frequency": "daily",
"destination_attributes": {
"connection_id": 15,
"object": "user_data"
},
"source_attributes": {
"connection_id": 12,
"object": {
"type": "model",
"name": "test_ads"
}
},
"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"
}
]
}'
{
"status": "created",
"data": {
"sync_id": 4545
}
}
Request Property
Description
operation
required. How records are synced to the destination. Valid options:
  • append
  • insert
  • mirror
  • update
  • upsert
source_attributes
required. Attributes used to identify the data source for this sync. The specific properties are described below.
destination_attributes
required. Attributes used to identify the destination for this sync. The specific properties are described below.
mappings
required. A list of mappings between the source and destination. The specific properties are described below.
label
A label to give to this sync.
schedule_frequency
When this sync should be run. Valid options:
  • never
  • continuous
  • quarter_hourly
  • hourly
  • daily
  • weekly
  • expression
schedule_day
What day of the week this sync should run. Valid options:
  • Sunday
  • Monday
  • Tuesday
  • Wednesday
  • Thursday
  • Friday
  • Saturday
schedule_hour
What hour of the day this sync should run. Valid values are integers between 0 and 24 inclusive.
schedule_minute
What minute of the hour this sync should run. Valid values are integers between 0 and 59 inclusive.
cron_expression
If schedule_frequency is "expression", specify what cron schedule this sync should run on. Valid value is a string containing a cron expression, such as "* 1 * * *".
paused
Whether or not this sync should be paused.
triggers
Specify dbt Cloud job id and project id and/or Fivetran job id and job name to trigger Census syncs after dbt Cloud jobs and/or Fivetran syncs/transforms successfully complete. dbt Cloud project and job ids can be found in the URL when navigated to a job in the dbt Cloud application or via API. Fivetran job name can be found in the table of Connectors or Transformations via the Fivetran application and the job id can be found in the URL when navigated to the specific connector/transform details page. These information can also be retrieved via API.
field_behavior
Specify sync_all_properties to configure this to automatically update mappings when the source changes.
field_normalization
If sync_all_properties is specified, specify how you would like automatic mappings to be named. Valid options are:
  • start_case
  • lower_case
  • upper_case
  • camel_case
  • snake_case
  • match_source_names
high_water_mark_attributes
Attributes used to identify the sync type. Only valid for append operation and source warehouse SnowflakeThe specific properties are described below.
validate_only
When true, checks if the given payload is valid to configure a sync. Does not create the sync.
failed_run_notifications_enabled
When true, will email all workspace users with email notifications enabled and all workspace additional emails when the sync fails and recovers. Default is true.
failed_record_notifications_enabled
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. Default is true.
failed_record_notifications_threshold_percent
The percentage of rejected and invalid records for which failed record emails will be triggered. Default is 75. Accepts integer values between 0 and 100 (inclusive), where 0 will alert for any failed records.
Source Attribute
Description
connection_id
required. The id used to identify the source connection.
filter_segment_id
optional. The id used to identify the segment data source. If specified, you must define the object property defined immediately below with values for the segment's underlying model. Ie, "object": {"type": "model", "id": <model id>}.
object
required. Attributes of the data source. Properties are expanded on immediately below.
type
required. The type of your data source. Valid options:
  • table
  • model
id
required unless either the following are specified:
  • name
  • table_name, table_schema, and table_catalog
The id of the data source.
name
required if the type is model, and the id is not specified. The name of the model.
table_name
required if the type is table, and the id is not specified. The name of the table.
table_schema
required if the type is table, and the id is not specified. The schema of the table.
table_catalog
required if the type is table, and the id is not specified. The catalog of the table.
Destination Attribute
Description
connection_id
required. The id used to identify the destination connection
object
required. The full name of the destination object
lead_union_insert_to
Where to insert a union object (for Salesforce connections)
Mapping Attribute
Description
from
required. An object with a type and data for the source.
For hardcoded (i.e. constant) values:
  • type should be constant_value.
  • data is an object with two keys. 1. basic_type - The type of this value (can be boolean, datetime, number, or text). 2. value should be a constant value.
For columns from your model or table:
  • type should be column.
  • data is the name of the column.
to
required. The full name of the field to sync in to. When the mapping represents an append key, this should be set to 'unique_id'
is_primary_identifier
required to be true for exactly one mapping. Whether or not this mapping is the primary identifier for this sync.
generate_field
Whether or not this mapping generates a custom field.
preserve_values
Whether or not an existing destination value should be overwritten.
operation
For arrays, whether Census should merge or overwrite values.
lookup_object
For a reference field, the full name of the object it refers to.
lookup_field
For a reference field, the field to lookup the referenced object by.
High Water Mark Attribute
Description
use_high_water_mark_diff_type
true or false to indicate use of high water mark diff type sync. Only valid for append operation and source warehouse Snowflake
column_name
The name of the column in the source
Response Property
Description
status
created or error indicating whether the sync was triggered.
data
Present if successful. An object containing the sync_id
message
Present if error. Contains message describing the error.

PATCH /syncs/[ID]

This endpoint updates a sync with the given ID.
Request
Response
curl --request PATCH 'https://app.getcensus.com/api/v1/syncs/[ID]' \
--header 'Authorization: Bearer [API_TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
"label": "Test Sync (edited via API)",
"schedule_frequency": "daily",
"triggers": {
"dbt_cloud": {
"project_id": "12345",
"job_id": "123456"
}
},
"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"
}
]
}'
{
"status": "updated",
"data": {
"id": 61,
"label": "Test Sync (edited via API)",
"schedule_frequency": "daily",
"schedule_day": null,
"schedule_hour": 0,
"schedule_minute": 0,
"cron_expression": null,
"created_at": "2021-10-22T00:40:11.246Z",
"updated_at": "2021-10-22T00:43:44.173Z",
"operation": "upsert",
"paused": false,
"status": "Ready",
"lead_union_insert_to": null,
"field_behavior": "specific_properties",
"field_normalization": null,
"failed_run_notifications_enabled": true,
"failed_record_notifications_enabled": true,
"failed_record_notifications_threshold_percent": 75
"source_attributes": {
"connection_id": 4,
"object": {
"type": "model",
"id": 15,
"name": "braze_test",
"created_at": "2021-10-11T20:52:58.293Z",
"updated_at": "2021-10-14T23:15:18.508Z",
"query": "select cast('[email protected]' as VARCHAR(2000)) as email, cast('random' as VARCHAR(2000)) as random_prop"
}
},
"destination_attributes": {
"connection_id": 15,
"object": "user"
},
"mappings": [
{
"from": {
"type": "column",
"data": "hashed_email"
},
"to": "user_identifier.hashed_email_PREHASHED",
"is_primary_identifier": true
"generate_field": false,
"preserve_values": false,
"operation": null
},
{
"from": {
"type": "column",
"data": "list_id"
},
"to": "list_id",
"lookup_object": "user_list",
"lookup_field": "name"
"is_primary_identifier": false,
"generate_field": false,
"preserve_values": false,
"operation": null
},
{
"from": {
"type": "constant_value",
"data": {
"value": "cohort_1",
"basic_type": "text"
}
},
"to": "cohort",
"is_primary_identifier": false,
"generate_field": false,
"preserve_values": false,
"operation": null
}
]
}
}
Request Property
Description
Sync parameters
A list of parameters to update the sync with, similar to the request parameters for POST /syncs. The only parameters that cannot be updated are source_attributes, destination_attributes, and operation.
Response Property
Description
status
updated or error indicating whether the sync was updated.
data
Present if successful. Returns the same object as GET /syncs/[ID]
message
Present if error. Contains message describing the error.

DELETE /syncs/[ID]

This endpoint deletes a sync with the given ID.
Request
Response
curl --request DELETE 'https://app.getcensus.com/api/v1/syncs/96' \
--header 'Authorization: Bearer [API_TOKEN]'
{
"status": "deleted"
}
Response Property
Description
status
deleted or 404 indicating whether the sync was found and deleted.

POST /syncs/[ID]/trigger

This endpoint triggers a specific sync to run.
Request
Response
curl -X POST 'https://app.getcensus.com/api/v1/syncs/[ID]/trigger' \
--header 'Authorization: Bearer [API_TOKEN]'
{
"status": "success",
"data": {
"sync_run_id": 1234567890
}
}
URL Argument
Description
force_full_sync
If this trigger request should be a Full Sync, add force_full_sync=true to the request URL. Note that some sync configurations such as Append do not support full syncs.
Response Property
Description
status
success or error indicating whether the sync was triggered.
data
Present if successful. An object containing the sync_run_id
message
Present if error. Contains message describing the error.