Insert or Update Records (Upsert)

Note

• The system checks for duplicate records based on the duplicate check field's values. There are two types of duplicate check fields:
  • The system-defined duplicate check fields - Certain system-generated fields are marked as unique, by default. When you upsert a record, the system checks for duplicate entries in these fields. Refer to System-defined Duplicate Check Fields section below to know the module-wise system-defined duplicate check fields.
  • The user-defined unique fields - The fields for which "Do not allow duplicate values" is enabled. Click here to know more.

• You can set the order in which the system checks for duplicate records by specifying the duplicate_check_field array in the input. Note that you can add only system-defined duplicate check fields and user-defined unique fields to the duplicate_check_field array.

  Example for the Leads module:

  "duplicate_check_fields": [
  "Email",
  "Phone",
  "Fax"
  ]

  Here, "Email" is the system-defined duplicate check field, and "Phone" and "Fax" are the user-defined unique fields for the Leads module.

• If you do not specify the duplicate_check_fields, the system checks for duplicate records in this order: system-defined duplicate check fields > user-defined unique fields..
• The 'INVALID_DATA' error is thrown if the field value length exceeds the maximum length defined for that field.
• If an API is used inside a Function and the field value length exceeds the limit, then that function receives an error response from the API. For ex: If the max length for a "Text field" is defined as 10, then value given for it in API cannot be "12345678901", since it has 11 characters.
• A maximum of 100 records can be inserted/updated per API call.
• You must use only Field API names in the input. You can obtain the field API names from
  • Fields metadata API (the value for the key “api_name” for every field). (Or)
  • Setup > Developer Hub > APIs and SDKs > API Names > {Module}. Choose “Fields” from the “Filter By” drop-down.
• The trigger input can be workflow, approval, or blueprint. If the trigger is not mentioned, the workflows, approvals and blueprints related to the API will get executed. Enter the trigger value as [] to not execute the workflows.
• Records with Subform details can also be updated to CRM using the Records API. Please look at Subforms API to learn more about updating subform information within a record.
• Refer to Get Records API to know more about field types and limits.
• The $append_values key represents whether you want to append the values of the multi-select picklist you specified in the input to the existing values. Specify the API names of the multi-select picklists and "true" or "false" as key-value pairs in this JSON object. The value "true" adds the values in the input to the multi-select picklist, while the value "false" replaces the existing values with the ones in the input.
• The apply_feature_execution array allows you to apply an existing layout rule when you create or update a record. Layout rules allow you to show a section, certain fields, set mandatory fields, or show a subform. However, you can only trigger the "Set Mandatory Field" option through the API.
  Specify the value layout_rules for the key name to apply a layout rule to the record. Note that you must give this key parallel to "data".
  Ensure that the input body includes all the keys required to satisfy the criteria in the layout rule. The system throws an error, otherwise. For example, if the layout rule triggers when the Lead_Source is Employee Referral, and you have mandated the Company field, then the system throws the MANDATORY_NOT_FOUND error if you fail to give the Company key in the input.
• You must provide the layout ID field if you want to
  • include the layout specific mandatory fields in the API-level mandatory check
  • include only the fields that are defined in your layout for API- level processing and ignore the rest