Test a sync

Creates a test sync run to validate the sync configuration with the provided parameters. This allows you to test your sync setup before running a full sync. Use the fetch test sync run status endpoint to get updates on the sync status.

Request schema

Header parameters

Authorization

stringrequired

HTTP: basicAuth

HTTP AuthorizationScheme: basic

Request

label

string

A label to give to this sync.

example:

New Signups to Leads

operation

stringrequired

How records are synced to the destination.

enum:

"append""insert""mirror""update""upsert"

destination_attributes

objectrequired

connection_id

integer

The id used to identify the destination connection.

object

string

The full name of the destination object.

lead_union_insert_to

string

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

alert_attributes

array

type

stringrequired

enum:

"FailureAlertConfiguration""InvalidRecordPercentAlertConfiguration""FullSyncTriggerAlertConfiguration""RecordCountDeviationAlertConfiguration""RuntimeAlertConfiguration""StatusAlertConfiguration"

send_for

stringrequired

enum:

"first_time""every_time"

should_send_recovery

booleanrequired

options

objectrequired

FailureAlertConfiguration -- has no options

InvalidRecordPercentAlertConfiguration

threshold

integer

The percentage of invalid/rejected records that will trigger an alert.

maximum:

100

FullSyncTriggerAlertConfiguration -- has no options

RecordCountDeviationAlertConfiguration

threshold

integer

The percentage of deviation from the expected record count that will trigger an alert.

maximum:

100

record_type

string

The type of record count to monitor. Options include:

source_record_count: Records in source.
records_updates: Records changed in source.
records_deletes: Records deleted in source.
records_invalid: Records invalid in source.
records_processed: Records sent to destination.
records_updated: Records accepted by destination.
records_failed: Records rejected by destination.

enum:

"source_record_count""records_updates""records_deletes""records_invalid""records_processed""records_updated""records_failed"

units_in_past

integer

The number of sync runs in the past to compare against.

minimum:

maximum:

RuntimeAlertConfiguration

unit

string

The unit of time to use for the threshold.

enum:

"minutes""hours"

threshold

integer

The number of minutes/hours that the sync must run before triggering an alert.

start_type

string

Which time to evaluate the threshold against.

enum:

"actual""scheduled"

StatusAlertConfiguration

status_name

string

The status to trigger an alert on.

enum:

"started""completed"

mappings

arrayrequired

from

objectrequired

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

type

string

enum:

"constant_value"

data

object

basic_type

string

The type of the constant value.

enum:

"boolean""datetime""number""text"

value

string

A representation of the constant value.

type

string

enum:

"column"

data

string

The name of the column

type

string

enum:

"liquid_template"

data

object

liquid_template

string

A liquid template string used to format the data.

example:

stringrequired

The name of the destination field to map to.

is_primary_identifier

booleanrequired

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

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.

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.

operation

string

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

lookup_object

string

For reference mappings, the name of the related object to look up. Used in conjunction with lookup_field for relationship 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.

sync_null_values

boolean

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

default:

true

field_type

string

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

array_field

boolean

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

follow_source_type

boolean

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

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 }

mode

object

Specify run mode for the sync.

type

string

Defines mode type, can be either live or triggered.

enum:

"live""triggered"

triggers

object

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

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.

project_id

string

The dbt Cloud project id.

example:

12345

job_id

string

The dbt Cloud job id.

example:

123456

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.

job_id

string

The Fivetran job id.

example:

test_job_id

job_name

string

The Fivetran job name.

example:

test_job_name

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.

sync_id

integer

The dependent sync id.

example:

123

schedule

object

Specify schedule for the sync.

frequency

string

When this sync should be run.

enum:

"never""continuous""quarter_hourly""hourly""daily""weekly""expression"

day

string

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

enum:

"Sunday""Monday""Tuesday""Wednesday""Thursday""Friday""Saturday"

hour

integer

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

maximum:

example:

minute

integer

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

maximum:

example:

cron_expression

string

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

example:

* 1 * * *

paused

boolean

Whether or not this sync should be paused.

field_behavior

string

Specify "sync_all_properties" to automatically update mappings.

enum:

"sync_all_properties""specific_properties"

field_normalization

string

If field_behavior is set to "sync_all_properties", specify how automatic mappings should be named.

enum:

"start_case""lower_case""upper_case""camel_case""snake_case""match_source_names"

field_order

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.

enum:

"alphabetical_column_name""mapping_order"

sync_behavior_family

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

enum:

"activateEvents""mapRecords"

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

use_high_water_mark_diff_type

booleanrequired

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

example:

true

column_name

string

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

example:

updated_at

validate_only

boolean

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

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.

deprecated:

true

default:

true

failed_record_notifications_enabled

boolean

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.

deprecated:

true

default:

true

failed_record_notifications_threshold_percent

integer

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.

deprecated:

true

default:

maximum:

100

example:

historical_sync_operation

string

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

enum:

"skip_current_records""backfill_all_records"

mirror_strategy

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.

enum:

"sync_updates_and_nulls""upload_and_swap""sync_updates_and_deletes"

source_attributes

objectrequired

Source attributes

Table source

connection_id

integerrequired

The id used to identify the source connection.

example:

123

object

Table source

type

stringrequired

The type of your data source.

enum:

"table"

table_name

stringrequired

The name of the table

example:

events

table_schema

stringrequired

The schema of the table

example:

publish

table_catalog

stringrequired

The catalog of the table

example:

data_mart

Dataset source

object

objectrequired

Dataset source

type

stringrequired

The type of your data source.

default:

dataset

enum:

"dataset"

integerrequired

The id of the dataset

example:

1543

Model source

object

objectrequired

Model source

type

stringrequired

The type of your data source.

default:

model

enum:

"model"

integer

The id of the model. Required if name not provided

example:

1543

name

string

The name of the model. Required if id not provided

example:

New Signups

Topic source

object

objectrequired

Topic source

type

stringrequired

The type of your data source.

default:

topic

enum:

"topic"

integer

The id of the topic. Required if name not provided

example:

1543

name

string

The name of the topic. Required if id not provided

example:

New Signups

Segment source

object

objectrequired

Dataset source

type

stringrequired

The type of your data source.

default:

dataset

enum:

"dataset"

integerrequired

The id of the dataset

example:

1543

filter_segment_id

integerrequired

The id of the filter segment source of this sync. When creating a sync from a segment, the dataset source information should be specified in the object payload.

Cohort source

object

objectrequired

Dataset source

type

stringrequired

The type of your data source.

default:

dataset

enum:

"dataset"

integerrequired

The id of the dataset

example:

1543

cohort_id

integerrequired

The id of the cohort source of this sync. When creating a sync from a cohort, the dataset source information should be specified in the object payload.

Http + 1.1

POST

https://app.getcensus.com/api/v1/syncs/test

POST /api/v1/syncs/test HTTP/1.1
Authorization: Bearer REPLACE_BEARER_TOKEN
Content-Type: application/json
Host: app.getcensus.com
Content-Length: 2409

{
  "label": "New Signups to Leads",
  "operation": "mirror",
  "destination_attributes": {
    "connection_id": 0,
    "object": "string",
    "lead_union_insert_to": "string"
  },
  "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"
    },
    {
      "from": {
        "type": "liquid_template",
        "data": {
          "liquid_template": "{{ record['first_name'] }} {{ record['last_name'] }}"
        }
      },
      "to": "full_name"
    }
  ],
  "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": 123,
    "object": {
      "type": "table",
      "table_name": "events",
      "table_schema": "publish",
      "table_catalog": "data_mart"
    }
  }
}

Responses

200

Test sync run created successfully.

`200`

sync_run_id

integer

ID of the created test sync run

example:

1234567890

{
  "sync_run_id": 1234567890
}