> 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 (basic auth, required) — This is the Polytomic deployment key (on-premises only)
- `Authorization` header (bearer token, required) — This is the Polytomic API key

## Request

### Path parameters

- `id` (string, required)

### Body (application/json)

This endpoint expects a V2UpdateBulkSyncRequest.

- `destination_configuration` (map from string to any, required)
- `destination_connection_id` (string, required)
- `mode` (enum, required)
  - Allowed values: `snapshot`, `replicate`, `append`
- `name` (string, required)
- `schedule` (BulkSchedule, required)
- `source_connection_id` (string, required)
- `active` (boolean, optional, nullable)
- `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` (string, optional, nullable)
- `disable_record_timestamps` (boolean, optional, nullable, default: false)
- `discover` (boolean, optional, nullable) — DEPRECATED: Use automatically_add_new_objects/automatically_add_new_fields instead
- `normalize_names` (enum, optional)
  - Allowed values: `enabled`, `disabled`, `legacy`
- `organization_id` (string, optional, nullable)
- `policies` (list of string, optional, nullable)
- `resync_concurrency_limit` (integer, optional, nullable) — Override the default resync concurrency limit for this sync.
- `schemas` (list of V2UpdateBulkSyncRequestSchemasItems, 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)

## Response

### 200

OK

- `data` (V2BulkSyncResponse, optional)

## Errors

### 400 Bad Request Error

Bad Request

- `key` (string, optional)
- `message` (string, optional)
- `metadata` (map from string to any, optional)
- `status` (integer, optional)

### 401 Unauthorized Error

Unauthorized

- `code` (integer, optional) — Application-specific error code.
- `context` (map from string to any, optional) — Application context.
- `error` (string, optional) — Error message.
- `status` (string, optional) — Status text.

### 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

### BulkSchedule

- `frequency` (enum, required)
  - Allowed values: `manual`, `continuous`, `hourly`, `daily`, `weekly`, `custom`, `builder`, `runafter`, `multi`, `dbtcloud`
- `day_of_month` (string, optional)
- `day_of_week` (string, optional)
- `hour` (string, optional)
- `minute` (string, optional)
- `month` (string, optional)
- `multi` (BulkMultiScheduleConfiguration, optional)

### V2UpdateBulkSyncRequestSchemasItems

### V2BulkSyncResponse

- `active` (boolean, optional)
- `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` (string, optional)
- `created_by` (OutputActor, optional)
- `data_cutoff_timestamp` (string, optional, nullable)
- `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)
- `disable_record_timestamps` (boolean, optional, default: false)
- `id` (string, optional)
- `mode` (enum, optional)
  - Allowed values: `snapshot`, `replicate`, `append`
- `name` (string, optional) — Name of the bulk sync
- `normalize_names` (enum, optional)
  - Allowed values: `enabled`, `disabled`, `legacy`
- `organization_id` (string, optional)
- `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.
- `schedule` (BulkSchedule, optional)
- `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)
- `updated_at` (string, optional)
- `updated_by` (OutputActor, optional)
- `discover` (boolean, optional, deprecated) — DEPRECATED: Use automatically_add_new_objects/automatically_add_new_fields instead

### BulkMultiScheduleConfiguration

- `schedules` (list of BulkItemizedSchedule, required, nullable)
- `type` (string, optional, nullable)

### V2SchemaConfiguration

- `data_cutoff_timestamp` (string, 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 V2SchemaConfigurationFieldsItems, 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.

### OutputActor

- `id` (string, optional)
- `name` (string, optional)
- `type` (string, optional)

### BulkItemizedSchedule

- `item` (enum, required)
  - Allowed values: `none`, `incrementalFields`, `nonincrementalFields`
- `schedule` (BulkSchedule, required)

### V2SchemaConfigurationFieldsItems

### 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)

### V2FieldConfiguration

- `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
{
  "destination_configuration": {
    "schema": "my_schema"
  },
  "destination_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
  "mode": "snapshot",
  "name": "My Bulk Sync",
  "schedule": {
    "frequency": "manual"
  },
  "source_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d"
}
```

**Response**

```json
{
  "data": {
    "active": true,
    "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",
    "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,
    "schedule": {
      "frequency": "manual",
      "day_of_month": "1",
      "day_of_week": "monday",
      "hour": "0",
      "minute": "0",
      "month": "1",
      "multi": {
        "schedules": [
          {
            "item": "none"
          }
        ],
        "type": "string"
      }
    },
    "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"
    },
    "discover": true
  }
}
```

**SDK Code**

```python
import requests

url = "https://app.polytomic.com/api/bulk/syncs/248df4b7-aa70-47b8-a036-33ac447e668d"

payload = {
    "destination_configuration": { "schema": "my_schema" },
    "destination_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "mode": "snapshot",
    "name": "My Bulk Sync",
    "schedule": { "frequency": "manual" },
    "source_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d"
}
headers = {
    "X-Polytomic-Version": "X-Polytomic-Version"
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers, auth=("<username>", "<password>"))

print(response.json())
```

```javascript
const url = 'https://app.polytomic.com/api/bulk/syncs/248df4b7-aa70-47b8-a036-33ac447e668d';
const credentials = btoa("<username>:<password>");

const options = {
  method: 'PUT',
  headers: {
    'X-Polytomic-Version': 'X-Polytomic-Version',
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json'
  },
  body: '{"destination_configuration":{"schema":"my_schema"},"destination_connection_id":"248df4b7-aa70-47b8-a036-33ac447e668d","mode":"snapshot","name":"My Bulk Sync","schedule":{"frequency":"manual"},"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  \"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  \"schedule\": {\n    \"frequency\": \"manual\"\n  },\n  \"source_connection_id\": \"248df4b7-aa70-47b8-a036-33ac447e668d\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("X-Polytomic-Version", "X-Polytomic-Version")
	req.SetBasicAuth("<username>", "<password>")
	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["X-Polytomic-Version"] = 'X-Polytomic-Version'
request.basic_auth("<username>", "<password>")
request["Content-Type"] = 'application/json'
request.body = "{\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  \"schedule\": {\n    \"frequency\": \"manual\"\n  },\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<String> response = Unirest.put("https://app.polytomic.com/api/bulk/syncs/248df4b7-aa70-47b8-a036-33ac447e668d")
  .header("X-Polytomic-Version", "X-Polytomic-Version")
  .basicAuth("<username>", "<password>")
  .header("Content-Type", "application/json")
  .body("{\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  \"schedule\": {\n    \"frequency\": \"manual\"\n  },\n  \"source_connection_id\": \"248df4b7-aa70-47b8-a036-33ac447e668d\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://app.polytomic.com/api/bulk/syncs/248df4b7-aa70-47b8-a036-33ac447e668d', [
  'body' => '{
  "destination_configuration": {
    "schema": "my_schema"
  },
  "destination_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
  "mode": "snapshot",
  "name": "My Bulk Sync",
  "schedule": {
    "frequency": "manual"
  },
  "source_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-Polytomic-Version' => 'X-Polytomic-Version',
  ],
    'auth' => ['<username>', '<password>'],
]);

echo $response->getBody();
```

```csharp
using RestSharp;
using RestSharp.Authenticators;

var client = new RestClient("https://app.polytomic.com/api/bulk/syncs/248df4b7-aa70-47b8-a036-33ac447e668d");
client.Authenticator = new HttpBasicAuthenticator("<username>", "<password>");
var request = new RestRequest(Method.PUT);
request.AddHeader("X-Polytomic-Version", "X-Polytomic-Version");

request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\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  \"schedule\": {\n    \"frequency\": \"manual\"\n  },\n  \"source_connection_id\": \"248df4b7-aa70-47b8-a036-33ac447e668d\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let credentials = Data("<username>:<password>".utf8).base64EncodedString()

let headers = [
  "X-Polytomic-Version": "X-Polytomic-Version",
  "Authorization": "Basic \(credentials)",
  "Content-Type": "application/json"
]
let parameters = [
  "destination_configuration": ["schema": "my_schema"],
  "destination_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
  "mode": "snapshot",
  "name": "My Bulk Sync",
  "schedule": ["frequency": "manual"],
  "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()
```