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 added to your account
- Custom fields in both standard and custom modules
There's no fixed list of streams. During discovery, the connector calls the Modules API to list your modules, then the Modules Metadata API and Fields Metadata API to build a schema for each one. Discovery usually takes 10 to 30 seconds.
A module appears as a stream only if the Zoho CRM API returns module and field metadata for it. Some modules aren't available because of your Zoho CRM edition or because your OAuth token lacks the scope for them. For details, see Scopes in the Zoho CRM documentation.
Data type mapping
| Integration Type | Airbyte Type | Notes |
|---|---|---|
boolean | boolean | |
double | number | |
currency | number | |
integer | integer | |
profileimage | string | |
picklist | string | enum |
textarea | string | |
website | string | format: uri |
date | string | format: date |
datetime | string | format: date-time |
text | string | |
phone | string | |
bigint | string | airbyte_type: big_integer |
event_reminder | string | |
email | string | format: email |
autonumber | string | airbyte_type: big_integer |
jsonarray | array | |
jsonobject | object | |
multiselectpicklist | array | |
lookup | object | |
ownerlookup | object | |
RRULE | object | |
ALARM | object |
Any other data type not listed in the table above will be treated as string.
Auto-number fields are the one exception to that table: when the field has a prefix or suffix configured in Zoho CRM, its values are plain strings such as INV-1042, so the connector drops the big_integer type and syncs them as strings.
Features
| Feature | Supported? (Yes/No) |
|---|---|
| Full Refresh Overwrite Sync | Yes |
| Full Refresh Append Sync | Yes |
| Incremental - Append Sync | Yes |
| Incremental - Append + Deduplication Sync | Yes |
| Namespaces | No |
Incremental syncs
Every stream supports incremental syncs. The connector resolves the cursor field separately for each module, using the first of these fields that the module's field metadata exposes:
Modified_TimeAction_Performed_TimeCreated_Time
Most modules use Modified_Time. Modules that don't expose it, such as Actions_Performed, use Action_Performed_Time instead. Because the cursor field varies by module, each stream stores its state under its own cursor field name.
To read only changed records, the connector sends the stored cursor value in the If-Modified-Since request header, advanced by one second so the last record of the previous sync isn't read again. Zoho CRM returns 304 Not Modified when nothing changed, which the connector treats as an empty page. If a record has no value in the cursor field, the connector emits the record but doesn't advance the stream's state.
Every stream schema includes id and Modified_Time, even for modules that don't have a Modified_Time field. For those modules the column is always null, and the module's real cursor field carries the timestamp.
Start date
Start Date is optional and sets how far back the first incremental sync reads. If you leave it empty, the connector reads from 1970-01-01T00:00:00+00:00. Use an ISO 8601 value, with or without a time and UTC offset: 2024-01-01, 2024-01-01 13:00:00, 2024-01-01T13:00:00-07:00, and 2024-01-01T13:00:00Z are all accepted.
Connector versions earlier than 0.1.4 can't parse UTC timestamps that end in Z, and fail the sync with Invalid isoformat string. Upgrade to 0.1.4 or later if your start date or saved cursor value uses that format.
List of Supported Environments for Zoho CRM
Production
| Environment | Base URL |
|---|---|
| US | https://zohoapis.com |
| AU | https://zohoapis.com.au |
| EU | https://zohoapis.eu |
| IN | https://zohoapis.in |
| CN | https://zohoapis.com.cn |
| JP | https://zohoapis.jp |
Sandbox
Developer
For more information about available environments, please visit this page
Performance considerations
Zoho CRM API calls consume credits, and each Zoho CRM edition has a credit limit in a 24-hour rolling window. Discovery is more expensive than it looks: the connector makes one call to list your modules, then two metadata calls per module (module metadata and field metadata). Take this into account when you set sync frequency. For the credit cost of each call, see API limits in the Zoho CRM documentation.
The connector detects your Zoho CRM Edition automatically from the Zoho organization API (/crm/v2/org), which requires the ZohoCRM.org.READ scope. The detected edition controls how many metadata requests the connector makes in parallel while it builds the list of streams:
| Edition | Parallel requests |
|---|---|
| Free | 5 |
| Standard | 10 |
| Professional | 15 |
| Enterprise | 20 |
| Ultimate | 25 |
If the connector can't detect your edition, it falls back to a concurrency limit of 5 (the Free tier) and logs a warning that explains why. Common causes:
- Your refresh token doesn't include the
ZohoCRM.org.READscope. Sources authenticated through Airbyte Cloud with connector version 0.2.0 didn't request this scope, so they fall into this group until you re-authenticate. - Zoho reports an edition name that isn't one of the five in the table. The warning includes the name Zoho returned.
To skip detection, set Max Concurrent Requests to the number of parallel requests you want. Use this to raise the limit without re-authenticating, to match the limit Zoho lists for your plan in its API limits table, or to throttle the connector when other integrations share the same Zoho API credits. A value higher than your account's concurrency limit can push the connector past what Zoho allows during discovery.
Note about using the Zoho Developer Environment
The Zoho Developer environment API is inconsistent with production environment API. It contains about half of the modules supported in the production environment. Keep this in mind when pulling data from the Developer environment.
Setup guide
There are two ways to authenticate, depending on where you run Airbyte. In both cases you also fill in these fields:
| Field | Required | Notes |
|---|---|---|
| Data Center Location | Yes | The region that hosts your Zoho CRM account: US, AU, EU, IN, CN, or JP |
| Environment | Yes | Production, Developer, or Sandbox |
| Start Date | No | See Start date |
| Max Concurrent Requests | No | Overrides edition detection. See Performance considerations |
Airbyte Cloud: sign in with Zoho
- Select your Data Center Location first. Zoho runs a separate accounts server per data center, and the sign-in flow uses the one for the region you pick.
- Select Authenticate your Zoho CRM account and sign in. Airbyte requests these read-only scopes:
ZohoCRM.settings.modules.READandZohoCRM.settings.fields.READ, to list your modules and their fieldsZohoCRM.modules.READandZohoCRM.modules.custom.READ, to read records from standard and custom modulesZohoCRM.org.READ, to detect your Zoho CRM edition and set the request concurrency
- Fill in 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 yourself, then enter the Client ID, Client Secret and Refresh Token in the source.
Get Client ID, Client Secret, and Grant Token
- Log into https://api-console.zoho.com/
- Choose client
- Enter the scopes the refresh and access tokens cover. The connector reads module and field metadata, reads records from each module, and detects the edition from the organization API, so grant
ZohoCRM.settings.modules.READ,ZohoCRM.settings.fields.READ,ZohoCRM.modules.READ,ZohoCRM.modules.custom.READ, andZohoCRM.org.READ(orZohoCRM.modules.ALLif you prefer a single module scope for records). Make sure the scope covers every module you want to sync. If the token lacks metadata access for a module, that module doesn't appear as a stream; if it lacks record access, the stream appears but the sync fails when it tries to read data. - Enter grant token's lifetime and description, click "Create".
- Copy Grant token, close the popup and copy Client ID and Client Secret on the "Client Secret" tab.
Create Refresh Token
For generating the refresh token, please refer to this page. Make sure to complete the auth flow quickly, as the initial token granted by Zoho CRM is only live for a few minutes before it can no longer be used to generate a refresh token.
IP allow list
If you use Airbyte Cloud and your organization restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.
Reference
Config fields reference
Changelog
Expand to review
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 0.3.1 | 2026-09-22 | 86874 | Update dependencies |
| 0.3.0 | 2026-09-21 | 86491 | Auto-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.0 | 2026-09-16 | 85833 | Add 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.6 | 2026-09-15 | 86301 | Update dependencies |
| 0.1.5 | 2026-08-25 | 79062 | Update dependencies |
| 0.1.4 | 2026-08-24 | 80278 | Fix incremental sync: tolerate Z-suffixed (UTC) cursor values and resolve cursor field per module instead of hardcoding Modified_Time |
| 0.1.3 | 2025-02-05 | 42864 | Migrate to Poetry |
| 0.1.2 | 2023-03-19 | 23906 | added support for the latest CDK, fixed SAT |
| 0.1.1 | 2023-03-15 | 24034 | Set airbyte type to string for zoho autonumbers when they include prefix or suffix |
| 0.1.0 | 2022-04-06 | 11193 | Initial release |