Top

Zoho Books API

Zoho Books API gives you programmatic access to the Zoho Books service, allowing you to expand and build on the Zoho Books platform for small businesses across the globe. The possibilities are manifold and constrained only by the limits of our imaginations. Here are some of the cool applications you can build with our API:

  • Slice and dice your Zoho Books data in myriad ways.
  • Synchronize customers and orders taken on your website to Zoho Books.
  • Use Zoho Books as your billing system!

Our API is based on REST principles making it super easy for you to develop and test your application.

Getting Started

To use our API you should have the following

  1. A valid Zoho username and password.
  2. An Authentication Token - authtoken in short!

Authentication

All Zoho Books API requests require an authtoken. You can obtain an authtoken in following ways:

  1. Accessing a URL in browser
  2. Programmatically using the API

Accessing a URL in browser

If you chosen to obtain an authtoken by accessing a URL, please follow the instructions below:

https://accounts.zoho.com/apiauthtoken/create?SCOPE=ZohoBooks/booksapi

You will be requested to sign in if you are not signed in already.

Sample Response

  #
  #Tue Nov 30 13:08:11 PST 2010
  AUTHTOKEN=a8b6de25b5bf481824c9c4173c56231a
  RESULT=TRUE
Parameter Description
Comment Authtoken generated date.
AUTHTOKEN The permanent authtoken generated for Zoho Books API access.
RESULT Value is TRUE if the authtoken is generated successfully.

Programmatically using the API

If you chosen to obtain your authtoken via an API, please follow the instructions below:

Submit an HTTP POST request to the following URL

https://accounts.zoho.com/apiauthtoken/nb/create

The POST body should include a string in the following format

?SCOPE=ZohoBooks/booksapi&EMAIL_ID=[ZohoID/EmailID]&PASSWORD=[Password]

Mandatory fields to be passed in the URL are

Parameter Description
SCOPE ZohoBooks/booksapi
EMAIL_ID Your Zoho ID or Email ID.
PASSWORD Password for the Zoho ID.

Note: The parameter names passed in the POST request are case-sensitive.

Sample Response

  #
  #Tue Nov 30 02:16:57 PST 2010
  AUTHTOKEN=e07119171812c29b3a0dacdb79a57e3f
  RESULT=TRUE
Parameter Values
Comment Authtoken generated date.
CAUSE If the parameters passed in the URL are incorrect, the user will get a warning message stating the reason, else the parameter will be empty.
AUTHTOKEN Authtoken generated for the request.
RESULT Value is TRUE if the authtoken is generated successfully, else it is FALSE.
Using Two-factor Authentication?

If you're using the two factor authentication to access your Zoho Books account, follow these steps to generate the AuthToken in API mode:

  1. Log in to Zoho Books.
  2. Open https://accounts.zoho.com.
  3. In the Zoho Accounts Home page, click Two Factor Authentication.
  4. In the Two Factor Authentication page, click on the Manage Application Specific Passwords.
  5. In the Application Specific Passwordspop-up, specify these details:
    1. Device or App Name
    2. Current Password
    3. Click Generate button You will receive the new application-specific password with spaces.
  6. Remove the spaces in password and include in the below URL:

Then generate the permanent authtoken by,

https://accounts.zoho.com/apiauthtoken/nb/create?SCOPE=ZohoBooks/booksapi&EMAIL_ID=username&PASSWORD=application_password

For more information, please refer Two factor Authentication help page.

Important Note:

  • Generating AUTHTOKEN is as simple as a single click. You need to generate your AUTHTOKEN only once and can continue to access Zoho Books- API service without interruption.

  • The users who log in to Zoho Books through their gmail, GApps or yahoo accounts will not be able to access the API mode as it is not possible to generate the API Authtoken without a Zoho password.

How does it work

HTTP verbs are used to access the resources - GET, POST, PUT and DELETE. All parameters in the request should be form-urlencoded. For all the APIs you need to pass authtoken and organization_id. Input JSON string should be passed using JSONString parameter.

If Zoho Books is able to process the request, then Zoho Books returns a success message wrapped in JSON format depending on the method invoked. If due to some reason Zoho Books is unable to process the API request, then it returns an appropriate error code and message.

Sample Error Response

  {
    code : 14,
    message: "Invalid value passed for authtoken."
  }

Organizations

In Zoho Books your business is termed as an organization. If you have multiple businesses, you simply set each of those up as an individual organization. Each organization will have its own organization id, base currency, time zone, language, customers, reports, etc. To sum it all up, each organization is an independent Zoho Books account accessible through the same credentials.

The parameter organization_id should be sent in every API request to identify the organization.

How to create an organization via API

To create an organization via API, refer the documentation link below

https://www.zoho.com/books/api/v3/settings/organizations/#create-an-organization

How to get organization ID

To get an organization ID, send a request to the organizations GET API. The organization_id from the response JSON can be used to send as a query parameter to the API.

Parameters to be passed authtoken

Method type : GET

https://books.zoho.com/api/v3/organizations?authtoken=[AUTHTOKEN]

Sample Response

{
  "code": 0,
  "message": "success",
  "organizations": [
    {
      "organization_id": "10234695",
      "name": "Zillium Inc",
      "contact_name": "John Smith",
      "email": "johnsmith@zilliuminc.com",
      "is_default_org": false,
      "plan_type": 0,
      "tax_group_enabled": true,
      "plan_name": "TRIAL",
      "plan_period": "",
      "language_code": "en",
      "fiscal_year_start_month": 0,
      "account_created_date": "2012-02-18",
      "account_created_date_formatted": "18 Feb 2012",
      "time_zone": "Asia/Calcutta",
      "is_org_active": true,
      "currency_id": "460000000000097",
      "currency_code": "USD",
      "currency_symbol": "$",
      "currency_format": "###,##0.00",
      "price_precision": 2
    },
    {
      "organization_id": "10407630",
      "name": "Winston Longbridge",
      "contact_name": "John Smith",
      "email": "johnsmith@zilliuminc.com",
      "is_default_org": false,
      "plan_type": 0,
      "tax_group_enabled": true,
      "plan_name": "TRIAL",
      "plan_period": "",
      "language_code": "en",
      "fiscal_year_start_month": 0,
      "account_created_date": "2012-07-11",
      "account_created_date_formatted": "11 Jul 2012",
      "time_zone": "Asia/Calcutta",
      "is_org_active": true,
      "currency_id": "541000000000099",
      "currency_code": "INR",
      "currency_symbol": "Rs.",
      "currency_format": "###,##0.00",
      "price_precision": 2
    }
  ]
}

Go through the below example to see how our API works.

Say, for example, you need to create an item

Method name

https://books.zoho.com/api/v3/items?authtoken=[AUTHTOKEN]&organization_id=[ORGANIZATION_ID]&JSONString=[REQUEST_JSON]

Method type : POST

API description : Create an item in your Zoho Books account

Parameters to be passed authtoken, organization_id ,JSONString

Sample Request


  https://books.zoho.com/api/v3/items
  ?authtoken=e07119171812c29b3a0dacdb79a57e3f
  &organization_id=10234695
  &JSONString={
      "name": "Hard Drive",
      "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
      "rate": 120.00,
      "account_id": "460000000000388",
      "tax_id": "460000000027005"
}

Sample Response

{
    "code": 0,
    "message": "The item has been added.",
    "item": {
        "item_id": "460000000027009",
        "name": "Hard Drive",
        "status": "active",
        "unit": "",
        "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
        "rate": 120,
        "account_id": "460000000000388",
        "account_name": "Sales",
        "tax_id": "460000000027005",
        "tax_name": "VAT",
        "tax_percentage": 12.5,
        "tax_type": "tax",
    }
}

To view list of all items

Method name

https://books.zoho.com/api/v3/items?authtoken=[AUTHTOKEN]&organization_id=[ORGANIZATION_ID]

Method type : GET

API description : View list of active items in your Zoho Books account

Parameters to be passed authtoken, organization_id

Sample Response

{
  "code": 0,
  "message": "success",
  "items": [
    {
      "item_id": "460000000027009",
      "name": "Hard Drive",
      "status": "active",
      "description": "500GB, USB 2.0 interface 1400 rpm, protective hard case.",
      "rate": 120.00,
      "tax_id": "460000000027005",
      "tax_name": "VAT",
      "tax_percentage": 12.5
    },
    {
      "item_id": "460000000027017",
      "name": "Premium Plan - Web hosting",
      "status": "active",
      "description": "10 GB Space, 300 GB Transfer 100 Email Accounts 10 MySQL Databases",
      "rate": 33.00,
      "tax_id": "460000000027007",
      "tax_name": "Sales Tax",
      "tax_percentage": 10.5
    }
  ],
  "page_context": {
    "page": 1,
    "per_page": 200,
    "has_more_page": false,
    "report_name": "Items",
    "applied_filter": "Status.All",
    "sort_column": "name",
    "sort_order": "A"
  }
}

API Request Usage Limit

Limit per minute

You can send a maximum of 150 API requests per minute per organization.

Limit per day

You can send a maximum of 1000 API requests per day per organization during the trial period. However, if the organization is on a paid plan you can send up to 2500 API requests per day per organization.

Response Format

Response will be in JSON format by default. Certain APIs support csv, html and pdf formats. Response Format can be specified in accept header or by accept paramter.

eg. accept=csv will return response as a csv file.

Each Response has code and a message. Code will have a non zero value in case of any error.

HTTP Response Codes are listed below

200 OK
201 Created
400 Bad Request
401 Unauthorized (Invalid Authtoken)
404 Not Found
405 Method Not Allowed (Method you have called is not supported for this API)
429 Rate Limit Exceeded (API usage limit exceeded)
500 Internal Error
501 Not Implemented (Method you have called is not implemented)

Pagination

List API Response comes with page_context with following details,

page Page number of the list
per_page Number of records in the page
applied_filter Filter applied
sort_column Applied sorting
sort_order Order by which the list is sorted

Customizing the number of records to be shown in a page

Zoho Books provides APIs to retrieve lists of invoices, estimates and other entities. These APIs' response comes with additional information related to the list in a page_context array using which you can control how you want to receive the response.

  • For navigating through pages, use page parameter. By default first page will be listed.
  • Use the per_page parameter to set the number of records you want to receive in the response.

List APIs - Some tips to filter and search your API results

Zoho Books API provides several ways to searching and filtering through responses of list APIs (invoices, estimates and other entities)

  1. Use the filter_by parameter to filter an API response
  2. You can search an API response using search_text parameter.
  3. We support advanced search as well. Furthermore, advanced search comes with multiple parameters. This is specific to each entity and details are available in the respective entity's API documentation.
  4. Only one of the above options would be used on the response in the following order of preference:
    • Search
    • Filter
    • Advanced Search
  5. If none of the above options are specified in a request, the response will be filtered using the default filter. This is specific to each entity and details are available in the respective entity's API documentation.
  6. You can sort your response using the sort_order parameter.
    • sort_order=A - Ascending
    • sort_order=D - Descending
  7. Advanced Search Parameters like {date}.start/before and {date}.end/after works only in pair. An exception will be thrown, if just one of the parameters have been specified.
  8. Use last_modified_time parameter to fetch resources modified after a time.Date format supported is yyyy-MM-ddTHH:MM:ssZZZZ (2014-02-11T10:11:23-0123).

Points to Note :

Date format supported for any API request is yyyy-MM-dd (2013-10-25). We do not support other formats as input.