> ## Documentation Index
> Fetch the complete documentation index at: https://control-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Zoho Books

> Authorize Control to read accounting data from a Zoho Books organization.

export const ControlAppLink = ({path, breadcrumb, children}) => {
  const link = <a href={`https://app.control.dev${path}`} target="_blank" rel="noopener noreferrer" aria-label={breadcrumb ? `Open ${breadcrumb} in Control` : undefined}>
      {children}
    </a>;
  return breadcrumb ? <Tooltip tip={breadcrumb}>{link}</Tooltip> : link;
};

Zoho Books connects to Control directly through OAuth. The connection does not use Nango. Control works with every
Zoho data centre, including India (`zoho.in`), the US (`zoho.com`), Europe (`zoho.eu`) and Australia (`zoho.com.au`).

## Before you begin

* Use a Zoho user who can open the intended organization and see its accounting data. An administrator or an
  accountant role works.
* Create the corresponding entity in Control before adding the data source. One Zoho Books organization maps to one
  Control entity.
* Check your Zoho Books plan. Zoho limits API requests per organization per day:

| Plan | Requests per day |
| - | - |
| Free | 1,000 |
| Standard | 2,000 |
| Professional | 5,000 |
| Premium, Elite or Ultimate | 10,000 |

A first import reads the full history once. Daily syncs use far fewer requests. On the Free plan, a large organization
can need more than one day for its first import.

## Connect in Control

1. Open <ControlAppLink path="/entities-data-sources/overview"><strong>Entities & sources</strong></ControlAppLink>.
2. Open the intended entity, choose **Add data source**, and select **Zoho Books**.
3. Give the data source a recognizable name.
4. Choose **Connect Zoho Books**.
5. Sign in to Zoho and approve Control's read access. Zoho sends you to your own data centre automatically.
6. Return to Control. If your Zoho user can open only one organization, the first sync starts right away.

## Choose the organization

Zoho asks for consent per user, not per organization. When your Zoho user can open several organizations, Control
shows them after you approve access.

1. Pick the organization that belongs to this entity. Each option shows its base currency.
2. Choose **Use this organization**. The first sync starts.

A Zoho Books sandbox is a separate organization. Pick your production organization unless you are testing.

## Permissions requested

Control requests read-only access. It never requests write access and cannot change your Zoho Books data.

| Scope | Purpose |
| - | - |
| `ZohoBooks.accountants.READ` | Chart of accounts, general-ledger postings, manual journals, transaction locks |
| `ZohoBooks.settings.READ` | Organization details, reporting tags and locations |
| `ZohoBooks.contacts.READ` | Customer and vendor names, used as counterparties |
| `ZohoBooks.projects.READ` | Projects, used as a dimension |

## Data imported

* Chart of accounts
* Every general-ledger posting per account, including invoices, bills, payments, expenses, bank transactions, manual
  journals, opening balances and base-currency adjustments. Amounts are in the organization's base currency.
* Manual-journal dimensions: project, reporting tags and location
* Customers and vendors as counterparties
* Transaction locks, which Control uses as the books-closed date

Control does not import attachments or invoice and bill documents. Dimensions on invoices, bills and expenses are not
imported yet; only manual journals carry dimensions.

## How syncing works

* Daily syncs re-read every period that is not locked in Zoho Books, and at least the last 90 days.
* Once a week, Control re-reads the full history. This picks up deleted transactions and edits in older periods.
* Lock your closed periods in Zoho Books (**Settings** → **Transaction Locking**). Control then treats them as closed
  and can keep daily syncs small.

## Verify the first import

1. Wait for the first sync to finish.
2. In Zoho Books, run **Trial Balance** for a closed month on an accrual basis.
3. Compare it with the same month in Control, including opening balances.
4. Report any difference to Control support with the account and month.

## Reconnect or revoke

Zoho revokes connected apps when the user changes their password or turns on multi-factor authentication. Choose
**Reconnect** on the Zoho Books data source to restore the connection.

To remove Control's access, open **Zoho Accounts** → **Connected Apps** and remove Control. Data already imported
stays in Control until you delete the data source.

## Common problems

* **Organization selection appears.** Your Zoho user can open several organizations. Pick the one for this entity.
* **The organization is already connected.** Each Zoho Books organization can belong to one data source per workspace.
  Remove the other data source first.
* **Daily API limit reached.** The sync stops and retries the next day. A higher Zoho Books plan raises the limit.
* **Reconnect required.** Zoho revoked the connection, usually after a password or multi-factor change. Reconnect.

## Provider documentation

* [Zoho Books API](https://www.zoho.com/books/api/v3/introduction/)
* [Zoho Books OAuth](https://www.zoho.com/books/api/v3/oauth/)
* [Transaction locking in Zoho Books](https://www.zoho.com/books/help/settings/transaction-locking.html)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.