---
title: "Replace the mappings document"
method: PUT
path: "/v1/sync/syncs/{sync_id}/mappings"
tags: ["Mappings"]
---

# Replace the mappings document

`PUT /v1/sync/syncs/{sync_id}/mappings`

## Request

- Base URL: `https://api.whalesync.com`
- URL: `https://api.whalesync.com/v1/sync/syncs/{sync_id}/mappings`
- Auth: HTTP bearer

Full replace: anything omitted is unmapped, omitted settings revert to defaults — fetch-modify-put is the intended editing pattern. `{"create": {"name": "…"}}` placeholders create the table/field on that side, typed from the mapped counterpart; retries safely adopt already-created objects. Referenced tables whose fields were never fetched are fetched during the call, so a first PUT can take a few seconds. Any change returns the sync to `draft` for a human to review and start. The read-only `filter` and `advanced_settings` a GET reports are ignored here and keep their stored values — they are edited in the app.

## Path parameters

- `sync_id` string, required

## Headers

- `Idempotency-Key` string
- `If-Match` string

## Request body

- MappingsDocument
  - `tables` MappingTable[], required: The mapped table pairs. Anything omitted is unmapped; omitted settings revert to defaults.
    - `left_table` union, required
      - string: An existing table/field: remote id, prefixed id, or exact name when unambiguous.
      - CreatePlaceholder
        - `create` object, required
          - `name` string, required
    - `right_table` union, required
      - string: An existing table/field: remote id, prefixed id, or exact name when unambiguous.
      - CreatePlaceholder
        - `create` object, required
          - `name` string, required
    - `direction` 'left_to_right' | 'right_to_left' | 'two_way', required: Writes take these three values. A read can additionally show `"invalid"` when schema drift has disabled every allowed direction for the pair — fix the mapping and PUT it back with a real direction.
    - `left` MappingSideSettings
      - `record_delete_behavior` 'sync' | 'do_nothing': What a deletion on the other side does to records in this table. Omitted = `sync`. `do_nothing` is Delete Protection for this table — records here survive the other side deleting theirs. See https://docs.whalesync.com/features/additional-features/delete-protection.
      - `view` string: The view to sync, by value from the table's `views.options`. REQUIRED whenever the table reports `views` (Airtable, Salesforce); use `"ALL_RECORDS"` for the whole table. Omitting it on a PUT clears any prior selection rather than keeping it.
    - `right` MappingSideSettings
      - `record_delete_behavior` 'sync' | 'do_nothing': What a deletion on the other side does to records in this table. Omitted = `sync`. `do_nothing` is Delete Protection for this table — records here survive the other side deleting theirs. See https://docs.whalesync.com/features/additional-features/delete-protection.
      - `view` string: The view to sync, by value from the table's `views.options`. REQUIRED whenever the table reports `views` (Airtable, Salesforce); use `"ALL_RECORDS"` for the whole table. Omitting it on a PUT clears any prior selection rather than keeping it.
    - `fields` MappingField[], required
      - `left_field` union, required
        - string: An existing table/field: remote id, prefixed id, or exact name when unambiguous.
        - CreatePlaceholder
          - `create` object, required
            - `name` string, required
      - `right_field` union, required
        - string: An existing table/field: remote id, prefixed id, or exact name when unambiguous.
        - CreatePlaceholder
          - `create` object, required
            - `name` string, required
      - `direction` 'left_to_right' | 'right_to_left' | 'two_way': Defaults to the table's direction; must be a subset of it.
    - `advanced_settings` MappingAdvancedSetting[]: Read-only. The pair's advanced settings that are off their default and cannot be set through the API — delay before syncing, row-level sync, and connector-specific per-table options. Absent when there are none, and ignored on write: these are edited on the Advanced settings tab in the app. Delete protection is not here; it is `record_delete_behavior` above.
      - `setting` 'delay_before_syncing' | 'row_level_sync' | 'connector_option', required: `delay_before_syncing` = changes wait out a quiet period before syncing; `row_level_sync` = only records whose sync-enabled field is true sync out of this table; `connector_option` = a per-table choice the connector asks for.
      - `side` 'left' | 'right', required: The table the setting is on.
      - `value` union, required: Seconds for `delay_before_syncing`, the sync-enabled field's remote id for `row_level_sync`, the chosen values otherwise.
        - number
        - string
        - string[]
      - `description` string, required: What the setting does here, in one sentence — safe to relay to a person.
      - `docs_url` string, uri: The docs page for this setting, where one exists.
    - `filter` MappingFilter
      - `match` 'all' | 'any', required: Whether every condition must pass, or just one.
      - `conditions` union[], required: Conditions, or nested groups.
        - union
          - MappingFilterCondition
            - `left_field` string, nullable, required: The tested field on the left side; null when the field mapping it referenced is gone.
            - `right_field` string, nullable, required: The same field on the right side.
            - `operator` 'equals' | 'not_equals' | 'greater_than' | 'greater_than_or_equal' | 'less_than' | 'less_than_or_equal' | 'contains' | 'not_contains' | 'is_empty' | 'is_not_empty' | 'is_any_of' | 'is_none_of', required
            - `value` string[]: Absent for `is_empty`/`is_not_empty`; several values for `is_any_of`/`is_none_of`.
            - `value_type` 'string' | 'number' | 'boolean' | 'date' | 'datetime', required: How the values are compared.
          - MappingFilterGroup
            - `match` 'all' | 'any', required: Whether every condition must pass, or just one.
            - `conditions` union[], required: Conditions, or nested groups.
              - …
      - `summary` string, required: The whole filter as one sentence — safe to relay to a person.
      - `docs_url` string, uri, required

## Response `200`

The resolved document, with created objects under their real remote ids.

- MappingsDocument
  - `tables` MappingTable[], required: The mapped table pairs. Anything omitted is unmapped; omitted settings revert to defaults.
    - `left_table` union, required
      - string: An existing table/field: remote id, prefixed id, or exact name when unambiguous.
      - CreatePlaceholder
        - `create` object, required
          - `name` string, required
    - `right_table` union, required
      - string: An existing table/field: remote id, prefixed id, or exact name when unambiguous.
      - CreatePlaceholder
        - `create` object, required
          - `name` string, required
    - `direction` 'left_to_right' | 'right_to_left' | 'two_way', required: Writes take these three values. A read can additionally show `"invalid"` when schema drift has disabled every allowed direction for the pair — fix the mapping and PUT it back with a real direction.
    - `left` MappingSideSettings
      - `record_delete_behavior` 'sync' | 'do_nothing': What a deletion on the other side does to records in this table. Omitted = `sync`. `do_nothing` is Delete Protection for this table — records here survive the other side deleting theirs. See https://docs.whalesync.com/features/additional-features/delete-protection.
      - `view` string: The view to sync, by value from the table's `views.options`. REQUIRED whenever the table reports `views` (Airtable, Salesforce); use `"ALL_RECORDS"` for the whole table. Omitting it on a PUT clears any prior selection rather than keeping it.
    - `right` MappingSideSettings
      - `record_delete_behavior` 'sync' | 'do_nothing': What a deletion on the other side does to records in this table. Omitted = `sync`. `do_nothing` is Delete Protection for this table — records here survive the other side deleting theirs. See https://docs.whalesync.com/features/additional-features/delete-protection.
      - `view` string: The view to sync, by value from the table's `views.options`. REQUIRED whenever the table reports `views` (Airtable, Salesforce); use `"ALL_RECORDS"` for the whole table. Omitting it on a PUT clears any prior selection rather than keeping it.
    - `fields` MappingField[], required
      - `left_field` union, required
        - string: An existing table/field: remote id, prefixed id, or exact name when unambiguous.
        - CreatePlaceholder
          - `create` object, required
            - `name` string, required
      - `right_field` union, required
        - string: An existing table/field: remote id, prefixed id, or exact name when unambiguous.
        - CreatePlaceholder
          - `create` object, required
            - `name` string, required
      - `direction` 'left_to_right' | 'right_to_left' | 'two_way': Defaults to the table's direction; must be a subset of it.
    - `advanced_settings` MappingAdvancedSetting[]: Read-only. The pair's advanced settings that are off their default and cannot be set through the API — delay before syncing, row-level sync, and connector-specific per-table options. Absent when there are none, and ignored on write: these are edited on the Advanced settings tab in the app. Delete protection is not here; it is `record_delete_behavior` above.
      - `setting` 'delay_before_syncing' | 'row_level_sync' | 'connector_option', required: `delay_before_syncing` = changes wait out a quiet period before syncing; `row_level_sync` = only records whose sync-enabled field is true sync out of this table; `connector_option` = a per-table choice the connector asks for.
      - `side` 'left' | 'right', required: The table the setting is on.
      - `value` union, required: Seconds for `delay_before_syncing`, the sync-enabled field's remote id for `row_level_sync`, the chosen values otherwise.
        - number
        - string
        - string[]
      - `description` string, required: What the setting does here, in one sentence — safe to relay to a person.
      - `docs_url` string, uri: The docs page for this setting, where one exists.
    - `filter` MappingFilter
      - `match` 'all' | 'any', required: Whether every condition must pass, or just one.
      - `conditions` union[], required: Conditions, or nested groups.
        - union
          - MappingFilterCondition
            - `left_field` string, nullable, required: The tested field on the left side; null when the field mapping it referenced is gone.
            - `right_field` string, nullable, required: The same field on the right side.
            - `operator` 'equals' | 'not_equals' | 'greater_than' | 'greater_than_or_equal' | 'less_than' | 'less_than_or_equal' | 'contains' | 'not_contains' | 'is_empty' | 'is_not_empty' | 'is_any_of' | 'is_none_of', required
            - `value` string[]: Absent for `is_empty`/`is_not_empty`; several values for `is_any_of`/`is_none_of`.
            - `value_type` 'string' | 'number' | 'boolean' | 'date' | 'datetime', required: How the values are compared.
          - MappingFilterGroup
            - `match` 'all' | 'any', required: Whether every condition must pass, or just one.
            - `conditions` union[], required: Conditions, or nested groups.
              - …
      - `summary` string, required: The whole filter as one sentence — safe to relay to a person.
      - `docs_url` string, uri, required

## Other responses

- `400`: The document is invalid: a structural problem or unknown reference names its JSON-pointer `path` in the message (`unknown_table`, `unknown_field`, `table_ambiguous`, `view_required`, `view_not_found`, `view_not_supported`); `invalid_mappings` carries the per-field problems in `details.issues`; a `create` that the connector refused is `create_failed`; a mapped table the connector could not prepare for syncing (some add a Whalesync ID column first) is `table_setup_failed`; an `Idempotency-Key` reused with a different body is `idempotency_key_reused`.
- `401`: The API key is missing, invalid, or revoked (`missing_api_key`, `invalid_api_key`). Carries a `required_action` linking a person to key creation, naming the smallest scope this endpoint needs.
- `403`: The key's scope does not allow this call (`insufficient_scope` on a mutation with a `read` key).
- `404`: No such sync on this account.
- `409`: A person has to act first (`requires_action`): the error carries `required_action` — relay its `instruction` and `url` to a human, then retry. Also `sync_active` (pause before editing) and `idempotency_key_in_use` (the first request is still running).
- `412`: The `If-Match` revision is no longer current (`revision_mismatch`).
- `429`: Rate limit exceeded. Wait for `Retry-After` seconds.

---

[API](https://skmtc.dev/whalesync/apis/whalesync-api.md) · [All operations](https://skmtc.dev/whalesync/apis/whalesync-api/llms.txt) · [OpenAPI document](https://skmtc.dev/whalesync/apis/whalesync-api/revisions/5131522b325a?raw)