---
title: "Create Sync"
method: POST
path: "/api/syncs"
tags: ["Model Sync"]
---

# Create Sync

`POST /api/syncs`

Creates a new model sync.

Create a new sync from one or more models to a destination.

All of the functionality described in [the product
documentation](https://docs.polytomic.com/docs/sync-destinations) is
configurable via the API.

Guides:

- [Model sync (Reverse ETL) from Snowflake query to Salesforce](../../guides/code-examples/model-sync-reverse-etl-from-snowflake-query-to-salesforce)
- [Joined model sync from Postgres, Airtable, and Stripe to Hubspot](../../guides/code-examples/joined-model-sync-from-postgres-airtable-and-stripe-to-hubspot)

## Targets (Destinations)

Polytomic refers to a model sync's destination as the "target object", or
target. Target objects are identified by a connection ID and an object ID. You
can retrieve a list of all target objects for a connection using the [Get Target
Objects](../../api-reference/model-sync/targets/list) endpoint.

The `target` object in the request specifies information about the sync destination.

```json
"target": {
    "connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "object": "Users",
},
```

Some connections support additional configuration for targets. For example,
[Salesforce
connections](../../guides/configuring-your-connections/connections/salesforce#target)
support optionally specifying the ingestion API to use. The target specific
options are passed as `configuration`; consult the [integration
guides](../../guides/configuring-your-connections/overview)
for details about specific connection configurations.

### Creating a new target

Some integrations support creating a new target when creating a model sync. For
example, an ad audience or database table.

When creating a new target, `object` is omitted and `create` is specified
instead. The `create` property is an object containing integration specific
configuration for the new target.

```json
"target": {
    "connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "create": {
        "name": "New audience",
        "type": "user_audience"
    }
},
```

The [Get Target List](../../api-reference/model-sync/targets/list) endpoint returns information about whether
a connection supports target creation.

## Headers

- `X-Polytomic-Version` string

## Request body

- CreateSyncRequest
  - `active` boolean — Whether the sync is enabled and scheduled.
  - `encryption_passphrase` string — Passphrase for encrypting the sync data.
  - `fields` SyncField[], required — Fields to sync from source to destination.
    - `encryption_enabled` boolean — Whether the field should be encrypted.
    - `new` boolean — New is set to true if the target field should be created by Polytomic. This is not supported by all backends.
    - `override_value` string — Value to set in the target field; a mapping with an override value and no source is stored as an override field.
    - `source` Source
      - `field` string, required
      - `model_id` string, uuid, required
    - `sync_mode` string — Sync mode for the field; defaults to 'updateOrCreate'. If set to 'create', the field will not be synced if it already has a value. This is not supported by all backends.
    - `target` string, required — Target field ID the source field value will be written to.
  - `filter_logic` string — Logical expression to combine filters.
  - `filters` Filter[], nullable — Filters to apply to the source data.
    - `field` Source
      - `field` string, required
      - `model_id` string, uuid, required
    - `field_id` string — Model or Target field name to filter on.
    - `field_type` 'Model' | 'Target'
    - `function` 'Equality' | 'Inequality' | 'IsNull' | 'IsNotNull' | 'True' | 'False' | 'OnOrAfter' | 'OnOrBefore' | 'GreaterThan' | 'GreaterThanEqual' | 'LessThan' | 'LessThanEqual' | 'StringContains' | 'StringStartsWith' | 'StringEndsWith' | 'StringDoesNotContain' | 'StringDoesNotStartWith' | 'StringDoesNotEndWith' | 'StringOneOf' | 'StringNotOneOf' | 'Between' | 'ArrayContains' | 'ArrayDoesNotContain' | 'InTheLast' | 'RelativeOnOrBefore' | 'RelativeOnOrAfter' | 'StringLike' | 'StringNotLike' | 'StringMatchesTrimmed', required
    - `label` string
    - `value` string
  - `identity` Identity
    - `function` 'Equality' | 'ISubstring' | 'OneOf' | 'DomainMatch' | 'HostnameMatch', required
    - `new_field` boolean
    - `remote_field_type_id` string, nullable
    - `source` Source, required
      - `field` string, required
      - `model_id` string, uuid, required
    - `target` string, required
  - `mode` 'create' | 'update' | 'updateOrCreate' | 'replace' | 'append' | 'remove' | 'snapshot', required
  - `name` string, required
  - `only_enrich_updates` boolean — Whether to use enrichment models as a source of possible changes to sync. If true, only changes to the base models will cause a record to sync.
  - `organization_id` string, uuid, nullable — Organization ID for the sync; read-only with a partner key.
  - `override_fields` OverrideFieldInput[], nullable — Target fields which are set to a fixed value for every record, rather than mapped from a model field.
    - `encryption_enabled` boolean — Deprecated. Encryption is ignored for override fields.
    - `new` boolean — New is set to true if the target field should be created by Polytomic. This is not supported by all backends.
    - `override_value` string — Value written to the target field for every record; required unless a source is provided.
    - `source` Source
      - `field` string, required
      - `model_id` string, uuid, required
    - `sync_mode` string — Sync mode for the field; defaults to 'updateOrCreate'. If set to 'create', the field will not be synced if it already has a value. This is not supported by all backends.
    - `target` string, required — Target field ID the value will be written to.
  - `overrides` Override[], nullable — Conditional value replacement for fields.
    - `field` Source
      - `field` string, required
      - `model_id` string, uuid, required
    - `field_id` string — Field ID of the model field to override.
    - `function` 'Equality' | 'Inequality' | 'IsNull' | 'IsNotNull' | 'True' | 'False' | 'OnOrAfter' | 'OnOrBefore' | 'GreaterThan' | 'GreaterThanEqual' | 'LessThan' | 'LessThanEqual' | 'StringContains' | 'StringStartsWith' | 'StringEndsWith' | 'StringDoesNotContain' | 'StringDoesNotStartWith' | 'StringDoesNotEndWith' | 'StringOneOf' | 'StringNotOneOf' | 'Between' | 'ArrayContains' | 'ArrayDoesNotContain' | 'InTheLast' | 'RelativeOnOrBefore' | 'RelativeOnOrAfter' | 'StringLike' | 'StringNotLike' | 'StringMatchesTrimmed'
    - `override` string
    - `value` string
  - `policies` string[], nullable
  - `schedule` Schedule, required
    - `connection_id` string, uuid
    - `day_of_month` string, nullable
    - `day_of_week` string, nullable
    - `frequency` 'manual' | 'continuous' | 'hourly' | 'daily' | 'weekly' | 'custom' | 'builder' | 'runafter' | 'multi' | 'dbtcloud'
    - `hour` string, nullable
    - `job_id` integer, nullable
    - `minute` string, nullable
    - `month` string, nullable
    - `run_after` RunAfter
      - `bulk_sync_ids` string[]
      - `sync_ids` string[]
    - `run_after_success_only` boolean, nullable — If true, the sync will only run if the dependent syncs completed successfully.
  - `skip_initial_backfill` boolean — Whether to skip the initial backfill of records; if true only records seen after the sync is enabled will be synced.
  - `sync_all_records` boolean — Whether to sync all records from the source, regardless of whether they've changed since the previous execution.
  - `target` Target, required
    - `configuration` object
    - `connection_id` string, uuid, required
    - `create` object — Create a new target object with these properties.
    - `filter_logic` string
    - `new_name` string — Name for a new target object.
    - `object` string
    - `search_values` object

## Response `200`

OK

- SyncResponseEnvelope
  - `data` SyncResponse
    - `active` boolean
    - `created_at` string, date-time
    - `created_by` OutputActor
      - `id` string, uuid
      - `name` string
      - `type` string
    - `encryption_passphrase` string
    - `fields` SyncField[]
      - `encryption_enabled` boolean — Whether the field should be encrypted.
      - `new` boolean — New is set to true if the target field should be created by Polytomic. This is not supported by all backends.
      - `override_value` string — Value to set in the target field; a mapping with an override value and no source is stored as an override field.
      - `source` Source
        - `field` string, required
        - `model_id` string, uuid, required
      - `sync_mode` string — Sync mode for the field; defaults to 'updateOrCreate'. If set to 'create', the field will not be synced if it already has a value. This is not supported by all backends.
      - `target` string, required — Target field ID the source field value will be written to.
    - `filter_logic` string
    - `filters` Filter[]
      - `field` Source
        - `field` string, required
        - `model_id` string, uuid, required
      - `field_id` string — Model or Target field name to filter on.
      - `field_type` 'Model' | 'Target'
      - `function` 'Equality' | 'Inequality' | 'IsNull' | 'IsNotNull' | 'True' | 'False' | 'OnOrAfter' | 'OnOrBefore' | 'GreaterThan' | 'GreaterThanEqual' | 'LessThan' | 'LessThanEqual' | 'StringContains' | 'StringStartsWith' | 'StringEndsWith' | 'StringDoesNotContain' | 'StringDoesNotStartWith' | 'StringDoesNotEndWith' | 'StringOneOf' | 'StringNotOneOf' | 'Between' | 'ArrayContains' | 'ArrayDoesNotContain' | 'InTheLast' | 'RelativeOnOrBefore' | 'RelativeOnOrAfter' | 'StringLike' | 'StringNotLike' | 'StringMatchesTrimmed', required
      - `label` string
      - `value` string
    - `id` string, uuid
    - `identity` Identity
      - `function` 'Equality' | 'ISubstring' | 'OneOf' | 'DomainMatch' | 'HostnameMatch', required
      - `new_field` boolean
      - `remote_field_type_id` string, nullable
      - `source` Source, required
        - `field` string, required
        - `model_id` string, uuid, required
      - `target` string, required
    - `mode` 'create' | 'update' | 'updateOrCreate' | 'replace' | 'append' | 'remove' | 'snapshot'
    - `model_ids` string[] — Model IDs used in the sync.
    - `name` string
    - `only_enrich_updates` boolean
    - `organization_id` string, uuid
    - `override_fields` OverrideField[]
      - `new` boolean — New is set to true if the target field should be created by Polytomic. This is not supported by all backends.
      - `override_value` string, required — Value written to the target field for every record.
      - `sync_mode` string — Sync mode for the field; defaults to 'updateOrCreate'. If set to 'create', the field will not be synced if it already has a value. This is not supported by all backends.
      - `target` string, required — Target field ID the value will be written to.
    - `overrides` Override[]
      - `field` Source
        - `field` string, required
        - `model_id` string, uuid, required
      - `field_id` string — Field ID of the model field to override.
      - `function` 'Equality' | 'Inequality' | 'IsNull' | 'IsNotNull' | 'True' | 'False' | 'OnOrAfter' | 'OnOrBefore' | 'GreaterThan' | 'GreaterThanEqual' | 'LessThan' | 'LessThanEqual' | 'StringContains' | 'StringStartsWith' | 'StringEndsWith' | 'StringDoesNotContain' | 'StringDoesNotStartWith' | 'StringDoesNotEndWith' | 'StringOneOf' | 'StringNotOneOf' | 'Between' | 'ArrayContains' | 'ArrayDoesNotContain' | 'InTheLast' | 'RelativeOnOrBefore' | 'RelativeOnOrAfter' | 'StringLike' | 'StringNotLike' | 'StringMatchesTrimmed'
      - `override` string
      - `value` string
    - `policies` string[]
    - `schedule` Schedule
      - `connection_id` string, uuid
      - `day_of_month` string, nullable
      - `day_of_week` string, nullable
      - `frequency` 'manual' | 'continuous' | 'hourly' | 'daily' | 'weekly' | 'custom' | 'builder' | 'runafter' | 'multi' | 'dbtcloud'
      - `hour` string, nullable
      - `job_id` integer, nullable
      - `minute` string, nullable
      - `month` string, nullable
      - `run_after` RunAfter
        - `bulk_sync_ids` string[]
        - `sync_ids` string[]
      - `run_after_success_only` boolean, nullable — If true, the sync will only run if the dependent syncs completed successfully.
    - `skip_initial_backfill` boolean
    - `sync_all_records` boolean
    - `target` Target
      - `configuration` object
      - `connection_id` string, uuid, required
      - `create` object — Create a new target object with these properties.
      - `filter_logic` string
      - `new_name` string — Name for a new target object.
      - `object` string
      - `search_values` object
    - `updated_at` string, date-time
    - `updated_by` OutputActor
      - `id` string, uuid
      - `name` string
      - `type` string

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `422` — Unprocessable Entity
- `500` — Internal Server Error

---

[API](https://skmtc.net/polytomic/apis/polytomic-api.md) · [All operations](https://skmtc.net/polytomic/apis/polytomic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/polytomic/polytomic-api/revisions/31d9a913d396/schema)