---
updatedAt: 2026-06-02T20:36:34.000Z
agentTools:
  projectIndex: https://cloud.docs.tamr.com/llms.txt
---

# unmerge

Unmerges the specified record based on history

When unmerging a record (“undoing” the merge of two records), you must specify the record ID (`recordId`) on which to perform the unmerge action.

Optionally, you can:

* Preview unmerge results by setting the `dryRun` parameter to true.
* Specify the `expectedVersion`of the record to ensure that you are working from the latest version of the record.
* Specify the record version on which to perform the unmerge (`versionToUnmerge`). If you do not provide the version, Tamr performs the unmerge on the most recent version of the record.
* Specify the version of the record data to retain after the merge (`versionIdOfRecordDataToRetain`). The retained record will have the exact data of this version after the unmerge. If you do not provide the version, Tamr retains the data of the record  version prior to merge.

<br />

To obtain the  `versionId` for a given record, use the `get` operation to retrieve the record: `GET v1alpha1/tables/{tableId}/records/{recordId}`. The `versionId` is returned in the response.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Records",
    "version": "v1alpha1"
  },
  "tags": [
    {
      "name": "tamr.api.v1alpha1.Records"
    }
  ],
  "paths": {
    "/api/v1alpha1/tables/{tableId}/records/{recordId}:unmerge": {
      "post": {
        "summary": "unmerge",
        "description": "Unmerges the specified record based on history",
        "operationId": "Records_UnmergeRecords",
        "responses": {
          "200": {
            "description": "A successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/tamr.api.v1alpha1.UnmergeRecordsResponse"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "tableId",
            "description": "Required. The table that the records belong to.",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "recordId",
            "description": "Required. The record to unmerge.",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/tamr.api.v1alpha1.Records.UnmergeRecordsBody"
              }
            }
          },
          "required": true
        },
        "tags": [
          "tamr.api.v1alpha1.Records"
        ]
      }
    }
  },
  "x-readme": {
    "headers": [
      {
        "key": "X-API-KEY",
        "value": "example-api-key"
      }
    ]
  },
  "servers": [
    {
      "url": "https://api-examples.tamr.cloud"
    }
  ],
  "components": {
    "schemas": {
      "tamr.api.v1alpha1.ChangeType": {
        "type": "string",
        "enum": [
          "CHANGE_TYPE_UNSET",
          "CREATE",
          "UPDATE",
          "DELETE"
        ],
        "default": "CHANGE_TYPE_UNSET",
        "title": "- CHANGE_TYPE_UNSET: DO NOT USE"
      },
      "tamr.api.v1alpha1.DataChangeEvent": {
        "type": "object",
        "properties": {
          "tableId": {
            "type": "string"
          },
          "recordId": {
            "type": "string"
          },
          "versionId": {
            "type": "string",
            "format": "uint64",
            "description": "Unique ID for the logical operation."
          },
          "changeType": {
            "description": "The type of the physical change.",
            "allOf": [
              {
                "$ref": "#/components/schemas/tamr.api.v1alpha1.ChangeType"
              }
            ]
          },
          "recordNumber": {
            "type": "integer",
            "format": "int64",
            "description": "Zero-based ordinal uniquely identifying the record within the logical operation."
          },
          "newData": {
            "type": "object",
            "description": "The new record data after the change."
          },
          "commitTime": {
            "type": "string",
            "format": "date-time",
            "description": "When the change was committed to storage."
          },
          "user": {
            "description": "The user who committed the change.",
            "allOf": [
              {
                "$ref": "#/components/schemas/tamr.api.v1alpha1.User"
              }
            ]
          },
          "mergeMetadata": {
            "$ref": "#/components/schemas/tamr.api.v1alpha1.MergeMetadata"
          },
          "unmergeMetadata": {
            "$ref": "#/components/schemas/tamr.api.v1alpha1.UnmergeMetadata"
          },
          "enrichMetadata": {
            "$ref": "#/components/schemas/tamr.api.v1alpha1.EnrichMetadata"
          }
        },
        "description": "Describes a change made to a single record and the context for the change."
      },
      "tamr.api.v1alpha1.EnrichMetadata": {
        "type": "object",
        "description": "empty for now."
      },
      "tamr.api.v1alpha1.MergeMetadata": {
        "type": "object",
        "properties": {
          "survivingRecordId": {
            "type": "string"
          },
          "retiredRecordIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "tamr.api.v1alpha1.Record": {
        "type": "object",
        "properties": {
          "tableId": {
            "type": "string",
            "description": "The table that the record belongs to."
          },
          "recordId": {
            "type": "string",
            "description": "The identifier for the record."
          },
          "versionId": {
            "type": "string",
            "format": "int64",
            "description": "Output only. The current version of the record.",
            "readOnly": true
          },
          "createTime": {
            "type": "string",
            "format": "date-time",
            "description": "Output only. The time at which the record was created.",
            "readOnly": true
          },
          "updateTime": {
            "type": "string",
            "format": "date-time",
            "description": "Output only. The time at which the record was last updated.",
            "readOnly": true
          },
          "data": {
            "type": "object",
            "description": "The contents of the record."
          }
        },
        "description": "Represents a record that has been published for data access."
      },
      "tamr.api.v1alpha1.Records.UnmergeRecordsBody": {
        "type": "object",
        "properties": {
          "expectedVersion": {
            "description": "The expected version of the record.\nIf specified, operation is performed only if the current of the record matches this.",
            "allOf": [
              {
                "$ref": "#/components/schemas/tamr.api.v1alpha1.VersionValidation"
              }
            ]
          },
          "versionToUnmerge": {
            "type": "string",
            "format": "int64",
            "description": "The version of the merge to revert.\nIf not provided, will attempt to unmerge from the most recent version of the record id."
          },
          "dryRun": {
            "type": "boolean",
            "description": "Optional. Return the result of unmerge without applying it. Default is false."
          },
          "versionIdOfRecordDataToRetain": {
            "type": "string",
            "format": "int64",
            "description": "Optional. The version of the record data to retain after unmerge.\nThe retained record will have the exact data of this version after unmerge when specified.\nBy default will retain the data of the record prior to merge."
          }
        }
      },
      "tamr.api.v1alpha1.UnmergeMetadata": {
        "type": "object",
        "properties": {
          "retainedRecordId": {
            "type": "string"
          },
          "resurrectedRecordId": {
            "type": "string"
          }
        }
      },
      "tamr.api.v1alpha1.UnmergeRecordsResponse": {
        "type": "object",
        "properties": {
          "records": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/tamr.api.v1alpha1.Record"
            }
          },
          "details": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/tamr.api.v1alpha1.UnmergeRecordsResponse.Detail"
            }
          }
        }
      },
      "tamr.api.v1alpha1.UnmergeRecordsResponse.Detail": {
        "type": "object",
        "properties": {
          "dataChangeEvent": {
            "description": "The events taken by the system in response to the unmerge.\nIf dry_run is true, this is the set of events that would be taken.",
            "allOf": [
              {
                "$ref": "#/components/schemas/tamr.api.v1alpha1.DataChangeEvent"
              }
            ]
          }
        }
      },
      "tamr.api.v1alpha1.User": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "string",
            "description": "The unique identifier of the user."
          },
          "email": {
            "type": "string",
            "description": "The email address of the user."
          }
        }
      },
      "tamr.api.v1alpha1.VersionValidation": {
        "type": "object",
        "properties": {
          "versionId": {
            "type": "string",
            "format": "int64"
          }
        }
      }
    }
  }
}
```