> 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. # Update Bulk Sync PUT https://app.polytomic.com/api/bulk/syncs/{id} Content-Type: application/json Updates an existing bulk sync's top-level configuration. Updating a bulk sync is a **full replacement** of the sync's top-level configuration. Every field in the request body is written to the sync; any field you omit is cleared or reset to its default value. To make a partial change — for example, toggling `active` or swapping a schedule — fetch the current sync with [`GET /api/bulk/syncs/{id}`](../../../../api-reference/bulk-sync/get), modify the fields you want to change, and send the complete object back in the update request. Updates to `active`, `schedules`, and `policies` take effect immediately. Changes to source or destination configuration take effect on the sync's next execution. Because omitted fields are reset to their defaults, the discovery and naming options behave the same as on create when left out: * `automatically_add_new_objects` resets to not enabling newly discovered source objects automatically. * `automatically_add_new_fields` resets to enabling newly discovered fields on already selected objects. * `normalize_names` resets to enabled. Send the existing values explicitly if you want to preserve a non-default or non-empty setting. > 📘 Updating schemas > > When `schemas` is present, it replaces the sync's schema selection: schemas > not in the list are disabled. When `schemas` is omitted or empty, the sync's > schemas are left unchanged. Use the > [Update Bulk Sync Schemas](../../../../api-reference/bulk-sync/schemas/patch) > endpoint to change a subset of schemas, or > [Update Bulk Sync Schema](../../../../api-reference/bulk-sync/schemas/update) > to replace a single schema's configuration. Reference: https://apidocs.polytomic.com/api-reference/bulk-sync/update ## Authentication - `Authorization` header (bearer token, required) — Bearer user API key - `Authorization` header (basic auth, required) — Basic organization-scoped API key ## Request ### Path parameters - `id` (string, required) — Unique identifier of the bulk sync to update. ### Body (application/json) This endpoint expects an UpdateBulkSyncRequest. - `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 belongs to. Only used by partner callers; normal callers are always scoped to 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 UpdateBulkSyncRequestSchemasItems, optional, nullable) — Schemas to sync. Schemas not in the list are disabled; if omitted or empty, the sync's schemas are left unchanged. - `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) ### 404 Not Found Error Not Found - `key` (string, optional) - `message` (string, optional) - `metadata` (map from string to any, optional) - `status` (integer, optional) ### 409 Conflict Error Conflict - `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` ### UpdateBulkSyncRequestSchemasItems ### 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/248df4b7-aa70-47b8-a036-33ac447e668d" 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.put(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://app.polytomic.com/api/bulk/syncs/248df4b7-aa70-47b8-a036-33ac447e668d'; const options = { method: 'PUT', 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/248df4b7-aa70-47b8-a036-33ac447e668d" 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("PUT", 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/248df4b7-aa70-47b8-a036-33ac447e668d") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Put.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.put("https://app.polytomic.com/api/bulk/syncs/248df4b7-aa70-47b8-a036-33ac447e668d") .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('PUT', 'https://app.polytomic.com/api/bulk/syncs/248df4b7-aa70-47b8-a036-33ac447e668d', [ '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/248df4b7-aa70-47b8-a036-33ac447e668d"); var request = new RestRequest(Method.PUT); 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/248df4b7-aa70-47b8-a036-33ac447e668d")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PUT" 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() ```