Update Sync | Polytomic Docs

curl -X PUT https://app.polytomic.com/api/syncs/248df4b7-aa70-47b8-a036-33ac447e668d \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "fields": [
    {
      "target": "name"
    }
  ],
  "mode": "create",
  "name": "Users Sync",
  "schedule": {},
  "target": {
    "connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d"
  }
}'

{
  "data": {
    "active": true,
    "created_at": "2024-01-15T09:30:00Z",
    "created_by": {
      "id": "12345678-1234-1234-1234-123456789012",
      "name": "John Doe",
      "type": "user"
    },
    "encryption_passphrase": "string",
    "fields": [
      {
        "target": "name",
        "encryption_enabled": true,
        "new": false,
        "override_value": "fixed_value",
        "source": {
          "field": "id",
          "model_id": "248df4b7-aa70-47b8-a036-33ac447e668d"
        },
        "sync_mode": "create"
      }
    ],
    "id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "identities": {
      "mappings": [
        {
          "function": "Equality",
          "source": {
            "field": "id",
            "model_id": "248df4b7-aa70-47b8-a036-33ac447e668d"
          },
          "target": "name",
          "new_field": true,
          "remote_field_type_id": "string"
        }
      ],
      "strategy": "priority"
    },
    "mode": "create",
    "model_filters": {
      "conditions": [
        {
          "function": "Equality",
          "source": {
            "field": "id",
            "model_id": "248df4b7-aa70-47b8-a036-33ac447e668d"
          },
          "label": "A",
          "value": null
        }
      ],
      "logic": "A and B or C"
    },
    "model_ids": [
      "string"
    ],
    "name": "Users Sync",
    "only_enrich_updates": false,
    "organization_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "override_fields": [
      {
        "override_value": "fixed_value",
        "target": "name",
        "new": false,
        "sync_mode": "create"
      }
    ],
    "overrides": [
      {
        "field": {
          "field": "id",
          "model_id": "248df4b7-aa70-47b8-a036-33ac447e668d"
        },
        "field_id": "field1",
        "function": "Equality",
        "override": null,
        "value": null
      }
    ],
    "policies": [
      "248df4b7-aa70-47b8-a036-33ac447e668d"
    ],
    "problems": [
      {
        "code": "unknown_target_field",
        "message": "string",
        "path": "target_filters.conditions[1].field",
        "severity": "error"
      }
    ],
    "schedule": {
      "connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
      "day_of_month": "1",
      "day_of_week": "1",
      "frequency": "manual",
      "hour": "12",
      "job_id": 1,
      "minute": "30",
      "month": "1",
      "run_after": {
        "bulk_sync_ids": [
          "248df4b7-aa70-47b8-a036-33ac447e668d"
        ],
        "sync_ids": [
          "248df4b7-aa70-47b8-a036-33ac447e668d"
        ]
      },
      "run_after_success_only": true
    },
    "skip_initial_backfill": false,
    "sync_all_records": false,
    "target": {
      "connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
      "configuration": {
        "key": "value"
      },
      "create": {
        "name": "value"
      },
      "object": "Users",
      "filter_logic": "string",
      "new_name": "string",
      "search_values": {
        "name": "value"
      }
    },
    "target_filters": {
      "conditions": [
        {
          "field": "Email",
          "function": "Equality",
          "label": "A",
          "value": null,
          "value_source": {
            "field": "id",
            "model_id": "248df4b7-aa70-47b8-a036-33ac447e668d"
          }
        }
      ],
      "logic": "A and B"
    },
    "updated_at": "2024-01-15T09:30:00Z",
    "updated_by": {
      "id": "12345678-1234-1234-1234-123456789012",
      "name": "John Doe",
      "type": "user"
    },
    "filter_logic": "string",
    "filters": [
      {
        "function": "Equality",
        "field": {
          "field": "id",
          "model_id": "248df4b7-aa70-47b8-a036-33ac447e668d"
        },
        "field_id": "field1",
        "field_type": "Model",
        "label": "A",
        "value": null,
        "value_field": {
          "field": "id",
          "model_id": "248df4b7-aa70-47b8-a036-33ac447e668d"
        }
      }
    ],
    "identity": {
      "function": "Equality",
      "source": {
        "field": "id",
        "model_id": "248df4b7-aa70-47b8-a036-33ac447e668d"
      },
      "target": "name",
      "new_field": true,
      "remote_field_type_id": "string"
    }
  }
}

Updates a model sync’s configuration.

Updating a model sync is a full replacement of the sync’s configuration. Every field in the request body is written to the sync; any field you omit is cleared or reset to its default value. An empty or omitted policies list leaves the sync’s current policies unchanged.

To make a partial change — for example, toggling active or adjusting a single field mapping — fetch the current sync with GET /api/syncs/{id}, modify the fields you want to change, and send the complete object back in the update request.

Updates to active, schedule, and policies take effect immediately. Changes to source fields, target configuration, filters, or field mappings take effect on the sync’s next execution.

Authentication

AuthorizationBearer

Bearer user API key

AuthorizationBasic

Basic organization-scoped API key

Path parameters

idstringRequiredformat: "uuid"

Model sync ID

Request

This endpoint expects an object.

fieldslist of objectsRequired

Fields to sync from source to destination

modeenumRequired

How source records are written to the target

namestringRequired

Name of the model sync

scheduleobjectRequired

Sync schedule. Schedule times are interpreted in UTC.

targetobjectRequired

Sync destination configuration

activebooleanOptional

Whether the sync is enabled and scheduled

encryption_passphrasestringOptional

Passphrase for encrypting the sync data

identitiesobjectOptional

Identity mappings for the sync and the strategy combining them, replacing any the sync has. When this is omitted, ‘identity’ is used instead; updating a sync with more than one mapping requires this property.

model_filtersobjectOptional

Filters narrowing the records read from the source. When either filter object is present it governs both kinds, and an absent object means that kind has no filters.

only_enrich_updatesbooleanOptional

Whether to use enrichment models as a source of possible changes to sync. If true, only changes to the base models will cause a record to sync.

organization_idstring or nullOptionalformat: "uuid"

Ignored for user and organization-scoped API keys, which always act in their own organization

override_fieldslist of objects or nullOptional

Target fields which are set to a fixed value for every record, rather than mapped from a model field

overrideslist of objects or nullOptional

Conditional value replacement for fields

policieslist of strings or nullOptional

Permissions policy IDs applied to the sync. On update, a non-empty list replaces the sync’s policies and an empty or omitted list leaves them unchanged.

skip_initial_backfillbooleanOptional

Whether to skip the initial backfill of records; if true only records seen after the sync is enabled will be synced.

sync_all_recordsbooleanOptional

Whether to sync all records from the source, regardless of whether they've changed since the previous execution

target_filtersobjectOptional

Filters narrowing the records written to the destination. When either filter object is present it governs both kinds, and an absent object means that kind has no filters.

filter_logicstringOptionalDeprecated

Deprecated. Use ‘model_filters.logic’. Combines the model filters in ‘filters’ only.

filterslist of objects or nullOptionalDeprecated

Deprecated. Use ‘model_filters.conditions’ and ‘target_filters.conditions’, which say which kind each condition is rather than inferring it. Ignored when either of those is present, except that a request carrying both shapes is rejected if they describe different filters.

identityobjectOptionalDeprecated

Deprecated. Use 'identities'. Reports and accepts the first identity mapping only.

Response

dataobjectOptional

The model sync

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

500

Internal Server Error

Authentication

Path parameters

Headers

Request

Response

Errors