- Introduction
- OAuth
- HTTP Methods
- Response
- Errors
- Pagination
- Organizations
- Contacts
- Contact Persons
- Item Groups
- Items
- Composite Items
- Item Adjustments
- Transfer Orders
- Sales Orders
- Packages
- Shipment Orders
- Invoices
- Overview
- Create an invoice
- List invoices
- Update an invoice
- Get an invoice
- Delete an invoice
- Mark an invoice as sent
- Void an invoice
- Mark as draft
- Email an invoice
- Get invoice email content
- Email invoices
- Get payment reminder mail content
- Bulk export Invoices
- Bulk print invoices
- Disable payment reminder
- Enable payment reminder
- Write off invoice
- Cancel write off
- Update billing address
- Update shipping address
- List invoice templates
- Update invoice template
- List invoice payments
- List credits applied
- Apply credits
- Delete a payment
- Delete applied credit
- Add attachment to an invoice
- Update attachment preference
- Get an invoice attachment
- Delete an attachment
- Add comment
- List invoice comments & history
- Update comment
- Delete a comment
- Retainer Invoices
- Overview
- Create a retainer invoice
- List a retainer invoices
- update a retainer invoice
- Get a retainer invoice
- Delete a retainer invoice
- Mark a retainer invoice as sent
- Update retainer invoice template
- Void a retainer invoice
- Mark as draft
- Submit a retainer invoice for approval
- Approve a retainer invoice.
- Email a retainer invoice
- Get retainer invoice email content
- Update billing address
- List retainer invoice templates
- Add attachment to a retainer invoice
- Get a retainer invoice attachment
- Delete an attachment
- Add comment
- List retainer invoice comments & history
- Update comment
- Delete a comment
- Customer Payments
- Sales Returns
- Credit Notes
- Overview
- Create a credit note
- List all Credit Notes
- Update a credit note
- Get a credit note
- Delete a credit note
- Email a credit note
- Get email content
- Void a Credit Note
- Convert Credit Note to Draft
- Convert credit note to Open
- Submit a credit note for approval
- Approve a credit note
- Email history
- Update billing address
- Update Shipping address
- List the credit note templates
- Update a credit note template
- Apply credits to invoices
- List invoices credited
- Delete credits applied to an invoice
- Add a comment
- List credit note comments & history
- Delete a Comment
- List credit note refunds
- Refund credit note
- List refunds of a credit note
- Update credit note refund
- Get credit note refund
- Delete credit note refund
- Purchase Orders
- Purchase Receives
- Bills
- Vendor Credits
- Overview
- Create a vendor credit
- List vendor credits
- Update vendor credit
- Get vendor credit
- Delete vendor credit
- Convert to open
- Void vendor credit
- Submit a Vendor credit for approval
- Approve a Vendor credit
- Apply credits to a bill
- List bills credited
- Delete bills credited
- Refund a vendor credit
- List refunds of a vendor credit
- Update vendor credit refund
- Get vendor credit refund
- Delete vendor credit refund
- List vendor credit refunds
- Add a comment
- List vendor credit comments & history
- Delete a comment
- Warehouse Settings
- Price Lists
- Taxes
OAuth
Zakya REST APIs uses the OAuth 2.0 protocol to authorize and authenticate calls. It provides secure access to protect resources thereby reducing the hassle of asking for a username and password every time a user logs in. Follow the steps listed here, to access Zakya's APIs using OAuth 2.0
Note: The API URLs in this section should be modified, based on your domain.
Data Center | Domain | Base API URI |
---|---|---|
United States | .com | https://accounts.zoho.com/ |
India | .in | https://accounts.zoho.in/ |
You can read more about this here.
Step 1: Registering New Client
You will have to first register your application with Zoho's Developer console in order get your Client ID and Client Secret.
To register your application, go to https://accounts.zoho.com/developerconsole and click on Add Client ID. Provide the required details to register your application.
On successful registration, you will be provided with a set of OAuth 2.0 credentials such as a Client ID and Client Secret that are known to both Zoho and your application. Do not share these credentials anywhere.
Step 2: Generating Grant Token
Redirect to the following authorization URL with the given params
Parameter | Description |
---|---|
scope* | SCOPE for which the token to be generated. Multiple scopes can be given which has to be separated by commas. Ex : ZakyaAPI.FullAccess.all |
client_id* | Client ID obtained during Client Registration |
state | An opaque string that is round-tripped in the protocol; ie., whatever value given to this will be passed back to you. |
response_type* | code |
redirect_uri* | One of the redirect URI given in above step. This param should be same redirect url mentioned while registering the Client |
access_type | The allowed values are offline and online. The online access_type gives your application only the access_token which is valid for one hour. The offline access_type will give the application an access_token as well as a refresh_token. By default it is taken as online |
prompt | Prompts for user consent each time your app tries to access user credentials. Ex: Consent |
Note: Fields with * are mandatory
On this request, you will be shown with a "user consent page".
Upon clicking “Accept”, Zoho will redirect to the given redirect_uri with code and state param. This code value is mandatory to get the access token in the next step and this code is valid for 60 seconds.
On clicking “Deny”, the server returns an error
https://accounts.zoho.com/oauth/v2/auth?scope=ZakyaAPI.invoices.CREATE,ZakyaAPI.invoices.READ,ZakyaAPI.invoices.UPDATE,ZakyaAPI.invoices.DELETE&client_id=1000.0SRSxxxxxxxxxxxxxxxxxxxx239V&state=testing&response_type=code&prompt=consent&redirect_uri=http://www.zakya.com&access_type=offline
Step 3: Generate Access And Refresh Token
After getting code from the above step, make a POST request for the following URL with given params, to generate the
Parameter | Description |
---|---|
code* | code which is obtained in the above step |
client_id* | Client ID obtained during Client Registration |
client_secret* | Client secret obtained during Client Registration |
redirect_uri* | This param should be same redirect url mentioned while adding Client |
grant_type* | authorization_code |
scope | SCOPE for which token to be generated. Ex : ZakyaAPI.fullaccess.all. Multiple scopes has to be separated by commas. |
state | An opaque string that is round-tripped in the protocol; that is to say, value will be passed back to you. |
Note: Fields with * are mandatory
In the response, you will get both
and .1. The
will expire after a particular period (as given in param in the response).2. The
is permanent and will be used to regenerate new , if the current access token is expired.Note
- Each time a re-consent page is accepted, a new refresh token is generated. The maximum limit is 20 refresh tokens per user. If this limit is crossed, the first refresh token is automatically deleted to accommodate the latest one. This is done irrespective of whether the first refresh token is in use or not.
https://accounts.zoho.com/oauth/v2/token?code=1000.dd7exxxxxxxxxxxxxxxxxxxxxxxx9bb8.b6c0xxxxxxxxxxxxxxxxxxxxxxxxdca4&client_id=1000.0SRSxxxxxxxxxxxxxxxxxxxx239V&client_secret=fb01xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8abf&redirect_uri=http://www.zoho.com/inventory&grant_type=authorization_code
Step 4: Generate Access Token From Refresh Token
Access Tokens have limited validity. In most general cases the access tokens expire in one hour. Until then, the access token has unlimited usage. Once it expires, your app will have to use the refresh token to request for a new access token. Redirect to the following POST URL with the given params to get a new access token
Parameter | Description |
---|---|
refresh_token | REFRESH TOKEN which is obtained in the above step |
client_id | Client ID obtained during Client Registration |
client_secret | Client secret obtained during Client Registration |
redirect_uri | This param should be same redirect url mentioned while adding Client |
grant_type | refresh_token |
https://accounts.zoho.com/oauth/v2/token?refresh_token=1000.8ecdxxxxxxxxxxxxxxxxxxxxxxxx5cb7.463xxxxxxxxxxxxxxxxxxxxxxxxebdc&client_id=1000.0SRSxxxxxxxxxxxxxxxxxxxx239V&client_secret=fb01xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8abf&redirect_uri=http://www.zoho.com/inventory&grant_type=refresh_token
Step 5: Revoking A Refresh Token
To revoke a refresh token, call the following POST URL with the given params
Parameter | Description |
---|---|
token | REFRESH TOKEN which is to be revoked |
https://accounts.zoho.com/oauth/v2/token/revoke?token=1000.8ecdxxxxxxxxxxxxxxxxxxxxxxxx5cb7.4638xxxxxxxxxxxxxxxxxxxxxxxxebdc
Step 6: Calling An API
Access Token can be passed only in header and cannot be passed in the request param.
- Header name should be
- Header value should be
List of scopes available in Zakya :
Scope | Description |
---|---|
contacts | To access contacts related APIs Availabe types: ZakyaAPI.contacts.CREATE, ZakyaAPI.contacts.UPDATE, ZakyaAPI.contacts.READ, ZakyaAPI.contacts.DELETE |
items | To access item related APIs Availabe types: ZakyaAPI.items.CREATE, ZakyaAPI.items.UPDATE, ZakyaAPI.items.READ, ZakyaAPI.items.DELETE |
composite items | To access item related APIs Availabe types: ZakyaAPI.compositeitems.CREATE, ZakyaAPI.compositeitems.UPDATE, ZakyaAPI.compositeitems.READ, ZakyaAPI.compositeitems.DELETE |
inventory adjustments | To access inventory adjustments related APIs Availabe types: ZakyaAPI.inventoryadjustments.CREATE, ZakyaAPI.inventoryadjustments.READ, ZakyaAPI.inventoryadjustments.DELETE |
transfer orders | To access transfer order related APIs Availabe types: ZakyaAPI.transferorders.CREATE, ZakyaAPI.transferorders.READ, ZakyaAPI.transferorders.DELETE |
settings | To access users, taxes, currencies related APIs Availabe types: ZakyaAPI.settings.CREATE, ZakyaAPI.settings.UPDATE, ZakyaAPI.settings.READ, ZakyaAPI.settings.DELETE |
preferences | To access preferences related APIs Availabe types: ZakyaAPI.preferences.CREATE, ZakyaAPI.preferences.UPDATE, ZakyaAPI.preferences.READ, ZakyaAPI.preferences.DELETE |
salesorder | To access salesorder related APIs Availabe types: ZakyaAPI.salesorders.CREATE, ZakyaAPI.salesorders.UPDATE, ZakyaAPI.salesorders.READ, ZakyaAPI.salesorders.DELETE |
packages | To access Package related APIs Availabe types: ZakyaAPI.packages.CREATE, ZakyaAPI.packages.UPDATE, ZakyaAPI.packages.READ, ZakyaAPI.packages.DELETE |
shipmentorders | To access Shipment order related APIs Availabe types: ZakyaAPI.shipmentorders.CREATE, ZakyaAPI.shipmentorders.UPDATE, ZakyaAPI.shipmentorders.READ, ZakyaAPI.shipmentorders.DELETE |
invoices | To access invoices related APIs Availabe types: ZakyaAPI.invoices.CREATE, ZakyaAPI.invoices.UPDATE, ZakyaAPI.invoices.READ, ZakyaAPI.invoices.DELETE |
customerpayments | To access customer payments related APIs Availabe types: ZakyaAPI.customerpayments.CREATE, ZakyaAPI.customerpayments.UPDATE, ZakyaAPI.customerpayments.READ, ZakyaAPI.customerpayments.DELETE |
vendorpayments | To access vendor payments related APIs Availabe types: ZakyaAPI.vendorpayments.CREATE, ZakyaAPI.vendorpayments.UPDATE, ZakyaAPI.vendorpayments.READ, ZakyaAPI.vendorpayments.DELETE |
creditnotes | To access credit notes related APIs Availabe types: ZakyaAPI.creditnotes.CREATE, ZakyaAPI.creditnotes.UPDATE, ZakyaAPI.creditnotes.READ, ZakyaAPI.creditnotes.DELETE |
debitnotes | To access vendor credit related APIs Availabe types: ZakyaAPI.debitnotes.CREATE, ZakyaAPI.debitnotes.UPDATE, ZakyaAPI.debitnotes.READ, ZakyaAPI.debitnotes.DELETE |
purchaseorder | To access purchaseorder related APIs Availabe types: ZakyaAPI.purchaseorders.CREATE, ZakyaAPI.purchaseorders.UPDATE, ZakyaAPI.purchaseorders.READ, ZakyaAPI.purchaseorders.DELETE |
purchase receives | To access purchase receive related APIs Availabe types: ZakyaAPI.purchasereceives.CREATE, ZakyaAPI.purchasereceives.READ, ZakyaAPI.purchasereceives.DELETE |
bills | To access bills related APIs Availabe types: ZakyaAPI.bills.CREATE, ZakyaAPI.bills.UPDATE, ZakyaAPI.bills.READ, ZakyaAPI.bills.DELETE |