v8. The manifest has been checked against
Zoho’s API reference and exercised against a live account, including a synthetic
lead created through the CRM UI. Resources without enabled features or populated
parent records have not received the same level of live verification.
Configuration
Create a Zoho OAuth client and obtain an access token using Zoho’s
authorization flow.
Use the returned
api_domain as the host so requests reach the correct data
center and environment. Access tokens
expire after one hour.
Filament does not acquire or refresh them. Replace the token before a run and
finish within its lifetime.
Use read scopes for the selected modules and settings. Broad read access uses
ZohoCRM.modules.READ, ZohoCRM.settings.READ, ZohoCRM.users.READ, and
ZohoCRM.org.READ; narrower scopes are listed on each endpoint in the
API reference.
Connection testing calls the users endpoint and requires ZohoCRM.users.READ.
Additional scope families apply to these optional resources:
User permissions, edition, and enabled features still control visibility.
Notes require administrator access. Portals, territories, multi-currency,
scoring, enrichment, and automation resources may require additional features
or administrative privileges. Errors remain visible when a selected resource
is unavailable.
Resources
Users, leads, accounts, contacts, deals, tasks, events, calls, campaigns, modules, and the four named field resources are selected by default. Everything else is optional. Selecting a child also reads its parents, but only selected resources are written. Internal record indexes are not selectable. Sales, activity, inventory, and scheduling record resources list IDs and then fetch each record individually. Notes use a paginated listing of note fields. This preserves returned custom fields, inventory line items, and nested values inraw, alongside typed columns where defined. events represents meetings.
Leads include converted records. Detail reads cost one additional API call per
record; they remain subject to the nested-data limits described below.
CRM records
Configured module
Set
module_api_name to a standard or custom module API name. These resources
read one configured module per Pipeline; they do not automatically traverse all
custom modules or related lists. Use separate destination tables when changing
the module or relation. Select only endpoints supported by that module.
module_related_lists identifies available relationships. Set
related_list_api_name and related_fields for ordinary related-record lists;
use the dedicated email, attachment, and timeline resources for those APIs.
The generic related-record resource returns selected fields, not full details.
Reference data and templates
Organization and access
Automation, enrichment, and export metadata
IDs are strings. Rows retain additional returned fields in
raw. Child tables
include parent keys where IDs are scoped to a parent. Profile, template, workflow,
custom-view, and automation detail resources include fields omitted from their
corresponding listings. Nested definitions remain JSON rather than separate tables.
Modes
All resources support full reads. Use full upsert for keyed resources or full replace to remove rows no longer returned within your visibility. Use full replace for resources without a primary key, including configuration snapshots, sharing entries, usage reports, notification subscriptions, and backup URLs. These resources do not invent IDs for rows without a stable upstream key. Incremental reads are not supported. Update timestamps do not establish that relationship changes or newly visible records can be captured incrementally.Behavior
- Auth: requests use
Zoho-oauthtokenagainst the configured host. Refresh is external; this is not an unattended OAuth integration. - Pagination: record indexes and ordinary related records follow
info.next_page_token. Email lists useinfo.next_index. Paged collections use numbered pages and their documented completion signal. Most request 200 rows; scoring rules request 50 and organization enrichment requests 100. Detail and unpaged settings endpoints use one request per parent. - Record limit: the Get Records API permits at most 100,000 records per module in a page-token walk. Larger modules require export or partitioning logic outside this connector.
- Nested data: individual records can return partial subforms, multi-select
lookups, or multi-user lookups. Inspect
$has_moreinraw; this connector does not automatically paginate those embedded arrays. Use separately supported subform or linking-module APIs where available. Ordinary record reads truncate rich text to 500 characters;module_rich_textfetches the separate full content. - Relationships: related records use the configured relation and selected fields. Historical associations such as deal stage history need their own related-list selection. Email details require visibility of the owner’s mail. Attachments contain metadata only; binary content is not downloaded.
- History windows: deleted records cover Zoho’s 60-day recycle-bin and
120-day permanent-deletion windows. Appointment rescheduling exposes only the
latest 20 changes per appointment. Webhook failures default to 30 days and
action usage reports to seven days. Backup history covers the past year.
workflow_usagerequires both dates within Zoho’s supported 90-day window. - Recovery: top-level paged reads can resume from saved cursors. Zoho page tokens expire after 24 hours and are bound to the user and request parameters. Parent-dependent reads restart from their parent listing.
- Rate limiting: Zoho enforces credit and concurrency limits. Detail reads increase credit usage. Filament retries HTTP 429 and transient server errors; it does not track the organization’s rolling credit budget.
- Empty results: HTTP 204 produces no rows. Permission, feature, and token
errors fail the read. Blueprint reads select records whose
$process_flowflag is true. If a record leaves its process before the detail request, the read fails visibly.