Update Bulk Sync | Polytomic Docs

curl -X PUT https://app.polytomic.com/api/bulk/syncs/248df4b7-aa70-47b8-a036-33ac447e668d \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "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"
}'

{
  "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"
    }
  }
}

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}, 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 endpoint to change a subset of schemas, or Update Bulk Sync Schema to replace a single schema’s configuration.

Authentication

AuthorizationBearer

Bearer user API key

AuthorizationBasic

Basic organization-scoped API key

Path parameters

idstringRequiredformat: "uuid"

Unique identifier of the bulk sync to update

Request

This endpoint expects an object.

default_scheduleobjectRequired

The default bulk sync schedule. This schedule applies to all fields and schemas. Schedules are interpreted in UTC.

destination_configurationmap from strings to anyRequired

Destination-specific bulk sync configuration (e.g. output schema name, file format). The accepted keys depend on the destination connection type.

destination_connection_idstringRequiredformat: "uuid"

Unique identifier of the connection rows are written to

modeenumRequired

How source data is written to the destination. replicate keeps the destination in sync with the source; snapshot writes a timestamped copy per execution; append adds every delivered record, including full reads, without updating existing rows.

Allowed values:

namestringRequired

Human-readable name for the bulk sync

source_connection_idstringRequiredformat: "uuid"

Unique identifier of the connection rows are read from

activeboolean or nullOptional

Whether the sync is active. Inactive syncs do not run on their schedule but can still be triggered manually.

additional_scheduleslist of objects or nullOptional

Additional bulk sync schedules. Schedule times are interpreted in UTC.

automatically_add_new_fieldsenumOptional

Controls whether Polytomic automatically enables newly discovered fields on existing objects. Valid values depend on the source backend.

Allowed values:

automatically_add_new_objectsenumOptional

Controls whether Polytomic automatically enables newly discovered source objects (tables). Valid values depend on the source backend.

Allowed values:

concurrency_limitinteger or nullOptional

Override the default concurrency limit for this sync.

data_cutoff_timestampdatetime or nullOptional

Global cutoff applied across schemas. Source records older than this timestamp are excluded from sync runs.

disable_record_timestampsboolean or nullOptionalDefaults to false

When true, Polytomic will not add its own timestamp columns to destination rows.

normalize_namesenumOptional

Controls whether destination object and field names are normalized (e.g. lowercased, special characters replaced). Valid values depend on the destination backend.

Allowed values:

organization_idstring or nullOptionalformat: "uuid"

Organization the sync belongs to. Only used by partner callers; normal callers are always scoped to their own organization.

policieslist of strings or nullOptional

Identifiers of permissions policies applied to the bulk sync

resync_concurrency_limitinteger or nullOptional

Override the default resync concurrency limit for this sync.

schemaslist of strings or objects or nullOptional

Schemas to sync. Schemas not in the list are disabled; if omitted or empty, the sync’s schemas are left unchanged.

source_configurationmap from strings to any or nullOptional

Source-specific bulk sync configuration (e.g. replication slot name, sync lookback). The accepted keys depend on the source connection type.

Response

dataobjectOptional

The bulk sync

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

500

Internal Server Error

Authentication

Path parameters

Headers

Request

Response

Errors