Advanced Analytica Advanced Analytica: IBOM
← All connectors
ZohoCRM logo

Source connector

ZohoCRM

Set up ZohoCRM as a source and move its data into your chosen destination.

Version 0.4.1 community alpha

Zoho CRM

Sync overview

The Zoho CRM source supports Full Refresh and Incremental syncs. It reads data through version 2 of the Zoho CRM REST API.

Output schema

The connector syncs:

  • Standard modules in your Zoho CRM account
  • Custom modules you’ve added to your account
  • Custom fields in standard and custom modules

The connector doesn’t use a fixed list of streams. During discovery, it calls the Modules API to list your modules. It then uses the Modules Metadata API and Fields Metadata API to build each module’s schema. Discovery usually takes 10 to 30 seconds.

A module appears as a stream only when the Zoho CRM API returns its module and field metadata. Your Zoho CRM edition may make some modules unavailable. Modules may also be unavailable when your OAuth token doesn’t include the required scope. For details, see Scopes in the Zoho CRM documentation.

Data type mapping

Integration TypeAirbyte TypeNotes
booleanboolean
doublenumber
currencynumber
integerinteger
profileimagestring
pickliststring
textareastring
websitestringformat: uri
datestringformat: date
datetimestringformat: date-time
textstring
phonestring
bigintstringairbyte_type: big_integer
event_reminderstring
emailstringformat: email
autonumberstringairbyte_type: big_integer
jsonarrayarray
jsonobjectobject
multiselectpicklistarray
lookupobject
ownerlookupobject
RRULEobject
ALARMobject

The connector treats any data type not listed above as string.

Picklist and multi-select picklist fields aren’t limited to values currently defined in Zoho CRM. When you remove a picklist value, Zoho CRM keeps it on existing records. The connector therefore syncs the value held by each record.

Auto-number fields are the exception to this table. When you configure a prefix or suffix in Zoho CRM, values become plain strings such as INV-1042. The connector then drops the big_integer type and syncs them as strings.

Features

FeatureSupported? (Yes/No)
Full Refresh Overwrite SyncYes
Full Refresh Append SyncYes
Incremental - Append SyncYes
Incremental - Append + Deduplication SyncYes
NamespacesNo

Incremental syncs

Every stream supports incremental syncs. The connector resolves each module’s cursor field separately. It uses the first field exposed by the module’s field metadata:

  1. Modified_Time
  2. Action_Performed_Time
  3. Created_Time

Most modules use Modified_Time. Modules that don’t expose it, such as Actions_Performed, use Action_Performed_Time instead. Each stream stores its state under its own cursor field name because cursor fields vary by module.

The connector reads only changed records by sending the stored cursor value in the If-Modified-Since request header. It advances this value by one second, avoiding another read of the previous sync’s final record. Zoho CRM returns 304 Not Modified when nothing has changed, which the connector treats as an empty page. If a record lacks a cursor value, the connector emits it without advancing the stream’s state.

Every stream schema includes id and Modified_Time, including modules without a Modified_Time field. For these modules, the column is always null. The module’s actual cursor field contains the timestamp.

Stream schemas mark only id and Modified_Time as required. Fields marked as mandatory in Zoho CRM’s metadata aren’t required in stream schemas. Records with empty values for these fields still match the schema.

Start date

Start Date is optional and controls how far back the first incremental sync reads. If you leave it empty, the connector reads from 1970-01-01T00:00:00+00:00. Enter an ISO 8601 value, with or without a time and UTC offset. Accepted values include 2024-01-01, 2024-01-01 13:00:00, 2024-01-01T13:00:00-07:00 and 2024-01-01T13:00:00Z.

Connector versions before 0.1.4 can’t parse UTC timestamps ending in Z. They fail the sync with Invalid isoformat string. Upgrade to 0.1.4 or later when your start date or saved cursor value uses this format.

Supported Zoho CRM environments

Production

EnvironmentBase URL
UShttps://zohoapis.com
AUhttps://zohoapis.com.au
EUhttps://zohoapis.eu
INhttps://zohoapis.in
CNhttps://zohoapis.com.cn
JPhttps://zohoapis.jp

Sandbox

EnvironmentEndpoint
UShttps://sandbox.zohoapis.com
AUhttps://sandbox.zohoapis.com.au
EUhttps://sandbox.zohoapis.eu
INhttps://sandbox.zohoapis.in
CNhttps://sandbox.zohoapis.com.cn
JPhttps://sandbox.zohoapis.jp

Developer

EnvironmentEndpoint
UShttps://developer.zohoapis.com
AUhttps://developer.zohoapis.com.au
EUhttps://developer.zohoapis.eu
INhttps://developer.zohoapis.in
CNhttps://developer.zohoapis.com.cn
JPhttps://developer.zohoapis.jp

For more information about available environments, visit this page.

Performance considerations

Zoho CRM API calls consume credits. Each Zoho CRM edition has a credit limit within a rolling 24-hour window. Discovery uses one call to list your modules, followed by two metadata calls per module. These calls retrieve module metadata and field metadata. Consider this usage when setting your sync frequency. For each call’s credit cost, see API limits in the Zoho CRM documentation.

The connector retries record requests that return HTTP 429 Too Many Requests or a 5xx server error before failing the sync.

The connector automatically detects your Zoho CRM Edition through the Zoho organization API (/crm/v2/org). This API requires the ZohoCRM.org.READ scope. Your detected edition controls the number of parallel metadata requests used to build the stream list:

EditionParallel requests
Free5
Standard10
Professional15
Enterprise20
Ultimate25

If the connector can’t detect your edition, it uses the Free tier concurrency limit of 5. It also logs a warning explaining why. Common causes include:

  • Your refresh token doesn’t include the ZohoCRM.org.READ scope. Airbyte Cloud sources using connector version 0.2.0 didn’t request this scope. These sources remain in this group until you re-authenticate.
  • Zoho returns an edition name that isn’t one of the five listed in the table. The warning includes the name Zoho returned.

To skip detection, set Max Concurrent Requests to your preferred number of parallel requests. You can raise the limit without re-authenticating or match your plan’s limit in Zoho’s API limits table. You can also throttle the connector when other integrations share the same Zoho API credits. Exceeding your account’s concurrency limit can push the connector beyond Zoho’s discovery allowance.

Zoho Developer environment

The Zoho Developer environment API isn’t consistent with the production environment API. It contains about half the modules supported in production. Consider this difference when pulling data from the Developer environment.

Setup guide

Your authentication method depends on where you run Airbyte. In both cases, you also complete these fields:

FieldRequiredNotes
Data Center LocationYesThe region that hosts your Zoho CRM account: US, AU, EU, IN, CN, or JP
EnvironmentYesProduction, Developer, or Sandbox
Start DateNoSee Start date
Max Concurrent RequestsNoOverrides edition detection. See Performance considerations

Airbyte Cloud: sign in with Zoho

  1. Select your Data Center Location first. Zoho uses a separate accounts server for each data centre. The sign-in flow uses the server for your selected region.
  2. Select Authenticate your Zoho CRM account and sign in. Airbyte requests these read-only scopes:
    • ZohoCRM.settings.modules.READ and ZohoCRM.settings.fields.READ, to list your modules and their fields
    • ZohoCRM.modules.READ and ZohoCRM.modules.custom.READ, to read records from standard and custom modules
    • ZohoCRM.org.READ, to detect your Zoho CRM edition and set request concurrency
  3. Complete the remaining fields and select Set up source.

The flow stores only the refresh token in your source. The client ID and secret belong to Airbyte’s Zoho app.

Airbyte Open Source

Create a Zoho API client and generate a refresh token. Then enter the Client ID, Client Secret and Refresh Token in the source.

Get Client ID, Client Secret, and Grant Token

  1. Log into https://api-console.zoho.com/.
  2. Choose client.
  3. Enter the scopes covered by the refresh and access tokens. The connector reads module and field metadata, reads module records and detects your edition through the organization API. Grant ZohoCRM.settings.modules.READ, ZohoCRM.settings.fields.READ, ZohoCRM.modules.READ, ZohoCRM.modules.custom.READ and ZohoCRM.org.READ. Alternatively, grant ZohoCRM.modules.ALL if you prefer one module scope for records. Make sure the scope covers every module you want to sync. If the token lacks metadata access, that module doesn’t appear as a stream. If it lacks record access, the stream appears, but the sync fails when reading data.
  4. Enter the grant token’s lifetime and description, then click “Create”.
  5. Copy Grant token and close the pop-up. Then copy Client ID and Client Secret from the “Client Secret” tab.

Create Refresh Token

To generate the refresh token, see this page. Complete the authentication flow quickly. Zoho CRM’s initial token remains active for only a few minutes. After that, you can’t use it to generate a refresh token.

IP allow list

If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Changelog

Expand to review
VersionDatePull RequestSubject
0.4.12026-11-1091774Update dependencies
0.4.02026-11-0390861Upgrade to Python 3.13 base image and airbyte-cdk 7; stop marking Zoho mandatory fields as required in stream schemas
0.3.82026-11-0390811Update dependencies
0.3.72026-11-0288944Stop declaring picklist values as a closed enum in stream schemas, as records keep values removed from a picklist
0.3.62026-10-2790099Update dependencies
0.3.52026-10-2089462Update dependencies
0.3.42026-10-1388877Update dependencies
0.3.32026-10-0688089Update dependencies
0.3.22026-09-2987414Update dependencies
0.3.12026-09-2286874Update dependencies
0.3.02026-09-2186491Auto-detect Zoho CRM edition from the organization API instead of the edition config field (defaulting to a concurrency limit of 5 when detection fails); add optional max_concurrent_requests override
0.2.02026-09-1685833Add advanced_auth with declarative OAuth (data-center-aware consent and token URLs) requesting Zoho’s documented read scopes; document the OAuth and manual setup paths
0.1.62026-09-1586301Update dependencies
0.1.52026-08-2579062Update dependencies
0.1.42026-08-2480278Fix incremental sync: tolerate Z-suffixed (UTC) cursor values and resolve cursor field per module instead of hardcoding Modified_Time
0.1.32025-02-0542864Migrate to Poetry
0.1.22023-03-1923906added support for the latest CDK, fixed SAT
0.1.12023-03-1524034Set airbyte type to string for zoho autonumbers when they include prefix or suffix
0.1.02022-04-0611193Initial release
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.