Skip to main content

Zoho Books

Read and create Zoho Books invoices, bills, contacts, items and expenses.

Connect it with: Sign in (OAuth). Zoho Books's own documentation: https://www.zoho.com/books/api/v3/oauth/.

What agents can do​

Connect Zoho Books so the agents working your tasks can reach it. With it connected, they can:

  • List unpaid and overdue invoices and the customers who owe them.
  • Draft invoices or record bills and expenses from a task's details for a person to approve.
  • Look up or add customers, vendors and items.
  • Run the profit and loss or aged receivables report for a period.

Before you start​

  • A Zoho Books organization whose Zoho account is in the US data centre (you sign in at accounts.zoho.com, not .eu, .in or .com.au).
  • A Zoho Books user with the rights agents should have: agents act as the user who connects.
  • A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.

Connect with Zoho Books​

This is the quickest way in: you sign in to Zoho Books and approve what Jaah asks for. You never copy a key.

  1. In Jaah, open Secrets and select New.
  2. Search for Zoho Books and select its card.
  3. Give the secret a name you will recognize, such as the account or workspace it reaches, and choose who can use it (see Who can use it).
  4. Select Connect Zoho Books. Zoho Books's sign-in window opens.
  5. Sign in to Zoho Books if asked, check the access listed, and approve it.
  6. You land back in Jaah on the new secret, which reads Connected once its test passes.

If the button reads Jaah app not configured, this Jaah has no app registered at Zoho Books yet. Use your own OAuth app until it does (see Use your own OAuth app).

Scopes Jaah requests​

Jaah asks Zoho Books for these scopes, and no others. A scope marked optional is a checkbox on the Connect screen: untick it and agents simply cannot do that part.

ScopeWhy Jaah asks for itRequired
ZohoBooks.settings.READRead your organizations and settings, so Test can name the organization and agents can find its IDYes
ZohoBooks.contacts.ALLRead and update customers and vendorsNo — you may untick it
ZohoBooks.invoices.ALLRead, draft and update invoicesNo — you may untick it
ZohoBooks.bills.ALLRead and record vendor billsNo — you may untick it
ZohoBooks.expenses.ALLRead and record expensesNo — you may untick it
ZohoBooks.customerpayments.ALLRead and record customer payments against invoicesNo — you may untick it
ZohoBooks.reports.READRun reports such as profit and loss or aged receivablesNo — you may untick it

Connect with an API key​

Zoho Books has no API key option in Jaah: connect with the sign-in above.

Use your own OAuth app​

Register your own OAuth app at Zoho Books when your company requires apps it controls, or before this Jaah has an app registered there.

  1. Create an OAuth app in Zoho Books's developer console, https://api-console.zoho.com/ (Zoho Books's documentation).
  2. Set its redirect URI to https://app.jaah.ai/api/credentials/connect/callback (on your own Jaah, its console address followed by /api/credentials/connect/callback).
  3. Give it the scopes in Scopes Jaah requests.
  4. Copy its client ID and client secret.
  5. In Jaah, start a new Zoho Books secret, select Use your own OAuth app, paste both values and select Connect Zoho Books.

The client secret is stored with the connection, encrypted, like any other secret value.

Test the connection​

Select Test on the secret. Jaah calls Zoho Books's API once (GET https://www.zohoapis.com/books/v3/organizations) with the stored values, and shows who it answered as, or which value Zoho Books refused and the status it answered. Jaah also tests automatically when you save or reconnect.

The last result and its time stay on the secret's page, so you can see whether it still works without testing again.

Who can use it​

Every secret has an owner, and the owner decides who can use it:

  • Personal — only your own tasks can use it. This is the default.
  • Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
  • Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.

More on owners and access: How secrets work.

Use it in an agent session​

An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:

  • org/<name> for an organization secret,
  • projects/<project>/<name> for one attached to a project,
  • me/<name> for your personal one.

A signed-in connection hands the agent a live access_token, with access_token_expires_at. Jaah refreshes it before it expires, so an agent never handles a refresh token.

Tell the agent in your task description which secret to use, for example “use the Zoho Books secret org/zoho-books”.

Manage, rotate or disconnect​

Everything is on the secret's page under Secrets:

  • Reconnect: when Zoho Books ends the grant (a password change, a revoked app, an expired refresh), the secret shows Needs reconnect. Select Reconnect and sign in again; agents get the new token on their next call.
  • Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at Zoho Books's side too, revoke Jaah in Zoho Books's settings.

Limitations​

  • Only Zoho accounts in the US data centre (zoho.com) can connect for now; accounts in the EU, India, Australia, Japan, Canada and other data centres are refused at sign-in.
  • Most Zoho Books calls need the organization's ID; agents read it from the organizations list first.
  • Zoho Books allows 100 calls a minute per organization and a daily quota by plan (1,000 on Free up to 10,000 on higher plans).
  • Agents send the access token under Zoho's own scheme, Authorization: Zoho-oauthtoken <token>, not as a Bearer token.
  • Agents can do only what the connected Zoho Books account and its granted scopes allow.

Troubleshooting​

Test says Zoho Books rejected the access token (401)

The grant was revoked in Zoho (Accounts > Sessions > Connected Apps) or the user lost access to Zoho Books. Select Reconnect.

Signing in fails or never returns to Jaah

The Zoho account lives outside the US data centre. Only accounts that sign in at accounts.zoho.com can connect for now.

Agents get error 44 or 45 from Zoho Books

The per-minute (44) or daily (45) API limit was reached. Wait for it to reset, or ask the agent to work in smaller batches.

Still stuck? Select Test and read the result: it names the value Zoho Books refused and the status it answered.

FAQ​

Why does Zoho ask for consent every time I connect?

Jaah asks for offline access so it can renew the token on its own, and Zoho shows the consent screen each time it issues that.

Does Test change anything?

No. It lists your Zoho Books organizations and nothing else.

Can Jaah or an admin see the key or token?

No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.

Can I connect more than one Zoho Books account?

Yes. Add one secret per account, each with its own name, and tell the agent which one to use.