search then create or update record

Logic for Search before Create or Update

The diagram below illustrates the logic applied when searching for an existing matching record before either updating an existing record or creating a new record.

If a matching ID or record is found, the new record is merged into the existing record as follows:

• Existing field values are updated with the provided values from the merged record. Consider these examples for a phone_number field in the existing record with the value 8675309:
  • If the phone_number field is provided in the merged record, the value from the merged record replaces the existing value, even if it is empty.
  • If the phone_number field is not provided in the merged record, the existing value 8675309value is retained.
• If the merged record contains new fields that are not present in the existing record, those fields are not added to the existing record.

Previewing Results before Creating or Updating a Record

You can preview the results of this operation by setting the dryRun body parameter to true.

Using the Try It Feature

You can use the Try It feature on the right to see a variety of example responses:

• If you use Try It without entering sample input values, it returns a default response with two sample golden records.

• To see an example in which a matching record is found and updated, first use Try It without supplying any sample values to return several sample golden records. Then, either:

  • Match to a recordId value: Use one of the recordId values when submitting another Try It request. This returns a sample response in which the existing record is updated, with "matchType": "ID_MATCH".
  • Match to several field values: Supply two or more of the field values from one of the returned records when submitting another Try It request. This returns a sample response in which the existing record is updated, with "matchType": "SEARCH_MATCH".

• To see an example in which a possible duplicate is identified and a new golden record is created:

  • First use Try It without supplying any sample values to return several sample golden records.
  • Then, supply a single field value from one of the returned records when submitting another Try It request. This returns a sample response in which a new record is created, with "matchType": "POSSIBLE_DUPLICATE".