Introduction
Organization APIs
- Users
- Invitations
- Workspaces
Workspace APIs
- Syncs
- Sync Management Links
- Sync Runs
- Destination Types
- Destinations
- Destination Connect Links
- Source Types
- Sources
- Source Connect Links
- Segment Management Links
List Syncs
curl --request GET \
--url https://app.getcensus.com/api/v1/syncs \
--header 'Authorization: Bearer <token>'{
"status": "success",
"pagination": {
"total_records": 14,
"per_page": 25,
"prev_page": 1,
"page": 2,
"next_page": 3,
"last_page": 10
},
"data": [
{
"status": "ready",
"id": 15135,
"created_at": "2023-09-05T19:42:42.672Z",
"updated_at": "2023-09-05T19:42:42.672Z",
"match_rate_details": {
"match_rate": 0.5,
"match_rate_last_calculated_at": "2023-09-05T19:42:42.672Z"
},
"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
}
]
}Authorizations
Bearer token for the current workspace. Can be retrieved from the Workspace's settings page.
Query Parameters
Designates which page of results to return. Always starts at 1. If 0 is specified, it defaults to 1.
Determines the number of results on each page. It can't exceed 100.
x <= 100Organizes the results based on their creation time, either ascending or descending.
asc, desc Response
A successfully fetched list of results.
The outcome of the request
success "success"
An object to help you navigate the list of results.
Total records in the collection.
14
Records on each page.
25
The previous page number, or null for the first page.
1
The current page number.
2
The next page number, or null if it's the last page.
3
The number of the last page with records.
10
The list of results.
How records are synced to the destination.
append, insert, mirror, update, upsert "mirror"
Attributes used to identify the data source for this sync.
The id used to identify the source connection.
Table source
The type of your data source.
table The name of the table
"events"
The schema of the table
"publish"
The catalog of the table
"data_mart"
An object representing the source of the mapping. It will either be an object describing a column or a constant value.
constant_value Indicates if null values in the source should be synced to the destination.
[
{
"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"
}
]
The sync's current status. Ready means that the sync has not yet run, up to date implies the last sync completed successfully and failing means that the sync failed.
ready, up to date, failing The identifier for the sync.
15135
The time the sync was created.
"2023-09-05T19:42:42.672Z"
The time the sync was updated.
"2023-09-05T19:42:42.672Z"
Details about the match rate for this sync. Only applies to syncs created from segments to Ad Platforms via our One Click Sync capability.
The total size of your audience in the destination divided by the total size of the sync's source. Read more on Audience match rates here. Can be null if audience size data has not been fetched yet, or if the size of the source data is 0.
0.5
The last time audience size data was fetched to calculate the match rate. Audience data is fetched daily. Can be null if audience size data has not been fetched yet.
"2023-09-05T19:42:42.672Z"
A label to give to this sync.
"New Signups to Leads"
FailureAlertConfiguration, InvalidRecordPercentAlertConfiguration, FullSyncTriggerAlertConfiguration, RecordCountDeviationAlertConfiguration, RuntimeAlertConfiguration, StatusAlertConfiguration first_time, every_time FailureAlertConfiguration -- has no options
[
{
"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 }
}
]
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.
{
"data_source_country": "US, GB",
"bulk_id_lookup": true
}
Specify run mode for the sync.
Defines mode type, can be either live or triggered.
live, triggered "triggered"
Specify triggers for the sync. More than one type trigger can be configured.
Contains the dbt Cloud job details that should trigger the sync upon success. dbt Cloud project and job IDs can be found in the URL when navigating to a job in the dbt Cloud application or via API.
The Fivetran job details that should trigger the sync upon success. 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.
The sync details that should trigger the sync upon success. The sync id can be found via the API or in the URL within the Census management UI.
The dependent sync id.
123
Specify schedule for the sync.
When this sync should be run.
never, continuous, quarter_hourly, hourly, daily, weekly, expression "daily"
What day of the week this sync should run if schedule_frequency is set to "weekly".
Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday "Monday"
What hour of the day this sync should run if schedule_frequency is set to "weekly" or "daily".
0 <= x <= 2410
What minute of the hour this sync should run if scheule_frequency is set to "weekly", "daily" or "hourly".
0 <= x <= 5930
Specify what cron schedule this sync should run on if the schedule_frequency is set to "experessions".
"* 1 * * *"
{
"schedule": {
"frequency": "daily",
"hour": 10,
"minute": 30
}
}
Whether or not this sync should be paused.
false
Specify "sync_all_properties" to automatically update mappings.
sync_all_properties, specific_properties If field_behavior is set to "sync_all_properties", specify how automatic mappings should be named.
start_case, lower_case, upper_case, camel_case, snake_case, match_source_names "snake_case"
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.
alphabetical_column_name, mapping_order "alphabetical_column_name"
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).
When true, checks if the given payload is valid to configure a sync. Does not create the sync.
true
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.
false
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.
false
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.
0 <= x <= 10010
Was this page helpful?
curl --request GET \
--url https://app.getcensus.com/api/v1/syncs \
--header 'Authorization: Bearer <token>'{
"status": "success",
"pagination": {
"total_records": 14,
"per_page": 25,
"prev_page": 1,
"page": 2,
"next_page": 3,
"last_page": 10
},
"data": [
{
"status": "ready",
"id": 15135,
"created_at": "2023-09-05T19:42:42.672Z",
"updated_at": "2023-09-05T19:42:42.672Z",
"match_rate_details": {
"match_rate": 0.5,
"match_rate_last_calculated_at": "2023-09-05T19:42:42.672Z"
},
"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
}
]
}