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

# Create Bulk Sync

`POST /api/bulk/syncs`

Creates a new bulk sync.

Bulk syncs are used for the ELT pattern (Extract, Load, and Transform), where you want to sync un-transformed data to your data warehouses, databases, or cloud storage buckets like S3.

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

Sample code examples:

- [Bulk sync (ELT) from Salesforce to S3](../../../guides/code-examples/bulk-sync-elt-from-salesforce-to-s-3)
- [Bulk sync (ELT) from Salesforce to Snowflake](../../../guides/code-examples/bulk-sync-elt-from-salesforce-to-snowflake)
- [Bulk sync (ELT) from HubSpot to PostgreSQL](../../../guides/code-examples/bulk-sync-elt-from-hub-spot-to-postgre-sql)

## Connection specific configuration

The `destination_configuration` is integration-specific configuration for the
selected bulk sync destination. This includes settings such as the output schema
and is required when creating a new sync.

The `source_configuration` is optional. It allows configuration for how
Polytomic reads data from the source connection. This will not be available for
integrations that do not support additional configuration.

Consult the [connection configurations](../../../guides/configuring-your-connections/overview)
to see configurations for particular integrations (for example, [here](../../../guides/configuring-your-connections/connections/postgre-sql#source-1) is the available source configuration for the PostgreSQL bulk sync source).

## Defaults and selection behavior

If `schemas` is omitted, the sync is created with all available source schemas
selected. Pass `schemas` explicitly if you want the initial sync to include
only a subset of tables or objects.

Schedule times are interpreted in UTC.

When omitted, automatic discovery defaults are conservative:

- `automatically_add_new_objects` defaults to not enabling newly discovered
  source objects automatically.
- `automatically_add_new_fields` defaults to enabling newly discovered fields
  on already selected objects.
- `normalize_names` defaults to enabled.

## Headers

- `X-Polytomic-Version` string

## Request body

- CreateBulkSyncRequest
  - `active` boolean, nullable — Whether the sync is active. Inactive syncs do not run on their schedule but can still be triggered manually.
  - `additional_schedules` BulkSyncAdditionalScheduleRequest[], nullable — Additional bulk sync schedules. Schedule times are interpreted in UTC.
    - `day_of_month` string — Day of the month (1-31) to run monthly schedules.
    - `day_of_week` string — Day of the week to run weekly schedules.
    - `frequency` 'manual' | 'continuous' | 'hourly' | 'daily' | 'weekly' | 'custom' | 'builder' | 'runafter' | 'multi' | 'dbtcloud', required
    - `hour` string — Hour of the day (0-23, in UTC) to run hourly, daily, weekly, or monthly schedules.
    - `id` string, uuid
    - `minute` string — Minute of the hour (0-59) to run the schedule.
    - `month` string — Month of the year (1-12) to run yearly schedules.
    - `resync_mode` 'normal' | 'refetch' | 'resync' | 'rebuild'
    - `schemas` string[] — Optional list of schema IDs this schedule applies to. If empty, the schedule applies to all schemas.
    - `selective_mode` 'none' | 'incrementalFields' | 'nonincrementalFields'
  - `automatically_add_new_fields` 'all' | 'onlyIncremental' | 'onlyNonIncremental' | 'none', nullable
  - `automatically_add_new_objects` 'all' | 'onlyIncremental' | 'onlyNonIncremental' | 'none', nullable
  - `concurrency_limit` integer, nullable — Override the default concurrency limit for this sync.
  - `data_cutoff_timestamp` string, date-time, nullable — Global cutoff applied across schemas. Source records older than this timestamp are excluded from sync runs.
  - `default_schedule` BulkSyncDefaultScheduleRequest, required
    - `day_of_month` string — Day of the month (1-31) to run monthly schedules.
    - `day_of_week` string — Day of the week to run weekly schedules.
    - `frequency` 'manual' | 'continuous' | 'hourly' | 'daily' | 'weekly' | 'custom' | 'builder' | 'runafter' | 'multi' | 'dbtcloud', required
    - `hour` string — Hour of the day (0-23, in UTC) to run hourly, daily, weekly, or monthly schedules.
    - `id` string, uuid
    - `minute` string — Minute of the hour (0-59) to run the schedule.
    - `month` string — Month of the year (1-12) to run yearly schedules.
  - `destination_configuration` object, required — Destination-specific bulk sync configuration (e.g. output schema name, file format). The accepted keys depend on the destination connection type.
  - `destination_connection_id` string, uuid, required — Unique identifier of the connection rows are written to.
  - `disable_record_timestamps` boolean, nullable — When true, Polytomic will not add its own timestamp columns to destination rows.
  - `mode` 'snapshot' | 'replicate', nullable, required
  - `name` string, required — Human-readable name for the bulk sync.
  - `normalize_names` 'enabled' | 'disabled' | 'legacy', nullable
  - `organization_id` string, uuid, nullable — Organization the sync is created in. Only used by partner callers; normal callers always create syncs in their own organization.
  - `policies` string[], nullable — Identifiers of permissions policies applied to the bulk sync.
  - `resync_concurrency_limit` integer, nullable — Override the default resync concurrency limit for this sync.
  - `schemas` union[], nullable — List of schemas to sync; if omitted, all schemas will be selected for syncing.
    - union
      - string
      - SchemaConfiguration
        - `data_cutoff_timestamp` string, date-time, nullable
        - `disable_data_cutoff` boolean, nullable — Whether data cutoff is disabled for this schema.
        - `enabled` boolean, nullable — Whether the schema is enabled for syncing.
        - `fields` union[]
          - union
            - string
            - FieldConfiguration
              - …
        - `filters` BulkFilter[]
          - `field_id` string — Schema field ID to filter on.
          - `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
          - `value` string
        - `id` string
        - `partition_key` string, nullable
        - `tracking_field` string, nullable
  - `source_configuration` object, nullable — Source-specific bulk sync configuration (e.g. replication slot name, sync lookback). The accepted keys depend on the source connection type.
  - `source_connection_id` string, uuid, required — Unique identifier of the connection rows are read from.

## Response `200`

OK

- BulkSyncResponseEnvelope
  - `data` BulkSyncResponse
    - `active` boolean — Whether the sync is active. Inactive syncs do not run on their schedule.
    - `additional_schedules` BulkSyncAdditionalScheduleResponse[], nullable — Additional bulk sync schedules. Schedule times are interpreted in UTC.
      - `created_at` string, date-time — Timestamp the schedule was created.
      - `created_by` OutputActor
        - `id` string, uuid
        - `name` string
        - `type` string
      - `day_of_month` string — Day of the month (1-31) for monthly schedules.
      - `day_of_week` string — Day of the week for weekly schedules.
      - `frequency` 'manual' | 'continuous' | 'hourly' | 'daily' | 'weekly' | 'custom' | 'builder' | 'runafter' | 'multi' | 'dbtcloud', required
      - `hour` string — Hour of the day (0-23, in UTC) the schedule fires.
      - `id` string, uuid — Unique identifier of the schedule.
      - `minute` string — Minute of the hour (0-59) the schedule fires.
      - `month` string — Month of the year (1-12) for yearly schedules.
      - `resync_mode` 'normal' | 'refetch' | 'resync' | 'rebuild'
      - `schemas` string[] — Schema IDs this schedule applies to. Empty means all schemas.
      - `selective_mode` 'none' | 'incrementalFields' | 'nonincrementalFields'
      - `updated_at` string, date-time — Timestamp the schedule was last updated.
      - `updated_by` OutputActor
        - `id` string, uuid
        - `name` string
        - `type` string
    - `automatically_add_new_fields` 'all' | 'onlyIncremental' | 'onlyNonIncremental' | 'none', nullable
    - `automatically_add_new_objects` 'all' | 'onlyIncremental' | 'onlyNonIncremental' | 'none', nullable
    - `concurrency_limit` integer, nullable — Per-sync concurrency limit override.
    - `created_at` string, date-time — Timestamp the sync was created.
    - `created_by` OutputActor
      - `id` string, uuid
      - `name` string
      - `type` string
    - `data_cutoff_timestamp` string, date-time, nullable — Global cutoff applied across schemas; source records older than this timestamp are excluded.
    - `default_schedule` BulkSyncDefaultScheduleResponse
      - `created_at` string, date-time — Timestamp the schedule was created.
      - `created_by` OutputActor
        - `id` string, uuid
        - `name` string
        - `type` string
      - `day_of_month` string — Day of the month (1-31) for monthly schedules.
      - `day_of_week` string — Day of the week for weekly schedules.
      - `frequency` 'manual' | 'continuous' | 'hourly' | 'daily' | 'weekly' | 'custom' | 'builder' | 'runafter' | 'multi' | 'dbtcloud', required
      - `hour` string — Hour of the day (0-23, in UTC) the schedule fires.
      - `id` string, uuid — Unique identifier of the schedule.
      - `minute` string — Minute of the hour (0-59) the schedule fires.
      - `month` string — Month of the year (1-12) for yearly schedules.
      - `updated_at` string, date-time — Timestamp the schedule was last updated.
      - `updated_by` OutputActor
        - `id` string, uuid
        - `name` string
        - `type` string
    - `destination_configuration` object, nullable — Destination-specific bulk sync configuration. e.g. output schema name, s3 file format, etc.
    - `destination_connection_id` string, uuid — Connection rows are written to.
    - `disable_record_timestamps` boolean — When true, Polytomic does not add its own timestamp columns to destination rows.
    - `id` string, uuid — Unique identifier of the bulk sync.
    - `mode` 'snapshot' | 'replicate', nullable
    - `name` string — Human-readable name of the bulk sync.
    - `normalize_names` 'enabled' | 'disabled' | 'legacy', nullable
    - `organization_id` string, uuid — Organization the sync belongs to.
    - `policies` string[] — List of permissions policies applied to the bulk sync.
    - `resync_concurrency_limit` integer, nullable — Per-sync resync concurrency limit override.
    - `source_configuration` object, nullable — Source-specific bulk sync configuration. e.g. replication slot name, sync lookback, etc.
    - `source_connection_id` string, uuid — Connection rows are read from.
    - `updated_at` string, date-time — Timestamp the sync was last updated.
    - `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/versions/b509e00e80aa/schema)