API Documentation
Introduction

Introduction

API Root Endpoint

https://expense.zoho.com/api/v1

Zoho expense service can be accessed via Zoho expense API. It gives you the freedom to expand and build on our programmatic base to suit your needs.

Built using REST principles, it makes application development incredibly easy for you. A wide range of HTTP clients can be used with this API since it follows HTTP rules.

Every resource is exposed as a URL. The URL of each resource can be obtained by accessing the API Root Endpoint.

Getting Started

Example

$ curl -X GET 'https://expense.zoho.com/api/v1/organizations' \ -H 'X-com-zoho-expense-organizationid: 11352208' \ -H 'Authorization: Zoho-oauthtoken 6e80ed905055deb9fd2d12d71f518a80'

All Zoho Expense APIs require a minimum of two mandatory headers.

  1. Authorization - Authentication request url parameter.
  2. X-com-zoho-expense-organizationid - the url parameter that contains the organization ID of the organization you need to access.

Authentication

All Zoho Expense APIs need to be authenticated using an oauth token.

OAuth 2.0 is an open authorization protocol which grants third party applications limited access to user accounts on an HTTP service. The authentication and authorization process is facilitated only between the end-user and the HTTP service. Zoho APIs use OAuth 2.0 to provide dependable security for your application data. OAuth 2.0 delegates authorization and authentication for web and desktop applications, and mobile devices.

You can abtain an OAuth token by following the steps mentioned below:

  1. Register your application
  2. Get an authorization grant
  3. Get an access token

1. Register your application

Before integrating Zoho APIs with your application using OAuth, you must register your application with Zoho. This can be done through the developer console of your Zoho account, where you will have to provide details regarding your application like Name , Website , Redirect URI, or Callback URL. Once the authorization is approved or denied, the user will be redirected to the callback URL specified at the time of registration.

Once your application is registered, the service will issue a client ID and a client secret. The Client ID is used by Zoho to verify the identity of the application and has a public visibility. The Client Secret is used to authorize the appropriate resources that can be accessed by the authenticated application. The Client Secret will be known only to Zoho APIs and the authenticated application.

Sample Response

On calling the API, it will redirect to the redirect uri given with the authorization grant appended to it like below:
https://app.example.com/oauth?state=tempstate&code=1000.47b8fa1a1676bda5da938decdf0cf0d6.d3f48797707de05fcac81d135dc7b6c0

2. Get an authorization grant

URL: https://accounts.zoho.com/oauth/v2/auth

Params:

Available Scopes:

Scopes Scope operations available
all ZohoExpense.fullaccess.ALL
expensereport ZohoExpense.expensereport.UPDATE, ZohoExpense.expensereport.READ, ZohoExpense.expensereport.CREATE, ZohoExpense.expensereport.DELETE
approval ZohoExpense.approval.CREATE
reimbursement ZohoExpense.reimbursement.CREATE
advance ZohoExpense.advance.UPDATE, ZohoExpense.advance.CREATE, ZohoExpense.advance.DELETE
users ZohoExpense.users.UPDATE, ZohoExpense.users.CREATE, ZohoExpense.users.DELETE,ZohoExpense.users.READ
settings ZohoExpense.orgsettings.UPDATE, ZohoExpense.orgsettings.CREATE, ZohoExpense.orgsettings.DELETE,ZohoExpense.orgsettings.READ

Actions under each scope:

1. all

2. expensereport

3. approval

4. reimbursement

5. advance

6. users

7. settings

Sample Response

{ "access_token": "1000.c656b09869cfef3be0ca145e44143fa9.a11f43090a54d71dc0797ec92bf34b9e", "refresh_token": "1000.4038qw5a8a5af1234ce920a45sx388a6.a450db33ca9e80701b1a23c8fe98e62e", "expires_in_sec": 3600, "api_domain": "https://www.zohoapis.com", "token_type": "Bearer", "expires_in": 3600000 }

3. Get an access token

After getting the authorization grant, post it to the below API to get the access token and the refresh token.

URL: https://accounts.zoho.com/oauth/v2/token

Params:

Note: expires_in parameter in response contains expiry time of access_token in milliseconds.

Sample Response

{ "access_token": "1000.e896b09869afef6be0ca145e44143fa9.a78f43090a54d71dc0797ec92bg44b9e", "expires_in_sec": 3600, "api_domain": "https://www.zohoapis.com", "token_type": "Bearer", "expires_in": 3600000 }

Regenerating the access token with the refresh token

Once the access token has expired, it can be regenerated from the refresh token by making POST call to the API given below.

URL: https://accounts.zoho.com/oauth/v2/token

Params:

Sample Response

{"status":"success"}

Revoking a Refresh Token

A Refresh Token can be revoked by calling the API given below.

URL: https://accounts.zoho.com/oauth/v2/token

Params: token = <Refresh token>

Organization ID

Request Example

$ curl -X GET 'https://expense.zoho.com/api/v1/organizations' \ -H 'Authorization: Zoho-oauthtoken 6e80ed905055deb9fd2d12d71f518a80'

Response Example

HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "organizations": [ { "organization_id": "10234695", "name": "Zillum", "contact_name": "John Smith", "email": "johnsmith@zillum.com", "is_default_org": false, "language_code": "en", "fiscal_year_start_month": 0, "account_created_date": "2016-02-18", "time_zone": "PST", "is_org_active": true, "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "currency_format": "###,##0.00", "price_precision": 2 }, {...}, {...} ] }

In Zoho Expense, your business is termed as an organization. If you have multiple business, you need to setup an individual organization for each of them. Each organization is an independent Zoho Expense Organization with its own organization ID, base currency, time zone, language, customers, reports, etc.

The Url parameter organization_id along with the organization ID should be sent in with every API request to identify the organization.

The organization_id can be obtained from the GET /organizations API’s JSON response.

HTTP Methods

Using GET method, you can get the list of resources or details of a particular instance of a resource. To get a list of customers
$ curl -X GET 'https://expense.zoho.com/api/v1/contacts' \ -H 'X-com-zoho-expense-organizationid: 11352208' \ -H 'Authorization: Zoho-oauthtoken 6e80ed905055deb9fd2d12d71f518a80'
To get the details of a customer referred to by a specified customer_id
$ curl -X GET 'https://expense.zoho.com/api/v1/contacts/903000000000099' \ -H 'X-com-zoho-expense-organizationid: 11352208' \ -H 'Authorization: Zoho-oauthtoken 6e80ed905055deb9fd2d12d71f518a80'

Zoho Expense API uses appropriate HTTP verbs for every action.

Method Description
GET Used for retrieving resources.
POST Used for creating resources and performing resource actions.
PUT Used for updating resources.
DELETE Used for deleting resources.

Response

Response Structure

The response structure for the expense API follows the below format.
{ "code" : 0, "message" : "success", "expense" : { "expense_id" : "..." } }

Request Example

$ curl -X GET 'https://expense.zoho.com/api/v1/expenses/7000000079426' \ -H 'X-com-zoho-expense-organizationid: 11352208' \ -H 'Authorization: Zoho-oauthtoken 6e80ed905055deb9fd2d12d71f518a80' \ -H 'Accept=pdf' OR $ curl -X GET 'https://expense.zoho.com/api/v1/expenses/7000000079426?accept=pdf' \ -H 'X-com-zoho-expense-organizationid: 11352208' \ -H 'Authorization: Zoho-oauthtoken 6e80ed905055deb9fd2d12d71f518a80'

Responses will be in the JSON format.

Node Name Description
code Zoho Expense error code. This will be zero for a success response and non-zero in case of an error.
message Message for the invoked API.
resource name Comprises the invoked API’s Data.

Response Header Example

HTTP/1.1 200 OK Content-Disposition: attachment; filename="EXP-384.pdf" Content-Type: application/pdf;charset=UTF-8


Other Formats

Certain APIs also support csv and pdf formats. The required response format needs to be specified in the respective request’s Accept header or accept query parameter.



















Date

All timestamps are returned in the ISO 8601 format - YYYY-MM-DDThh:mm:ssTZD.

Example: 2016-06-11T17:38:06-0700

Errors

Request Example

$ curl -X GET 'https://expense.zoho.com/api/v1/expenses/700000007942' \ -H 'X-com-zoho-expense-organizationid: 11352208' \ -H 'Authorization: Zoho-oauthtoken 6e80ed905055deb9fd2d12d71f518a80'

Response Example

HTTP/1.1 404 Not Found Content-Type: application/json;charset=UTF-8 { "code": 1002, "message": "Expense does not exist." }

Zoho Expense uses HTTP status codes to indicate success or failure of an API call. In general, status codes in the 2xx range means success, 4xx range means there was an error in the provided information, and those in the 5xx range indicate server side errors. Commonly used HTTP status codes are listed below.

HTTP Status Codes

Status Code Description
200 OK
201 Created
400 Bad request
401 Unauthorized (Invalid AuthToken)
404 URL Not Found
405 Method Not Allowed (Method you have called is not supported for the invoked API)
429 Rate Limit Exceeded (API usage limit exceeded)
500 Internal Error

Pagination

Example

$ curl -X GET 'https://expense.zoho.com/api/v1/contacts?page=2&per_page=25' \ -H 'X-com-zoho-expense-organizationid: 11352208' \ -H 'Authorization: Zoho-oauthtoken 6e80ed905055deb9fd2d12d71f518a80' { "code": 0, "message": "success", "customers": [ {...}, {...} ], "page_context": { "page": 2, "per_page": 25, "has_more_page": false } }

Zoho Expense provides APIs to retrieve lists of contacts, plans and other resources - paginated to 200 items by default. The pagination information will be included in the list API response under the node name page_context.

Expense Reports

An expense report entity allows you to maintain details of an expense report.

Example

{ "report_id": "16367000000081005", "report_name": "Trip to SFA", "description": "To client office", "report_number": "ER-00001", "start_date": "2017-02-07", "end_date": "2017-02-18", "due_date": "2017-03-15", "status": "submitted", "is_archived": false, "due_days": "Due in 15 days", "submitted_date": "2017-02-28", "last_submitted_date": "2017-02-28", "currency_id": "16367000000000099", "price_precision": 2, "currency_code": "INR", "approver_id": "16367000000073001", "approver_name": "PATRICIA BOYLE", "approver_email": "patriciab@zillum.com", "approver_photo_url": "https://contacts.zoho.com/file?ID=16b87b9dbae5b1008b32c9736141b6f63b3864c8cf94d900cf9bb346f0eb97b105c58df21a12283d421fa80a6cb97ffca294a909bc0c7ae9f1e14dd2e499565d&fs=thumb", "submitted_to_id": "16367000000073001", "submitted_to_name": "PATRICIA BOYLE", "submitted_to_email": "patriciab@zillum.com", "submitted_to_employee_no": "E001", "submitted_to_department_name": "Finance", "submitted_to_photo_url": "https://contacts.zoho.com/file?ID=16b87b9dbae5b1008b32c9736141b6f63b3864c8cf94d900cf9bb346f0eb97b105c58df21a12283d421fa80a6cb97ffca294a909bc0c7ae9f1e14dd2e499565d&fs=thumb", "submitted_by": "16367000000073071", "submitter_name": "Will Smith", "submitter_email": "will.smith@gmail.com", "total": 70000, "reimbursable_total": 70000, "non_reimbursable_total": 0, "created_time": "2017-02-28T18:18:03+0530", "created_date": "2017-02-28", "last_modified_time": "2017-02-28T18:31:09+0530", "created_by_id": "16367000000073071", "created_by_name": "Will Smith", "created_by_email": "will.smith@gmail.com", "creator_photo_url": "https://contacts.zoho.com/file?ID=16b87b9dbae5b1008b32c9736141b6f63b3864c8cf94d900cf9bb346f0eb97b105c58df21a12283d421fa80a6cb97ffca294a909bc0c7ae9f1e14dd2e499565d&fs=thumb", "tags": [ { "tag_id": "16367000000000301", "tag_name": "Tag 1", "tag_option_id": "16367000000225001", "tag_option_name": "Option 1" } ], "expenses": [ { "date": "2017-02-20", "receipt_name": "receipt1.jpg", "tax_amount": 5000, "start_reading": "", "category_name": "Lodging", "line_item_count": 1, "paid_through_account_id": "16367000000036003", "documents": [ { "file_name": "receipt1.jpg", "file_size_formatted": "35.6 KB", "attachment_order": 1, "document_id": "16367000000078085" } ], "project_name": "Brochure Design - Spa", "per_diem_rate": 0, "per_diem_days": 0, "project_id": "16367000000223045", "mileage_rate": 0, "order": 0, "expense_type": "non_mileage", "exchange_rate": 1, "is_inclusive_tax": false, "custom_fields": [ { "customfield_id": "16367000000277001", "label": "Other Name", "value": "Trip" } ], "attendees": "Will Smith", "per_diem_name": "", "merchant_name": "ABS Solutions", "transaction_description": "Has to be done Immediately..", "reference_number": "DD145", "tax_id": "16367000000219093", "is_personal": false, "due_days": "Due in 15 days", "comments_count": 0, "distance": 0, "policy_id": "16367000000092011", "description": "To client office", "merchant_id": "16367000000074027", "currency_code": "INR", "end_reading": "", "bcy_total": 70000, "total": 70000, "category_id": "16367000000033011", "receipt_type": "jpg", "maximum_allowed_amount": 0, "is_uncategorized": false, "is_mandatory_fields_missing": false, "paid_through_account_name": "Employee Reimbursements", "amount": 70000, "payment_mode": "Check", "last_modified_time": "2017-02-28T18:31:09+0530", "per_diem_id": "", "tax_name": "Service", "bcy_tax_amount": 2000, "vehicle_type": "Bike", "is_billable": false, "mileage_unit": "km", "is_expired": false, "receipt_required_amount": 0, "is_reimbursable": true, "expired_by": "", "tax_percentage": 4, "location": "Washington", "customer_name": "Peter", "customer_id": "16367000000088005", "expense_id": "16367000000078079", "currency_id": "16367000000000099" } ], "expired_expense_count": 0, "custom_fields": [ { "customfield_id": "16367000000277001", "label": "Other Name", "value": "Trip" } ], "uncategorized_expense_count": 0, "policy_violated": false, "reimbursements": [ { "employee_reimbursement_id": "16367000000101099", "date": "2017-02-20", "amount": 70000, "entity_type": 62, "bcy_amount": 70000, "notes": "Finish", "currency_code": "INR", "currency_id": "16367000000000099" } ], "advance_payments": [ { "date": "2017-02-20", "advance_payment_id": "16367000000243203", "reimbursement_entity_id": "", "currency_id": "16367000000000099", "currency_code": "INR", "exchange_rate": 1, "amount": 70000, "bcy_amount": 70000, "excess_amount": 0, "excess_bcy_amount": 0, "applied_amount": 70000, "applied_bcy_amount": 70000, "excess_applied_amount": 0, "excess_applied_bcy_amount": 0, "excess_unapplied_amount": 0, "excess_unapplied_bcy_amount": 0, "price_precision": 2 } ], "amount_to_be_reimbursed": 70000, "remaining_reimbursement_total": 0, "amount_to_be_refunded": 0, "advance_total": 70000, "customer_id": "16367000000088005", "customer_name": "Peter", "project_id": "16367000000223045", "project_name": "Brochure Design - Spa" }

Attribute

report_id
long
Unique ID for expense report generated by the server . This is used as identifier.
report_name
string
Name of the report.
description
string
Description of the report.
report_number
string
Report Number.
start_date
string
Start date of the report.
end_date
string
End date of the report.
due_date
string
Due date for the expense report.
status
string
Status of the report. Possible values can be draft or submitted or approved or rejected or reimbursed or recalled.
is_archived
boolean
Whether the report is archived. It can either be true or false.
due_days
string
Number of days till the due date.
submitted_date
string
Date of report submission.
last_submitted_date
string
Date of previous submission.
currency_id
long
Unique ID for currency.
price_precision
integer
Precise amount upto n decimal points.
currency_code
string
Currency code.
approver_id
long
Unique ID for the current approver.
approver_name
string
Current approver name.
approver_email
string
Email ID of the current approver.
approver_photo_url
string
Photo Url of the current approver.
submitted_to_id
long
ID of the person to whom the report was submitted first.
submitted_to_name
string
Name of the person to whom the report was submitted first.
submitted_to_email
string
Email ID of the person to whom the report was submitted first.
submitted_to_employee_no
string
Employee Number of the person to whom the report was submitted first.
submitted_to_department_name
string
Department Name of the person to whom the report was submitted first.
submitted_to_photo_url
string
Photo Url of the person to whom the report was submitted first.
submitted_by
long
Unique ID of the submitter.
submitter_name
string
Name of the submitter.
submitter_email
string
Email ID of the submitter.
total
double
Total amount.
reimbursable_total
double
Reimbursable amount.
non_reimbursable_total
double
Non reimbursable total.
created_time
string
Time when the report was created.
created_date
string
Date when the report was created.
last_modified_time
string
Time when the report was last modified.
created_by_id
long
ID of the person who created the report.
created_by_name
string
Name of the person who created the report.
created_by_email
string
Email ID of the person who created the report.
creator_photo_url
string
Photo Url of the person who created the report.
list
Tags associated with the Report.
tag_id
long
Unique ID for Tag generated by the server.
tag_name
string
Name of the Tag.
tag_option_id
long
Unique ID for Tag option generated by the server.
tag_option_name
string
Name of the Tag Option.
list
Expenses associated with User.
date
string
Date of Expense.
receipt_name
string
Receipt Name
tax_amount
double
Tax amount.
start_reading
string
Start reading of the odometer.
category_name
string
Name of the Expense Category.
line_item_count
integer
Number of Line Items.
paid_through_account_id
long
Unique ID for the paid through account.
list
Details of Documents attached.
file_name
string
Name of the Document.
file_size_formatted
string
Formatted value of File Size.
attachment_order
integer
Order of the Attached Document.
document_id
long
Unique Id for the Document.
project_name
string
Name of the project.
per_diem_rate
double
Rate per Diem.
per_diem_days
double
Number of Days for Diem.
project_id
long
Unique ID for project.
mileage_rate
double
Rate for mileage.
order
integer
Order of the expense in Report.
expense_type
string
Type of Expense.
exchange_rate
double
Exchange rate for the foreign currency.
is_inclusive_tax
boolean
Whether the Expense is inclusive of tax. It can either be true or false.
custom_fields
list
Custom Fields related to Expense.
customfield_id
long
Unique Id for the Custom Field.
label
string
Label of the Custom Field.
value
string
Value of the Custom Field.
attendees
string
Attendees of the Expense.
per_diem_name
string
Name of the Per Diem.
merchant_name
string
Name of the merchant.
transaction_description
string
Decription for Transaction.
reference_number
string
Reference Number
tax_id
long
Unique Id for the tax.
is_personal
boolean
Whether the expense is personal. It can either be true or false.
due_days
string
Number of days till the due date.
comments_count
integer
Number of Comments.
distance
double
Distance travelled.
policy_id
long
Unique Id for the Policy.
description
string
Description of the report.
merchant_id
long
Unique Id for Merchant.
currency_code
string
Currency code.
end_reading
long
End readind of the odometer.
bcy_total
double
Total in base currency.
total
double
Total amount.
category_id
long
Unique Id for the expense category.
receipt_type
string
Type of receipt.
maximum_allowed_amount
double
Maximum allowed expense amount.
is_uncategorized
boolean
Whether the expense is Uncategorized. It can either be true or false.
is_mandatory_fields_missing
boolean
Whether the mandatory fields are missing. It can either be true or false.
paid_through_account_name
string
Name of the paid through account.
amount
double
Total Amount.
payment_mode
string
Mode of payment for the expense.
last_modified_time
string
Time when the report was last modified.
per_diem_id
long
Unique Id for Per Diem.
tax_name
string
Name of the tax.
bcy_tax_amount
double
Tax Amount in Base Currency.
vehicle_type
string
Type of Vehicle.
is_billable
boolean
Whether the expense is a billable expense. It can either be true or false.
mileage_unit
string
Unit of mileage. Can be km or mile.
is_expired
boolean
Whether the expense is expired. It can either be true or false.
receipt_required_amount
double
Required Amount for Receipt.
is_reimbursable
boolean
Whether the expense is reimbursable. It can either be true or false.
expired_by
string
No. of days since the expense has expired.
tax_percentage
double
Percentage of Tax.
location
string
Location.
customer_name
string
Name of the Customer.
customer_id
long
Unique Id for the Customer.
expense_id
long
Unique Id of the Expense.
currency_id
long
Unique ID for currency.
expired_expense_count
integer
Number of expenses expired.
custom_fields
list
Custom Fields related to Expense.
customfield_id
long
Unique Id for the Custom Field.
label
string
Label of the Custom Field.
value
string
Value of the Custom Field.
uncategorized_expense_count
integer
Number of uncategorised expenses.
policy_violated
boolean
Whether expense policies are violated. It can either be true or false.
reimbursements
list
Reimbursements made for the expense report.
employee_reimbursement_id
long
Unique Id of reimbursement.
date
string
Date of Expense.
amount
double
Total Amount.
entity_type
integer
Type of entity.
bcy_amount
double
Amount in Base Currency.
notes
string
Notes on Reimbursement.
currency_code
string
Currency code.
currency_id
long
Unique ID for currency.
advance_payments
list
Advance payments made on the expense report.
date
string
Date of Expense.
advance_payment_id
long
Unique Id of advance payment.
reimbursement_entity_id
string
Entity Id of reimbursement.
currency_id
long
Unique ID for currency.
currency_code
string
Currency code.
exchange_rate
double
Exchange rate for the foreign currency.
amount
double
Total Amount.
bcy_amount
double
Amount in Base Currency.
excess_amount
double
Excess Amount.
excess_bcy_amount
double
Excess Amount in Base Currency.
applied_amount
double
Applied Amount.
applied_bcy_amount
double
Applied Amount in Base Currency.
excess_applied_amount
double
Excess Applied Amount.
excess_applied_bcy_amount
double
Excess Applied Amount in Base Currency.
excess_unapplied_amount
double
Excess Unapplied Amount.
excess_unapplied_bcy_amount
double
Excess Unapplied Amount in Base Currency.
price_precision
integer
Precise amount upto n decimal points.
amount_to_be_reimbursed
double
Amount to be reimbursed.
remaining_reimbursement_total
long
Remaining reimbursement amount.
amount_to_be_refunded
double
Amount to be refunded.
advance_total
double
Total advance amount.
customer_id
long
Unique Id for the Customer.
customer_name
string
Name of the Customer.
project_id
long
Unique ID for project.
project_name
string
Name of the project.

Create an expense report

Create a new expense report.

POST /expensereports

Request Example

  
$ curl https://expense.zoho.com/api/v1/expensereports -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "report_name": "Trip to SFA", "description": "To client office", "start_date": "2017-02-07", "end_date": "2017-02-18", "expenses": [ { "expense_id": "16367000000078079", "order": 0 } ], "custom_fields": [ { "customfield_id": "16367000000277001", "value": "Trip" } ], "customer_id": "16367000000088005", "project_id": "16367000000223045", "tags": [ { "tag_id": "16367000000000301", "tag_option_id": "16367000000225001" } ] }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Expense report created successfully.", "expense_report": { "report_id": "16367000000081005", "report_name": "Trip to SFA", "description": "To client office", "report_number": "ER-00001", "start_date": "2017-02-07", "end_date": "2017-02-18", "status": "submitted", "currency_id": "16367000000000099", "price_precision": 2, "currency_code": "INR", "total": 70000, "reimbursable_total": 70000, "non_reimbursable_total": 0, "created_time": "2017-02-28T18:18:03+0530", "created_date": "2017-02-28", "created_by_id": "16367000000073071", "created_by_name": "Will Smith", "created_by_email": "will.smith@gmail.com", "tags": [ { "tag_id": "16367000000000301", "tag_name": "Tag 1", "tag_option_id": "16367000000225001", "tag_option_name": "Option 1" } ], "expenses": [ { "date": "2017-02-20", "receipt_name": "receipt1.jpg", "tax_amount": 5000, "start_reading": "", "category_name": "Lodging", "line_item_count": 1, "paid_through_account_id": "16367000000036003", "documents": [ { "file_name": "receipt1.jpg", "file_size_formatted": "35.6 KB", "attachment_order": 1, "document_id": "16367000000078085" } ], "project_name": "Brochure Design - Spa", "per_diem_rate": 0, "per_diem_days": 0, "project_id": "16367000000223045", "mileage_rate": 0, "order": 0, "expense_type": "non_mileage", "exchange_rate": 1, "is_inclusive_tax": false, "custom_fields": [ { "customfield_id": "16367000000277001", "label": "Other Name", "value": "Trip" } ], "attendees": "Will Smith", "per_diem_name": "", "merchant_name": "ABS Solutions", "transaction_description": "Has to be done Immediately..", "reference_number": "DD145", "tax_id": "16367000000219093", "is_personal": false, "due_days": "Due in 15 days", "comments_count": 0, "distance": 0, "policy_id": "16367000000092011", "description": "To client office", "merchant_id": "16367000000074027", "currency_code": "INR", "end_reading": "", "bcy_total": 70000, "total": 70000, "category_id": "16367000000033011", "receipt_type": "jpg", "maximum_allowed_amount": 0, "is_uncategorized": false, "is_mandatory_fields_missing": false, "paid_through_account_name": "Employee Reimbursements", "amount": 70000, "payment_mode": "Check", "last_modified_time": "2017-02-28T18:31:09+0530", "per_diem_id": "", "tax_name": "Service", "bcy_tax_amount": 2000, "vehicle_type": "Bike", "is_billable": false, "mileage_unit": "km", "is_expired": false, "receipt_required_amount": 0, "is_reimbursable": true, "expired_by": "", "tax_percentage": 4, "location": "Washington", "customer_name": "Peter", "customer_id": "16367000000088005", "expense_id": "16367000000078079", "currency_id": "16367000000000099" } ], "expired_expense_count": 0, "reimbursable_expenses_count": 1, "non_reimbursable_expenses_count": 0, "custom_fields": [ { "customfield_id": "16367000000277001", "label": "Other Name", "value": "Trip" } ], "customer_id": "16367000000088005", "customer_name": "Peter", "project_id": "16367000000223045", "project_name": "Brochure Design - Spa", "employee_number": "E001", "department_id": "16367000000093001", "department_name": "Finance", "policy_id": "16367000000092011", "policy_name": "Savings" } }

ARGUMENTS

report_name
Required
Name of the report.
description
Optional
Description of the report.
start_date
Required
Start date of the report.
end_date
Required
End date of the report.
Optional
Expenses associated with User.
expense_id
Required
Unique Id of the Expense.
order
Optional
Order of the expense in Report.
custom_fields
Optional
Custom Fields related to Expense.
customfield_id
Required
Unique Id for the Custom Field.
value
Required
Value of the Custom Field.
customer_id
Optional
Unique Id for the Customer.
project_id
Optional
Unique ID for project.
Optional
Tags associated with the Report.
tag_id
Required
Unique ID for Tag generated by the server.
tag_option_id
Required
Unique ID for Tag option generated by the server.

Retrieve details of an expense report

Details of an existing expense report.

GET /expensereports/{expense_report_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/expensereports/{expense_report_id} -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "expense_report": { "report_id": "16367000000081005", "report_name": "Trip to SFA", "description": "To client office", "report_number": "ER-00001", "start_date": "2017-02-07", "end_date": "2017-02-18", "due_date": "2017-03-15", "status": "submitted", "is_archived": false, "due_days": "Due in 15 days", "submitted_date": "2017-02-28", "last_submitted_date": "2017-02-28", "currency_id": "16367000000000099", "price_precision": 2, "currency_code": "INR", "approver_id": "16367000000073001", "approver_name": "PATRICIA BOYLE", "approver_email": "patriciab@zillum.com", "approver_photo_url": "https://contacts.zoho.com/file?ID=16b87b9dbae5b1008b32c9736141b6f63b3864c8cf94d900cf9bb346f0eb97b105c58df21a12283d421fa80a6cb97ffca294a909bc0c7ae9f1e14dd2e499565d&fs=thumb", "submitted_to_id": "16367000000073001", "submitted_to_name": "PATRICIA BOYLE", "submitted_to_email": "patriciab@zillum.com", "submitted_to_employee_no": "E001", "submitted_to_department_name": "Finance", "submitted_to_photo_url": "https://contacts.zoho.com/file?ID=16b87b9dbae5b1008b32c9736141b6f63b3864c8cf94d900cf9bb346f0eb97b105c58df21a12283d421fa80a6cb97ffca294a909bc0c7ae9f1e14dd2e499565d&fs=thumb", "submitted_by": "16367000000073071", "submitter_name": "Will Smith", "submitter_email": "will.smith@gmail.com", "submitter_photo_url": "https://contacts.zoho.com/file?ID=16b87b9dbae5b1008b32c9736141b6f63b3864c8cf94d900cf9bb346f0eb97b105c58df21a12283d421fa80a6cb97ffca294a909bc0c7ae9f1e14dd2e499565d&fs=thumb", "submitter_employee_no": "E002", "submitter_department_name": "Maintenance", "total": 70000, "reimbursable_total": 70000, "non_reimbursable_total": 0, "created_time": "2017-02-28T18:18:03+0530", "created_date": "2017-02-28", "last_modified_time": "2017-02-28T18:31:09+0530", "created_by_id": "16367000000073071", "created_by_name": "Will Smith", "created_by_email": "will.smith@gmail.com", "creator_photo_url": "https://contacts.zoho.com/file?ID=16b87b9dbae5b1008b32c9736141b6f63b3864c8cf94d900cf9bb346f0eb97b105c58df21a12283d421fa80a6cb97ffca294a909bc0c7ae9f1e14dd2e499565d&fs=thumb", "tags": [ { "tag_id": "16367000000000301", "tag_name": "Tag 1", "tag_option_id": "16367000000225001", "tag_option_name": "Option 1" } ], "expenses": [ { "date": "2017-02-20", "receipt_name": "receipt1.jpg", "tax_amount": 5000, "start_reading": "", "category_name": "Lodging", "line_item_count": 1, "paid_through_account_id": "16367000000036003", "documents": [ { "file_name": "receipt1.jpg", "file_size_formatted": "35.6 KB", "attachment_order": 1, "document_id": "16367000000078085" } ], "project_name": "Brochure Design - Spa", "per_diem_rate": 0, "per_diem_days": 0, "project_id": "16367000000223045", "mileage_rate": 0, "order": 0, "expense_type": "non_mileage", "exchange_rate": 1, "is_inclusive_tax": false, "custom_fields": [ { "customfield_id": "16367000000277001", "label": "Other Name", "value": "Trip" } ], "attendees": "Will Smith", "per_diem_name": "", "merchant_name": "ABS Solutions", "transaction_description": "Has to be done Immediately..", "reference_number": "DD145", "tax_id": "16367000000219093", "is_personal": false, "due_days": "Due in 15 days", "comments_count": 0, "distance": 0, "policy_id": "16367000000092011", "description": "To client office", "merchant_id": "16367000000074027", "currency_code": "INR", "end_reading": "", "bcy_total": 70000, "total": 70000, "category_id": "16367000000033011", "receipt_type": "jpg", "maximum_allowed_amount": 0, "is_uncategorized": false, "is_mandatory_fields_missing": false, "paid_through_account_name": "Employee Reimbursements", "amount": 70000, "payment_mode": "Check", "last_modified_time": "2017-02-28T18:31:09+0530", "per_diem_id": "", "tax_name": "Service", "bcy_tax_amount": 2000, "vehicle_type": "Bike", "is_billable": false, "mileage_unit": "km", "is_expired": false, "receipt_required_amount": 0, "is_reimbursable": true, "expired_by": "", "tax_percentage": 4, "location": "Washington", "customer_name": "Peter", "customer_id": "16367000000088005", "expense_id": "16367000000078079", "currency_id": "16367000000000099" } ], "expired_expense_count": 0, "reimbursable_expenses_count": 1, "non_reimbursable_expenses_count": 0, "custom_fields": [ { "customfield_id": "16367000000277001", "label": "Other Name", "value": "Trip" } ], "uncategorized_expense_count": 0, "policy_violated": false, "reimbursements": [ { "employee_reimbursement_id": "16367000000101099", "date": "2017-02-20", "amount": 70000, "entity_type": 62, "bcy_amount": 70000, "notes": "Finish", "currency_code": "INR", "currency_id": "16367000000000099" } ], "advance_payments": [ { "date": "2017-02-20", "advance_payment_id": "16367000000243203", "reimbursement_entity_id": "", "currency_id": "16367000000000099", "currency_code": "INR", "exchange_rate": 1, "amount": 70000, "bcy_amount": 70000, "excess_amount": 0, "excess_bcy_amount": 0, "applied_amount": 70000, "applied_bcy_amount": 70000, "excess_applied_amount": 0, "excess_applied_bcy_amount": 0, "excess_unapplied_amount": 0, "excess_unapplied_bcy_amount": 0, "price_precision": 2 } ], "is_advancepayment_allowed": true, "amount_to_be_reimbursed": 70000, "remaining_reimbursement_total": 0, "amount_to_be_refunded": 0, "advance_total": 70000, "can_create_advance": true, "customer_id": "16367000000088005", "customer_name": "Peter", "project_id": "16367000000223045", "project_name": "Brochure Design - Spa", "employee_number": "E001", "department_id": "16367000000093001", "department_name": "Finance", "next_approver_id": "16367000000073001", "next_approver_email": "patriciab@zillum.com", "next_approver_name": "PATRICIA BOYLE", "approver_employee_no": "E001", "approver_department_name": "Finance", "previous_approver_id": "", "previous_approver_name": "", "previous_approver_employee_no": "", "previous_approver_department_name": "", "policy_id": "16367000000092011", "policy_name": "Savings", "unreported_expenses_count": 1, "unreported_expenses": [ { "expense_id": "16367000000078079", "date": "2017-02-20", "category_id": "16367000000033011", "category_name": "Lodging", "total": 70000, "paid_through_account_id": "16367000000036003", "paid_through_account_name": "Employee Reimbursements", "bcy_total": 70000, "currency_code": "INR", "currency_id": "16367000000000099", "receipt_name": "receipt1.jpg", "is_billable": false, "customer_id": "16367000000088005", "customer_name": "Peter", "project_id": "16367000000223045", "project_name": "Brochure Design - Spa", "is_reimbursable": true, "merchant_id": "16367000000074027", "merchant_name": "ABS Solutions", "distance": 0, "mileage_rate": 0, "mileage_unit": "km", "mileage_type": "non_mileage", "start_reading": "", "end_reading": "", "receipt_type": "jpg", "documents": [ { "file_name": "receipt1.jpg", "file_size_formatted": "35.6 KB", "attachment_order": 1, "document_id": "16367000000078085" } ], "exchange_rate": 1, "is_uncategorized": false, "due_days": "Due in 15 days", "expired_by": "", "is_expired": false, "payment_mode": "Check", "transaction_description": "Has to be done Immediately.." } ], "users": [ { "user_id": "16367000000073001", "role_id": "16367000000030001", "name": "Will Smith", "email": "will.smith@gmail.com", "default_approver_id": "16367000000030001", "default_approver_name": "PATRICIA BOYLE", "user_role": "admin", "can_approve": true, "is_current_user": true, "email_ids": [ { "is_selected": true, "email": "will.smith@gmail.com" } ], "status": "submitted", "photo_url": "https://contacts.zoho.com/file?ID=16b87b9dbae5b1008b32c9736141b6f63b3864c8cf94d900cf9bb346f0eb97b105c58df21a12283d421fa80a6cb97ffca294a909bc0c7ae9f1e14dd2e499565d&fs=thumb", "approves_to_id": "16367000000030001", "approves_to_name": "PATRICIA BOYLE", "submission_amount_limit": 0, "approval_amount_limit": 0, "created_time": "2017-02-28T18:18:03+0530", "last_modified_time": "2017-02-28T18:31:09+0530", "policy_id": "16367000000092011", "policy_name": "Savings" } ] } }

List of all expense reports

List of all the submitted expense reports.

GET /expensereports?filter_by=Type.Approval%2CStatus.Approved

Request Example

  
$ curl https://expense.zoho.com/api/v1/expensereports?filter_by=Type.Approval%2CStatus.Approved -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "expense_reports": [ { "report_id": "16367000000081005", "report_name": "Trip to SFA", "description": "To client office", "report_number": "ER-00001", "start_date": "2017-02-07", "end_date": "2017-02-18", "status": "submitted", "is_archived": false, "due_date": "2017-03-15", "submitted_date": "2017-02-28", "approved_date": "2017-03-01", "last_submitted_date": "2017-02-28", "currency_id": "16367000000000099", "currency_code": "INR", "approver_id": "16367000000073001", "approver_name": "PATRICIA BOYLE", "approver_email": "patriciab@zillum.com", "submitted_to_id": "16367000000073001", "submitted_to_name": "PATRICIA BOYLE", "submitted_to_email": "patriciab@zillum.com", "submitter_email": "will.smith@gmail.com", "submitted_by": "16367000000073071", "submitter_name": "Will Smith", "total": 70000, "reimbursable_total": 70000, "reimbursement_date": "2017-03-01", "non_reimbursable_total": 0, "created_time": "2017-02-28T18:18:03+0530", "last_modified_time": "2017-02-28T18:31:09+0530", "created_by_id": "16367000000073071", "created_by_name": "Will Smith", "comments_count": 0, "policy_violated": false, "uncategorized_expense_count": 0, "customer_id": "16367000000088005", "custom_fields": [ { "customfield_id": "16367000000277001", "label": "Other Name", "value": "Trip" } ], "project_id": "16367000000223045", "customer_name": "Peter", "project_name": "Brochure Design - Spa", "policy_id": "16367000000092011", "policy_name": "Savings", "due_days": "Due in 15 days" }, {...}, {...} ] }

Query Params

Optional
For Filtering Expense Reports based on status.
Type.Approval%2CStatus.Submitted
Optional
List of all Submitted Reports.
Type.Approval%2CStatus.Approved
Optional
List of all Approved Reports.
Type.Approval%2CStatus.Rejected
Optional
List of all Rejected Reports.
Type.Approval%2CStatus.Reimbursed
Optional
List of all Reimbursed Reports.

Update an expense report

Update the details of an expense report.

PUT /expensereports/{expense_report_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/expensereports/{expense_report_id} -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "report_name": "Trip to SFA", "description": "To client office", "start_date": "2017-02-07", "end_date": "2017-02-18", "expenses": [ { "expense_id": "16367000000078079", "order": 0 } ], "custom_fields": [ { "customfield_id": "16367000000277001", "value": "Trip" } ], "customer_id": "16367000000088005", "project_id": "16367000000223045", "tags": [ { "tag_id": "16367000000000301", "tag_option_id": "16367000000225001" } ] }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Expense report details updated successfully.", "expense_report": { "report_id": "16367000000081005", "report_name": "Trip to SFA", "description": "To client office", "report_number": "ER-00001", "start_date": "2017-02-07", "end_date": "2017-02-18", "status": "submitted", "currency_id": "16367000000000099", "price_precision": 2, "currency_code": "INR", "total": 70000, "reimbursable_total": 70000, "non_reimbursable_total": 0, "created_time": "2017-02-28T18:18:03+0530", "created_date": "2017-02-28", "created_by_id": "16367000000073071", "created_by_name": "Will Smith", "created_by_email": "will.smith@gmail.com", "last_modified_time": "2017-02-28T18:31:09+0530", "tags": [ { "tag_id": "16367000000000301", "tag_name": "Tag 1", "tag_option_id": "16367000000225001", "tag_option_name": "Option 1" } ], "expenses": [ { "date": "2017-02-20", "receipt_name": "receipt1.jpg", "tax_amount": 5000, "start_reading": "", "category_name": "Lodging", "line_item_count": 1, "paid_through_account_id": "16367000000036003", "documents": [ { "file_name": "receipt1.jpg", "file_size_formatted": "35.6 KB", "attachment_order": 1, "document_id": "16367000000078085" } ], "project_name": "Brochure Design - Spa", "per_diem_rate": 0, "per_diem_days": 0, "project_id": "16367000000223045", "mileage_rate": 0, "order": 0, "expense_type": "non_mileage", "exchange_rate": 1, "is_inclusive_tax": false, "custom_fields": [ { "customfield_id": "16367000000277001", "label": "Other Name", "value": "Trip" } ], "attendees": "Will Smith", "per_diem_name": "", "merchant_name": "ABS Solutions", "transaction_description": "Has to be done Immediately..", "reference_number": "DD145", "tax_id": "16367000000219093", "is_personal": false, "due_days": "Due in 15 days", "comments_count": 0, "distance": 0, "policy_id": "16367000000092011", "description": "To client office", "merchant_id": "16367000000074027", "currency_code": "INR", "end_reading": "", "bcy_total": 70000, "total": 70000, "category_id": "16367000000033011", "receipt_type": "jpg", "maximum_allowed_amount": 0, "is_uncategorized": false, "is_mandatory_fields_missing": false, "paid_through_account_name": "Employee Reimbursements", "amount": 70000, "payment_mode": "Check", "last_modified_time": "2017-02-28T18:31:09+0530", "per_diem_id": "", "tax_name": "Service", "bcy_tax_amount": 2000, "vehicle_type": "Bike", "is_billable": false, "mileage_unit": "km", "is_expired": false, "receipt_required_amount": 0, "is_reimbursable": true, "expired_by": "", "tax_percentage": 4, "location": "Washington", "customer_name": "Peter", "customer_id": "16367000000088005", "expense_id": "16367000000078079", "currency_id": "16367000000000099" } ], "expired_expense_count": 0, "reimbursable_expenses_count": 1, "non_reimbursable_expenses_count": 0, "custom_fields": [ { "customfield_id": "16367000000277001", "label": "Other Name", "value": "Trip" } ], "customer_id": "16367000000088005", "customer_name": "Peter", "project_id": "16367000000223045", "project_name": "Brochure Design - Spa", "employee_number": "E001", "department_id": "16367000000093001", "department_name": "Finance", "policy_id": "16367000000092011", "policy_name": "Savings" } }

ARGUMENTS

report_name
Optional
Name of the report.
description
Optional
Description of the report.
start_date
Optional
Start date of the report.
end_date
Optional
End date of the report.
Required
Expenses associated with User.
expense_id
Required
Unique Id of the Expense.
order
Optional
Order of the expense in Report.
custom_fields
Optional
Custom Fields related to Expense.
customfield_id
Required
Unique Id for the Custom Field.
value
Required
Value of the Custom Field.
customer_id
Optional
Unique Id for the Customer.
project_id
Optional
Unique ID for project.
Optional
Tags associated with the Report.
tag_id
Required
Unique ID for Tag generated by the server.
tag_option_id
Required
Unique ID for Tag option generated by the server.

Approve an expense report

Approve an expense report.

POST /expensereports/{expense_report_id}/approve

Request Example

  
$ curl https://expense.zoho.com/api/v1/expensereports/{expense_report_id}/approve -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Report approved successfully" }

Reject an expense report

Reject an expense report.

POST /expensereports/{expense_report_id}/reject

Request Example

  
$ curl https://expense.zoho.com/api/v1/expensereports/{expense_report_id}/reject -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "comments": "Purpose is not valid." }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Report has been rejected" }

ARGUMENTS

comments
Optional
Comments on the report.

Reimburse an expense report

Reimburse an expense report.

POST /expensereports/{expense_report_id}/reimburse

Request Example

  
$ curl https://expense.zoho.com/api/v1/expensereports/{expense_report_id}/reimburse -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "notes": "Finish", "date": "2017-02-20", "amount": 70000, "reference_number": "DD145", "currency_id": "16367000000000099" }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Report has been reimbursed", "expense_report_reimbursed": { "report_id": "16367000000081005", "report_name": "Trip to SFA", "description": "To client office", "report_number": "ER-00001", "start_date": "2017-02-07", "end_date": "2017-02-18", "due_date": "2017-03-15", "status": "submitted", "is_archived": false, "due_days": "Due in 15 days", "submitted_date": "2017-02-28", "last_submitted_date": "2017-02-28", "currency_id": "16367000000000099", "price_precision": 2, "currency_code": "INR", "approver_id": "16367000000073001", "approver_name": "PATRICIA BOYLE", "approver_email": "patriciab@zillum.com", "approver_photo_url": "https://contacts.zoho.com/file?ID=16b87b9dbae5b1008b32c9736141b6f63b3864c8cf94d900cf9bb346f0eb97b105c58df21a12283d421fa80a6cb97ffca294a909bc0c7ae9f1e14dd2e499565d&fs=thumb", "submitted_to_id": "16367000000073001", "submitted_to_name": "PATRICIA BOYLE", "submitted_to_email": "patriciab@zillum.com", "submitted_to_employee_no": "E001", "submitted_to_department_name": "Finance", "submitted_to_photo_url": "https://contacts.zoho.com/file?ID=16b87b9dbae5b1008b32c9736141b6f63b3864c8cf94d900cf9bb346f0eb97b105c58df21a12283d421fa80a6cb97ffca294a909bc0c7ae9f1e14dd2e499565d&fs=thumb", "submitted_by": "16367000000073071", "submitter_name": "Will Smith", "submitter_email": "will.smith@gmail.com", "submitter_photo_url": "https://contacts.zoho.com/file?ID=16b87b9dbae5b1008b32c9736141b6f63b3864c8cf94d900cf9bb346f0eb97b105c58df21a12283d421fa80a6cb97ffca294a909bc0c7ae9f1e14dd2e499565d&fs=thumb", "submitter_employee_no": "E002", "submitter_department_name": "Maintenance", "total": 70000, "reimbursable_total": 70000, "non_reimbursable_total": 0, "created_time": "2017-02-28T18:18:03+0530", "created_date": "2017-02-28", "last_modified_time": "2017-02-28T18:31:09+0530", "created_by_id": "16367000000073071", "created_by_name": "Will Smith", "created_by_email": "will.smith@gmail.com", "creator_photo_url": "https://contacts.zoho.com/file?ID=16b87b9dbae5b1008b32c9736141b6f63b3864c8cf94d900cf9bb346f0eb97b105c58df21a12283d421fa80a6cb97ffca294a909bc0c7ae9f1e14dd2e499565d&fs=thumb", "expenses": [ { "date": "2017-02-20", "receipt_name": "receipt1.jpg", "tax_amount": 5000, "start_reading": "", "category_name": "Lodging", "line_item_count": 1, "paid_through_account_id": "16367000000036003", "documents": [ { "file_name": "receipt1.jpg", "file_size_formatted": "35.6 KB", "attachment_order": 1, "document_id": "16367000000078085" } ], "project_name": "Brochure Design - Spa", "per_diem_rate": 0, "per_diem_days": 0, "project_id": "16367000000223045", "mileage_rate": 0, "order": 0, "expense_type": "non_mileage", "exchange_rate": 1, "is_inclusive_tax": false, "custom_fields": [ { "customfield_id": "16367000000277001", "label": "Other Name", "value": "Trip" } ], "attendees": "Will Smith", "per_diem_name": "", "merchant_name": "ABS Solutions", "transaction_description": "Has to be done Immediately..", "reference_number": "DD145", "tax_id": "16367000000219093", "is_personal": false, "due_days": "Due in 15 days", "comments_count": 0, "distance": 0, "policy_id": "16367000000092011", "description": "To client office", "merchant_id": "16367000000074027", "currency_code": "INR", "end_reading": "", "bcy_total": 70000, "total": 70000, "category_id": "16367000000033011", "receipt_type": "jpg", "maximum_allowed_amount": 0, "is_uncategorized": false, "is_mandatory_fields_missing": false, "paid_through_account_name": "Employee Reimbursements", "amount": 70000, "payment_mode": "Check", "last_modified_time": "2017-02-28T18:31:09+0530", "per_diem_id": "", "tax_name": "Service", "bcy_tax_amount": 2000, "vehicle_type": "Bike", "is_billable": false, "mileage_unit": "km", "is_expired": false, "receipt_required_amount": 0, "is_reimbursable": true, "expired_by": "", "tax_percentage": 4, "location": "Washington", "customer_name": "Peter", "customer_id": "16367000000088005", "expense_id": "16367000000078079", "currency_id": "16367000000000099" } ], "expired_expense_count": 0, "reimbursable_expenses_count": 1, "non_reimbursable_expenses_count": 0, "custom_fields": [ { "customfield_id": "16367000000277001", "label": "Other Name", "value": "Trip" } ], "uncategorized_expense_count": 0, "policy_violated": false, "reimbursements": [ { "employee_reimbursement_id": "16367000000101099", "date": "2017-02-20", "amount": 70000, "entity_type": 62, "bcy_amount": 70000, "notes": "Finish", "currency_code": "INR", "currency_id": "16367000000000099" } ], "advance_payments": [ { "date": "2017-02-20", "advance_payment_id": "16367000000243203", "reimbursement_entity_id": "", "currency_id": "16367000000000099", "currency_code": "INR", "exchange_rate": 1, "amount": 70000, "bcy_amount": 70000, "excess_amount": 0, "excess_bcy_amount": 0, "applied_amount": 70000, "applied_bcy_amount": 70000, "excess_applied_amount": 0, "excess_applied_bcy_amount": 0, "excess_unapplied_amount": 0, "excess_unapplied_bcy_amount": 0, "price_precision": 2 } ], "is_advancepayment_allowed": true, "amount_to_be_reimbursed": 70000, "remaining_reimbursement_total": 0, "amount_to_be_refunded": 0, "advance_total": 70000, "can_create_advance": true, "customer_id": "16367000000088005", "customer_name": "Peter", "project_id": "16367000000223045", "project_name": "Brochure Design - Spa", "employee_number": "E001", "department_id": "16367000000093001", "department_name": "Finance", "next_approver_id": "16367000000073001", "next_approver_email": "patriciab@zillum.com", "next_approver_name": "PATRICIA BOYLE", "approver_employee_no": "E001", "approver_department_name": "Finance", "previous_approver_id": "", "previous_approver_name": "", "previous_approver_employee_no": "", "previous_approver_department_name": "", "policy_id": "16367000000092011", "policy_name": "Savings" } }

ARGUMENTS

notes
Optional
Notes on Reimbursement.
date
Optional
Date of Expense.
amount
Optional
Total Amount.
reference_number
Optional
Reference Number
currency_id
Optional
Unique ID for currency.

Approval history of an expense report

Approval history of an expense report.

GET /expensereports/{expense_report_id}/approvalhistory

Request Example

  
$ curl https://expense.zoho.com/api/v1/expensereports/{expense_report_id}/approvalhistory -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "approval_history": [ { "approval_history_id": "16367000000101079", "report_name": "Trip to SFA", "report_id": "16367000000081005", "report_number": "ER-00001", "expense_id": "16367000000078079", "comments": "Purpose is not valid.", "description": "To client office", "type": "approval_history", "previous_status": "approved", "approval_status": "approved", "previous_approver_id": "", "previous_approver_name": "", "previous_approver_email": "will.smith@gmail.com", "approver_id": "16367000000073001", "approver_name": "PATRICIA BOYLE", "date": "2017-02-20", "time": "5:59 PM", "commented_by_id": "16367000000073001", "commented_by": "Will Smith", "photo_url": "https://contacts.zoho.com/file?ID=16b87b9dbae5b1008b32c9736141b6f63b3864c8cf94d900cf9bb346f0eb97b105c58df21a12283d421fa80a6cb97ffca294a909bc0c7ae9f1e14dd2e499565d&fs=thumb" }, {...}, {...} ] }

Expenses

An expense object allows you to maintain details of an expense.

Example

{ "expense_id": "16367000000083065", "date": "2017-02-21", "category_name": "Office Supplies", "category_id": "16367000000000400", "description": "Necessary Purchase", "created_by": "16367000000074021", "created_by_name": "PATRICIA", "employee_number": "E001", "currency_id": "16367000000000097", "currency_code": "USD", "paid_through_account_id": "16367000000036003", "paid_through_account_name": "Employee Reimbursements", "bcy_total": 13900.79, "bcy_subtotal": 13900.79, "total": 207.65, "total_without_tax": 207.65, "is_billable": true, "is_reimbursable": false, "reference_number": "DD145", "due_days": "Due in 15 days", "merchant_id": "16367000000074027", "merchant_name": "ABS Solutions", "status": "submitted", "created_time": "2017-02-21T18:33:12+0530", "last_modified_time": "2017-02-21T18:42:46+0530", "receipt_name": "receipt1.jpg", "report_id": "16367000000083075", "mileage_type": "non_mileage", "report_name": "Purchase", "is_receipt_only": false, "distance": 0, "per_diem_rate": 0, "per_diem_days": 0, "per_diem_id": "", "per_diem_name": "", "expense_type": "non_mileage", "location": "Washington", "receipt_type": "jpg", "policy_violated": false, "comments_count": 0, "report_status": "submitted", "price_precision": 2, "mileage_rate": 0, "mileage_unit": "km", "receipt_status": "processed", "is_uncategorized": false, "is_expired": false, "gl_code": "LG001", "exchange_rate": 66.943366, "start_reading": "", "end_reading": "", "payment_mode": "Check", "customer_id": "27927000000075081", "customer_name": "ACME Corp.", "custom_fields": [ { "customfield_id": "16367000000277001", "label": "Other Name", "value": "Trip" } ], "project_id": "27927000001243001", "project_name": "Coffee Research", "transaction_description": "", "tax_id": "16367000000086001", "tax_name": "Sales Tax", "tax_percentage": 2, "amount": 207.65, "is_inclusive_tax": false, "vehicle_type": "Bike", "vehicle_id": "17456000000078029", "fuel_type": "lpg", "engine_capacity_range": "between_1401cc_and_1600cc", "is_personal": false, "policy_id": "16367000000092011", "policy_name": "LIC", "documents": [ { "file_name": "receipt1.jpg", "file_size_formatted": "71.8 KB", "attachment_order": 1, "document_id": "16367000000083071" } ], "reimbursement_reference": "", "reimbursement_date": "", "reimbursement_paid_through_account_id": "", "reimbursement_paid_through_account_name": "", "reimbursement_currency_id": "", "reimbursement_currency_code": "", "attendees": [ { "attendee_id": "16367000000104051", "user_id": "27927000001331015", "department_id": "16367000000093001", "department_name": "Finance", "name": "Will Smith", "employee_number": "E001", "customer_id": "27927000000075081", "email": "will.smith@gmail.com" } ], "line_items": [ { "line_item_id": "16367000000354007", "category_id": "16367000000000400", "category_name": "Office Supplies", "description": "Necessary Purchase", "tax_id": "16367000000086001", "tax_name": "Sales Tax", "tax_percentage": 2, "item_total": 207.65, "amount": 207.65, "item_order": 0, "tags": [ { "tag_id": "16367000000000301", "tag_name": "Tag 1", "tag_option_id": "16367000000225001", "tag_option_name": "Option 1" } ] } ] }

Attribute

expense_id
long
Unique ID for expense. This is used as an identifier.
date
string
Date of the expense.
category_name
string
Name of the expense category.
category_id
long
Unique ID for expense category.
description
string
Description about the line item.
created_by
long
Unique ID of the person who created the expense.
created_by_name
string
Name of the person who created the expense.
employee_number
string
Employee Number.
currency_id
long
Unique ID for currency.
currency_code
string
Currency code.
paid_through_account_id
long
Unique ID for the paid through account.
paid_through_account_name
string
Name of the paid through account.
bcy_total
double
Total in base currency.
bcy_subtotal
double
Sub total in base currency.
total
double
Total.
total_without_tax
double
Total excluding tax.
is_billable
boolean
Whether the expense is billable. It can either be true or false.
is_reimbursable
boolean
Whether the expense is reimbursable. It can either be true or false.
reference_number
string
Reference number of the expense.
due_days
string
Number of days till the due date.
merchant_id
long
Unique ID for merchant.
merchant_name
string
Name of the merchant.
status
string
Status of the expense report with which the expense is associated.
created_time
string
Time when the expense was created.
last_modified_time
string
Time when the expense was last modified.
receipt_name
string
Receipt name.
report_id
long
Unique ID for report.
mileage_type
string
Mileage type. Possible values can be non_mileage or manual or odometer or gps or imaps or gmaps or wmaps.
report_name
string
Name of the expense report.
is_receipt_only
string
Whether the expense is a receipt only expense.
distance
double
Distance travelled.
per_diem_rate
double
Allowance per day.
per_diem_days
double
No of days for which per diem is applied.
per_diem_id
long
Unique id for per diem.
per_diem_name
string
Name of the per diem.
expense_type
string
Type of expense.Possible values can be non_mileage or manual or per_diem.
location
string
Location.
receipt_type
string
Receipt type.Possible values can be jpg or png.
policy_violated
boolean
Whether expense policies are violated. It can either be true or false.
comments_count
integer
Number of comments.
report_status
string
Status of the expense report.
price_precision
integer
Precise amount upto n decimal points.
mileage_rate
double
Mileage rate.
mileage_unit
string
Mileage unit.
receipt_status
string
Status of the receipt.
is_uncategorized
boolean
Whether the expense is uncategorized. It can either be true or false.
is_expired
boolean
Whether the expense is expired. It can either be true or false.
gl_code
string
A unique reference code for the category.
exchange_rate
double
Exchange rate.
start_reading
string
Start reading of the odometer.
end_reading
string
End reading of the odometer.
payment_mode
string
Payment mode.
customer_id
long
Unique ID for the customer.
customer_name
string
Name of the customer.
custom_fields
list
Custom Fields.
customfield_id
long
Unique Id for the Custom Field.
label
string
Label of the Custom Field.
value
string
Value of the Custom Field.
project_id
long
Unique ID for the project.
project_name
string
Name of the project.
transaction_description
string
Description about the transaction
tax_id
long
Unique ID for tax.
tax_name
string
Name of the tax.
tax_percentage
double
Tax percentage.
amount
double
Amount.
is_inclusive_tax
boolean
Whether the expense amount is inclusive of tax. It can either be true or false.
vehicle_type
string
Type of vehicle.(UK Edition Only)
vehicle_id
string
Unique id for the Vehicle.
fuel_type
string
Type of Fuel.Possible values can be petrol or lpg or diesel.(UK Edition Only)
engine_capacity_range
string
Range of the Engine Capacity.Possible values can be less_than_1400cc or between_1401cc_and_1600cc or between_1601cc_and_2000cc or more_than_2000cc.(UK Edition Only)
is_personal
boolean
Whether the expense personal. It can either be true or false.
policy_id
long
Unique id for the policy.
policy_name
string
Name of the policy.
list
Documents attached with expense.
file_name
string
Name of the receipt file.
file_size_formatted
string
Formatted file size of receipt.
attachment_order
integer
Order of the attached receipt.
document_id
long
Unique id for the receipt.
reimbursement_reference
long
Reference id for Reimbursement.
reimbursement_date
string
Date for Reimbursement.
reimbursement_paid_through_account_id
long
Account id of the Reimbursement Payment.
reimbursement_paid_through_account_name
string
Account Name of the Reimbursement.
reimbursement_currency_id
long
Unique ID for Reimbursement currency.
reimbursement_currency_code
string
Currency code for Reimbursement.
list
Attendees for the expense.
attendee_id
long
Unique ID for the attendee.
user_id
long
Unique ID for user.
department_id
long
Unique ID of the department.
department_name
string
Name of the department.
name
string
Name of the User.
employee_number
string
Employee Number.
customer_id
long
Unique ID for the customer.
email
string
Email Id of the User.
list
Line Items of the expense.
line_item_id
long
Unique ID for the line item.
category_id
long
Unique ID for expense category.
category_name
string
Name of the expense category.
description
string
Description about the line item.
tax_id
long
Unique ID for tax.
tax_name
string
Name of the tax.
tax_percentage
double
Tax percentage.
item_total
double
Total amount for the line item.
amount
double
Amount.
item_order
integer
Order of the line item.
list
Tags associated with the Line Item.
tag_id
long
Unique ID for Tag generated by the server.
tag_name
string
Name of the Tag.
tag_option_id
long
Unique ID for Tag option generated by the server.
tag_option_name
string
Name of the Tag Option.

Create an expense

Create a new expense.

POST /expenses

Request Example

  
$ curl https://expense.zoho.com/api/v1/expenses -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "currency_id": "16367000000000097", "date": "2017-02-21", "is_reimbursable": false, "paid_through_account_id": "16367000000036003", "distance": 0, "merchant_id": "16367000000074027", "report_id": "16367000000083075", "payment_mode": "Check", "customer_id": "27927000000075081", "project_id": "27927000001243001", "is_billable": true, "is_inclusive_tax": false, "attendees": [ { "user_id": "27927000001331015" } ], "custom_fields": [ { "customfield_id": "16367000000277001", "value": "Trip" } ], "line_items": [ { "category_id": "16367000000000400", "amount": 207.65, "tax_id": "16367000000086001", "description": "Necessary Purchase", "tags": [ { "tag_id": "16367000000000301", "tag_name": "Tag 1", "tag_option_id": "16367000000225001", "tag_option_name": "Option 1" } ] } ] }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The expense has been recorded.", "expenses": [ { "expense_id": "16367000000083065", "total": 207.65, "bcy_total": 13900.79, "is_billable": true, "is_reimbursable": false, "date": "2017-02-21", "currency_id": "16367000000000097", "currency_code": "USD", "exchange_rate": 66.943366, "is_inclusive_tax": false, "customer_id": "27927000000075081", "customer_name": "ACME Corp.", "project_id": "27927000001243001", "project_name": "Coffee Research", "paid_through_account_id": "16367000000036003", "paid_through_account_name": "Employee Reimbursements", "created_time": "2017-02-21T18:33:12+0530", "last_modified_time": "2017-02-21T18:42:46+0530", "status": "submitted", "merchant_id": "16367000000074027", "merchant_name": "ABS Solutions", "report_id": "16367000000083075", "report_name": "Purchase", "mileage_type": "non_mileage", "due_days": "Due in 15 days", "is_expired": false, "gl_code": "LG001", "payment_mode": "Check", "attendees": [ { "attendee_id": "16367000000104051", "user_id": "27927000001331015", "department_id": "16367000000093001", "department_name": "Finance", "name": "Will Smith", "employee_number": "E001", "customer_id": "27927000000075081", "email": "will.smith@gmail.com" } ], "custom_fields": [ { "customfield_id": "16367000000277001", "label": "Other Name", "value": "Trip" } ], "line_items": [ { "line_item_id": "16367000000354007", "category_id": "16367000000000400", "category_name": "Office Supplies", "description": "Necessary Purchase", "tax_id": "16367000000086001", "tax_name": "Sales Tax", "tax_percentage": 2, "item_total": 207.65, "amount": 207.65, "item_order": 0, "tags": [ { "tag_id": "16367000000000301", "tag_name": "Tag 1", "tag_option_id": "16367000000225001", "tag_option_name": "Option 1" } ] } ] } ] }

ARGUMENTS

currency_id
Required
Unique ID for currency.
date
Optional
Date of the expense.
is_reimbursable
Optional
Whether the expense is reimbursable. It can either be true or false.
paid_through_account_id
Optional
Unique ID for the paid through account.
distance
Optional
Distance travelled.
merchant_id
Optional
Unique ID for merchant.
report_id
Optional
Unique ID for report.
payment_mode
Optional
Payment mode.
customer_id
Optional
Unique ID for the customer.
project_id
Optional
Unique ID for the project.
is_billable
Optional
Whether the expense is billable. It can either be true or false.
is_inclusive_tax
Optional
Whether the expense amount is inclusive of tax. It can either be true or false.
Optional
Attendees for the expense.
user_id
Optional
Unique ID for user.
custom_fields
Optional
Custom Fields.
customfield_id
Required
Unique Id for the Custom Field.
value
Required
Value of the Custom Field.
Required
Line Items of the expense.
category_id
Required
Unique ID for expense category.
amount
Required
Amount.
tax_id
Optional
Unique ID for tax.
description
Optional
Description about the line item.
Optional
Tags associated with the Line Item.
tag_id
Required
Unique ID for Tag generated by the server.
tag_name
Optional
Name of the Tag.
tag_option_id
Required
Unique ID for Tag option generated by the server.
tag_option_name
Optional
Name of the Tag Option.

List all expenses

List of all existing expenses.

GET /reports/expensedetails?status={status}&date_start={date_start}&date_end={date_end}&user_id={user_id}&category_id={category_id}&merchant_id={merchant_id}&customer_id={customer_id}&project_id={project_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/reports/expensedetails?status={status}&date_start={date_start}&date_end={date_end}&user_id={user_id}&category_id={category_id}&merchant_id={merchant_id}&customer_id={customer_id}&project_id={project_id} -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "expenses": [ { "expense_id": "16367000000083065", "date": "2017-02-21", "description": "Necessary Purchase", "created_by": "16367000000074021", "created_by_name": "PATRICIA", "employee_number": "E001", "currency_id": "16367000000000097", "currency_code": "USD", "paid_through_account_id": "16367000000036003", "paid_through_account_name": "Employee Reimbursements", "bcy_total": 13900.79, "bcy_subtotal": 13900.79, "total": 207.65, "total_without_tax": 207.65, "is_billable": true, "is_reimbursable": false, "reference_number": "DD145", "due_days": "Due in 15 days", "merchant_id": "16367000000074027", "merchant_name": "ABS Solutions", "status": "submitted", "created_time": "2017-02-21T18:33:12+0530", "last_modified_time": "2017-02-21T18:42:46+0530", "receipt_name": "receipt1.jpg", "report_id": "16367000000083075", "mileage_type": "non_mileage", "report_name": "Purchase", "is_receipt_only": false, "distance": 0, "per_diem_rate": 0, "per_diem_days": 0, "per_diem_id": "", "per_diem_name": "", "expense_type": "non_mileage", "location": "Washington", "receipt_type": "jpg", "policy_violated": false, "comments_count": 0, "report_status": "submitted", "price_precision": 2, "mileage_rate": 0, "mileage_unit": "km", "receipt_status": "processed", "is_uncategorized": false, "is_expired": false, "gl_code": "LG001", "exchange_rate": 66.943366, "start_reading": "", "end_reading": "", "payment_mode": "Check", "customer_id": "27927000000075081", "customer_name": "ACME Corp.", "custom_fields": [ { "customfield_id": "16367000000277001", "label": "Other Name", "value": "Trip" } ], "project_id": "27927000001243001", "project_name": "Coffee Research", "transaction_description": "", "tax_id": "16367000000086001", "tax_name": "Sales Tax", "tax_percentage": 2, "amount": 207.65, "is_inclusive_tax": false, "vehicle_type": "Bike", "vehicle_id": "17456000000078029", "fuel_type": "lpg", "engine_capacity_range": "between_1401cc_and_1600cc", "is_personal": false, "policy_id": "16367000000092011", "policy_name": "LIC", "documents": [ { "file_name": "receipt1.jpg", "file_size_formatted": "71.8 KB", "attachment_order": 1, "document_id": "16367000000083071" } ], "reimbursement_reference": "", "reimbursement_date": "", "reimbursement_paid_through_account_id": "", "reimbursement_paid_through_account_name": "", "reimbursement_currency_id": "", "reimbursement_currency_code": "" }, {...}, {...} ] }

Query Params

status
Optional
Status of the expense report with which the expense is associated.
date_start
Optional
Starting Date
date_end
Optional
Ending Date
user_id
Optional
Unique ID for user.
category_id
Optional
Unique ID for expense category.
merchant_id
Optional
Unique ID for merchant.
customer_id
Optional
Unique ID for the customer.
project_id
Optional
Unique ID for the project.

Update an expense

Update the details of an expense.

PUT /expenses/{expense_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/expenses/{expense_id} -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "paid_through_account_id": "16367000000036003", "date": "2017-02-21", "is_reimbursable": false, "currency_id": "16367000000000097", "merchant_id": "16367000000074027", "report_id": "16367000000083075", "payment_mode": "Check", "customer_id": "27927000000075081", "project_id": "27927000001243001", "is_billable": true, "is_inclusive_tax": false, "attendees": [ { "attendee_id": "16367000000104051", "user_id": "27927000001331015" } ], "custom_fields": [ { "customfield_id": "16367000000277001", "value": "Trip" } ], "line_items": [ { "line_item_id": "16367000000354007", "category_id": "16367000000000400", "description": "Necessary Purchase", "tax_id": "16367000000086001", "amount": 207.65, "item_order": 0, "tags": [ { "tag_id": "16367000000000301", "tag_name": "Tag 1", "tag_option_id": "16367000000225001", "tag_option_name": "Option 1" } ] } ] }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Expense information has been updated.", "expense": { "expense_id": "16367000000083065", "total": 207.65, "bcy_total": 13900.79, "is_billable": true, "is_reimbursable": false, "date": "2017-02-21", "currency_id": "16367000000000097", "currency_code": "USD", "exchange_rate": 66.943366, "is_inclusive_tax": false, "customer_id": "27927000000075081", "customer_name": "ACME Corp.", "project_id": "27927000001243001", "project_name": "Coffee Research", "paid_through_account_id": "16367000000036003", "paid_through_account_name": "Employee Reimbursements", "created_time": "2017-02-21T18:33:12+0530", "last_modified_time": "2017-02-21T18:42:46+0530", "status": "submitted", "merchant_id": "16367000000074027", "merchant_name": "ABS Solutions", "report_id": "16367000000083075", "report_name": "Purchase", "mileage_type": "non_mileage", "due_days": "Due in 15 days", "is_expired": false, "gl_code": "LG001", "payment_mode": "Check", "attendees": [ { "attendee_id": "16367000000104051", "user_id": "27927000001331015", "department_id": "16367000000093001", "department_name": "Finance", "name": "Will Smith", "employee_number": "E001", "customer_id": "27927000000075081", "email": "will.smith@gmail.com" } ], "policy_name": "LIC", "custom_fields": [ { "customfield_id": "16367000000277001", "label": "Other Name", "value": "Trip" } ], "line_items": [ { "line_item_id": "16367000000354007", "category_id": "16367000000000400", "category_name": "Office Supplies", "description": "Necessary Purchase", "tax_id": "16367000000086001", "tax_name": "Sales Tax", "tax_percentage": 2, "item_total": 207.65, "amount": 207.65, "item_order": 0, "tags": [ { "tag_id": "16367000000000301", "tag_name": "Tag 1", "tag_option_id": "16367000000225001", "tag_option_name": "Option 1" } ] } ] } }

ARGUMENTS

paid_through_account_id
Optional
Unique ID for the paid through account.
date
Optional
Date of the expense.
is_reimbursable
Optional
Whether the expense is reimbursable. It can either be true or false.
currency_id
Optional
Unique ID for currency.
merchant_id
Optional
Unique ID for merchant.
report_id
Optional
Unique ID for report.
payment_mode
Optional
Payment mode.
customer_id
Optional
Unique ID for the customer.
project_id
Optional
Unique ID for the project.
is_billable
Optional
Whether the expense is billable. It can either be true or false.
is_inclusive_tax
Optional
Whether the expense amount is inclusive of tax. It can either be true or false.
Optional
Attendees for the expense.
attendee_id
Optional
Unique ID for the attendee.
user_id
Optional
Unique ID for user.
custom_fields
Optional
Custom Fields.
customfield_id
Required
Unique Id for the Custom Field.
value
Required
Value of the Custom Field.
Required
Line Items of the expense.
line_item_id
Optional
Unique ID for the line item.
category_id
Optional
Unique ID for expense category.
description
Optional
Description about the line item.
tax_id
Optional
Unique ID for tax.
amount
Optional
Amount.
item_order
Optional
Order of the line item.
Optional
Tags associated with the Line Item.
tag_id
Required
Unique ID for Tag generated by the server.
tag_name
Optional
Name of the Tag.
tag_option_id
Required
Unique ID for Tag option generated by the server.
tag_option_name
Optional
Name of the Tag Option.

Merge expenses

Merge multiple expenses.

POST /expenses/{expense_id}/merge?duplicate_expense_id={expense_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/expenses/{expense_id}/merge?duplicate_expense_id={expense_id} -X POST -H "Content-Type: multipart/form-data" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -f 'duplicate_expense_id=16367000000083070'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Expenses merged successfully." }

ARGUMENTS

duplicate_expense_id
Required
Unique ID of the expense to be merged.

Upload Receipts

Upload receipts for autoscanning.

POST /expenses

Request Example

  
$ curl https://expense.zoho.com/api/v1/expenses -X POST -H "Content-Type: multipart/form-data" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -f 'receipt=@/receipt.jpg'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The receipt has been uploaded successfully." }

ARGUMENTS

receipt
Required
File Path of the Receipt to be uploaded.

Trips

A trip entity allows you to maintain information about the trips of your employees.

Example

{ "trip_id": "34017000000000103", "currency_id": "16367000000000097", "budget_amount": 5000, "bcy_budget_amount": 5000, "start_date": "2017-02-21", "end_date": "2017-02-27", "is_round_trip": true, "is_international": true, "is_visa_required": true, "trip_number": "TRIP-00001", "business_purpose": "Meeting with client", "description": "Regarding business proposal", "departure": "ABC International Airport", "destination_country": "Australia", "destination_city": "melbourne", "meal_preference": "avml", "seat_preference": "middle", "is_billable": false, "customer_id": "16367000000096001", "project_id": "16367000000096055", "customer_name": "Kenny Digital", "project_name": "Brochure Design - Spa", "status": "draft", "custom_fields": [ { "customfield_id": "16367000000093005", "data_type": "string", "is_active": true, "is_mandatory": false, "label": "Nick Name", "value": "Tric" } ], "submitted_date": "2017-02-28", "last_submitted_date": "2017-02-28", "approver_id": "16367000000073001", "approver_name": "PATRICIA BOYLE", "approver_email": "patriciab@zillum.com", "submitted_to_id": "16367000000073001", "submitted_to_email": "patriciab@zillum.com", "submitted_to_name": "PATRICIA BOYLE", "submitted_by": "34017000000091001", "submitter_name": "Will Smith", "submitter_email": "will.smith@gmail.com", "submitter_employee_no": "E002", "submitter_department_name": "Maintenance", "employee_number": "E003", "department_id": "16367000000093001", "next_approver_id": "16367000000073001", "next_approver_email": "patriciab@zillum.com", "next_approver_name": "PATRICIA BOYLE", "approver_employee_no": "E001", "approver_department_name": "Finance", "previous_approver_id": "16367000000073001", "previous_approver_name": "Will Smith", "previous_approver_email": "will.smith@gmail.com", "previous_approver_employee_no": "E008", "previous_approver_department_name": "Marketing", "air_travel_itinerary": [ { "is_accomodation": false, "is_personal_travel": true, "line_item_id": "34017000000091584", "departure_state": "tamil nadu", "departure_date": "2017-09-08", "description": "Regarding business proposal", "departure_city": "chennai", "departure_country": "india", "arrival_country": "australia", "travel_mode": "flight", "arrival_state": "victoria", "arrival_city": "melbourne", "arrival_date": "2017-09-08", "order": 1 } ], "hotel_reservation_itinerary": [ { "is_accomodation": false, "is_personal_travel": true, "line_item_id": "34017000000091584", "departure_state": "tamil nadu", "departure_date": "2017-09-08", "description": "Regarding business proposal", "departure_city": "chennai", "departure_country": "india", "arrival_country": "australia", "travel_mode": "flight", "arrival_state": "victoria", "arrival_city": "melbourne", "arrival_date": "2017-09-08", "order": 1 } ], "car_rental_itinerary": [ { "is_accomodation": false, "is_personal_travel": true, "line_item_id": "34017000000091584", "departure_state": "tamil nadu", "departure_date": "2017-09-08", "description": "Regarding business proposal", "departure_city": "chennai", "departure_country": "india", "arrival_country": "australia", "travel_mode": "flight", "arrival_state": "victoria", "arrival_city": "melbourne", "arrival_date": "2017-09-08", "order": 1 } ], "other_itinerary": [ { "is_accomodation": false, "is_personal_travel": true, "line_item_id": "34017000000091584", "departure_state": "tamil nadu", "departure_date": "2017-09-08", "description": "Regarding business proposal", "departure_city": "chennai", "departure_country": "india", "arrival_country": "australia", "travel_mode": "flight", "arrival_state": "victoria", "arrival_city": "melbourne", "arrival_date": "2017-09-08", "order": 1 } ], "attendees": [ { "department_id": "16367000000093001", "user_id": "16367000000073001", "attendee_id": "31672000000003102", "name": "Jayson", "employee_number": "E003", "email": "jayson@gmail.com" } ], "line_items": [ { "line_item_id": "34017000000091584", "order": 1, "departure_date": "2017-09-08", "departure_country": "india", "departure_state": "tamil nadu", "departure_city": "chennai", "arrival_date": "2017-09-08", "arrival_country": "australia", "arrival_state": "victoria", "arrival_city": "melbourne", "travel_mode": "flight", "is_personal_travel": true, "is_accomodation": false } ], "comments": [ { "description": "Regarding business proposal", "commented_by_id": "34017000000091216", "commented_by": "Will Smith" } ], "currency_code": "INR", "price_precision": 2, "created_time": "2017-02-28T18:18:03+0530", "created_date": "2017-02-28", "last_modified_time": "2017-02-28T18:31:09+0530", "created_by_id": "16367000000073071", "created_by_name": "Will Smith", "created_by_email": "will.smith@gmail.com", "user_id": "16367000000073001", "policy_id": "30082000000003588", "policy_name": "Official Trips", "user_name": "Will Smith", "user_email": "will.smith@gmail.com", "user_employee_no": "E002", "user_department_name": "Maintenance", "documents": [ { "file_name": "receipt1.jpg", "file_size_formatted": "35.6 KB", "attachment_order": 1, "document_id": "16367000000078085" } ] }

Attribute

trip_id
long
Unique ID generated by the server. This is used as a identifier.
currency_id
long
Unique ID for currency.
budget_amount
double
Budget amount for the trip.
bcy_budget_amount
double
Budget amount for the trip in base currency.
start_date
string
Start date of the trip.
end_date
string
End date of the trip.
is_round_trip
boolean
Whether the trip is a round trip.
is_international
boolean
Whether the trip is an international trip.
is_visa_required
boolean
Whether visa is required for the trip.
trip_number
string
Trip's unique number
business_purpose
string
Purpose of the trip.
description
string
Any comments about the trip.
departure
string
Place of departure.
destination_country
string
Destination Country of the trip.
destination_city
string
Destination City of the trip.
meal_preference
string
Meal preference for the traveller in flight.
seat_preference
string
Seat preference for the traveller in flight.
is_billable
boolean
Whether the customer needs to be billed for the trip.
customer_id
long
Unique ID of the customer associated with the trip.
project_id
long
Unique ID of the project associated with the trip.
customer_name
string
Name of the customer associated with the trip.
project_name
string
Name of the project associated with the trip.
status
string
Status of the trip.
custom_fields
list
Custom field added.
customfield_id
long
Unique ID for the Custom Field.
data_type
string
Data Type of the Custom Field.
is_active
boolean
Whether the Custom Field is Active. It can either be true or false.
is_mandatory
boolean
Whether the Custom Field is Mandatory. It can either be true or false.
label
string
Label for the Custom Field.
value
string
Value entered in the Custom Field.
submitted_date
string
Date of trip submission.
last_submitted_date
string
Date of previous submission.
approver_id
long
Unique ID for the current approver.
approver_name
string
Current approver name.
approver_email
string
Email ID of the current approver.
submitted_to_id
long
Unique ID of the person to whom the trip was submitted first.
submitted_to_email
string
Email ID of the person to whom the trip was submitted first.
submitted_to_name
string
Name of the person to whom the trip was submitted first.
submitted_by
long
Unique ID of the submitter.
submitter_name
string
Name of the submitter.
submitter_email
string
Email ID of the submitter.
submitter_employee_no
string
Employee Number of the submitter.
submitter_department_name
string
Department Name of the submitter.
employee_number
string
Employee Number of the owner of the trip.
department_id
long
Unique ID of the department.
next_approver_id
long
Unique ID of the Next Approver.
next_approver_email
string
Email Id of Next Approver.
next_approver_name
string
Name of the Next Approver.
approver_employee_no
string
Employee Number of the Approver.
approver_department_name
string
Department Name of the Approver.
previous_approver_id
long
Unique ID of Previous Approver.
previous_approver_name
string
Name of the Previous Approver.
previous_approver_email
string
Email ID of the Previous Approver.
previous_approver_employee_no
string
Employee Number of the Previous Approver.
previous_approver_department_name
string
Department Name of the Previous Approver.
air_travel_itinerary
list
Air Travel Itinerary
is_accomodation
boolean
Whether accomodation is provided.
is_personal_travel
boolean
Whether it is a personal trip.
line_item_id
long
Unique ID for identifying the line item. This is server generated.
departure_state
string
Departure State.
departure_date
string
Date of departure.
description
string
Any comments about the trip.
departure_city
string
Departure City.
departure_country
string
Departure Country.
arrival_country
string
Arrival Country
travel_mode
string
Mode of transportation. Possible values are flight ,by_road, train, bus
arrival_state
string
Arrival State
arrival_city
string
Arrival City
arrival_date
string
Date of arrival.
order
int
Order of the line item.
hotel_reservation_itinerary
list
Hotel Accommodation Itinerary
is_accomodation
boolean
Whether accomodation is provided.
is_personal_travel
boolean
Whether it is a personal trip.
line_item_id
long
Unique ID for identifying the line item. This is server generated.
departure_state
string
Departure State.
departure_date
string
Date of departure.
description
string
Any comments about the trip.
departure_city
string
Departure City.
departure_country
string
Departure Country.
arrival_country
string
Arrival Country
travel_mode
string
Mode of transportation. Possible values are flight ,by_road, train, bus
arrival_state
string
Arrival State
arrival_city
string
Arrival City
arrival_date
string
Date of arrival.
order
int
Order of the line item.
car_rental_itinerary
list
Car Rental Itinerary
is_accomodation
boolean
Whether accomodation is provided.
is_personal_travel
boolean
Whether it is a personal trip.
line_item_id
long
Unique ID for identifying the line item. This is server generated.
departure_state
string
Departure State.
departure_date
string
Date of departure.
description
string
Any comments about the trip.
departure_city
string
Departure City.
departure_country
string
Departure Country.
arrival_country
string
Arrival Country
travel_mode
string
Mode of transportation. Possible values are flight ,by_road, train, bus
arrival_state
string
Arrival State
arrival_city
string
Arrival City
arrival_date
string
Date of arrival.
order
int
Order of the line item.
other_itinerary
list
Other Itinerary
is_accomodation
boolean
Whether accomodation is provided.
is_personal_travel
boolean
Whether it is a personal trip.
line_item_id
long
Unique ID for identifying the line item. This is server generated.
departure_state
string
Departure State.
departure_date
string
Date of departure.
description
string
Any comments about the trip.
departure_city
string
Departure City.
departure_country
string
Departure Country.
arrival_country
string
Arrival Country
travel_mode
string
Mode of transportation. Possible values are flight ,by_road, train, bus
arrival_state
string
Arrival State
arrival_city
string
Arrival City
arrival_date
string
Date of arrival.
order
int
Order of the line item.
list
Other travellers of the trip.
department_id
long
Unique ID of the department.
user_id
long
Unique ID of the owner of the trip.
attendee_id
long
Unique ID of the attendee as a identifier.
name
string
Name of the User.
employee_number
string
Employee Number of the owner of the trip.
email
string
Email ID of the User.
list
line_item_id
long
Unique ID for identifying the line item. This is server generated.
order
int
Order of the line item.
departure_date
string
Date of departure.
departure_country
string
Departure Country.
departure_state
string
Departure State.
departure_city
string
Departure City.
arrival_date
string
Date of arrival.
arrival_country
string
Arrival Country
arrival_state
string
Arrival State
arrival_city
string
Arrival City
travel_mode
string
Mode of transportation. Possible values are flight ,by_road, train, bus
is_personal_travel
boolean
Whether it is a personal trip.
is_accomodation
boolean
Whether accomodation is provided.
list
description
string
Any comments about the trip.
commented_by_id
long
Unique ID of the person who commented.
commented_by
string
Name of the User Commented.
currency_id
long
Unique ID for currency.
currency_code
string
Currency code.
price_precision
integer
Amount precision upto n decimal points.
created_time
string
Time when the trip was created.
created_date
string
Date when the trip was created.
last_modified_time
string
Time when the trip was last modified.
created_by_id
long
Unique ID of the person who created the trip.
created_by_name
string
Name of the person who created the trip.
created_by_email
string
Email ID of the person who created the trip.
user_id
long
Unique ID of the owner of the trip.
policy_id
long
Unique ID of the policy applied to the trip request.
policy_name
string
Name of the Policy.
user_name
string
Name of the User.
user_email
string
Email Id of the User.
user_employee_no
string
Employee number of the user
user_department_name
string
Department of the user
list
Details of Documents attached.
file_name
string
Name of the Document.
file_size_formatted
string
Formatted value of File Size.
attachment_order
integer
Order of the Attached Document.
document_id
long
Unique Id for the Document.

Create a trip

Create a new trip.

POST /trips

Request Example

  
$ curl https://expense.zoho.com/api/v1/trips -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "currency_id": "16367000000000097", "exchange_rate": 1, "budget_amount": 5000, "is_international": true, "is_visa_required": true, "business_purpose": "Meeting with client", "is_billable": false, "customer_id": "16367000000096001", "project_id": "16367000000096055", "destination_country": "Australia", "meal_preference": "avml", "seat_preference": "middle", "line_items": [ { "line_item_id": "34017000000091584", "order": 1, "departure_date": "2017-09-08", "departure_country": "india", "departure_state": "tamil nadu", "departure_city": "chennai", "arrival_date": "2017-09-08", "arrival_country": "australia", "arrival_state": "victoria", "arrival_city": "melbourne", "travel_mode": "flight", "is_personal_travel": true, "is_accomodation": false } ], "description": "Regarding business proposal", "custom_fields": [ { "customfield_id": "16367000000093005", "value": "Tric" } ], "attendees": [ { "user_id": "16367000000073001" } ] }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "trip created successfully", "trip": { "trip_id": "34017000000000103", "is_international": true, "is_round_trip": true, "is_visa_required": true, "start_date": "2017-02-21", "end_date": "2017-02-27", "trip_number": "TRIP-00001", "business_purpose": "Meeting with client", "description": "Regarding business proposal", "departure": "ABC International Airport", "destination_country": "Australia", "destination_city": "melbourne", "meal_preference": "avml", "seat_preference": "middle", "is_billable": false, "customer_id": "16367000000096001", "project_id": "16367000000096055", "project_name": "Brochure Design - Spa", "customer_name": "Kenny Digital", "currency_id": "16367000000000097", "currency_code": "INR", "exchange_rate": 1, "price_precision": 2, "budget_amount": 5000, "bcy_budget_amount": 5000, "status": "draft", "custom_fields": [ { "customfield_id": "16367000000093005", "data_type": "string", "is_active": true, "is_mandatory": false, "label": "Nick Name", "value": "Tric" } ], "submitted_date": "2017-02-28", "last_submitted_date": "2017-02-28", "approved_date": "2017-03-01", "approver_id": "16367000000073001", "approver_name": "PATRICIA BOYLE", "approver_email": "patriciab@zillum.com", "submitted_to_id": "16367000000073001", "submitted_to_name": "PATRICIA BOYLE", "submitted_to_email": "patriciab@zillum.com", "submitted_to_employee_no": "E001", "submitted_to_department_name": "Finance", "submitted_by": "34017000000091001", "submitter_name": "Will Smith", "submitter_email": "will.smith@gmail.com", "submitter_employee_no": "E002", "submitter_department_name": "Maintenance", "employee_number": "E003", "department_id": "16367000000093001", "department_name": "Finance", "air_travel_itinerary": [ { "is_accomodation": false, "is_personal_travel": true, "line_item_id": "34017000000091584", "departure_state": "tamil nadu", "departure_date": "2017-09-08", "description": "Regarding business proposal", "departure_city": "chennai", "departure_country": "india", "arrival_country": "australia", "travel_mode": "flight", "arrival_state": "victoria", "arrival_city": "melbourne", "arrival_date": "2017-09-08", "order": 1 } ], "created_time": "2017-02-28T18:18:03+0530", "created_date": "2017-02-28", "last_modified_time": "2017-02-28T18:31:09+0530", "documents": [ { "file_name": "receipt1.jpg", "file_size_formatted": "35.6 KB", "attachment_order": 1, "document_id": "16367000000078085" } ], "created_by_id": "16367000000073071", "created_by_name": "Will Smith", "user_id": "16367000000073001", "user_name": "Will Smith", "user_email": "will.smith@gmail.com", "created_by_email": "will.smith@gmail.com" } }

ARGUMENTS

currency_id
Optional
Unique ID for currency.
exchange_rate
Optional
Exchange rate of the currency with respect to base currency.
budget_amount
Optional
Budget amount for the trip.
is_international
Required
Whether the trip is an international trip.
is_visa_required
Optional
Whether visa is required for the trip.
business_purpose
Optional
Purpose of the trip.
is_billable
Optional
Whether the customer needs to be billed for the trip.
customer_id
Optional
Unique ID of the customer associated with the trip.
project_id
Optional
Unique ID of the project associated with the trip.
destination_country
Required
Destination Country of the trip.
meal_preference
Optional
Meal preference for the traveller in flight.
seat_preference
Optional
Seat preference for the traveller in flight.
Optional
line_item_id
Optional
Unique ID for identifying the line item. This is server generated.
order
Optional
Order of the line item.
departure_date
Optional
Date of departure.
departure_country
Optional
Departure Country.
departure_state
Optional
Departure State.
departure_city
Optional
Departure City.
arrival_date
Optional
Date of arrival.
arrival_country
Optional
Arrival Country
arrival_state
Optional
Arrival State
arrival_city
Optional
Arrival City
travel_mode
Optional
Mode of transportation. Possible values are flight ,by_road, train, bus
is_personal_travel
Optional
Whether it is a personal trip.
is_accomodation
Optional
Whether accomodation is provided.
description
Optional
Any comments about the trip.
custom_fields
Optional
Custom field added.
customfield_id
Optional
Unique ID for the Custom Field.
value
Optional
Value entered in the Custom Field.
Optional
Other travellers of the trip.
user_id
Optional
Unique ID of the owner of the trip.

Retrive details of a trip

Retrive details of an existing trip.

GET /trips/{trip_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/trips/{trip_id} -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "trip": { "trip_id": "34017000000000103", "is_international": true, "is_round_trip": true, "is_visa_required": true, "start_date": "2017-02-21", "end_date": "2017-02-27", "trip_number": "TRIP-00001", "business_purpose": "Meeting with client", "description": "Regarding business proposal", "departure": "ABC International Airport", "destination_country": "Australia", "destination_city": "melbourne", "meal_preference": "avml", "seat_preference": "middle", "is_billable": false, "customer_id": "16367000000096001", "project_id": "16367000000096055", "project_name": "Brochure Design - Spa", "customer_name": "Kenny Digital", "currency_id": "16367000000000097", "currency_code": "INR", "exchange_rate": 1, "price_precision": 2, "budget_amount": 5000, "bcy_budget_amount": 5000, "status": "draft", "custom_fields": [ { "customfield_id": "16367000000093005", "data_type": "string", "is_active": true, "is_mandatory": false, "label": "Nick Name", "value": "Tric" } ], "submitted_date": "2017-02-28", "last_submitted_date": "2017-02-28", "approved_date": "2017-03-01", "approver_id": "16367000000073001", "approver_name": "PATRICIA BOYLE", "approver_email": "patriciab@zillum.com", "submitted_to_id": "16367000000073001", "submitted_to_name": "PATRICIA BOYLE", "submitted_to_email": "patriciab@zillum.com", "submitted_to_employee_no": "E001", "submitted_to_department_name": "Finance", "submitted_by": "34017000000091001", "submitter_name": "Will Smith", "submitter_email": "will.smith@gmail.com", "submitter_employee_no": "E002", "submitter_department_name": "Maintenance", "employee_number": "E003", "department_id": "16367000000093001", "department_name": "Finance", "air_travel_itinerary": [ { "is_accomodation": false, "is_personal_travel": true, "line_item_id": "34017000000091584", "departure_state": "tamil nadu", "departure_date": "2017-09-08", "description": "Regarding business proposal", "departure_city": "chennai", "departure_country": "india", "arrival_country": "australia", "travel_mode": "flight", "arrival_state": "victoria", "arrival_city": "melbourne", "arrival_date": "2017-09-08", "order": 1 } ], "created_time": "2017-02-28T18:18:03+0530", "created_date": "2017-02-28", "last_modified_time": "2017-02-28T18:31:09+0530", "documents": [ { "file_name": "receipt1.jpg", "file_size_formatted": "35.6 KB", "attachment_order": 1, "document_id": "16367000000078085" } ], "created_by_id": "16367000000073071", "created_by_name": "Will Smith", "user_id": "16367000000073001", "user_name": "Will Smith", "user_email": "will.smith@gmail.com", "created_by_email": "will.smith@gmail.com" } }

Retrive list of all trips

List all existing trips.

GET /trips

Request Example

  
$ curl https://expense.zoho.com/api/v1/trips -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "trips": [ { "currency_id": "16367000000000097", "budget_amount": 5000, "bcy_budget_amount": 5000, "start_date": "2017-02-21", "end_date": "2017-02-27", "trip_id": "34017000000000103", "is_round_trip": true, "is_international": true, "is_visa_required": true, "trip_number": "TRIP-00001", "business_purpose": "Meeting with client", "description": "Regarding business proposal", "departure": "ABC International Airport", "destination_country": "Australia", "destination_city": "melbourne", "meal_preference": "avml", "seat_preference": "middle", "is_billable": false, "customer_id": "16367000000096001", "project_id": "16367000000096055", "customer_name": "Kenny Digital", "project_name": "Brochure Design - Spa", "status": "draft", "custom_fields": [ { "customfield_id": "16367000000093005", "data_type": "string", "is_active": true, "is_mandatory": false, "label": "Nick Name", "value": "Tric" } ], "submitted_date": "2017-02-28", "last_submitted_date": "2017-02-28", "approver_id": "16367000000073001", "approver_name": "PATRICIA BOYLE", "approver_email": "patriciab@zillum.com", "submitted_to_id": "16367000000073001", "submitted_to_email": "patriciab@zillum.com", "submitted_to_name": "PATRICIA BOYLE", "submitted_by": "34017000000091001", "submitter_name": "Will Smith", "submitter_email": "will.smith@gmail.com", "submitter_employee_no": "E002", "submitter_department_name": "Maintenance", "employee_number": "E003", "department_id": "16367000000093001", "next_approver_id": "16367000000073001", "next_approver_email": "patriciab@zillum.com", "next_approver_name": "PATRICIA BOYLE", "approver_employee_no": "E001", "approver_department_name": "Finance", "previous_approver_id": "16367000000073001", "previous_approver_name": "Will Smith", "previous_approver_email": "will.smith@gmail.com", "previous_approver_employee_no": "E008", "previous_approver_department_name": "Marketing", "air_travel_itinerary": [ { "is_accomodation": false, "is_personal_travel": true, "line_item_id": "34017000000091584", "departure_state": "tamil nadu", "departure_date": "2017-09-08", "description": "Regarding business proposal", "departure_city": "chennai", "departure_country": "india", "arrival_country": "australia", "travel_mode": "flight", "arrival_state": "victoria", "arrival_city": "melbourne", "arrival_date": "2017-09-08", "order": 1 } ], "hotel_reservation_itinerary": [ { "is_accomodation": false, "is_personal_travel": true, "line_item_id": "34017000000091584", "departure_state": "tamil nadu", "departure_date": "2017-09-08", "description": "Regarding business proposal", "departure_city": "chennai", "departure_country": "india", "arrival_country": "australia", "travel_mode": "flight", "arrival_state": "victoria", "arrival_city": "melbourne", "arrival_date": "2017-09-08", "order": 1 } ], "car_rental_itinerary": [ { "is_accomodation": false, "is_personal_travel": true, "line_item_id": "34017000000091584", "departure_state": "tamil nadu", "departure_date": "2017-09-08", "description": "Regarding business proposal", "departure_city": "chennai", "departure_country": "india", "arrival_country": "australia", "travel_mode": "flight", "arrival_state": "victoria", "arrival_city": "melbourne", "arrival_date": "2017-09-08", "order": 1 } ], "other_itinerary": [ { "is_accomodation": false, "is_personal_travel": true, "line_item_id": "34017000000091584", "departure_state": "tamil nadu", "departure_date": "2017-09-08", "description": "Regarding business proposal", "departure_city": "chennai", "departure_country": "india", "arrival_country": "australia", "travel_mode": "flight", "arrival_state": "victoria", "arrival_city": "melbourne", "arrival_date": "2017-09-08", "order": 1 } ], "attendees": [ { "department_id": "16367000000093001", "user_id": "16367000000073001", "attendee_id": "31672000000003102", "name": "Jayson", "employee_number": "E003", "email": "jayson@gmail.com" } ], "line_items": [ { "line_item_id": "34017000000091584", "order": 1, "departure_date": "2017-09-08", "departure_country": "india", "departure_state": "tamil nadu", "departure_city": "chennai", "arrival_date": "2017-09-08", "arrival_country": "australia", "arrival_state": "victoria", "arrival_city": "melbourne", "travel_mode": "flight", "is_personal_travel": true, "is_accomodation": false } ], "comments": [ { "description": "Regarding business proposal", "commented_by_id": "34017000000091216", "commented_by": "Will Smith" } ], "currency_code": "INR", "price_precision": 2, "created_time": "2017-02-28T18:18:03+0530", "created_date": "2017-02-28", "last_modified_time": "2017-02-28T18:31:09+0530", "created_by_id": "16367000000073071", "created_by_name": "Will Smith", "created_by_email": "will.smith@gmail.com", "user_id": "16367000000073001", "policy_id": "30082000000003588", "policy_name": "Official Trips", "user_name": "Will Smith", "user_email": "will.smith@gmail.com", "user_employee_no": "E002", "user_department_name": "Maintenance", "documents": [ { "file_name": "receipt1.jpg", "file_size_formatted": "35.6 KB", "attachment_order": 1, "document_id": "16367000000078085" } ] }, {...}, {...} ] }

Query Params

Optional
For filtering trips based on status.
Type.Trip%2CStatus.Submitted
Optional
List all submitted trip requests
Type.Trip%2CStatus.Approved
Optional
List all approved trip requests
Type.Trip%2CStatus.Rejected
Optional
List all rejected trip requests
Type.Trip%2CStatus.Closed
Optional
List all closed trips
Type.Trip%2CStatus.Cancelled
Optional
List all the cancelled trips.

Update a trip

Update an existing Trip.

PUT /trips/{trip_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/trips/{trip_id} -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "currency_id": "16367000000000097", "budget_amount": 5000, "is_international": true, "is_visa_required": true, "business_purpose": "Meeting with client", "is_billable": false, "customer_id": "16367000000096001", "project_id": "16367000000096055", "destination_country": "Australia", "meal_preference": "avml", "seat_preference": "middle", "line_items": [ { "line_item_id": "34017000000091584", "order": 1, "departure_date": "2017-09-08", "departure_country": "india", "departure_state": "tamil nadu", "departure_city": "chennai", "arrival_date": "2017-09-08", "arrival_country": "australia", "arrival_state": "victoria", "arrival_city": "melbourne", "travel_mode": "flight", "is_personal_travel": true, "is_accomodation": false } ], "description": "Regarding business proposal", "custom_fields": [ { "customfield_id": "16367000000093005", "value": "Tric" } ], "attendees": [ { "user_id": "16367000000073001" } ] }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Trip details updated successfully", "trips": { "currency_id": "16367000000000097", "budget_amount": 5000, "bcy_budget_amount": 5000, "start_date": "2017-02-21", "end_date": "2017-02-27", "trip_id": "34017000000000103", "is_round_trip": true, "is_international": true, "is_visa_required": true, "trip_number": "TRIP-00001", "business_purpose": "Meeting with client", "description": "Regarding business proposal", "departure": "ABC International Airport", "destination_country": "Australia", "destination_city": "melbourne", "meal_preference": "avml", "seat_preference": "middle", "is_billable": false, "customer_id": "16367000000096001", "project_id": "16367000000096055", "customer_name": "Kenny Digital", "project_name": "Brochure Design - Spa", "status": "draft", "custom_fields": [ { "customfield_id": "16367000000093005", "data_type": "string", "is_active": true, "is_mandatory": false, "label": "Nick Name", "value": "Tric" } ], "submitted_date": "2017-02-28", "last_submitted_date": "2017-02-28", "approver_id": "16367000000073001", "approver_name": "PATRICIA BOYLE", "approver_email": "patriciab@zillum.com", "submitted_to_id": "16367000000073001", "submitted_to_email": "patriciab@zillum.com", "submitted_to_name": "PATRICIA BOYLE", "submitted_by": "34017000000091001", "submitter_name": "Will Smith", "submitter_email": "will.smith@gmail.com", "submitter_employee_no": "E002", "submitter_department_name": "Maintenance", "employee_number": "E003", "department_id": "16367000000093001", "next_approver_id": "16367000000073001", "next_approver_email": "patriciab@zillum.com", "next_approver_name": "PATRICIA BOYLE", "approver_employee_no": "E001", "approver_department_name": "Finance", "previous_approver_id": "16367000000073001", "previous_approver_name": "Will Smith", "previous_approver_email": "will.smith@gmail.com", "previous_approver_employee_no": "E008", "previous_approver_department_name": "Marketing", "air_travel_itinerary": [ { "is_accomodation": false, "is_personal_travel": true, "line_item_id": "34017000000091584", "departure_state": "tamil nadu", "departure_date": "2017-09-08", "description": "Regarding business proposal", "departure_city": "chennai", "departure_country": "india", "arrival_country": "australia", "travel_mode": "flight", "arrival_state": "victoria", "arrival_city": "melbourne", "arrival_date": "2017-09-08", "order": 1 } ], "hotel_reservation_itinerary": [ { "is_accomodation": false, "is_personal_travel": true, "line_item_id": "34017000000091584", "departure_state": "tamil nadu", "departure_date": "2017-09-08", "description": "Regarding business proposal", "departure_city": "chennai", "departure_country": "india", "arrival_country": "australia", "travel_mode": "flight", "arrival_state": "victoria", "arrival_city": "melbourne", "arrival_date": "2017-09-08", "order": 1 } ], "car_rental_itinerary": [ { "is_accomodation": false, "is_personal_travel": true, "line_item_id": "34017000000091584", "departure_state": "tamil nadu", "departure_date": "2017-09-08", "description": "Regarding business proposal", "departure_city": "chennai", "departure_country": "india", "arrival_country": "australia", "travel_mode": "flight", "arrival_state": "victoria", "arrival_city": "melbourne", "arrival_date": "2017-09-08", "order": 1 } ], "other_itinerary": [ { "is_accomodation": false, "is_personal_travel": true, "line_item_id": "34017000000091584", "departure_state": "tamil nadu", "departure_date": "2017-09-08", "description": "Regarding business proposal", "departure_city": "chennai", "departure_country": "india", "arrival_country": "australia", "travel_mode": "flight", "arrival_state": "victoria", "arrival_city": "melbourne", "arrival_date": "2017-09-08", "order": 1 } ], "attendees": [ { "department_id": "16367000000093001", "user_id": "16367000000073001", "attendee_id": "31672000000003102", "name": "Jayson", "employee_number": "E003", "email": "jayson@gmail.com" } ], "line_items": [ { "line_item_id": "34017000000091584", "order": 1, "departure_date": "2017-09-08", "departure_country": "india", "departure_state": "tamil nadu", "departure_city": "chennai", "arrival_date": "2017-09-08", "arrival_country": "australia", "arrival_state": "victoria", "arrival_city": "melbourne", "travel_mode": "flight", "is_personal_travel": true, "is_accomodation": false } ], "comments": [ { "description": "Regarding business proposal", "commented_by_id": "34017000000091216", "commented_by": "Will Smith" } ], "currency_code": "INR", "price_precision": 2, "created_time": "2017-02-28T18:18:03+0530", "created_date": "2017-02-28", "last_modified_time": "2017-02-28T18:31:09+0530", "created_by_id": "16367000000073071", "created_by_name": "Will Smith", "created_by_email": "will.smith@gmail.com", "user_id": "16367000000073001", "policy_id": "30082000000003588", "policy_name": "Official Trips", "user_name": "Will Smith", "user_email": "will.smith@gmail.com", "user_employee_no": "E002", "user_department_name": "Maintenance", "documents": [ { "file_name": "receipt1.jpg", "file_size_formatted": "35.6 KB", "attachment_order": 1, "document_id": "16367000000078085" } ] } }

ARGUMENTS

currency_id
Optional
Unique ID for currency.
budget_amount
Optional
Budget amount for the trip.
is_international
Required
Whether the trip is an international trip.
is_visa_required
Optional
Whether visa is required for the trip.
business_purpose
Optional
Purpose of the trip.
is_billable
Optional
Whether the customer needs to be billed for the trip.
customer_id
Optional
Unique ID of the customer associated with the trip.
project_id
Optional
Unique ID of the project associated with the trip.
destination_country
Required
Destination Country of the trip.
meal_preference
Optional
Meal preference for the traveller in flight.
seat_preference
Optional
Seat preference for the traveller in flight.
Optional
line_item_id
Optional
Unique ID for identifying the line item. This is server generated.
order
Optional
Order of the line item.
departure_date
Optional
Date of departure.
departure_country
Optional
Departure Country.
departure_state
Optional
Departure State.
departure_city
Optional
Departure City.
arrival_date
Optional
Date of arrival.
arrival_country
Optional
Arrival Country
arrival_state
Optional
Arrival State
arrival_city
Optional
Arrival City
travel_mode
Optional
Mode of transportation. Possible values are flight ,by_road, train, bus
is_personal_travel
Optional
Whether it is a personal trip.
is_accomodation
Optional
Whether accomodation is provided.
description
Optional
Any comments about the trip.
custom_fields
Optional
Custom field added.
customfield_id
Optional
Unique ID for the Custom Field.
value
Optional
Value entered in the Custom Field.
Optional
Other travellers of the trip.
user_id
Optional
Unique ID of the owner of the trip.

Approve a trip request

Approve a submitted trip request.

POST /trips/{trip_id}/approve

Request Example

  
$ curl https://expense.zoho.com/api/v1/trips/{trip_id}/approve -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Trip approved successfully" }

Reject a trip request

Reject a submitted trip request.

POST /trips/{trip_id}/reject

Request Example

  
$ curl https://expense.zoho.com/api/v1/trips/{trip_id}/reject -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d comments="Trip got rescheduled"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Trip has been rejected." }

ARGUMENTS

comments
Optional
Reason for the Trip's rejection.

Cancel a trip

Cancel a trip.

POST /trips/{trip_id}/cancel

Request Example

  
$ curl https://expense.zoho.com/api/v1/trips/{trip_id}/cancel -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d comments="Trip got rescheduled"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Trip has been marked 'Cancelled'." }

ARGUMENTS

comments
Optional
Reason for cancelling the trip.

Close a trip

Close an approved trip.

POST /trips/{trip_id}/close

Request Example

  
$ curl https://expense.zoho.com/api/v1/trips/{trip_id}/close -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Trip closed successfully" }

Delete a trip request

Delete a trip request. Approved, Closed and Cancelled trips cannot be deleted.

DELETE /trips/{trip_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/trips/{trip_id} -X DELETE -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Trip(s) deleted successfully" }

Expense Categories

An expense category entity allows you to maintain details of an expense category.

Example

{ "category_id": "16367000000000418", "category_name": "Air Travel Expense", "gl_code": "air01", "description": "Expenses on business travels like hotel booking charges, flight charges, etc. are recorded as travel expenses.", "status": "active", "attachment_file_name": "", "flat_amount": 500, "is_description_required": false, "is_receipt_required": false, "is_maximum_amount_required": false, "receipt_required_amount": 500, "maximum_allowed_amount": 1000, "created_time": "2011-10-19T23:19:28-0700", "is_mileage": false, "has_transaction": false, "category_icon": "travel", "last_modified_time": "2017-02-28T17:01:02+0530", "can_override_settings": false, "can_delete": true, "category_type": "expense", "is_enabled": true, "parent_account_id": "16367000000106279", "parent_account_name": "expense" }

Attribute

category_id
long
Unique ID for expense category generated by the server. This is used as an identifier.
category_name
string
Name of the expense category.
gl_code
string
Unique account code for the expense category.
description
string
Description of the expense category.
status
string
Whether the expense category is active. It can either be true or false.
attachment_file_name
string
Name of the attachment file.
flat_amount
double
Amount for the expense category.
is_description_required
boolean
Whether description is mandatory. It can either be true or false.
is_receipt_required
boolean
Whether receipt is required. It can either be true or false.
is_maximum_amount_required
boolean
Whether there is any maximum amount limit for expense. It can either be true or false.
receipt_required_amount
double
Amount limit above which receipt is mandatory.
maximum_allowed_amount
double
Expense amount limit.
created_time
string
Time at which this expense category was created.
is_mileage
boolean
Whether this is a mileage category. It can either be true or false.
has_transaction
boolean
Whether this expense category has transactions associated with it. It can either be true or false.
category_icon
string
Icon for the category.
last_modified_time
string
Last modified time.
can_override_settings
boolean
Whether this expense category can override the default polices. It can either be true or false.
can_delete
boolean
Whether we can delete this expense category. It can either be true or false.
category_type
string
Type of the Category.
is_enabled
boolean
Whether the category is currently enabled. It can either be true or false.
parent_account_id
long
Account ID of parent category.
parent_account_name
string
Account name of the parent.

Create an expense category

Create a new expense category.

POST /expensecategories

Request Example

  
$ curl https://expense.zoho.com/api/v1/expensecategories -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "category_name": "Air Travel Expense", "gl_code": "air01", "description": "Expenses on business travels like hotel booking charges, flight charges, etc. are recorded as travel expenses.", "maximum_allowed_amount": 1000, "receipt_required_amount": 500, "flat_amount": 500, "parent_account_id": "16367000000106279" }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The expense category has been created.", "expense_category": { "category_id": "16367000000000418", "category_name": "Air Travel Expense", "gl_code": "air01", "description": "Expenses on business travels like hotel booking charges, flight charges, etc. are recorded as travel expenses.", "status": "active", "attachment_file_name": "", "flat_amount": 500, "is_description_required": false, "is_receipt_required": false, "is_maximum_amount_required": false, "receipt_required_amount": 500, "maximum_allowed_amount": 1000, "created_time": "2011-10-19T23:19:28-0700", "is_custom": false, "is_mileage": false, "has_transaction": false, "category_icon": "travel", "last_modified_time": "2017-02-28T17:01:02+0530", "can_override_settings": false, "can_delete": true, "category_type": "expense", "is_enabled": true, "parent_account_id": "16367000000106279", "parent_account_name": "expense" } }

ARGUMENTS

category_name
Required
Name of the expense category.
gl_code
Optional
Unique account code for the expense category.
description
Optional
Description of the expense category.
maximum_allowed_amount
Optional
Expense amount limit.
receipt_required_amount
Optional
Amount limit above which receipt is mandatory.
flat_amount
Optional
Amount for the expense category.
parent_account_id
Optional
Account ID of parent category.

Retrieve details of an expense category

Details of an existing expense category.

GET /expensecategories/{expense_category_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/expensecategories/{expense_category_id} -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "expense_category": { "category_id": "16367000000000418", "category_name": "Air Travel Expense", "gl_code": "air01", "description": "Expenses on business travels like hotel booking charges, flight charges, etc. are recorded as travel expenses.", "status": "active", "attachment_file_name": "", "flat_amount": 500, "is_description_required": false, "is_receipt_required": false, "is_maximum_amount_required": false, "receipt_required_amount": 500, "maximum_allowed_amount": 1000, "created_time": "2011-10-19T23:19:28-0700", "is_custom": false, "is_mileage": false, "has_transaction": false, "category_icon": "travel", "last_modified_time": "2017-02-28T17:01:02+0530", "can_override_settings": false, "can_delete": true, "category_type": "expense", "is_enabled": true, "parent_account_id": "16367000000106279", "parent_account_name": "expense" } }

List of expense categories

List of all active expense categories.

GET /expensecategories

Request Example

  
$ curl https://expense.zoho.com/api/v1/expensecategories -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "expense_categories": [ { "category_id": "16367000000000418", "category_name": "Air Travel Expense", "gl_code": "air01", "description": "Expenses on business travels like hotel booking charges, flight charges, etc. are recorded as travel expenses.", "status": "active", "attachment_file_name": "", "flat_amount": 500, "is_maximum_amount_required": false, "maximum_allowed_amount": 1000, "is_description_required": false, "is_receipt_required": false, "is_mileage": false, "is_perdiem_account": false, "receipt_required_amount": 500, "can_override_settings": false, "is_custom": false, "is_super_parent": false, "is_enabled": true, "category_icon": "travel", "can_delete": true, "category_type": "expense", "parent_account_id": "16367000000106279", "parent_account_name": "expense", "depth": 0, "is_child_present": false, "child_count": "" }, {...}, {...} ] }

Query Params

Optional
For filtering Expense Categories based on Status.
Status.Inactive
Optional
List of all Inactive Expense Categories.
Status.All
Optional
List of all Expense Categories.

Update an expense category

Update the details of an existing expense category.

PUT /expensecategories/{expense_category_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/expensecategories/{expense_category_id} -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "category_name": "Air Travel Expense", "gl_code": "air01", "description": "Expenses on business travels like hotel booking charges, flight charges, etc. are recorded as travel expenses.", "maximum_allowed_amount": 1000, "receipt_required_amount": 500, "flat_amount": 500 }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The details of the expense category has been updated.", "expense_category": { "category_id": "16367000000000418", "category_name": "Air Travel Expense", "gl_code": "air01", "description": "Expenses on business travels like hotel booking charges, flight charges, etc. are recorded as travel expenses.", "status": "active", "attachment_file_name": "", "flat_amount": 500, "is_description_required": false, "is_receipt_required": false, "is_maximum_amount_required": false, "receipt_required_amount": 500, "maximum_allowed_amount": 1000, "created_time": "2011-10-19T23:19:28-0700", "is_custom": false, "is_mileage": false, "has_transaction": false, "category_icon": "travel", "last_modified_time": "2017-02-28T17:01:02+0530", "can_override_settings": false, "can_delete": true, "category_type": "expense", "is_enabled": true, "parent_account_id": "16367000000106279", "parent_account_name": "expense" } }

ARGUMENTS

category_name
Optional
Name of the expense category.
gl_code
Optional
Unique account code for the expense category.
description
Optional
Description of the expense category.
maximum_allowed_amount
Optional
Expense amount limit.
receipt_required_amount
Optional
Amount limit above which receipt is mandatory.
flat_amount
Optional
Amount for the expense category.

Enable an expense category

Enable an expense category.

POST /expensecategories/{expense_category_id}/show

Request Example

  
$ curl https://expense.zoho.com/api/v1/expensecategories/{expense_category_id}/show -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The expense category has been marked as active." }

Disable an expense category

Disable an expense category.

POST /expensecategories/{expense_category_id}/hide

Request Example

  
$ curl https://expense.zoho.com/api/v1/expensecategories/{expense_category_id}/hide -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The expense category has been marked as inactive." }

Delete an expense category

Delete an existing expense category.

DELETE /expensecategories/{expense_category_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/expensecategories/{expense_category_id} -X DELETE -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The expense category has been deleted." }

Users

A user entity allows you to maintain information about a user.

Example

{ "user_id": "16367000000073071", "name": "Tricia Boyle", "first_name": "Tricia", "last_name": "Boyle", "email": "patriciab@zillum.com", "email_ids": [ { "email": "patriciab@zillum.com", "is_selected": true } ], "status": "active", "role_id": "16367000000030005", "user_role": "submitter", "user_type": "zoho", "photo_url": "https://contacts.zoho.com/file?ID=a8625cce152ee5dc0ca36e254b6ccd89a644a6e131442dd531484dc7a3a15ad4cdd0803c615479b1c1a699af5729301fa0a180e1d691bb9609894e60544ef753&fs=thumb", "default_approver_id": "16367000000073001", "default_approver_name": "Will Smith", "default_approver_email": "will.smith@yahoo.in", "created_time": "2017-02-15", "last_modified_time": "2017-02-21", "approves_to_id": "16367000000073001", "approves_to_name": "Will Smith", "approves_to_email": "will.smith@yahoo.in", "submission_amount_limit": 5000, "approval_amount_limit": 1000, "employee_number": "E001", "department_id": "16367000000093001", "department_name": "Finance", "designation_name": "Manager", "designation_id": "16367000000093003", "date_of_birth": "1996-07-25", "date_of_joining": "2017-01-04", "mobile": "9500881944", "gender": "male", "policy_id": "16367000000092011", "policy_name": "Expense Saver", "bank_name": "HDFC", "bank_account_type": "Savings", "custom_fields": [ { "customfield_id": "16367000000093005", "data_type": "string", "is_active": true, "is_basecurrency_amount": true, "is_mandatory": false, "label": "Nick Name", "value": "Tric" } ], "user_mail_in_id": "tricia.boyle.9k2rrt@zohoexpensemail.com" }

Attribute

user_id
long
Unique ID for user generated by the server. This is used as identifier.
name
string
Name of the user.
first_name
string
First Name of the User.
last_name
string
Last Name of the User.
email
string
Active Email ID of the user.
list
Registered Email Ids of the user.
email
string
Active Email ID of the user.
is_selected
boolean
Whether selected as active. It can either be true or false.
status
string
Status of the user. It can either be active or inactive or deleted or invited.
role_id
long
Unique ID for the role of user.
user_role
string
Role of the user.
user_type
string
Type of the User.
photo_url
string
Url of the profile photo.
default_approver_id
long
ID of the Approver.
default_approver_name
string
Name of the Approver for a user.
default_approver_email
string
Email Id of the Approver for a user.
created_time
string
Time at which this user was created.
last_modified_time
string
Time at which this user's details were last modified.
approves_to_id
long
ID of the User getting approved by.
approves_to_name
string
Name of to user getting approved by.
approves_to_email
string
Email ID of the user getting approved by.
submission_amount_limit
double
Limit of the amount being submitted.
approval_amount_limit
double
Limit of the amount being approved.
employee_number
string
Number of the employee.
department_id
long
Unique ID for the department.
department_name
string
Name of the department.
designation_name
string
Name of the designation.
designation_id
long
Unique ID for the designation generated by server.
date_of_birth
string
Date Of Birth of the User.
date_of_joining
string
Date of Joining of the User.
mobile
long
Mobile Number of the User.
gender
string
Gender of the User.
policy_id
long
Unique ID for the Policy.
policy_name
string
Name of the Policy.
bank_name
string
Name of the bank.
bank_account_type
string
Type of Bank Account.
custom_fields
list
Custom Fields added.
customfield_id
long
Unique ID for the Custom Field.
data_type
string
Data Type of the Custom Field.
is_active
boolean
Whether the Custom Field is Active. It can either be true or false.
is_basecurrency_amount
boolean
Whether the Custom Field is Base Currency Amount. It can either be true or false.
is_mandatory
boolean
Whether the Custom Field is Mandatory. It can either be true or false.
label
string
Label for the Custom Field.
value
string
Value entered in the Custom Field.
user_mail_in_id
string
Mail ID generated by Zoho Expense for the User.

Create an user

Create a new user.

POST /users

Request Example

  
$ curl https://expense.zoho.com/api/v1/users -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "name": "Tricia Boyle", "email": "patriciab@zillum.com", "user_role": "submitter", "default_approver_email": "will.smith@yahoo.in", "approves_to_email": "will.smith@yahoo.in", "submission_amount_limit": 5000, "approval_amount_limit": 1000, "employee_number": "E001", "department_name": "Finance", "designation_name": "Manager", "date_of_birth": "1996-07-25", "date_of_joining": "2017-01-04", "mobile": "9500881944", "gender": "male", "policy_name": "Expense Saver", "custom_fields": [ { "customfield_id": "16367000000093005", "value": "Tric" } ] }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your invitation has been sent.", "user": { "user_id": "16367000000073071", "name": "Tricia Boyle", "first_name": "Tricia", "last_name": "Boyle", "email": "patriciab@zillum.com", "email_ids": [ { "email": "patriciab@zillum.com", "is_selected": true } ], "status": "active", "role_id": "16367000000030005", "user_role": "submitter", "user_type": "zoho", "photo_url": "https://contacts.zoho.com/file?ID=a8625cce152ee5dc0ca36e254b6ccd89a644a6e131442dd531484dc7a3a15ad4cdd0803c615479b1c1a699af5729301fa0a180e1d691bb9609894e60544ef753&fs=thumb", "default_approver_id": "16367000000073001", "default_approver_name": "Will Smith", "default_approver_email": "will.smith@yahoo.in", "created_time": "2017-02-15", "last_modified_time": "2017-02-21", "approves_to_id": "16367000000073001", "approves_to_name": "Will Smith", "approves_to_email": "will.smith@yahoo.in", "submission_amount_limit": 5000, "approval_amount_limit": 1000, "employee_number": "E001", "department_id": "16367000000093001", "department_name": "Finance", "designation_name": "Manager", "designation_id": "16367000000093003", "date_of_birth": "1996-07-25", "date_of_joining": "2017-01-04", "mobile": "9500881944", "gender": "male", "policy_id": "16367000000092011", "policy_name": "Expense Saver", "bank_name": "HDFC", "bank_account_type": "Savings", "custom_fields": [ { "customfield_id": "16367000000093005", "data_type": "string", "is_active": true, "is_basecurrency_amount": true, "is_mandatory": false, "label": "Nick Name", "value": "Tric" } ], "user_mail_in_id": "tricia.boyle.9k2rrt@zohoexpensemail.com" } }

ARGUMENTS

name
Required
Name of the user.
email
Required
Active Email ID of the user.
user_role
Required
Role of the user.
default_approver_email
Optional
Email Id of the Approver for a user.
approves_to_email
Optional
Email ID of the user getting approved by.
submission_amount_limit
Optional
Limit of the amount being submitted.
approval_amount_limit
Optional
Limit of the amount being approved.
employee_number
Optional
Number of the employee.
department_name
Optional
Name of the department.
designation_name
Optional
Name of the designation.
date_of_birth
Optional
Date Of Birth of the User.
date_of_joining
Optional
Date of Joining of the User.
mobile
Optional
Mobile Number of the User.
gender
Optional
Gender of the User.
policy_name
Optional
Name of the Policy.
custom_fields
Optional
Custom Fields added.
customfield_id
Required
Unique ID for the Custom Field.
value
Required
Value entered in the Custom Field.

Retrieve details of an user

Details of an existing user.

GET /users/{user_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/users/{user_id} -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "user": { "user_id": "16367000000073071", "name": "Tricia Boyle", "first_name": "Tricia", "last_name": "Boyle", "email": "patriciab@zillum.com", "email_ids": [ { "email": "patriciab@zillum.com", "is_selected": true } ], "status": "active", "role_id": "16367000000030005", "user_role": "submitter", "user_type": "zoho", "photo_url": "https://contacts.zoho.com/file?ID=a8625cce152ee5dc0ca36e254b6ccd89a644a6e131442dd531484dc7a3a15ad4cdd0803c615479b1c1a699af5729301fa0a180e1d691bb9609894e60544ef753&fs=thumb", "default_approver_id": "16367000000073001", "default_approver_name": "Will Smith", "default_approver_email": "will.smith@yahoo.in", "created_time": "2017-02-15", "last_modified_time": "2017-02-21", "approves_to_id": "16367000000073001", "approves_to_name": "Will Smith", "approves_to_email": "will.smith@yahoo.in", "submission_amount_limit": 5000, "approval_amount_limit": 1000, "employee_number": "E001", "department_id": "16367000000093001", "department_name": "Finance", "designation_name": "Manager", "designation_id": "16367000000093003", "date_of_birth": "1996-07-25", "date_of_joining": "2017-01-04", "mobile": "9500881944", "gender": "male", "policy_id": "16367000000092011", "policy_name": "Expense Saver", "bank_name": "HDFC", "bank_account_type": "Savings", "custom_fields": [ { "customfield_id": "16367000000093005", "data_type": "string", "is_active": true, "is_basecurrency_amount": true, "is_mandatory": false, "label": "Nick Name", "value": "Tric" } ], "user_mail_in_id": "tricia.boyle.9k2rrt@zohoexpensemail.com" } }

Retrieve list of users

Details of all existing users.

GET /users

Request Example

  
$ curl https://expense.zoho.com/api/v1/users -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "users": [ { "user_id": "16367000000073071", "role_id": "16367000000030005", "name": "Tricia Boyle", "email": "patriciab@zillum.com", "user_role": "submitter", "user_type": "zoho", "can_approve": true, "status": "active", "default_approver_id": "16367000000073001", "default_approver_name": "Will Smith", "default_approver_email": "will.smith@yahoo.in", "is_from_crm": false, "is_current_user": true, "photo_url": "https://contacts.zoho.com/file?ID=a8625cce152ee5dc0ca36e254b6ccd89a644a6e131442dd531484dc7a3a15ad4cdd0803c615479b1c1a699af5729301fa0a180e1d691bb9609894e60544ef753&fs=thumb", "approves_to_id": "16367000000073001", "approves_to_name": "Will Smith", "approves_to_email": "will.smith@yahoo.in", "submission_amount_limit": 5000, "approval_amount_limit": 1000, "created_time": "2017-02-15", "last_modified_time": "2017-02-21", "user_mail_in_id": "tricia.boyle.9k2rrt@zohoexpensemail.com", "employee_number": "E001", "department_id": "16367000000093001", "department_name": "Finance", "policy_id": "16367000000092011", "policy_name": "Expense Saver" }, {...}, {...} ] }

Make an user inactive

Make an user inactive.

POST /users/{user_id}/inactive

Request Example

  
$ curl https://expense.zoho.com/api/v1/users/{user_id}/inactive -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The user has been marked as inactive." }

Update details of an user

Update the details of an existing user.

PUT /users/{user_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/users/{user_id} -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "name": "Tricia Boyle", "user_role": "submitter", "approval_amount_limit": 1000, "submission_amount_limit": 5000, "department_id": "16367000000093001", "department_name": "Finance", "designation_name": "Manager", "mobile": "9500881944", "custom_fields": [ { "customfield_id": "16367000000093005", "value": "Tric" } ] }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The user details has been updated.", "user_id": "16367000000073071", "name": "Tricia Boyle", "first_name": "Tricia", "last_name": "Boyle", "email": "patriciab@zillum.com", "email_ids": [ { "email": "patriciab@zillum.com", "is_selected": true } ], "status": "active", "role_id": "16367000000030005", "user_role": "submitter", "user_type": "zoho", "photo_url": "https://contacts.zoho.com/file?ID=a8625cce152ee5dc0ca36e254b6ccd89a644a6e131442dd531484dc7a3a15ad4cdd0803c615479b1c1a699af5729301fa0a180e1d691bb9609894e60544ef753&fs=thumb", "default_approver_id": "16367000000073001", "default_approver_name": "Will Smith", "default_approver_email": "will.smith@yahoo.in", "created_time": "2017-02-15", "last_modified_time": "2017-02-21", "approves_to_id": "16367000000073001", "approves_to_name": "Will Smith", "approves_to_email": "will.smith@yahoo.in", "submission_amount_limit": 5000, "approval_amount_limit": 1000, "employee_number": "E001", "department_id": "16367000000093001", "department_name": "Finance", "designation_name": "Manager", "designation_id": "16367000000093003", "date_of_birth": "1996-07-25", "date_of_joining": "2017-01-04", "mobile": "9500881944", "gender": "male", "policy_id": "16367000000092011", "policy_name": "Expense Saver", "bank_name": "HDFC", "bank_account_type": "Savings", "custom_fields": [ { "customfield_id": "16367000000093005", "data_type": "string", "is_active": true, "is_basecurrency_amount": true, "is_mandatory": false, "label": "Nick Name", "value": "Tric" } ], "user_mail_in_id": "tricia.boyle.9k2rrt@zohoexpensemail.com" }

ARGUMENTS

name
Optional
Name of the user.
user_role
Optional
Role of the user.
approval_amount_limit
Optional
Limit of the amount being approved.
submission_amount_limit
Optional
Limit of the amount being submitted.
department_id
Optional
Unique ID for the department.
department_name
Optional
Name of the department.
designation_name
Optional
Name of the designation.
mobile
Optional
Mobile Number of the User.
custom_fields
Optional
Custom Fields added.
customfield_id
Required
Unique ID for the Custom Field.
value
Required
Value entered in the Custom Field.

Make an user active

Make an user active.

POST /users/{user_id}/active

Request Example

  
$ curl https://expense.zoho.com/api/v1/users/{user_id}/active -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The user has been marked as active." }

Assign a role to user

Assign a role to user.

POST /users/{user_id}/role/{role_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/users/{user_id}/role/{role_id} -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Role has been assigned to the user" }

Delete an user

Delete an existing user.

DELETE /users/{user_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/users/{user_id} -X DELETE -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The user has been deleted." }

Customers

A customer entity allows you to maintain information about a customer.

Example

{ "contact_id": "16367000000096001", "contact_name": "Kenny Digital", "company_name": "Kenny Digital", "website": "kennedyr.com", "payment_terms": 0, "payment_terms_label": "Due on Receipt", "currency_id": "16367000000000097", "currency_code": "USD", "currency_symbol": "$", "price_precision": 2, "status": "active", "billing_address": { "address_id": "16367000000096004", "address": "3500, Bayshore, Burlingame", "city": "San Francisco", "state": "CA", "zip": "94010", "country": "USA", "fax": "342-421234", "attention": "" }, "shipping_address": { "address_id": "16367000000096004", "address": "3500, Bayshore, Burlingame", "city": "San Francisco", "state": "CA", "zip": "94010", "country": "USA", "fax": "342-421234", "attention": "" }, "contact_persons": [ { "contact_person_id": "16367000000096003", "salutation": "Mr.", "first_name": "Ken", "last_name": "Kennedy", "email": "ken.kennedy@gmail.com", "phone": "235456", "mobile": "9566977190", "department": "", "designation": "", "skype": "Kenny", "fax": "342-421234", "can_invite": true, "is_primary_contact": true } ], "notes": "note", "created_time": "2017-02-28T10:36:40+0530", "last_modified_time": "2017-02-28T10:36:40+0530" }

Attribute

contact_id
long
Unique ID for the contact. This is used as an identifier.
contact_name
string
Name of the contact.
company_name
string
Registered name of the company the contact represents.
website
string
Website of the contact.
payment_terms
integer
Payment terms for contact.
payment_terms_label
string
Payment term label.
currency_id
long
Unique ID for currency.
currency_code
string
Base currency of contact.
currency_symbol
string
Symbol of the currency.
price_precision
integer
Precise amount upto n decimal points.
status
string
Status of the contact. It can either be activeor inactive.
billing_address
object
Contact's billing address object.
address_id
long
Unique ID for address.
address
string
Address
city
string
City
state
string
State
zip
string
Zip Code
country
string
Country
fax
string
Fax Number
attention
string
attention
shipping_address
object
Contact’s shipping address object.
address_id
long
Unique ID for address.
address
string
Address
city
string
City
state
string
State
zip
string
Zip Code
country
string
Country
fax
string
Fax Number
attention
string
attention
contact_persons
list
List of contact persons for the contact. It contains contact_person_id, salutation, first_name,last_name,email,phone,mobile and is_primary_contact.
contact_person_id
long
Unique ID for contact person. This is used as an identifier.
salutation
string
Salutation of the contact person. Possible values are Mr or Mrs or Miss or Ms or Dr
first_name
string
First name of the contact person.
last_name
string
Last name of the contact person.
email
string
Email address of the contact person.
phone
long
Landline phone number of the contact person.
mobile
long
Mobile number of the contact person.
department
string
Department of the contact person.
designation
string
Designation of the contact person.
skype
string
Skype Name / Number of the contact person.
fax
string
Fax Number
can_invite
boolean
Whether the contact person is allowed to invite others. It can either be true or false.
is_primary_contact
boolean
Whether this person is the primary contact person for this contact. It can either be true or false.
notes
string
A short note about the contact.
created_time
string
Time at which the contact details were created.
last_modified_time
string
Time at which the contact details were last updated.

Create a customer

Create a new customer.

POST /contacts

Request Example

  
$ curl https://expense.zoho.com/api/v1/contacts -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "contact_name": "Kenny Digital", "company_name": "Kenny Digital", "website": "kennedyr.com", "email": "ken.kennedy@gmail.com", "mobile": "9566977190", "twitter": "kenkennedy", "facebook": "ken.kennedy", "phone": "235456", "billing_address": { "address_id": "16367000000096004", "address": "3500, Bayshore, Burlingame", "city": "San Francisco", "state": "CA", "zip": "94010", "country": "USA", "fax": "342-421234", "attention": "" }, "shipping_address": { "address_id": "16367000000096004", "address": "3500, Bayshore, Burlingame", "city": "San Francisco", "state": "CA", "zip": "94010", "country": "USA", "fax": "342-421234", "attention": "" }, "contact_persons": [ { "contact_person_id": "16367000000096003", "salutation": "Mr.", "first_name": "Ken", "last_name": "Kennedy", "email": "ken.kennedy@gmail.com", "phone": "235456", "mobile": "9566977190", "department": "", "designation": "", "skype": "Kenny", "fax": "342-421234", "can_invite": true, "is_primary_contact": true } ] }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The customer has been created.", "contact": { "contact_id": "16367000000096001", "contact_name": "Kenny Digital", "company_name": "Kenny Digital", "website": "kennedyr.com", "contact_salutation": "Mr", "has_transaction": false, "contact_type": "customer", "source": "user", "is_crm_customer": false, "is_linked_with_zohocrm": false, "primary_contact_id": "16367000000096003", "payment_terms": 0, "payment_terms_label": "Due on Receipt", "currency_id": "16367000000000097", "currency_code": "USD", "currency_symbol": "$", "price_precision": 2, "status": "active", "vat_reg_no": "", "vat_treatment": "", "first_name": "Ken", "last_name": "Kennedy", "email": "ken.kennedy@gmail.com", "phone": "235456", "mobile": "9566977190", "twitter": "kenkennedy", "facebook": "ken.kennedy", "billing_address": { "address_id": "16367000000096004", "address": "3500, Bayshore, Burlingame", "city": "San Francisco", "state": "CA", "zip": "94010", "country": "USA", "fax": "342-421234", "attention": "" }, "shipping_address": { "address_id": "16367000000096004", "address": "3500, Bayshore, Burlingame", "city": "San Francisco", "state": "CA", "zip": "94010", "country": "USA", "fax": "342-421234", "attention": "" }, "contact_persons": [ { "contact_person_id": "16367000000096003", "salutation": "Mr.", "first_name": "Ken", "last_name": "Kennedy", "email": "ken.kennedy@gmail.com", "phone": "235456", "mobile": "9566977190", "department": "", "designation": "", "skype": "Kenny", "fax": "342-421234", "can_invite": true, "is_primary_contact": true } ], "notes": "note", "created_time": "2017-02-28T10:36:40+0530", "last_modified_time": "2017-02-28T10:36:40+0530" } }

ARGUMENTS

contact_name
Required
Name of the contact.
company_name
Optional
Registered name of the company the contact represents.
website
Optional
Website of the contact.
email
Optional
Email address of the contact person.
mobile
Optional
Mobile number of the contact person.
twitter
Optional
Twitter handle of the contact person.
facebook
Optional
Facebook ID of the contact person.
phone
Optional
Landline phone number of the contact person.
billing_address
Optional
Contact's billing address object.
address_id
Optional
Unique ID for address.
address
Optional
Address
city
Optional
City
state
Optional
State
zip
Optional
Zip Code
country
Optional
Country
fax
Optional
Fax Number
attention
Optional
attention
shipping_address
Optional
Contact’s shipping address object.
address_id
Optional
Unique ID for address.
address
Optional
Address
city
Optional
City
state
Optional
State
zip
Optional
Zip Code
country
Optional
Country
fax
Optional
Fax Number
attention
Optional
attention
contact_persons
Optional
List of contact persons for the contact. It contains contact_person_id, salutation, first_name,last_name,email,phone,mobile and is_primary_contact.
contact_person_id
Optional
Unique ID for contact person. This is used as an identifier.
salutation
Optional
Salutation of the contact person. Possible values are Mr or Mrs or Miss or Ms or Dr
first_name
Optional
First name of the contact person.
last_name
Optional
Last name of the contact person.
email
Optional
Email address of the contact person.
phone
Optional
Landline phone number of the contact person.
mobile
Optional
Mobile number of the contact person.
department
Optional
Department of the contact person.
designation
Optional
Designation of the contact person.
skype
Optional
Skype Name / Number of the contact person.
fax
Optional
Fax Number
can_invite
Optional
Whether the contact person is allowed to invite others. It can either be true or false.
is_primary_contact
Optional
Whether this person is the primary contact person for this contact. It can either be true or false.

Retrieve details of a customer

Details of an existing customer.

GET /contacts/{customer_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/contacts/{customer_id} -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contact": { "contact_id": "16367000000096001", "contact_name": "Kenny Digital", "company_name": "Kenny Digital", "website": "kennedyr.com", "contact_salutation": "Mr", "has_transaction": false, "contact_type": "customer", "source": "user", "is_crm_customer": false, "is_linked_with_zohocrm": false, "primary_contact_id": "16367000000096003", "payment_terms": 0, "payment_terms_label": "Due on Receipt", "currency_id": "16367000000000097", "currency_code": "USD", "currency_symbol": "$", "price_precision": 2, "status": "active", "vat_reg_no": "", "vat_treatment": "", "first_name": "Ken", "last_name": "Kennedy", "email": "ken.kennedy@gmail.com", "phone": "235456", "mobile": "9566977190", "twitter": "kenkennedy", "facebook": "ken.kennedy", "billing_address": { "address_id": "16367000000096004", "address": "3500, Bayshore, Burlingame", "city": "San Francisco", "state": "CA", "zip": "94010", "country": "USA", "fax": "342-421234", "attention": "" }, "shipping_address": { "address_id": "16367000000096004", "address": "3500, Bayshore, Burlingame", "city": "San Francisco", "state": "CA", "zip": "94010", "country": "USA", "fax": "342-421234", "attention": "" }, "contact_persons": [ { "contact_person_id": "16367000000096003", "salutation": "Mr.", "first_name": "Ken", "last_name": "Kennedy", "email": "ken.kennedy@gmail.com", "phone": "235456", "mobile": "9566977190", "department": "", "designation": "", "skype": "Kenny", "fax": "342-421234", "can_invite": true, "is_primary_contact": true } ], "notes": "note", "created_time": "2017-02-28T10:36:40+0530", "last_modified_time": "2017-02-28T10:36:40+0530" } }

List of all customers

List of all customers.

GET /contacts

Request Example

  
$ curl https://expense.zoho.com/api/v1/contacts -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "customers": [ { "contact_id": "16367000000096001", "contact_name": "Kenny Digital", "company_name": "Kenny Digital", "contact_type": "customer", "status": "active", "source": "user", "is_linked_with_zohocrm": false, "currency_id": "16367000000000097", "currency_code": "USD", "first_name": "Ken", "last_name": "Kennedy", "email": "ken.kennedy@gmail.com", "phone": "235456", "mobile": "9566977190", "created_time": "2017-02-28T10:36:40+0530", "last_modified_time": "2017-02-28T10:36:40+0530" }, {...}, {...} ] }

Update a customer

Update the details of an existing customer.

PUT /contacts/{customer_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/contacts/{customer_id} -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "contact_name": "Kenny Digital", "company_name": "Kenny Digital", "website": "kennedyr.com", "notes": "note", "email": "ken.kennedy@gmail.com", "phone": "235456", "facebook": "ken.kennedy", "mobile": "9566977190", "billing_address": { "address_id": "16367000000096004", "address": "3500, Bayshore, Burlingame", "city": "San Francisco", "state": "CA", "zip": "94010", "country": "USA", "fax": "342-421234", "attention": "" } }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Customer information has been saved.", "contact": { "contact_id": "16367000000096001", "contact_name": "Kenny Digital", "company_name": "Kenny Digital", "website": "kennedyr.com", "contact_salutation": "Mr", "has_transaction": false, "contact_type": "customer", "source": "user", "is_crm_customer": false, "is_linked_with_zohocrm": false, "primary_contact_id": "16367000000096003", "payment_terms": 0, "payment_terms_label": "Due on Receipt", "currency_id": "16367000000000097", "currency_code": "USD", "currency_symbol": "$", "price_precision": 2, "status": "active", "vat_reg_no": "", "vat_treatment": "", "first_name": "Ken", "last_name": "Kennedy", "email": "ken.kennedy@gmail.com", "phone": "235456", "mobile": "9566977190", "twitter": "kenkennedy", "facebook": "ken.kennedy", "billing_address": { "address_id": "16367000000096004", "address": "3500, Bayshore, Burlingame", "city": "San Francisco", "state": "CA", "zip": "94010", "country": "USA", "fax": "342-421234", "attention": "" }, "shipping_address": { "address_id": "16367000000096004", "address": "3500, Bayshore, Burlingame", "city": "San Francisco", "state": "CA", "zip": "94010", "country": "USA", "fax": "342-421234", "attention": "" }, "contact_persons": [ { "contact_person_id": "16367000000096003", "salutation": "Mr.", "first_name": "Ken", "last_name": "Kennedy", "email": "ken.kennedy@gmail.com", "phone": "235456", "mobile": "9566977190", "department": "", "designation": "", "skype": "Kenny", "fax": "342-421234", "can_invite": true, "is_primary_contact": true } ], "notes": "note", "created_time": "2017-02-28T10:36:40+0530", "last_modified_time": "2017-02-28T10:36:40+0530" } }

ARGUMENTS

contact_name
Optional
Name of the contact.
company_name
Optional
Registered name of the company the contact represents.
website
Optional
Website of the contact.
notes
Optional
A short note about the contact.
email
Optional
Email address of the contact person.
phone
Optional
Landline phone number of the contact person.
facebook
Optional
Facebook ID of the contact person.
mobile
Optional
Mobile number of the contact person.
billing_address
Optional
Contact's billing address object.
address_id
Optional
Unique ID for address.
address
Optional
Address
city
Optional
City
state
Optional
State
zip
Optional
Zip Code
country
Optional
Country
fax
Optional
Fax Number
attention
Optional
attention

Delete a customer

Delete an existing customer.

DELETE /contacts/{customer_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/contacts/{customer_id} -X DELETE -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The customer has been deleted." }

Projects

A project entity allows you to maintain information about a project.

Example

{ "project_id": "16367000000096055", "project_name": "Brochure Design - Spa", "customer_id": "16367000000096001", "customer_name": "Kenny Digital", "currency_code": "USD", "description": "8.5 x 11 Pet Hotel and Spa brochure template", "status": "active", "billing_type": "based_on_task_hours", "budget_type": "hours_per_task", "show_to_all_users": true, "project_head_id": "16367000000073071", "project_head_name": "Tricia", "created_time": "2017-02-28T12:30:34+0530", "users": [ { "user_id": "16367000000073001", "is_current_user": true, "name": "Will Smith", "email": "will.smith@gmail.com", "user_role": "admin", "role_id": "16367000000030001", "status": "active", "rate": 0 } ] }

Attribute

project_id
long
Unique ID for the project generated by the server. This is used as identifier.
project_name
string
Name of the project.
customer_id
long
Unique ID of the customer.
customer_name
string
Name of the customer.
currency_code
string
Base currency for the project.
description
string
Description about the project.
status
string
Status of the project. It can either be active or inactive.
billing_type
string
Type of billing for the project. Give based_on_task_hours as default.
budget_type
string
Type of budget of the project. Possible values are hours_per_staff or hours_per_task or total_project_hours or total_project_cost.
show_to_all_users
boolean
Whether the Project is shown to all users.
project_head_id
long
Unique ID of Project Head.
project_head_name
string
Name of the Project Head.
created_time
string
Time of project creation.
list
Associated user details list.
user_id
long
Unique ID of the user.
is_current_user
boolean
Whether he/she is the current user. It can either be true or false.
name
string
Name of the user.
email
string
Email ID of the user.
user_role
string
Role of the user.
role_id
long
Unique ID for the role.
status
string
Status of the project. It can either be active or inactive.
rate
double
Fixed rate for user.

Create a project

Create a new project.

POST /projects

Request Example

  
$ curl https://expense.zoho.com/api/v1/projects -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "project_name": "Brochure Design - Spa", "customer_id": "16367000000096001", "description": "8.5 x 11 Pet Hotel and Spa brochure template", "billing_type": "based_on_task_hours", "show_to_all_users": true, "project_head_id": "16367000000073071", "users": [ { "user_id": "16367000000073001", "is_current_user": true, "name": "Will Smith", "email": "will.smith@gmail.com", "user_role": "admin", "role_id": "16367000000030001", "status": "active", "rate": 0 } ] }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The project has been created.", "project": { "project_id": "16367000000096055", "project_name": "Brochure Design - Spa", "customer_id": "16367000000096001", "customer_name": "Kenny Digital", "currency_code": "USD", "description": "8.5 x 11 Pet Hotel and Spa brochure template", "status": "active", "billing_type": "based_on_task_hours", "budget_type": "hours_per_task", "show_to_all_users": true, "project_head_id": "16367000000073071", "project_head_name": "Tricia", "created_time": "2017-02-28T12:30:34+0530", "users": [ { "user_id": "16367000000073001", "is_current_user": true, "name": "Will Smith", "email": "will.smith@gmail.com", "user_role": "admin", "role_id": "16367000000030001", "status": "active", "rate": 0 } ] } }

ARGUMENTS

project_name
Required
Name of the project.
customer_id
Required
Unique ID of the customer.
description
Optional
Description about the project.
billing_type
Optional
Type of billing for the project. Give based_on_task_hours as default.
show_to_all_users
Optional
Whether the Project is shown to all users.
project_head_id
Optional
Unique ID of Project Head.
Optional
Associated user details list.
user_id
Optional
Unique ID of the user.
is_current_user
Optional
Whether he/she is the current user. It can either be true or false.
name
Optional
Name of the user.
email
Optional
Email ID of the user.
user_role
Optional
Role of the user.
role_id
Optional
Unique ID for the role.
status
Optional
Status of the project. It can either be active or inactive.
rate
Optional
Fixed rate for user.

Retrieve details of a project

Details of an existing project.

GET /projects/{project_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/projects/{project_id} -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "project": { "project_id": "16367000000096055", "project_name": "Brochure Design - Spa", "customer_id": "16367000000096001", "customer_name": "Kenny Digital", "currency_code": "USD", "description": "8.5 x 11 Pet Hotel and Spa brochure template", "status": "active", "billing_type": "based_on_task_hours", "budget_type": "hours_per_task", "show_to_all_users": true, "project_head_id": "16367000000073071", "project_head_name": "Tricia", "created_time": "2017-02-28T12:30:34+0530", "users": [ { "user_id": "16367000000073001", "is_current_user": true, "name": "Will Smith", "email": "will.smith@gmail.com", "user_role": "admin", "role_id": "16367000000030001", "status": "active", "rate": 0 } ] } }

List of all projects

List of all projects.

GET /projects

Request Example

  
$ curl https://expense.zoho.com/api/v1/projects -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "projects": [ { "project_id": "16367000000096055", "project_name": "Brochure Design - Spa", "customer_id": "16367000000096001", "customer_name": "Kenny Digital", "description": "8.5 x 11 Pet Hotel and Spa brochure template", "status": "active", "created_time": "2017-02-28T12:30:34+0530" }, {...}, {...} ] }

Update the details of a project

Update the details of an existing project.

PUT /projects/{project_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/projects/{project_id} -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "project_name": "Brochure Design - Spa", "customer_id": "16367000000096001", "description": "8.5 x 11 Pet Hotel and Spa brochure template", "billing_type": "based_on_task_hours" }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The project details has been updated.", "project": { "project_id": "16367000000096055", "project_name": "Brochure Design - Spa", "customer_id": "16367000000096001", "customer_name": "Kenny Digital", "currency_code": "USD", "description": "8.5 x 11 Pet Hotel and Spa brochure template", "status": "active", "billing_type": "based_on_task_hours", "budget_type": "hours_per_task", "show_to_all_users": true, "project_head_id": "16367000000073071", "project_head_name": "Tricia", "created_time": "2017-02-28T12:30:34+0530", "users": [ { "user_id": "16367000000073001", "is_current_user": true, "name": "Will Smith", "email": "will.smith@gmail.com", "user_role": "admin", "role_id": "16367000000030001", "status": "active", "rate": 0 } ] } }

ARGUMENTS

project_name
Optional
Name of the project.
customer_id
Optional
Unique ID of the customer.
description
Optional
Description about the project.
billing_type
Optional
Type of billing for the project. Give based_on_task_hours as default.

Make a project active

Mark a project as active.

POST /projects/{project_id}/active

Request Example

  
$ curl https://expense.zoho.com/api/v1/projects/{project_id}/active -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The project has been marked as active." }

Make a project inactive

Mark a project as inactive.

POST /projects/{project_id}/inactive

Request Example

  
$ curl https://expense.zoho.com/api/v1/projects/{project_id}/inactive -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The project has been marked as inactive." }

Delete a project

Delete an existing project.

DELETE /projects/{project_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/projects/{project_id} -X DELETE -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The project has been deleted." }

Currencies

A currency entity allows you to maintain details of a currency.

Example

{ "currency_id": "16367000000000097", "currency_code": "USD", "currency_name": "USD- US Dollar", "currency_symbol": "$", "price_precision": 2, "currency_format": "1,234,567.89", "is_base_currency": false, "exchange_rate": 20.780488, "effective_date": "2009-01-27" }

Attribute

currency_id
long
Unique ID for currency generated by the server. This is used as an identifier.
currency_code
string
Currency code.
currency_name
string
Name of the currency.
currency_symbol
string
Symbol for the currency.
price_precision
integer
Precise amount upto n decimal points.
currency_format
string
Currency format.
is_base_currency
boolean
Whether it is the base currency. It can either be true or false.
exchange_rate
double
Exchange rate for the Currency.
effective_date
string
Effective date for the currency.

Create a currency

Create a currency.

POST /settings/currencies

Request Example

  
$ curl https://expense.zoho.com/api/v1/settings/currencies -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "currency_code": "USD", "currency_name": "USD- US Dollar", "currency_symbol": "$", "price_precision": 2, "currency_format": "1,234,567.89" }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The currency has been created.", "currency": { "currency_id": "16367000000000097", "currency_code": "USD", "currency_name": "USD- US Dollar", "currency_symbol": "$", "price_precision": 2, "currency_format": "1,234,567.89", "is_base_currency": false } }

ARGUMENTS

currency_code
Required
Currency code.
currency_name
Optional
Name of the currency.
currency_symbol
Optional
Symbol for the currency.
price_precision
Optional
Precise amount upto n decimal points.
currency_format
Required
Currency format.

Retrieve details of a currency

Details of an existing currency.

GET /settings/currencies/{currency_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/settings/currencies/{currency_id} -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success.", "currency": { "currency_id": "16367000000000097", "currency_code": "USD", "currency_name": "USD- US Dollar", "currency_symbol": "$", "price_precision": 2, "currency_format": "1,234,567.89", "is_base_currency": false } }

Retrieve list of currencies

Details of all existing currencies.

GET /settings/currencies

Request Example

  
$ curl https://expense.zoho.com/api/v1/settings/currencies -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "currencies": [ { "currency_id": "16367000000000097", "currency_code": "USD", "currency_name": "USD- US Dollar", "currency_symbol": "$", "price_precision": 2, "currency_format": "1,234,567.89", "is_base_currency": false, "exchange_rate": 20.780488, "effective_date": "2009-01-27" }, {...}, {...} ] }

Update details of a currency

Update the details of an existing currency.

PUT /settings/currencies/{currency_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/settings/currencies/{currency_id} -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "currency_symbol": "$", "price_precision": 2, "currency_format": "1,234,567.89" }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The currency details have been updated.", "currency": { "currency_id": "16367000000000097", "currency_code": "USD", "currency_name": "USD- US Dollar", "currency_symbol": "$", "price_precision": 2, "currency_format": "1,234,567.89" } }

ARGUMENTS

currency_symbol
Optional
Symbol for the currency.
price_precision
Optional
Precise amount upto n decimal points.
currency_format
Required
Currency format.

Delete a currency

Delete an existing currency.

DELETE /settings/currencies/{currency_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/settings/currencies/{currency_id} -X DELETE -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The currency has been deleted." }

Taxes

A tax entity allows you to maintain details of a tax.(Not supported for US Version)

Example

{ "tax_id": "16367000000086009", "tax_name": "Vat", "tax_percentage": 7, "tax_type": "tax", "is_value_added": true, "tax_authority_id": "17455000000076047", "tax_authority_name": "Canada Revenue Agency", "tax_group_id": "27927000000681015", "tax_group_name": "Saviour group", "tax_group_percentage": 7 }

Attribute

tax_id
long
Unique ID for tax generated by the server. This is used as an identifier.
tax_name
string
Name of the tax.
tax_percentage
double
Tax percentage.
tax_type
string
Type of tax. Possible values are tax or compound_tax or tax_group.
is_value_added
Canada Edition Only
boolean
Whether it is a value added tax. It can either be true or false.
tax_authority_id
Canada Edition Only
long
Unique Id of the Tax Agency.
tax_authority_name
Canada Edition Only
string
Name of the Tax Agency.
tax_group_id
long
Unique ID for tax group generated by the server. This is used as an identifier.
tax_group_name
string
Name of the tax group.
tax_group_percentage
double
Total percentage of the tax group.

Create a tax

Create a tax.

POST /settings/taxes

Request Example

  
$ curl https://expense.zoho.com/api/v1/settings/taxes -X POST -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "tax_name": "Vat", "tax_percentage": 7, "tax_type": "tax", "is_value_added": true, "tax_authority_name": "Canada Revenue Agency" }'

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The tax has been created.", "tax": { "tax_id": "16367000000086009", "tax_name": "Vat", "tax_percentage": 7, "tax_type": "tax", "is_value_added": true, "tax_authority_id": "17455000000076047", "tax_authority_name": "Canada Revenue Agency" } }

ARGUMENTS

tax_name
Required
Name of the tax.
tax_percentage
Required
Tax percentage.
tax_type
Optional
Type of tax. Possible values are tax or compound_tax or tax_group.
is_value_added
Canada Edition Only
Optional
Whether it is a value added tax. It can either be true or false.
tax_authority_name
Canada Edition Only
Required
Name of the Tax Agency.

Retrieve list of taxes

Details of all existing taxes.

GET /settings/taxes

Request Example

  
$ curl https://expense.zoho.com/api/v1/settings/taxes -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "taxes": [ { "tax_id": "16367000000086009", "tax_name": "Vat", "tax_percentage": 7, "tax_type": "tax", "is_value_added": true, "tax_authority_id": "17455000000076047", "tax_authority_name": "Canada Revenue Agency" }, {...}, {...} ] }

Retrieve details of a tax

Details of an existing tax.

GET /settings/taxes/{tax_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/settings/taxes/{tax_id} -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "tax": { "tax_id": "16367000000086009", "tax_name": "Vat", "tax_percentage": 7, "tax_type": "tax", "is_value_added": true } }

Retrieve details of a tax group

Details of an existing tax group.

GET /settings/taxgroups/{tax_group_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/settings/taxgroups/{tax_group_id} -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "tax_group": { "tax_group_id": "27927000000681015", "tax_group_name": "Saviour group", "tax_group_percentage": 7, "taxes": [ { "tax_id": "16367000000086009", "tax_name": "Vat", "tax_percentage": 7, "tax_type": "tax" } ] } }

Update details of a tax

Update the details of an existing tax.

PUT /settings/taxes/{tax_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/settings/taxes/{tax_id} -X PUT -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5" -d JSONString='{ "tax_name": "Vat", "tax_percentage": 7, "tax_type": "tax", "is_value_added": true }'

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The tax details has been updated.", "tax": { "tax_id": "16367000000086009", "tax_name": "Vat", "tax_percentage": 7, "tax_type": "tax", "is_value_added": true } }

ARGUMENTS

tax_name
Optional
Name of the tax.
tax_percentage
Optional
Tax percentage.
tax_type
Optional
Type of tax. Possible values are tax or compound_tax or tax_group.
is_value_added
Canada Edition Only
Optional
Whether it is a value added tax. It can either be true or false.

Delete a tax

Delete an existing tax.

DELETE /settings/taxes/{tax_id}

Request Example

  
$ curl https://expense.zoho.com/api/v1/settings/taxes/{tax_id} -X DELETE -H "Content-Type: application/json;charset=UTF-8" -H "X-com-zoho-expense-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken ba4604e8e433g9c892e360d53463oec5"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The tax has been deleted." }