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

# merge

Merges a record with another record.

When merging two records, you must specify which record will be the surviving record (`toRecordId`) and which record will be retired (`fromRecordId`).

All links associated with the retired record become associated with the surviving record; references to the retired record return the surviving record.

By default, the surviving record is updated with values from the merged record.  For more information about merge options, see [tamr.api.v1alpha1.Records](https://cloud.docs.tamr.com/tamr-cloud/reference/tamrapiv1alpha1records).

Optionally, you can:

* Preview merge results by setting the `dryRun` parameter to `true`.
* Choose to disable the merge rules in order to retain all current values in the surviving record when merging.
  * Set `disableMergeRules` to `true` to retain all current values in the surviving record when merging.
  * Set `disableMergeRules` parameter to `false` (default) to update values in the surviving record with values from the merged record (including replacing existing values in the surviving record with null values from the merged record).
* Replace all field values in the surviving record by supplying field (key)/value pairs in the `data` object.
* Supply the `expectedVersions` of the surviving and retired record to ensure that you are working from the latest versions of both records.

<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:merge": {
      "post": {
        "summary": "merge",
        "description": "Merges a record with another record.",
        "operationId": "Records_MergeRecords",
        "responses": {
          "200": {
            "description": "A successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/tamr.api.v1alpha1.MergeRecordsResponse"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "tableId",
            "description": "Required. The table that the records belong to.",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/tamr.api.v1alpha1.Records.MergeRecordsBody"
              }
            }
          },
          "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.MergeRecordsRequest.MergeDataOptions": {
        "type": "object",
        "properties": {
          "merge": {
            "description": "Configure use of merge rules.",
            "allOf": [
              {
                "$ref": "#/components/schemas/tamr.api.v1alpha1.MergeRecordsRequest.MergeDataOptions.Merge"
              }
            ]
          },
          "replace": {
            "description": "Instead of using merge rules, replace data in surviving record with what is provided.",
            "allOf": [
              {
                "$ref": "#/components/schemas/tamr.api.v1alpha1.MergeRecordsRequest.MergeDataOptions.Replace"
              }
            ]
          }
        }
      },
      "tamr.api.v1alpha1.MergeRecordsRequest.MergeDataOptions.Merge": {
        "type": "object",
        "properties": {
          "disableMergeRules": {
            "type": "boolean",
            "description": "Optional. If true, the merge rules are disabled and the surviving data is left unchanged.\nIf false, the merge rules are used. Default is false."
          }
        }
      },
      "tamr.api.v1alpha1.MergeRecordsRequest.MergeDataOptions.Replace": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "description": "Optional. If set, the data in the surviving record will be replaced with this data.\nIf not set, the merge rules are used unless disabled."
          }
        }
      },
      "tamr.api.v1alpha1.MergeRecordsRequest.VersionValidations": {
        "type": "object",
        "properties": {
          "fromVersion": {
            "description": "The expected versions of the records to be merged\nIf specified, operation is performed only if the current of the records\nboth match the specified versions.",
            "allOf": [
              {
                "$ref": "#/components/schemas/tamr.api.v1alpha1.VersionValidation"
              }
            ]
          },
          "toVersion": {
            "$ref": "#/components/schemas/tamr.api.v1alpha1.VersionValidation"
          }
        }
      },
      "tamr.api.v1alpha1.MergeRecordsResponse": {
        "type": "object",
        "properties": {
          "record": {
            "description": "The resulting record after merge.\nIf dry_run was set to true then the\nversion_id, create_time, and update_time fields\nfor the returned record will be empty.",
            "allOf": [
              {
                "$ref": "#/components/schemas/tamr.api.v1alpha1.Record"
              }
            ]
          }
        }
      },
      "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.MergeRecordsBody": {
        "type": "object",
        "properties": {
          "toRecordId": {
            "type": "string",
            "description": "Required. The record id for the record to survive when merging."
          },
          "fromRecordId": {
            "type": "string",
            "description": "Required. The record id to retire when merging. Their links will be added to the surviving record."
          },
          "mergeData": {
            "description": "Options for how to update surviving record data.\nBy default, pre-configured merge rules for the table are applied to the data of the surviving record.",
            "allOf": [
              {
                "$ref": "#/components/schemas/tamr.api.v1alpha1.MergeRecordsRequest.MergeDataOptions"
              }
            ]
          },
          "expectedVersions": {
            "$ref": "#/components/schemas/tamr.api.v1alpha1.MergeRecordsRequest.VersionValidations"
          },
          "dryRun": {
            "type": "boolean",
            "description": "Optional. Return the result of merge on the values of the data being merged without applying it. Default is false."
          }
        },
        "required": [
          "toRecordId",
          "fromRecordId"
        ]
      },
      "tamr.api.v1alpha1.VersionValidation": {
        "type": "object",
        "properties": {
          "versionId": {
            "type": "string",
            "format": "int64"
          }
        }
      }
    }
  }
}
```