Insert or Update Records (Upsert)

Note

• When using the Upsert API, the system verifies records for duplicates based on duplicate check fields. There are two types of duplicate check fields:
  • System-Defined Duplicate Check Fields
    • These are predefined unique fields in each module.
    • The system automatically checks these fields to prevent duplicate entries.
    • Refer to the System-Defined Duplicate Check Fields section for module-wise details.
  • User-Defined Unique Fields
    • These are fields where the option "Do not allow duplicate values" is enabled.
    • Users can define custom unique fields to prevent duplicate data.
    • Learn more about enabling Mark a Field as Unique.

When a record is upserted, the system first checks for duplicates in these fields. If a matching record exists, it gets updated; otherwise, a new record is inserted.

• You can set the order in which the system verifies duplicate records using the duplicate_check_fields array in your API request.
  • Allowed Fields:
    • System-defined duplicate check fields. For example, Email for Leads.
    • User-defined unique fields. For example, Phone and Fax.

            Example: In the Leads module:

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

       If you do not specify duplicate_check_fields, the system follows this default order:

          i. System-defined duplicate check fields
          ii. User-defined unique fields

• The 'INVALID_DATA' error is thrown if the field value length is more than 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.
• Refer to our Kaizen post: Upsert Records API and Duplicate Check Preferences API vs. Upsert API, for more details with real-time use cases.
• 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 inserted or updated to CRM using the Records API. Refer to Subforms API to learn more about adding subform information within a record. For detailed information on subforms, refer to our Kaizen post : Manipulating Subform using Zoho CRM APIs.
• 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.
• 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