💡 This article is for you if…  
1. You want a quick start alternative to sifting through all the Zoho documentation.  
2. You’ve built your Zoho integration already but want to learn about common gotchas, best practices, and techniques to make your integration more robust.  
3. You want a convenient summary of everything you need to know to build a Zoho documentation (how to build Auth, rate limits, etc)

Zoho is a comprehensive suite of cloud-based business software that provides solutions for CRM, accounting, HR, project management, and more. Building a customer-facing integration with Zoho is a must if your product needs to interface with business data.

‍
However, building a Zoho integration can be challenging due to the complexity of its API. Fortunately, we’ve already gone through the process of building and maintaining a Zoho integration and have distilled our knowledge and best practices into this guide.

‍
If you’re unfamiliar with what native integrations are, you can reference our previous blog post, What Are Native Integrations, to get a better understanding of the concept.

‍
In this guide, I'll be using the Vessel SDK to build the Zoho integration which will simplify the authentication process and handle any Zoho API quirks.

‍
If you don’t want to use Vessel, no worries, I’ve kept this guide as generic as possible and it’ll be useful regardless of how you decide to build your native Zoho integration.

Getting Setup For Your Zoho Integration

Before you start writing code for your Zoho integration, there are a few logistical steps you'll need to complete.

Create a Developer Account

To get started, you'll need to create a developer account with Zoho. This account will allow you to access the necessary resources and tools for building your Zoho integration.

‍
🔗 You can create a developer account by visiting the Zoho Developer Portal‍

Create a Zoho OAuth App

If you're using Vessel, you can skip this step as we provide a pre-approved Zoho application that you can use. However, if you're not using Vessel, you'll need to create your own OAuth app.

This app will allow you to authenticate users and access their Zoho data. To create an OAuth app, follow these steps:

• Visit the API console here
• Click on “Server-based Applications” since we’re going to authenticate from a Server

• Create a New Client, you can set the Redirect URI to localhost

Make sure to take note of the "Client ID" and "Client Secret" generated for your app, as you'll need these later for authentication.

The Zoho API at a Glance

Before diving into the details of building a Zoho integration, let's take a quick overview of some important aspects of the Zoho API.

Authentication

The first step to making an API call is to ask your user for permission to access their data. We do this by “installing” the OAuth app we created inside of their CRM instance.

During this process, your user will be shown a popup window that asks them to grant you permission to read and write their data.

OAuth is a complicated and nuanced topic, for brevity, I’m not going to touch on how to build out an OAuth flow since it’s not Zoho-specific.

If you’re new to OAuth and just need to get something going fast or don’t want to deal with the notorious headache of OAuth, you can use a framework like Vessel to handle it for you.

If you’d prefer to do this yourself, you can read Zoho tutorial on OAuth which is pretty thorough. Forewarning, the Zoho tutorial is very Zoho specific so if you know you’ll need to build other integrations in the future, I’d invest in doing more research so you understand how to build a more generic Auth flow since OAuth is an infamously difficult problem.

Regardless of how you choose to build authentication, the important part is that you’re able to get an accessToken for your user. The accessToken is what will allow us to pull and push data to the user's Zoho instance.

Making an API Call

With the authentication process in place, you can now start making API calls to your customer’s Zoho CRM. In this section, we'll explore how to read and write data to the Zoho API in real-time.

Reading From the API

When reading data from the Zoho API, there are a few things to keep in mind.

• Pagination: Zoho API responses are paginated, meaning you'll need to make multiple API calls to retrieve all the data. You'll need to handle pagination by using the `page` and `per_page` parameters in your API requests.
• Rate Limits: Zoho imposes rate limits on API calls based on the edition of your Zoho CRM. It's important to be aware of these rate limits and design your integration accordingly.

Through Zoho API

const accessToken = 'YOUR_ACCESS_TOKEN';
const customerOrgUrl = 'YOUR_CUSTOMERS_INSTANCE_URL';
const url = `https://${customerOrgUrl}/crm/v3/Contacts`
const response = await fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': `Zoho-oauthtoken ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

With Vessel

You can use the Unified CRM API instead of needing to understand the nuances of Zoho. If you use the Unified API then you won’t need to repeat any of this setup if you want to support other CRMs like HubSpot and Salesforce.

import Vessel from '@vesselapi/sdk';
const vessel = Vessel({
  apiKey: process.env.API_KEY, 
  accessToken: 'YOUR_CUSTOMERS_ACCESS_TOKEN'
});

const response = await vessel.unifications.crm.contacts.list();

Writing to the API

When writing data to the Zoho API, there are a few considerations to keep in mind.

• Required Fields: Make sure to include all the required fields when creating or updating records in Zoho CRM. Missing required fields will result in an error.
• Data Validation: Zoho CRM has specific validation rules for certain fields. Make sure to adhere to these rules.

Through Zoho API

const accessToken = 'YOUR_ACCESS_TOKEN';
const customerOrgUrl = 'YOUR_CUSTOMERS_INSTANCE_URL';

const response = await fetch(`https://${customerOrgUrl}/crm/v2/contacts`, {
  method: 'POST',
  headers: {
    'Authorization': `Zoho-oauthtoken ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: [{
      First_Name: 'John',
      Last_Name: 'Doe',
      Email: 'john.doe@example.com'
    }]
  })
});
  
const contact = await response.json();

With Vessel

You can use the Unified CRM API again.

import Vessel from '@vesselapi/sdk';
const vessel = Vessel({
  apiKey: process.env.API_KEY,
  accessToken: 'YOUR_CUSTOMERS_ACCESS_TOKEN'
});

const response = await vessel.unifications.crm.contacts.create({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john.doe@example.com'
});

Closing Thoughts

Publishing your Application

Once you have successfully built your Zoho integration, you may consider publishing your application to the Zoho Marketplace to make it available to a wider audience. Publishing your application on the marketplace can provide additional visibility and opportunities for collaboration.

To publish your application, you'll need to follow the guidelines and requirements provided by Zoho. This may include submitting your application for review, ensuring compliance with security and privacy standards, and providing documentation and support for users.

About Us

Hopefully, you found this article helpful for building out your native Zoho integration. I know I certainly wish something like this existed when we built out our Zoho integration.

If you decided to give Vessel a spin while following this tutorial, thank you. If you have any feedback while using the SDK, don’t hesitate to reach out at support@vessel.dev We’re a team of engineers at heart and take every piece of feedback extremely seriously.

If you’re curious to learn more about why we started Vessel and how we view the future of customer-facing integrations, you can read more in our “what are native integration platforms” posts.

On that note, if you ever have any questions about building a Zoho integration while you’re going through this tutorial, regardless of if you decide to use Vessel, don’t hesitate to reach out at zach@vessel.dev and I’ll be more than happy to personally help.