List Syncs

Authorizations

Authorization

string

header

required

Bearer token for the current workspace. Can be retrieved from the Workspace's settings page.

Query Parameters

page

number

default:1

Designates which page of results to return. Always starts at 1. If 0 is specified, it defaults to 1.

per_page

number

default:25

Determines the number of results on each page. It can't exceed 100.

Required range: x <= 100

order

enum<string>

default:desc

Organizes the results based on their creation time, either ascending or descending.

Available options:

asc,

desc

Response

200 - application/json

Successfully retrieved the list of syncs.

A successfully fetched list of results.

status

enum<string>

required

The outcome of the request

Available options:

success

Example:

"success"

pagination

object

required

An object to help you navigate the list of results.

Show child attributes

pagination.total_records

number

Total records in the collection.

Example:

14

pagination.per_page

number

default:25

Records on each page.

Example:

25

pagination.prev_page

number | null

The previous page number, or null for the first page.

Example:

1

pagination.page

number

default:1

The current page number.

Example:

2

pagination.next_page

number | null

The next page number, or null if it's the last page.

Example:

3

pagination.last_page

number

The number of the last page with records.

Example:

10

data

object[]

required

The list of results.

Show child attributes

data.operation

enum<string>

required

How records are synced to the destination.

Available options:

append,

insert,

mirror,

update,

upsert

Example:

"mirror"

data.destination_attributes

object

required

Show child attributes

data.destination_attributes.connection_id

integer

The id used to identify the destination connection.

data.destination_attributes.object

string

The full name of the destination object.

data.destination_attributes.lead_union_insert_to

string

Where to insert a union object (for Salesforce connections).

Example:

{
  "connection_id": 15,
  "object": "user_data"
}

data.mappings

object[]

required

Show child attributes

data.mappings.from

object

required

An object representing the source of the mapping. It will either be an object describing a column or a constant value.

Option 1
Option 2
Option 3

Show child attributes

data.mappings.from.type

enum<string>

Available options:

constant_value

data.mappings.from.data

object

Show child attributes

data.mappings.from.data.basic_type

enum<string>

The type of the constant value.

Available options:

boolean,

datetime,

number,

text

data.mappings.from.data.value

string

A representation of the constant value.

data.mappings.to

string

required

The name of the destination field to map to.

data.mappings.is_primary_identifier

boolean

required

Whether this mapping is used as the primary identifier (sync key) for matching records between source and destination.

data.mappings.generate_field

boolean

Whether to create a new user-defined field in the destination. When true, the field will be created if it doesn't exist.

data.mappings.preserve_values

boolean

Whether to preserve existing values in the destination field when the source value is null or empty. When true, existing values are not overwritten.

data.mappings.operation

string

The operation to perform for array fields (e.g., "append", "set"). Only applicable when the destination field is an array type.

data.mappings.lookup_object

string

For reference mappings, the name of the related object to look up. Used in conjunction with lookup_field for relationship mappings.

data.mappings.lookup_field

string

For reference mappings, the field on the related object to use for matching. This field must be an ID or External ID field.

data.mappings.sync_null_values

boolean

default:true

Indicates if null values in the source should be synced to the destination.

data.mappings.field_type

string

The type of the destination field. Only present for user-defined fields (when generate_field is true).

data.mappings.array_field

boolean

Whether the destination field is an array type. Only present for user-defined fields (when generate_field is true).

data.mappings.follow_source_type

boolean

Whether the destination field type should automatically follow changes to the source column type.

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"
  }
]

data.source_attributes

Table source · object

required

Attributes used to identify the data source for this sync. Table source

Table source
Dataset source
Segment source
Cohort source
Topic source
Model source

Show child attributes

data.source_attributes.connection_id

integer

required

The id used to identify the source connection.

data.source_attributes.object

object

required

Show child attributes

data.source_attributes.object.type

enum<string>

required

The type of your data source.

Available options:

table

data.source_attributes.object.table_name

string

required

The name of the table

Example:

"events"

data.source_attributes.object.table_schema

string

required

The schema of the table

Example:

"publish"

data.source_attributes.object.table_catalog

string

required

The catalog of the table

Example:

"data_mart"

Example:

{
  "connection_id": 12,
  "object": {
    "type": "table",
    "table_catalog": "prod",
    "table_schema": "public",
    "table_name": "users"
  }
}

data.status

enum<string>

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.

Available options:

ready,

up to date,

failing

data.id

integer

The identifier for the sync.

Example:

15135

data.created_at

string<date-time>

The time the sync was created.

Example:

"2023-09-05T19:42:42.672Z"

data.updated_at

string<date-time>

The time the sync was updated.

Example:

"2023-09-05T19:42:42.672Z"

data.match_rate_details

object

Details about the match rate for this sync. Only applies to syncs created from segments to Ad Platforms via our One Click Sync capability.

Show child attributes

data.match_rate_details.match_rate

number<float> | null

required

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.

Example:

0.5

data.match_rate_details.match_rate_last_calculated_at

string<date-time> | null

required

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.

Example:

"2023-09-05T19:42:42.672Z"

data.label

string

A label to give to this sync.

Example:

"New Signups to Leads"

data.alert_attributes

object[]

Show child attributes

data.alert_attributes.type

enum<string>

required

Available options:

FailureAlertConfiguration,

InvalidRecordPercentAlertConfiguration,

FullSyncTriggerAlertConfiguration,

RecordCountDeviationAlertConfiguration,

RuntimeAlertConfiguration,

StatusAlertConfiguration

data.alert_attributes.send_for

enum<string>

required

Available options:

first_time,

every_time

data.alert_attributes.should_send_recovery

boolean

required

data.alert_attributes.options

object

required

FailureAlertConfiguration -- has no options

Option 1
Option 2
Option 3
Option 4
Option 5
Option 6

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 }
  }
]

data.advanced_configuration

object

Set of key-value pairs that describe advanced configuration options for specific destination object types. See the advanced_configuration_field_definitions attribute of the destination object response for specific available advanced configuration options.

Example:

{
  "data_source_country": "US, GB",
  "bulk_id_lookup": true
}

data.mode

object

Specify run mode for the sync.

Show child attributes

data.mode.type

enum<string>

Defines mode type, can be either live or triggered.

Available options:

live,

triggered

Example:

"triggered"

data.mode.triggers

object

Specify triggers for the sync. More than one type trigger can be configured.

Show child attributes

data.mode.triggers.dbt_cloud

object

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.

Show child attributes

data.mode.triggers.dbt_cloud.project_id

string

The dbt Cloud project id.

Example:

"12345"

data.mode.triggers.dbt_cloud.job_id

string

The dbt Cloud job id.

Example:

"123456"

data.mode.triggers.fivetran

object

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.

Show child attributes

data.mode.triggers.fivetran.job_id

string

The Fivetran job id.

Example:

"test_job_id"

data.mode.triggers.fivetran.job_name

string

The Fivetran job name.

Example:

"test_job_name"

data.mode.triggers.sync_sequence

object

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.

Show child attributes

data.mode.triggers.sync_sequence.sync_id

integer

The dependent sync id.

Example:

123

data.mode.triggers.schedule

object

Specify schedule for the sync.

Show child attributes

data.mode.triggers.schedule.frequency

enum<string>

When this sync should be run.

Available options:

never,

continuous,

quarter_hourly,

hourly,

daily,

weekly,

expression

Example:

"daily"

data.mode.triggers.schedule.day

enum<string>

What day of the week this sync should run if schedule_frequency is set to "weekly".

Available options:

Sunday,

Monday,

Tuesday,

Wednesday,

Thursday,

Friday,

Saturday

Example:

"Monday"

data.mode.triggers.schedule.hour

integer

What hour of the day this sync should run if schedule_frequency is set to "weekly" or "daily".

Required range: 0 <= x <= 24

Example:

10

data.mode.triggers.schedule.minute

integer

What minute of the hour this sync should run if schedule_frequency is set to "weekly", "daily" or "hourly".

Required range: 0 <= x <= 59

Example:

30

data.mode.triggers.schedule.cron_expression

string

Specify what cron schedule this sync should run on if the schedule_frequency is set to "expression".

Example:

"* 1 * * *"

Example:

{
  "schedule": {
    "frequency": "daily",
    "hour": 10,
    "minute": 30
  }
}

data.paused

boolean

Whether or not this sync should be paused.

Example:

false

data.field_behavior

enum<string>

Specify "sync_all_properties" to automatically update mappings.

Available options:

sync_all_properties,

specific_properties

data.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"

data.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"

data.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"

data.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"

data.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).

Show child attributes

data.high_water_mark_attributes.use_high_water_mark_diff_type

boolean

required

If true, the high water mark diff strategy will be used.

Example:

true

data.high_water_mark_attributes.column_name

string

The name of the column that should be used for identifying new records.

Example:

"updated_at"

data.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

data.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

data.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

data.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

data.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"

data.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"

Introduction

Organization APIs

Workspace APIs

Authorizations

Query Parameters

Response