Leave API

Purpose

Add Leave API is used to add leave records, Get Leave Details API is to list down the available leave types and their details in your Zoho People account and Get Holidays API is used to fetch specific holidays of any of the employees using their employee Id, email Id, and record Id parameters.

Add Leave API

Purpose:

You can add leave records using the below API.

Note:

  • Refer API Reference page to view the list of Forms and their corresponding Field values. Admin has to log in to view the page.

Request URL:

https://people.zoho.com/people/api/leave/records?authtoken=<token>&xmlData=<xmlData>

Request Parameter

authtokenSpecify the authentication token
xmlDatasample input: <Request><Record><field name="Labelname">value</field><field name="LabelName1">value1</field><field name="Labelname2">value2</field></Record></Request><date name="Date1">day1_value</date><date name="Date2">day2_value</date>

Example URL

https://people.zoho.com/people/api/leave/records?authtoken=7d985878998943g4j09h43dd0b167dda34b &xmlData=<Request><Record><field name='Employee_ID'>3000000020481</field><field name='From'>26-Jan-2017</field><field name='To'>30-Jan-2017</field><field name='Leavetype'>3000000046003</field><days><date name='26-Jan-2017'>0.25</date></days></Record></Request>

Note: 0.25 denotes quarter day and 0.5 denotes half a day. 

Time should be mentioned in the format - hh:mm (Eg: 02:00 - which denotes 2 hours of leave for the day)

If the leave period includes quarter day(s)/half day(s), it should be mentioned inside the <days></days> tag. Full days need not be included in this tag. They will be automatically included. 

XML response:

<Response Status="1">
<message>Successfully Added</message>
</Response>

JSON response:

[{"message":"Successfully Added","Response":1}]

 

Form based API for Add Leave

Purpose :

To add leave records in JSON and XML formats.

XML request:

https://people.zoho.com/people/api/forms/xml/leave/insertRecord?authtoken=7d985878998943g4j09h43dd0b167dda34b&inputData=<Request><Record><field name='Employee_ID'>3000000020481</field><field name=‘From’>26-Jan-2017</field><field name=‘To’>30-Jan-2017</field><field name='Leavetype'>3000000046003</field><days><date name='26-Jan-2017'>0.25</date></days></Record></Request>

XML response:

<Response Status="1">
<message>Successfully Added</message>
</Response>

JSON request(Date-based)

https://people.zoho.com/people/api/forms/json/leave/insertRecord?authtoken=7d985878998943g4j09h43dd0b167dda34b&inputData={‘Employee_ID':'3000000020481','Leavetype':'3000000046003','From’:26-Jan-2017,'To’:’30-Jan-2017’,’days’:{’26-Jan-2017' : ‘0.25’}}

JSON request(Day-based)

https://people.zoho.com/people/api/forms/json/leave/insertRecord?authtoken=7d985878998943g4j09h43dd0b167dda34b&inputData={‘Employee_ID':'3000000020481','Leavetype':'3000000046003','From’:26-Jan-2017,'To’:’30-Jan-2017’, 'days':{'26-Jan-2017' : '02:00'}

JSON response:

{"response":{"result":{"pkId":"3000000248001","message":"Successfully Added"},"message":"Data added successfully","uri":"/api/forms/json/leave/insertRecord","status":0}}

Get leave types API

Purpose:

You can get leave types of a specific employee using the below API.

Request URL:

https://people.zoho.com/people/api/leave/getLeaveTypeDetails?authtoken=<token>&userId=<userId>

Request Parameter

authtokenSpecify the authentication token
userIdEmployee Id/Employee MailId/Record Id of the Employee

Example URL

https://people.zoho.com/people/api/leave/getLeaveTypeDetails?authtoken=9c69640f94ebb37f50ca148734b2c5e4&userId=1

https://people.zoho.com/people/api/leave/getLeaveTypeDetails?authtoken=9c69640f94ebb37f50ca148734b2c5e4&userId=charless@zohocorp.com

https://people.zoho.com/people/api/leave/getLeaveTypeDetails?authtoken=9c69640f94ebb37f50ca148734b2c5e4&userId=3000000020481

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/leave/getLeaveTypeDetails">
<status>0</status>
<message>Data fetched successfully</message>
<result>
<LeaveType>
<Name>DayBased</Name>
<PermittedCount>90.0</PermittedCount>
<AvailedCount>0.0</AvailedCount>
<Id>3000000030001</Id>
<Unit>Days</Unit>
<BalanceCount>90.0</BalanceCount>
</LeaveType>
<LeaveType>
<Name>Emp based</Name>
<PermittedCount>60.0</PermittedCount>
<AvailedCount>0.0</AvailedCount>
<Id>3000000099013</Id>
<Unit>Days</Unit>
<BalanceCount>60.0</BalanceCount>
</LeaveType>
<LeaveType>
<Name>HalfDayBased</Name>
<PermittedCount>70.0</PermittedCount>
<AvailedCount>0.0</AvailedCount>
<Id>3000000046003</Id>
<Unit>Days</Unit>
<BalanceCount>70.0</BalanceCount>
</LeaveType>
<LeaveType>
<Name>Hour based</Name>
<PermittedCount>20.0</PermittedCount>
<AvailedCount>0.0</AvailedCount>
<Id>3000000046007</Id>
<Unit>Hours</Unit>
<BalanceCount>20.0</BalanceCount>
</LeaveType>
</result>
</response>

JSON response:

{ "response":
"message": "Data fetched successfully",
"result": [
{ "Name": "DayBased",
"PermittedCount": 90,
"AvailedCount": 0,
"Id": 3000000030001,
"Unit": "Days",
"BalanceCount": 90
}, { "Name": "Emp based",
"PermittedCount": 60,
"AvailedCount": 0,
"Id": 3000000099013,
"Unit": "Days",
"BalanceCount": 60
}, { "Name": "HalfDayBased",
"PermittedCount": 70,
"AvailedCount": 0,
"Id": 3000000046003,
"Unit": "Days",
"BalanceCount": 70
}, { "Name": "Hour based",
"PermittedCount": 20,
"AvailedCount": 0,
"Id": 3000000046007,
"Unit": "Hours",
"BalanceCount": 20
} ], "status": 0,
"uri": "/api/leave/getLeaveTypeDetails"
} }

 

Get Holidays API

Purpose:

This API is used to fetch specific holidays of any of the employees using their employee Id, email Id and record Id parameters.

Request URL:

https://people.zoho.com/people/api/leave/getHolidays?authtoken=<token>&userId=<userId>

Request Parameter

authtokenSpecify the authentication token
userIdEmployee Id/Employee MailId/Record Id of the Employee

Example URL

https://people.zoho.com/people/api/leave/getHolidays?authtoken=9c69640f94ebb37f50ca148734b2c5e4&userId=2

https://people.zoho.com/people/api/leave/getHolidays?authtoken=9c69640f94ebb37f50ca148734b2c5e4&userId=karenjohn@zykler.com

https://people.zoho.com/people/api/leave/getHolidays?authtoken=9c69640f94ebb37f50ca148734b2c5e4&userId=3000000011693

XML response:

<?xml version="1.0" encoding="UTF-8"?> <response uri="/api/leave/getHolidays"> <status>0</status> <message>Data fetched successfully</message> <result> <Holiday> <Name>Test</Name> <Remarks></Remarks> <Id>3000000065001</Id> </Holiday> <Holiday> <Name>Tokyo</Name> <LocationId>3000000237009;3000000237010;3000000237011</LocationId> <LocationName>Tokyo;Chennai;New York</LocationName> <Remarks></Remarks> <Id>3000000237021</Id> </Holiday> </result> </response>

JSON response:

{ "response": { "message": "Data fetched successfully", "result": [ { "Name": "Test", "LocationId": "",LocationName": "", "Remarks": "", "Id": 3000000065001 }, { "Name": "Tokyo", "LocationId": "3000000237009;3000000237010;3000000237011", "LocationName": "Tokyo;Chennai;New York" "Remarks": "", "Id": 3000000237021 } ], "status": 0, "uri": "/api/leave/getHolidays" } }

Fetch single leave record API

Purpose:

This API will fetch the record of Leave form indexed using a Record ID.

Request URL:

https://people.zoho.com/people/api/forms/leave/getDataByID?authtoken=c0c8e90f5d36a160ba2ghjdcf30cdb&recordId=413124000068132003

Request Parameters:

authtokenSpecify the authentication token
recordIdSpecifies the record Id of the leave record being fetched. The record Id can be identified using the fetch Records API.

Example URL

https://people.zoho.com/people/api/forms/leave/getDataByID?authtoken=c0c8e90f5d36a160ba2ghjdcf30cdb&recordId=413124000068132003

XML response:

<?xml version="1.0" encoding="UTF-8"?><br>
<response uri="/api/forms/leave/getDataByID">
<status>0</status>
<message>Data fetched successfully</message>
<result>
<field name="Employee_ID">Karan John 1</field>
<DayDetails name="DayDetails">
<date name="07-Mar-2020">
<detail name="LeaveCount">0.5</detail>
<detail name="Session">1</detail>
</date>
<date name="04-Mar-2020">
<detail name="LeaveCount">1</detail>
</date>
<date name="06-Mar-2020">
<detail name="LeaveCount">0.25</detail>
<detail name="Session">1</detail>
</date>
<date name="08-Mar-2020">
<detail name="LeaveCount">0.5</detail>
<detail name="Session">1</detail>
</date>
<date name="09-Mar-2020">
<detail name="LeaveCount">0.5</detail>
<detail name="Session">2</detail>
</date>
<date name="05-Mar-2020">
<detail name="LeaveCount">0.5</detail>
<detail name="Session">1</detail>
</date>
</DayDetails>
<field name="Leavetype.ID">413124000000645719</field>
<field name="From">04-Mar-2020</field>
<field name="Unit">Day</field>
<field name="ApprovalStatus">Pending</field>
<field name="Reasonforleave">Vacation</field>
<field name="Daystaken">2.25</field>
<field name="TeamEmailID">teamemail@gmail.com</field>
<field name="Department">HR</field>
<field name="Leavetype">Annual leave</field>
<field name="To">09-Mar-2020</field>
<field name="Department.ID">413124000000117067</field>
<field name="Employee_ID.ID">413124007800117005</field>
<field name="DateOfRequest">14-Aug-2019</field>
</result>
</response>

JSON response:

{
"response": {
"result": [
{
"Employee_ID": "Karan John 1",
"DayDetails": {
"07-Mar-2020": {
"LeaveCount": "0.5",
"Session": 1
},
"04-Mar-2020": {
"LeaveCount": "1"
},
"06-Mar-2020": {
"LeaveCount": "0.25",
"Session": 1
},
"08-Mar-2020": {
"LeaveCount": "0.5",
"Session": 1
},
"09-Mar-2020": {
"LeaveCount": "0.5",
"Session": 2
},
"05-Mar-2020": {
"LeaveCount": "0.5",
"Session": 1
}
},
"Leavetype.ID": "413124000000645719",
"From": "04-Mar-2020",
"Unit": "Day",
"ApprovalStatus": "Pending",
"Reasonforleave": "Vacation",
"Daystaken": "2.25",
"TeamEmailID": "teamemail@gmail.com",
"Department": "HR",
"Leavetype": "Annual leave",
"To": "09-Mar-2020",
"Department.ID": "413124680000117005",
"Employee_ID.ID": "413124000780117005",
"DateOfRequest": "14-Aug-2019",
}
],
"message": "Data fetched successfully",
"uri": "/api/forms/leave/getDataByID",
"status": 0
}
}

Response field details

Response fieldResponseExplanation
LeaveCount1One day leave
 .50Half day leave
 .25Quarter day leave
 01:00One hour leave
Session ( in .5 day leave)1First half of the day
 2Second half of the day
Session (.25 day leave)1First quarter of the day 
 2Second quarter of the day
 3Third quarter of the day
 4Fourth quarter of the day
StartTime (in hour based leave) Start time of the leave in HH:mm format
EndTime (in hour based leave) End time of the leave in HH:mm format

Note:

  • Daydetails for day based leave includes the date, leaveCount and Session details of all the dates within the applied leave's date range.
  • Daydetails for hour based leave includes the date, leaveCount, StartTime and EndTime of all the hours within the applied leave's date range.

 

Error codes

Please refer Error codes.