Syncs
This endpoint returns a list of your syncs.
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 |
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 |
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:
|
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:
|
schedule_day | What day of the week this sync should run. Valid options:
|
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:
|
high_water_mark_attributes | Attributes used to identify the sync type. Only valid for append operation and source warehouse Snowflake The 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:
|
id | required unless either the following are specified:
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:
For columns from your model or table:
|
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. |
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. |
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. |
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. |
Last modified 26d ago