xMatix ships three Zoho connectors — Zoho Books, Zoho Payroll and Zoho People — that plug into sync profiles as external systems. The shipped Zoho sync is inbound: it reads Zoho into xMatix, keeping xMatix records in step with what Zoho holds. That makes it the tool for migrating off Zoho or running xMatix alongside it as the destination of record; it does not push xMatix changes back into Zoho. Declare Zoho entities with direction Inbound.
Credentials and connection
All three products authenticate with Zoho OAuth using a refresh token. Create the connection inside an integration app with:
| Field | Notes |
|---|---|
| Client id / client secret | From a Zoho API client registration — store both as secrets and reference them |
| Refresh token | Generated for the integration; also a secret. Grant read scopes for the modules you sync |
| Data centre | The Zoho region your account lives in (com, in, eu, com.au, jp, ca, sa, ae, …). OAuth clients are region-bound: a client registered in one data centre is rejected by another |
| Organization id | Required for Books and Payroll. These are different values for the same company — Payroll has its own organization id; copying the Books one is a classic setup mistake. People needs none |
Access tokens are obtained and refreshed automatically, and the correct regional API host is taken from Zoho's own token response — so an account that migrated between data centres still routes correctly. Zoho rate-limit responses are honoured with backoff.
Zoho Books
Books covers contacts and contact persons, items, invoices, credit notes, sales orders, purchase orders, bills, expenses, estimates, customer and vendor payments, chart of accounts, bank accounts, bank transactions, taxes and tax groups, and currencies. The discovery list also exposes journals with a DO NOT SYNC warning: importing them is appropriate only for locked-period migration history, because syncing journals into a period where xMatix also posts source documents double-posts the same economics.
Document headers are ordinary record declarations. Line detail is available through inbound Lines declarations for invoices/line_items, bills/line_items, expenses/line_items, salesorders/line_items, purchaseorders/line_items and creditnotes/line_items. Each changed parent requires a detail API call, every line declaration must map a reference back to its parent, and the parent must run at a lower rank. Invoice, bill and expense response shapes are verified in the implementation; validate the other three against real tenant data before activation because their detail wrappers are still marked provisional in the catalog.
Change detection uses Books' last-modified stamp: most modules are read newest-first and the pass stops as soon as it reaches records already synced, so a quiet module costs one page per cycle. A handful of modules publish no usable ordering (chart of accounts, bank accounts, bank transactions, expenses, and the settings collections) — those are read whole each cycle, with the engine's content hash deciding what actually changed. Correct, just heavier, which is worth remembering when choosing a cadence.
Per-entity external filters are passed to Books as its own native query parameters — for example status=unpaid on invoices. Two applied examples: taxes and tax groups share one Zoho collection, split by tax_type=tax versus tax_type=tax_group; and Books hides inactive rows by default, so add the module's filter_by parameter (such as filter_by=Taxes.All) when you need them.
Books rarely deletes: posted documents are voided, which arrives as an ordinary status change. Keep delete mode None on Zoho entities — an out-of-band deletion in Zoho is not detected.
Zoho Payroll
Payroll modules covered: employees, pay runs, departments, designations, work locations, holidays and salary components. Payroll publishes no modification watermark on any module, so every cycle reads each module whole and the ledger's hash comparison finds the changes. That is affordable at payroll volumes on a nightly schedule — put Payroll profiles on a nightly cron, never a 15-minute one, or the re-reads will eat your Zoho organization's daily API allowance.
Payroll data is also read-only in spirit as well as direction: a pay run is a signed artifact. The inbound-only design means sync can never mutate one in Zoho.
Zoho People
People is form-based: the external "object" you declare is a form link name (for example P_EmployeeView), not a table. People offers the cleanest delta of the three — a true modified-since filter — so cycles fetch exactly what changed, in pages of up to 200 records.
Scheduling guidance
| Product | Suggested cadence | Why |
|---|---|---|
| Books | Hourly | Sorted-scan deltas are cheap, but full-scan modules and the org's daily API budget punish aggressive crons |
| Payroll | Nightly | Every cycle is a full scan |
| People | 15–60 minutes if needed | True delta filter; cost tracks change volume |
Common questions
Can xMatix write back to Zoho?
Not through the sync path — Zoho sync profiles are inbound by design, and that is enforced rather than merely conventional. If a specific outbound call to a Zoho API is genuinely needed, it can be hand-authored as an integration flow, but keeping xMatix as the system that receives is the supported shape.
Which Zoho org id goes in the connection?
The one belonging to the product the connection is for. Books and Payroll each issue their own organization id for the same company; using the Books id on a Payroll connection fails requests even though the credentials are right. People connections take no organization id.
Why did a Books module stop at some records and not others?
Check whether the module supports last-modified ordering. Modules that do are read incrementally; those that do not are read whole each cycle. If a specific module's records are missing entirely, also check the entity's external filter — Books ignores unsupported query parameters silently rather than rejecting them, so a mistyped filter narrows nothing while a wrong one can narrow everything.
What happens when someone deletes a record in Zoho?
Nothing, by default — Zoho publishes no deletion feed, and delete mode None (the recommended setting) never propagates deletions anyway. The xMatix record stays. Voided Books documents do sync, as the status change they are.