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.

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

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

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 `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: `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.

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.

Response Property	Description
status	`deleted` or `404` indicating whether the sync was found and deleted.

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.

Management API

Sync Runs

Last modified 26d ago