Use the Records endpoint to:

  • List all records in a table, or filter results to records with exact attribute values, specified as key/value pairs.
    To filter results matching similar attribute values instead of exact attribute values, use the Search endpoint.
  • Get a record by a specified current or historical record Id.
  • Create a new record.
    To avoid creating duplicate records, you can use Search then create or update record endpoint to search for a matching record before creating a new record.
  • Update an existing record.
  • Delete an existing record.
  • Merge two existing records into a single surviving record.

All calls to this endpoint require a tableId value; please contact Tamr at [email protected] for the correct value.

Options for Merging Records

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.

Default Merge Rules

By default, the surviving record is updated with values from the retired record.

Record-Level Merge Options

Optionally, you can:

  • 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 retired 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.

Attribute-level Merge Rules

You can also work with Tamr to configure specific merge rules for individual attributes.

You can specify one merge rule per attribute, and each rule can have a number of conditions to determine which value is retained when records are merged. Multiple conditions can be applied within the same rule with an order or precedence. You can also choose whether values from the retired or surviving record are used in the event of a tie.

The most common conditions to use in rules are:

  • Select non-null value: Retain the non-blank/non-null value

  • Preferred source: Retain the value from the record from the preferred source. You can specify the rank order for the sources. To use this condition, the records must include an attribute with the source name.

  • Most recent: Retain the value from the record with the most recent timestamp. To use this condition, the records must include an attribute with ISO 8601 timestamp values.

If you are interested in configuring attribute-level merge rules, contact Tamr at [email protected].

Examples: Attribute-Level Merges

Select non-null value

In this example, the middle_name value after merge is Jane.

recordIdmiddle_name
1blank
2Jane

Preferred source

In this example, the preferred source is salesforce. The middle_name value after merge is blank.

recordIdsource_namemiddle_name
1salesforceblank
2other_crmJane

Most recent

In this example, the middle_name value after merge is Jane.

recordIdtimestampmiddle_name
12024-07-23T15:01:31.759Zblank
22024-09-05T18:45:01.759ZJane

Multiple conditions

In this rule for middle_name, the following conditions are applied, in this order:

  1. Select non-null value
  2. Preferred source: salesforce
  3. Most recent

Example 1

In this example, the middle_name value after merge is Jayne.

recordIdsource_nametimestampmiddle_name
1salesforce2024-07-23T15:01:31.759ZJayne
2other_crm2024-09-05T18:45:01.759ZJane

First, Tamr checks for non-null values. Because both records have a middle name value, Tamr considers the next rule.

Second, Tamr checks whether the records are from the preferred source. Because record 1 is from the preferred salesforce source, Tamr selects Jayne as the middle_name value.

Example 2

In this example, the middle_name value after merge is Jane.

recordIdsource_nametimestampmiddle_name
1salesforce2024-07-23T15:01:31.759ZJayne
2salesforce2024-09-05T18:45:01.759ZJane

First, Tamr checks for non-null values. Because both records have a middle name value, Tamr considers the next rule.

Second, Tamr checks whether the records are from the preferred source. Because both records are from the preferred salesforce source, Tamr considers the next rule.

Third, Tamr checks the timestamp to identify the most recent record. Because record 2 is more recent, Tamr selects Jane as the middle_name value.