Upsert records

This API allows you to insert or update a record in Bigin using a single API request. The purpose of this API is to simplify the process of handling record updates and insertions, while also preventing the duplicate records.

To prevent duplicates, the upsert record API depends on the system-defined and/or user-defined unique fields that are used to determine whether a record is already exists in the Bigin. Based on the unique fields match, this API performs the following:

If a matching record is found, the API updates the existing record using the provided data.
If no matching record is found, the API inserts a new record using the provided data.

When using the upsert record API, you provide the data for the record you want to upsert, along with the duplicate check fields. The API then checks if a record is already exists with the duplicate check fields you provided. The duplicate check fields consist of the following:

System-defined unique fields: The system-defined mandatory fields which are marked as unique by default. For more information, see the System-defined mandatory fields for each module in Add Records API.
User-defined unique fields: The fields for which 'Do not allow duplicate values' is assigned. For more information, see Modules and Fields.

Endpoints

POST /{module_api_name}/upsert

Request URL

{api-domain}/bigin/v2/{module_api_name}/upsert

Choose domain-specific URL to replace {api-domain}

You can use the domain-specific URL to access Bigin resources. Based on the data center in which the Bigin account's resources are available, replace {api-domain} in the preceding request with one of the following API domain URLs:

For US, https://www.zohoapis.com
For EU, https://www.zohoapis.eu
For AU, https://www.zohoapis.com.au
For IN, https://www.zohoapis.in
For CN, https://www.zohoapis.com.cn
For JP, https://www.zohoapis.jp

For more information, see Multi DC Support.

Authorization

For this endpoint, pass the access token as an authorization header. See OAuth Authentication for more information about access tokens.

Authorization: Zoho-oauthtoken <ACCESS_TOKEN>

You must authenticate using an access token that is associated with one of the following scopes:

ZohoBigin.modules.ALL
ZohoBigin.modules.{module_name}.ALL
ZohoBigin.modules.{module_name}.WRITE
ZohoBigin.modules.{module_name}.CREATE

In the above scope, replace {module_name} with the module for which you want to retrieve the records. The possible modules include pipelines, contacts, accounts (companies in Bigin), products, calls, events, and tasks.

Notes:

If the length of a field value exceeds the specified maximum length, an error will occur.
If you are using the API inside a Function and the length of a field value exceeds the limit, the Function will receive an error response from the API. For example, if the maximum length for a "Text field" is defined as 10, providing a value like "12345678901" with 11 characters will result an error.
A maximum of 100 records can be upserted per API call.
Use only the Field API names in the input. To obtain the Field API names, you can make use of the Fields metadata API. Look for the value corresponding to the key api_name for each field.

Request parameters

The available request parameters are given below:

Path parameters

module_api_name stringRequired

The API name of the module. The possible modules for this endpoint and their API name are given below:

Module	API Name
Contacts	Contacts
Pipelines	Pipelines
Companies	Accounts
Products	Products
Tasks	Tasks
Events	Events
Calls	Calls

Body parameters

For upserting a record, the request body should contain the parameters specified in the Add records API for each module record. Depending on your specific needs, you can also include the following additional parameters in the request body.

duplicate_check_fields jsonarrayOptional

The list of fields that are used to check for duplicates when updating or inserting records.

To define the order of duplicate record checks, include the duplicate_check_fields array in the request body. This array should contain system-defined and/or user-defined unique fields.

For example, in the Pipelines module:

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

In this case, Deal_Name is a system-defined mandatory field marked as unique by default, while Phone and Fax are user-defined unique fields specific to the Pipelines module.

If no duplicate_check_fields are specified, the API executes duplicate record checks in the following order: system-defined unique fields first, followed by user-defined unique fields.

$append_values jsonobjectOptional

This field is used to control how the values of a multi-select picklist are handled. In this JSON object, provide the API names of multi-select picklist fields as keys and set the corresponding values to either true or false. The values of the keys set to true will be added to the existing values of the picklist field. On the other hand, the values of the keys set to false will replace the existing values with the ones specified in the input.

trigger jsonarrayOptional

The trigger input for the API is workflow. If you do not specify a trigger value, the workflows associated with the API will be executed. To prevent the execution of workflows, provide the trigger value as an empty array, i.e., [ ].

Sample request

Copiedcurl "https://www.zohoapis.com/bigin/v2/Pipelines/upsert" \
-X POST \
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf" \
-d "@upsertrecord.json"

Copiednew_contact = Map();

Sample request body

Copied//Consider the following data is saved in a file 'upsertrecord.json'
{
    "data": [
        {
            "Owner": {
                "id": "2034020000000457001"
            },
            "Sub_Pipeline": "Sales Pipeline Standard",
            "Deal_Name": "Wildlife Safari Package",
            "Contact_Name": {
                "id": "2034020000000478028"
            },
            "Stage": "Proposal/Price Quote",
            "Closing_Date": "2023-08-31",
            "Tag": [
                {
                    "name": "SuperCool"
                }
            ],
            "Description": "Package for brave and adventurous people. Experience the thrill!",
            "Pipeline": {
                "name": "Sales - Marketing",
                "id": "2034020000000095023"
            },
            "duplicate_check_fields": [
			"Deal_Name",
			"Sub_Pipeline",
			"Stage"
            ]
	},
        {
            "Owner": {
                "id": "2034020000000457001"
            },
            "Sub_Pipeline": "Marketing",
            "Deal_Name": "Wildlife Safari Social Media Activity",
            "Contact_Name": {
                "id": "2034020000000478028"
            },
            "Stage": "Campaign Planning",
            "Closing_Date": "2023-11-18",
            "Pipeline": {
                "name": "Sales - Marketing",
                "id": "2034020000000095023"
            },
            "duplicate_check_fields": [
			"Deal_Name",
			"Sub_Pipeline",
			"Stage"
            ]
	}
	]
}

Copiednew_contact = Map();

Response object

The response object provides information regarding the success message or status.

Possible error codes

The response of this resource includes HTTP status and error codes.

Sample response

Copied{
    "data": [
        {
            "code": "SUCCESS",
            "duplicate_field": "Deal_Name",
            "action": "update",
            "details": {
                "Modified_Time": "2023-07-14T12:47:23+05:30",
                "Modified_By": {
                    "name": "Zylker Travels",
                    "id": "2034020000000457001"
                },
                "Created_Time": "2023-04-19T15:54:21+05:30",
                "id": "2034020000000478276",
                "Created_By": {
                    "name": "Zylker Travels",
                    "id": "2034020000000457001"
                }
            },
            "message": "record updated",
            "status": "success"
        },
        {
            "code": "SUCCESS",
            "duplicate_field": null,
            "action": "insert",
            "details": {
                "Modified_Time": "2023-07-14T12:47:22+05:30",
                "Modified_By": {
                    "name": "Zylker Travels",
                    "id": "2034020000000457001"
                },
                "Created_Time": "2023-07-14T12:47:22+05:30",
                "id": "2034020000000683017",
                "Created_By": {
                    "name": "Zylker Travels",
                    "id": "2034020000000457001"
                },
                "$approval_state": "approved"
            },
            "message": "record added",
            "status": "success"
        }
    ]
}

Sample request body

Copied//Consider the following data is saved in a file 'upsertrecord.json'
{
    "data": [
        {
            "Owner": {
                "id": "2034020000000457001"
            },
            "Sub_Pipeline": "Sales Pipeline Standard",
            "Deal_Name": "Wildlife Safari Package",
            "Contact_Name": {
                "id": "2034020000000478028"
            },
            "Stage": "Proposal/Price Quote",
            "Closing_Date": "2023-08-31",
            "Tag": [
                {
                    "name": "SuperCool"
                }
            ],
            "Description": "Package for brave and adventurous people. Experience the thrill!",
            "Pipeline": {
                "name": "Sales - Marketing",
                "id": "2034020000000095023"
            },
            "duplicate_check_fields": [
			"Deal_Name",
			"Sub_Pipeline",
			"Stage"
            ]
	},
        {
            "Owner": {
                "id": "2034020000000457001"
            },
            "Sub_Pipeline": "Marketing",
            "Deal_Name": "Wildlife Safari Social Media Activity",
            "Contact_Name": {
                "id": "2034020000000478028"
            },
            "Stage": "Campaign Planning",
            "Closing_Date": "2023-11-18",
            "Pipeline": {
                "name": "Sales - Marketing",
                "id": "2034020000000095023"
            },
            "duplicate_check_fields": [
			"Deal_Name",
			"Sub_Pipeline",
			"Stage"
            ]
	}
	]
}

Copiednew_contact = Map();