> This page is for version 2025-09-18 (default). > For other versions, use one of these documentation indexes: > - 2025-09-18 (default): https://apidocs.polytomic.com/2025-09-18/llms.txt > - 2024-02-08: https://apidocs.polytomic.com/2024-02-08/llms.txt > - 2023-04-25: https://apidocs.polytomic.com/2023-04-25/llms.txt > - 2022-12-12: https://apidocs.polytomic.com/2022-12-12/llms.txt > - 2021-05-23: https://apidocs.polytomic.com/2021-05-23/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://apidocs.polytomic.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://apidocs.polytomic.com/_mcp/server. # Create Bulk Sync POST https://app.polytomic.com/api/bulk/syncs Content-Type: application/json 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. Reference: https://apidocs.polytomic.com/api-reference/bulk-sync/create ## Authentication - `Authorization` header (bearer token, required) — Bearer user API key - `Authorization` header (basic auth, required) — Basic organization-scoped API key ## Request ### Body (application/json) This endpoint expects a CreateBulkSyncRequest. - `default_schedule` (BulkSyncDefaultScheduleRequest, required) - `destination_configuration` (map from string to any, 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, required) — Unique identifier of the connection rows are written to. - `mode` (enum, required) - Allowed values: `snapshot`, `replicate`, `append` - `name` (string, required) — Human-readable name for the bulk sync. - `source_connection_id` (string, required) — Unique identifier of the connection rows are read from. - `active` (boolean, optional, nullable) — Whether the sync is active. Inactive syncs do not run on their schedule but can still be triggered manually. - `additional_schedules` (list of BulkSyncAdditionalScheduleRequest, optional, nullable) — Additional bulk sync schedules. Schedule times are interpreted in UTC. - `automatically_add_new_fields` (enum, optional) - Allowed values: `all`, `onlyIncremental`, `onlyNonIncremental`, `none` - `automatically_add_new_objects` (enum, optional) - Allowed values: `all`, `onlyIncremental`, `onlyNonIncremental`, `none` - `concurrency_limit` (integer, optional, nullable) — Override the default concurrency limit for this sync. - `data_cutoff_timestamp` (datetime, optional, nullable) — Global cutoff applied across schemas. Source records older than this timestamp are excluded from sync runs. - `disable_record_timestamps` (boolean, optional, nullable, default: false) — When true, Polytomic will not add its own timestamp columns to destination rows. - `normalize_names` (enum, optional) - Allowed values: `enabled`, `disabled`, `legacy` - `organization_id` (string, optional, nullable) — Organization the sync is created in. Only used by partner callers; normal callers always create syncs in their own organization. - `policies` (list of string, optional, nullable) — Identifiers of permissions policies applied to the bulk sync. - `resync_concurrency_limit` (integer, optional, nullable) — Override the default resync concurrency limit for this sync. - `schemas` (list of CreateBulkSyncRequestSchemasItems, optional, nullable) — List of schemas to sync; if omitted, all schemas will be selected for syncing. - `source_configuration` (map from string to any, optional, nullable) — Source-specific bulk sync configuration (e.g. replication slot name, sync lookback). The accepted keys depend on the source connection type. ## Response ### 200 OK - `data` (BulkSyncResponse, optional) ## Errors ### 400 Bad Request Error Bad Request - `key` (string, optional) - `message` (string, optional) - `metadata` (map from string to any, optional) - `status` (integer, optional) ### 403 Forbidden Error Forbidden - `key` (string, optional) - `message` (string, optional) - `metadata` (map from string to any, optional) - `status` (integer, optional) ### 422 Unprocessable Entity Error Unprocessable Entity - `key` (string, optional) - `message` (string, optional) - `metadata` (map from string to any, optional) - `status` (integer, optional) ### 500 Internal Server Error Internal Server Error - `key` (string, optional) - `message` (string, optional) - `metadata` (map from string to any, optional) - `status` (integer, optional) ## Types ### BulkSyncDefaultScheduleRequest - `frequency` (enum, required) - Allowed values: `manual`, `continuous`, `hourly`, `daily`, `weekly`, `custom`, `builder`, `runafter`, `multi`, `dbtcloud` - `day_of_month` (string, optional) — Day of the month (1-31) to run monthly schedules. - `day_of_week` (string, optional) — Day of the week to run weekly schedules. - `hour` (string, optional) — Hour of the day (0-23, in UTC) to run hourly, daily, weekly, or monthly schedules. - `id` (string, optional) - `minute` (string, optional) — Minute of the hour (0-59) to run the schedule. - `month` (string, optional) — Month of the year (1-12) to run yearly schedules. ### BulkSyncAdditionalScheduleRequest - `frequency` (enum, required) - Allowed values: `manual`, `continuous`, `hourly`, `daily`, `weekly`, `custom`, `builder`, `runafter`, `multi`, `dbtcloud` - `day_of_month` (string, optional) — Day of the month (1-31) to run monthly schedules. - `day_of_week` (string, optional) — Day of the week to run weekly schedules. - `hour` (string, optional) — Hour of the day (0-23, in UTC) to run hourly, daily, weekly, or monthly schedules. - `id` (string, optional) - `minute` (string, optional) — Minute of the hour (0-59) to run the schedule. - `month` (string, optional) — Month of the year (1-12) to run yearly schedules. - `resync_mode` (enum, optional) - Allowed values: `normal`, `refetch`, `resync`, `rebuild` - `schemas` (list of string, optional) — Optional list of schema IDs this schedule applies to. If empty, the schedule applies to all schemas. - `selective_mode` (enum, optional) - Allowed values: `none`, `incrementalFields`, `nonincrementalFields` ### CreateBulkSyncRequestSchemasItems ### BulkSyncResponse - `active` (boolean, optional) — Whether the sync is active. Inactive syncs do not run on their schedule. - `additional_schedules` (list of BulkSyncAdditionalScheduleResponse, optional, nullable) — Additional bulk sync schedules. Schedule times are interpreted in UTC. - `automatically_add_new_fields` (enum, optional) - Allowed values: `all`, `onlyIncremental`, `onlyNonIncremental`, `none` - `automatically_add_new_objects` (enum, optional) - Allowed values: `all`, `onlyIncremental`, `onlyNonIncremental`, `none` - `concurrency_limit` (integer, optional, nullable) — Per-sync concurrency limit override. - `created_at` (datetime, optional) — Timestamp the sync was created. - `created_by` (OutputActor, optional) - `data_cutoff_timestamp` (datetime, optional, nullable) — Global cutoff applied across schemas; source records older than this timestamp are excluded. - `default_schedule` (BulkSyncDefaultScheduleResponse, optional) - `destination_configuration` (map from string to any, optional, nullable) — Destination-specific bulk sync configuration. e.g. output schema name, s3 file format, etc. - `destination_connection_id` (string, optional) — Connection rows are written to. - `disable_record_timestamps` (boolean, optional, default: false) — When true, Polytomic does not add its own timestamp columns to destination rows. - `id` (string, optional) — Unique identifier of the bulk sync. - `mode` (enum, optional) - Allowed values: `snapshot`, `replicate`, `append` - `name` (string, optional) — Human-readable name of the bulk sync. - `normalize_names` (enum, optional) - Allowed values: `enabled`, `disabled`, `legacy` - `organization_id` (string, optional) — Organization the sync belongs to. - `policies` (list of string, optional) — List of permissions policies applied to the bulk sync. - `resync_concurrency_limit` (integer, optional, nullable) — Per-sync resync concurrency limit override. - `source_configuration` (map from string to any, optional, nullable) — Source-specific bulk sync configuration. e.g. replication slot name, sync lookback, etc. - `source_connection_id` (string, optional) — Connection rows are read from. - `updated_at` (datetime, optional) — Timestamp the sync was last updated. - `updated_by` (OutputActor, optional) ### SchemaConfiguration - `data_cutoff_timestamp` (datetime, optional, nullable) - `disable_data_cutoff` (boolean, optional, nullable, default: false) — Whether data cutoff is disabled for this schema. - `enabled` (boolean, optional, nullable, default: true) — Whether the schema is enabled for syncing. - `fields` (list of SchemaConfigurationFieldsItems, optional) - `filters` (list of BulkFilter, optional) - `history_enabled` (boolean, optional, nullable) — Whether a companion history table is maintained beside this schema's output, recording every version observed on successive runs. Requires a replicate-mode sync to a destination reporting supports_history_mode. Omit to keep the current value. - `id` (string, optional) - `partition_key` (string, optional, nullable) - `tracking_field` (string, optional, nullable) - `user_output_name` (string, optional, nullable) — User-specified override for the destination object name. Omit to keep the current value; send an empty string to clear it. ### BulkSyncAdditionalScheduleResponse - `frequency` (enum, required) - Allowed values: `manual`, `continuous`, `hourly`, `daily`, `weekly`, `custom`, `builder`, `runafter`, `multi`, `dbtcloud` - `created_at` (datetime, optional) — Timestamp the schedule was created. - `created_by` (OutputActor, optional) - `day_of_month` (string, optional) — Day of the month (1-31) for monthly schedules. - `day_of_week` (string, optional) — Day of the week for weekly schedules. - `hour` (string, optional) — Hour of the day (0-23, in UTC) the schedule fires. - `id` (string, optional) — Unique identifier of the schedule. - `minute` (string, optional) — Minute of the hour (0-59) the schedule fires. - `month` (string, optional) — Month of the year (1-12) for yearly schedules. - `resync_mode` (enum, optional) - Allowed values: `normal`, `refetch`, `resync`, `rebuild` - `schemas` (list of string, optional) — Schema IDs this schedule applies to. Empty means all schemas. - `selective_mode` (enum, optional) - Allowed values: `none`, `incrementalFields`, `nonincrementalFields` - `updated_at` (datetime, optional) — Timestamp the schedule was last updated. - `updated_by` (OutputActor, optional) ### OutputActor - `id` (string, optional) - `name` (string, optional) - `type` (string, optional) ### BulkSyncDefaultScheduleResponse - `frequency` (enum, required) - Allowed values: `manual`, `continuous`, `hourly`, `daily`, `weekly`, `custom`, `builder`, `runafter`, `multi`, `dbtcloud` - `created_at` (datetime, optional) — Timestamp the schedule was created. - `created_by` (OutputActor, optional) - `day_of_month` (string, optional) — Day of the month (1-31) for monthly schedules. - `day_of_week` (string, optional) — Day of the week for weekly schedules. - `hour` (string, optional) — Hour of the day (0-23, in UTC) the schedule fires. - `id` (string, optional) — Unique identifier of the schedule. - `minute` (string, optional) — Minute of the hour (0-59) the schedule fires. - `month` (string, optional) — Month of the year (1-12) for yearly schedules. - `updated_at` (datetime, optional) — Timestamp the schedule was last updated. - `updated_by` (OutputActor, optional) ### SchemaConfigurationFieldsItems ### BulkFilter - `function` (enum, required) - Allowed values: `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` - `field_id` (string, optional) — Schema field ID to filter on. - `value` (any, optional) ### FieldConfiguration - `enabled` (boolean, optional, nullable, default: true) — Whether the field is enabled for syncing. - `id` (string, optional) - `obfuscate` (boolean, optional, nullable, default: false) — Whether the field should be obfuscated. - `user_output_name` (string, optional, nullable) — User-specified override for the destination field name. Omit to keep the current value; send an empty string to clear it. ## Examples **Request** ```json { "default_schedule": { "frequency": "manual" }, "destination_configuration": { "schema": "my_schema" }, "destination_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d", "mode": "snapshot", "name": "My Bulk Sync", "source_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d" } ``` **Response** ```json { "data": { "active": true, "additional_schedules": [ { "frequency": "weekly", "created_at": "2023-04-25T12:00:00Z", "created_by": { "id": "12345678-1234-1234-1234-123456789012", "name": "John Doe", "type": "user" }, "day_of_week": "monday", "hour": "12", "minute": "30", "selective_mode": "nonincrementalFields", "updated_at": "2023-04-25T12:00:00Z", "updated_by": { "id": "12345678-1234-1234-1234-123456789012", "name": "John Doe", "type": "user" } }, { "frequency": "continuous", "created_at": "2023-04-25T12:00:00Z", "created_by": { "id": "12345678-1234-1234-1234-123456789012", "name": "John Doe", "type": "user" }, "selective_mode": "incrementalFields", "updated_at": "2023-04-25T12:00:00Z", "updated_by": { "id": "12345678-1234-1234-1234-123456789012", "name": "John Doe", "type": "user" } } ], "automatically_add_new_fields": "all", "automatically_add_new_objects": "all", "concurrency_limit": 50, "created_at": "2024-01-15T09:30:00Z", "created_by": { "id": "12345678-1234-1234-1234-123456789012", "name": "John Doe", "type": "user" }, "data_cutoff_timestamp": "2023-04-25T12:00:00Z", "default_schedule": { "frequency": "manual", "created_at": "2024-01-15T09:30:00Z", "created_by": { "id": "12345678-1234-1234-1234-123456789012", "name": "John Doe", "type": "user" }, "day_of_month": "1", "day_of_week": "monday", "hour": "12", "id": "248df4b7-aa70-47b8-a036-33ac447e668d", "minute": "30", "month": "1", "updated_at": "2024-01-15T09:30:00Z", "updated_by": { "id": "12345678-1234-1234-1234-123456789012", "name": "John Doe", "type": "user" } }, "destination_configuration": { "schema": "my_schema" }, "destination_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d", "disable_record_timestamps": false, "id": "248df4b7-aa70-47b8-a036-33ac447e668d", "mode": "snapshot", "name": "My Bulk Sync", "normalize_names": "enabled", "organization_id": "248df4b7-aa70-47b8-a036-33ac447e668d", "policies": [ "248df4b7-aa70-47b8-a036-33ac447e668d" ], "resync_concurrency_limit": 10, "source_configuration": { "replication_slot": "slot" }, "source_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d", "updated_at": "2024-01-15T09:30:00Z", "updated_by": { "id": "12345678-1234-1234-1234-123456789012", "name": "John Doe", "type": "user" } } } ``` **SDK Code** ```python import requests url = "https://app.polytomic.com/api/bulk/syncs" payload = { "default_schedule": { "frequency": "manual" }, "destination_configuration": { "schema": "my_schema" }, "destination_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d", "mode": "snapshot", "name": "My Bulk Sync", "source_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://app.polytomic.com/api/bulk/syncs'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"default_schedule":{"frequency":"manual"},"destination_configuration":{"schema":"my_schema"},"destination_connection_id":"248df4b7-aa70-47b8-a036-33ac447e668d","mode":"snapshot","name":"My Bulk Sync","source_connection_id":"248df4b7-aa70-47b8-a036-33ac447e668d"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://app.polytomic.com/api/bulk/syncs" payload := strings.NewReader("{\n \"default_schedule\": {\n \"frequency\": \"manual\"\n },\n \"destination_configuration\": {\n \"schema\": \"my_schema\"\n },\n \"destination_connection_id\": \"248df4b7-aa70-47b8-a036-33ac447e668d\",\n \"mode\": \"snapshot\",\n \"name\": \"My Bulk Sync\",\n \"source_connection_id\": \"248df4b7-aa70-47b8-a036-33ac447e668d\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://app.polytomic.com/api/bulk/syncs") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"default_schedule\": {\n \"frequency\": \"manual\"\n },\n \"destination_configuration\": {\n \"schema\": \"my_schema\"\n },\n \"destination_connection_id\": \"248df4b7-aa70-47b8-a036-33ac447e668d\",\n \"mode\": \"snapshot\",\n \"name\": \"My Bulk Sync\",\n \"source_connection_id\": \"248df4b7-aa70-47b8-a036-33ac447e668d\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://app.polytomic.com/api/bulk/syncs") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"default_schedule\": {\n \"frequency\": \"manual\"\n },\n \"destination_configuration\": {\n \"schema\": \"my_schema\"\n },\n \"destination_connection_id\": \"248df4b7-aa70-47b8-a036-33ac447e668d\",\n \"mode\": \"snapshot\",\n \"name\": \"My Bulk Sync\",\n \"source_connection_id\": \"248df4b7-aa70-47b8-a036-33ac447e668d\"\n}") .asString(); ``` ```php request('POST', 'https://app.polytomic.com/api/bulk/syncs', [ 'body' => '{ "default_schedule": { "frequency": "manual" }, "destination_configuration": { "schema": "my_schema" }, "destination_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d", "mode": "snapshot", "name": "My Bulk Sync", "source_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://app.polytomic.com/api/bulk/syncs"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"default_schedule\": {\n \"frequency\": \"manual\"\n },\n \"destination_configuration\": {\n \"schema\": \"my_schema\"\n },\n \"destination_connection_id\": \"248df4b7-aa70-47b8-a036-33ac447e668d\",\n \"mode\": \"snapshot\",\n \"name\": \"My Bulk Sync\",\n \"source_connection_id\": \"248df4b7-aa70-47b8-a036-33ac447e668d\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "default_schedule": ["frequency": "manual"], "destination_configuration": ["schema": "my_schema"], "destination_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d", "mode": "snapshot", "name": "My Bulk Sync", "source_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://app.polytomic.com/api/bulk/syncs")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```