For this tutorial in video form, click here

You’ve probably used the Insert Record and Update Record API endpoints. But how about upsert?

Upsert means insert if there is no matching record or update the record if there is an existing one. It recognises existing records based on the duplicate check fields of a given module.

If you provide data with an email, phone number or fax that matches an existing Lead, it will just update that lead instead of creating a new one.

Let’s go through an example. First of all we’ll update a record the normal way, supplying a record ID.

A lead with this info already exists, so when we change the email, it’s updated accordingly.

Now let’s change it to upsert, and update the first name:

We can see that “Jumping Jane” got updated to “Dancing Jane”.

Now let’s change the email (which will mean it won’t match the existing record):

Our function will succeed, but we’ll notice in the lead that the email doesn’t change.

Instead it has created a new lead:

We now have two “Dancing Jane” prospects.


This is really useful if you are wanting to synchronize data from another system. For example, we had a project where the client had an existing ERP system and they wanted to synchronize all of their leads, products, and other data in the ERP across the Zoho CRM. We did it using Upsert, because we knew that sometimes the data would change in the ERP, and wanted to update the data in the CRM, while also being able to insert new records. It’s much easier to use Upsert rather than having to do search records first and check if there are any existing records. It’s just a one liner using Upsert records. A very nice feature!

For this tutorial in video form, click here