Skip to main content
POST
/
syncs
Create a new sync
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",
  "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",
  "sync_behavior_family": "activateEvents",
  "high_water_mark_attribute": "updated_at",
  "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,
  "historical_sync_operation": "backfill_all_records",
  "mirror_strategy": "sync_updates_and_deletes",
  "source_attributes": {
    "connection_id": 12,
    "object": {
      "type": "dataset",
      "id": 123
    }
  }
}'
{
  "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"

​
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"
  }
]
​
source_attributes
object
required

Source attributes Table source

  • Table source
  • Dataset source
  • Model source
  • Topic source
  • Segment source
  • Cohort source
​
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"

​
sync_behavior_family
enum<string>

Specifies the behavior family for the sync. Use activateEvents for event-based activation syncs (only supported for live syncs from Kafka/streaming sources). Use mapRecords for record mapping syncs (not supported for live syncs from Materialize).

Available options:
activateEvents,
mapRecords
Example:

"activateEvents"

​
high_water_mark_attribute
string

The name of the timestamp column to use for the high water mark diffing strategy. When set, append syncs will use this column to identify new records instead of the default Census diff engine (using primary keys).

Example:

"updated_at"

​
high_water_mark_attributes
object
deprecated

DEPRECATED: Use high_water_mark_attribute instead. This field will be removed in a future version.

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

​
historical_sync_operation
enum<string>

Specifies how the first sync should handle historical records when using append operation. Only applicable for append syncs.

Available options:
skip_current_records,
backfill_all_records
Example:

"backfill_all_records"

​
mirror_strategy
enum<string>

Specifies the strategy for mirror syncs. Only applicable when operation is set to mirror. The strategy determines how Census keeps the destination in sync with the source data.

  • sync_updates_and_deletes: Incrementally syncs changes by inserting new records, updating modified records, and deleting records that no longer exist in the source. This is the most common and efficient strategy for keeping destinations in sync.
  • sync_updates_and_nulls: Similar to sync_updates_and_deletes but handles null values explicitly. Updates existing records and sets fields to null when the source contains null values, without performing deletes.
  • upload_and_swap: Replaces the entire destination table with the current source snapshot. This strategy is useful for destinations that don't support incremental updates or when you want to ensure a complete refresh of all data.
Available options:
sync_updates_and_nulls,
upload_and_swap,
sync_updates_and_deletes
Example:

"sync_updates_and_deletes"

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