Update a sync

PATCH

syncs

{sync_id}

curl --request PATCH \
  --url https://app.getcensus.com/api/v1/syncs/{sync_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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
}'

{
  "status": "updated",
  "data": {
    "id": 90967,
    "email": "newuser@example.com",
    "created_at": "2023-09-22T20:25:45.185Z",
    "created_by_id": 13,
    "claimed_at": "2023-09-22T20:25:45.185Z",
    "claimed_by_id": 11,
    "role": "admin",
    "associated_workspace_invitations": [
      {
        "id": 90967,
        "workspace_id": 1234,
        "role": "Viewer"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

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

Path Parameters

sync_id

integer

required

ID of the sync

Body

application/json

operation

enum<string>

required

How records are synced to the destination.

Available options:

append,

insert,

mirror,

update,

upsert

Example:

"mirror"

source_attributes

object

required

Attributes used to identify the data source for this sync.

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

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.

mode.type

enum<string>

Defines mode type, can be either live or triggered.

Available options:

live,

triggered

Example:

"triggered"

mode.triggers

object

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

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.

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.

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.

mode.triggers.schedule

object

Specify schedule for the sync.

Example:

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

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"

high_water_mark_attributes

object

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

Response

200

application/json

Successfully updated the sync

status

enum<string>

required

The outcome of the update request

Available options:

updated

Example:

"updated"

data

object

required

Fetch sync Delete a sync

curl --request PATCH \
  --url https://app.getcensus.com/api/v1/syncs/{sync_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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
}'

{
  "status": "updated",
  "data": {
    "id": 90967,
    "email": "newuser@example.com",
    "created_at": "2023-09-22T20:25:45.185Z",
    "created_by_id": 13,
    "claimed_at": "2023-09-22T20:25:45.185Z",
    "claimed_by_id": 11,
    "role": "admin",
    "associated_workspace_invitations": [
      {
        "id": 90967,
        "workspace_id": 1234,
        "role": "Viewer"
      }
    ]
  }
}

Introduction

Organization APIs

Workspace APIs

Authorizations

Path Parameters

Body

Response