Bigin by Zoho CRM is a customer relationship management (CRM) application from Zoho, built for small businesses. Teams use it to manage their companies and contacts, track deals through sales pipelines, and log their tasks and calls.
Hevo uses the Bigin REST API to replicate the companies, contacts, pipeline records (deals), tasks, calls, and users of your Bigin organization to the Destination of your choice. Hevo connects to Bigin using OAuth 2.0 with a Zoho API client that you register. To ingest data, you must provide Hevo with the Client ID and Client Secret of the API client, the edition of your Bigin organization, and the region of your Zoho account, and then authorize Hevo to access your Bigin data.
Supported Features
| Feature Name | Supported |
|---|---|
| Capture deletes | Yes |
| History mode | No |
| Custom data (user-configured tables & fields) | Yes, for the custom fields of the Account, Call, Contact, Pipeline, and Task objects |
| Data blocking (skip objects and fields) | Yes |
| Resync (objects and Pipelines) | Yes |
| API configurable | Yes |
Prerequisites
-
An active Bigin by Zoho CRM organization exists from which data is to be ingested.
-
Your Bigin user can view the records of the Companies, Contacts, Pipelines, Tasks, and Calls modules and the users of your organization. You do not need the Administrator profile. Hevo can ingest only the data that your user can access. Read Source Considerations.
-
A Zoho API client is registered, and its Client ID and Client Secret are available.
Create a Zoho API Client
Hevo connects to Bigin through an OAuth client that you register in the Zoho API Console. Register the client in the API Console of the data center where your Zoho account is hosted, for example, https://api-console.zoho.com for the US data center or https://api-console.zoho.eu for the Europe data center. Read Register your application.
Perform the following steps to create an API client:
-
Log in to the Zoho API Console with the Zoho account that you use to access Bigin.
-
On the Applications page, click ADD CLIENT. If you have not created a client before, Zoho displays the client types directly.
-
In the Choose a Client Type page, click CREATE NOW in the Server-based Applications card.
-
In the Create New Client page, specify the following, and then click CREATE:
-
Client Name: A name for the client. For example, Hevo Bigin Connector. Zoho does not allow the word Zoho in the client name.
-
Homepage URL: The URL of your company website. For example, https://hevodata.com.
-
Authorized Redirect URIs: https://westeros.hevodata.com/edge/oauth/callback. Hevo returns to this URL after you authorize it to access your Bigin data.
-
-
Click the Client Secret tab, and then copy the Client ID and the Client Secret and save them securely like any other password.
Use these credentials when configuring your Bigin Source in Hevo. The Client ID and Client Secret remain available on the Client Secret tab of the client, so you can copy them again later.
If you delete the API client, regenerate its Client Secret, or revoke the access granted to Hevo in your Zoho account, Hevo cannot authenticate with Bigin, and all active jobs of the Pipeline fail. To resume data replication, modify the Source configuration in the Pipeline with valid credentials and authorize Hevo again. Once the updated configuration is saved, Hevo re-authenticates the Source, and data ingestion resumes in the next run.
Scopes Required by Hevo
When you authorize Hevo, Zoho asks you to grant the following read-only scopes. Hevo does not create, modify, or delete any records in Bigin. Read Scopes.
| Scope | Purpose |
|---|---|
| ZohoBigin.modules.accounts.READ | To read the records of the Companies module. |
| ZohoBigin.modules.contacts.READ | To read the records of the Contacts module. |
| ZohoBigin.modules.pipelines.READ | To read the records of the Pipelines module. |
| ZohoBigin.modules.tasks.READ | To read the records of the Tasks module. |
| ZohoBigin.modules.calls.READ | To read the records of the Calls module. |
| ZohoBigin.settings.fields.READ | To read the field definitions of each module, including your custom fields. |
| ZohoBigin.users.READ | To read the users of your Bigin organization. |
Configure Bigin by Zoho CRM as a Source in your Pipeline
Perform the following steps to configure your Bigin by Zoho CRM Source:
-
Click Pipelines in the Navigation Bar.
-
Click + Create Pipeline in the Pipelines List View.
-
On the Select Source Type page, select Bigin by Zoho CRM.
-
On the Select Destination Type page, select the type of Destination you want to use.
-
In the Configure Source screen, specify the following:
-
Source Name: A unique name for your Source, not exceeding 255 characters. For example, Bigin by Zoho CRM Source.
-
In the Connect to Bigin section:
-
Client ID: The Client ID of the Server-based API client that you created in the Zoho API Console.
-
Client Secret: The Client Secret of the API client, from its Client Secret tab in the Zoho API Console.
-
Region: The data center where your Zoho account is hosted. Select one of the following: United States, Europe, India, Australia, Japan, or China. The region must match the domain of the Zoho API Console in which you created the API client. For example, select Europe if you created the client in api-console.zoho.eu. Default value: United States.
-
Edition: The edition of your Bigin organization. Select one of the following:
-
Free (5,000 API credits / 24 h): For the Free edition.
-
Express / Zoho One / Premier (up to 100,000 API credits / 24 h): For the Express, Premier, and Bigin 360 editions, and for Bigin as part of Zoho One.
Hevo uses the edition to decide how many API requests it sends to Bigin at the same time. Read API Limits.
-
-
Click Authorize, and log in with the Zoho account that you use for Bigin if prompted. Hevo opens the Zoho login page of the data center selected in Region. On the consent page, review the requested scopes, select the check box to allow access, and then click Accept. Once authorized, Hevo displays the email address of your Zoho account in Account Added.
-
-
-
Click Test & Continue to test the connection to your Bigin by Zoho CRM Source. Once the test is successful, you can proceed to set up your Destination.
When you click this button, Hevo performs the following validations:
-
Zoho accepts the Client ID and Client Secret in the selected region.
-
The authorization is valid, and Hevo can read the details of your Bigin user.
-
Hevo can read the records of the Contacts module and the field definitions of the Contacts module.
-
Data Replication
Hevo replicates data for all the objects selected on the Configure Objects page during Pipeline creation. By default, all supported objects and their available fields are selected. However, you can modify this selection while creating or editing the Pipeline. The Data Model lists the child objects of each parent object.
Bigin does not provide a reliable way to fetch only the records that changed since the last run. So, in each run of the Pipeline, as per the sync frequency, Hevo ingests all the records of the selected objects:
-
For the parent objects, Account, Call, Contact, Pipeline, Task, and Users, Hevo loads the records into the Destination tables, updating the existing rows and adding the new ones.
-
For the child objects, Hevo replaces the data in the Destination tables with the data ingested in the run.
As the number of records in your Bigin organization grows, each run takes longer and uses more API credits. If you do not need some objects, deselect them to reduce the API credits used.
Pipelines with this Source support only the Merge load mode.
API Limits
Bigin counts each API request against the API credit allowance of your organization for a rolling 24-hour window. The Free edition allows 5,000 credits. The Express, Premier, Bigin 360, and Zoho One editions allow 50,000 credits plus 250 credits for each user license, up to 100,000 credits. Bigin also limits the number of API requests that can run at the same time: 5 for the Free edition and 10 for the other editions. Read API Limits. These limits are shared by all the applications that use the Bigin API of your organization.
Hevo sends at most as many concurrent API requests as your selected Edition allows. Hevo does not count the API credits used. If Bigin returns a rate limit error, Hevo retries the request. If the error persists, Hevo stops ingesting data for the run. Objects that were not fully ingested are not loaded, and no records are marked as deleted for them. Hevo ingests all the objects again in the next run. To understand how Hevo handles such scenarios, read Handling Rate Limit Exceptions.
Schema and Primary Keys
Hevo uses the following schema to upload the records in the Destination. For a detailed view of the objects, fields, and relationships, click the ERD.
Data Model
The following is the list of tables (objects) that are created at the Destination when you run the Pipeline:
| Object | Description |
|---|---|
| Account | Contains the companies in your Bigin organization, with their name, website, phone, billing address, owner, and tags. The Bigin API name of this module is Accounts. It includes the following child objects: - Account Partner Type: Contains the values of the Partner Type multi-select field of each company. - Account Tag: Contains the tags of each company. |
| Call | Contains the calls logged in Bigin, with their subject, type, status, start time, duration, and the record each call is related to. It includes a child object, Call Tag, which contains the tags of each call. |
| Contact | Contains the contacts in your Bigin organization, with their name, email address, phone numbers, mailing address, company, and owner. It includes a child object, Contact Tag, which contains the tags of each contact. |
| Pipeline | Contains the records (deals) in your Bigin pipelines, with their name, stage, amount, closing date, and the company and contact of each record. The Bigin API name of this module is Pipelines. It includes the following child objects: - Pipeline Market, Pipeline Partner Type, Pipeline Property Management System, and Pipeline Prospect Pain Point: Contain the values of the Market, Partner Type, Property Management System, and Prospect Pain Point multi-select fields of each record. - Pipeline Tag: Contains the tags of each record. Note: The Account Partner Type table and the Pipeline Market, Pipeline Partner Type, Pipeline Property Management System, and Pipeline Prospect Pain Point tables are created for every Bigin organization. They remain empty if your organization does not have these fields. |
| Task | Contains the tasks created in Bigin, with their subject, status, priority, due date, owner, and the ID and module of the record each task is related to. |
| Users | Contains the users of your Bigin organization, with their name, email address, role, profile, and status. |
Additional Information
Read the detailed Hevo documentation for the following related topics:
Handling of Deletes
Bigin does not return deleted records in its API responses. Hevo captures deletes as follows:
-
For the parent objects, Account, Call, Contact, Pipeline, Task, and Users, Hevo compares the records ingested in each run with those in the Destination table. Records that are no longer returned by Bigin are marked as deleted by setting the value of the metadata column __hevo__marked_deleted to True.
-
For the child objects, Hevo replaces the data in the Destination table in each run. So, the tags and multi-select values removed in Bigin, and those of deleted records, are removed from the Destination table.
If a run fails, for example, because the API credit allowance is exhausted, Hevo does not mark any records as deleted in that run.
Source Considerations
-
Hevo ingests all the records of the selected objects in each run, and each API request uses the API credits that your other Bigin integrations also use. If your edition has a low credit allowance, increase the sync frequency interval of the Pipeline or deselect the objects that you do not need. Read API Limits.
-
Hevo ingests the custom fields of the Account, Call, Contact, Pipeline, and Task objects as separate columns. The column name is the API name of the field in lowercase, with any character other than letters and digits replaced by an underscore. For example, a custom field with the API name Crew_Number is loaded into the column crew_number. Hevo loads all custom fields as text, and the values of multi-select and subform fields as JSON text. When you add a custom field in Bigin, Hevo adds a column for it in the next run.
-
If Bigin denies access to a module for your user, Hevo marks the corresponding object as Inaccessible and displays it in the Needs Attention tab of the Pipeline. The other objects continue to be ingested. To ingest the object, grant your user access to the module in Bigin, and then resync the object.
-
Hevo reads data with the access token of the Zoho user who authorized Hevo. If this user can access only some records of a module, Hevo ingests only those records. Records that the user can no longer access are marked as deleted in the Destination.
-
Hevo ingests data from one Bigin organization in a Pipeline. To ingest data from more than one organization, create a Pipeline for each organization.
-
Hevo supports Zoho accounts hosted in the US, Europe, India, Australia, Japan, and China data centers. Accounts hosted in other Zoho data centers, such as Canada, Saudi Arabia, and UK, are not supported.