v1

latestOpenAPI 3.0.32026-08-06138294578.6 KB

Bulk Sync

Update Bulk Sync

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, including schema and field selections.

📘 Updating schemas

Schema updates are not performed through this endpoint. 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.

put/api/bulk/syncs/{id}

Path parameters

idstring uuid required

Unique identifier of the bulk sync to update.

Example:248df4b7-aa70-47b8-a036-33ac447e668d

Unique identifier of the bulk sync to update.

Headers

X-Polytomic-Versionstring

Request body

activeboolean nullable

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

automatically_add_new_fields'all' | 'onlyIncremental' | 'onlyNonIncremental' | 'none' nullable

automatically_add_new_objects'all' | 'onlyIncremental' | 'onlyNonIncremental' | 'none' nullable

concurrency_limitinteger nullable

Override the default concurrency limit for this sync.

data_cutoff_timestampstring date-time nullable

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

destination_configurationobject required

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

destination_connection_idstring uuid required

Unique identifier of the connection rows are written to.

disable_record_timestampsboolean nullable

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

mode'snapshot' | 'replicate' nullable required

namestring required

Human-readable name for the bulk sync.

normalize_names'enabled' | 'disabled' | 'legacy' nullable

organization_idstring uuid nullable

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

policiesstring[] nullable

Identifiers of permissions policies applied to the bulk sync.

resync_concurrency_limitinteger nullable

Override the default resync concurrency limit for this sync.

source_configurationobject nullable

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

source_connection_idstring uuid required

Unique identifier of the connection rows are read from.

Example request

{
  "active": true,
  "additional_schedules": [
    {
      "day_of_week": "monday",
      "frequency": "weekly",
      "hour": "12",
      "minute": "30",
      "selective_mode": "nonincrementalFields"
    },
    {
      "frequency": "continuous",
      "selective_mode": "incrementalFields"
    }
  ],
  "concurrency_limit": 50,
  "data_cutoff_timestamp": "2023-04-25T12:00:00Z",
  "default_schedule": {
    "day_of_month": "1",
    "day_of_week": "monday",
    "hour": "12",
    "id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "minute": "30",
    "month": "1"
  },
  "destination_configuration": {
    "schema": "my_schema"
  },
  "destination_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
  "name": "My Bulk Sync",
  "organization_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
  "policies": [
    "248df4b7-aa70-47b8-a036-33ac447e668d"
  ],
  "resync_concurrency_limit": 10,
  "schemas": [
    {
      "data_cutoff_timestamp": "2023-04-25T12:00:00Z",
      "disable_data_cutoff": true,
      "enabled": true,
      "fields": [
        {
          "enabled": true,
          "obfuscate": true
        }
      ],
      "filters": [
        {
          "field_id": "field1",
          "value": "value"
        }
      ]
    }
  ],
  "source_configuration": {
    "replication_slot": "slot"
  },
  "source_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d"
}

Response

Example response

{
  "data": {
    "active": true,
    "additional_schedules": [
      {
        "created_at": "2023-04-25T12:00:00Z",
        "created_by": {
          "id": "12345678-1234-1234-1234-123456789012",
          "name": "John Doe",
          "type": "user"
        },
        "day_of_week": "monday",
        "frequency": "weekly",
        "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"
        }
      },
      {
        "created_at": "2023-04-25T12:00:00Z",
        "created_by": {
          "id": "12345678-1234-1234-1234-123456789012",
          "name": "John Doe",
          "type": "user"
        },
        "frequency": "continuous",
        "selective_mode": "incrementalFields",
        "updated_at": "2023-04-25T12:00:00Z",
        "updated_by": {
          "id": "12345678-1234-1234-1234-123456789012",
          "name": "John Doe",
          "type": "user"
        }
      }
    ],
    "concurrency_limit": 50,
    "created_by": {
      "id": "12345678-1234-1234-1234-123456789012",
      "name": "John Doe",
      "type": "user"
    },
    "data_cutoff_timestamp": "2023-04-25T12:00:00Z",
    "default_schedule": {
      "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_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",
    "id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "name": "My Bulk Sync",
    "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_by": {
      "id": "12345678-1234-1234-1234-123456789012",
      "name": "John Doe",
      "type": "user"
    }
  }
}