Zoho People

HR software. Read and update employee and other form records, apply for and cancel leave, check leave balances and holidays, and post announcements.

Actions

Action	What it does
Add a record	Add a record to any form, for example a Department or a custom form, from field values keyed by label name.
Add an employee	Add an employee.
Apply for leave	Apply for whole days of leave for an employee.
Cancel a leave request	Cancel a leave request.
Count records	Count the records in a form.
Get a leave request	Get one leave request: its dates, leave type, employee and approval status.
Get a record	Get one record of a form by its id, with every field.
Get an employee's leave summary	Get the leave types that apply to an employee, with how much of each is taken and available.
Get form fields	Get a form's fields: each one's label name (the key to use when adding or updating), type, whether it is mandatory, and the choice ids of lookup fields.
Get organization details	Get the organization's name, contact details, address, time zone and date format.
Get the leave balance report	Get booked leave and balances per employee and leave type for a period, up to 30 employees a page.
List announcements	List the organization's announcements, ten a page, newest first.
List forms	List the organization's forms (Employee, Department, custom forms and so on) with the link name used to address each.
List holidays	List the organization's holidays, optionally between two dates or for chosen locations.
List leave requests	List leave requests between two dates, optionally for chosen employees, leave types or approval status.
List records	List a form's records, optionally only one employee's (by Employee ID or email) or only those changed since a time.
Post an announcement	Post an announcement to the organization's feed.
Search records	Find a form's records where a field matches a condition, for example Employeestatus is Active.
Update a record	Change fields of a record in any form.

Add a record

Add a record to any form, for example a Department or a custom form, from field values keyed by label name.

Inputs

Formform_link_nametextRequired: The form, for example Employee or Department. Pick it from the list or type its link name (formLinkName from 'List forms').
FieldsfieldsobjectRequired: Field values keyed by the field's label name from 'Get form fields' (for example FirstName). For a lookup or pick-list field, send the choice's id. Dates are written in your organization's date format.
Save as draftis_drafttrue/false: Optional. Save the record as a draft instead of submitting it.Default: false.

Outputs

The record that was saved.

messagetext: Zoho's confirmation message.
record_idtext: The record's id (Zoho's pkId).

Example output

{
  "message": "Successfully Added",
  "record_id": "412762000000222222"
}

Add an employee

Add an employee. By default Zoho emails them an invitation and the profile stays inactive until they accept; choose 'Without a login' to add a profile that cannot sign in and gets no email.

Inputs

Employee IDemployee_idtextRequired: Your organization's Employee ID for them, for example EMP042.
First namefirst_nametextRequired: First name.
Last namelast_nametextRequired: Last name.
EmailemailtextRequired: Their email address.
Other fieldsother_fieldsobject: Optional. More Employee form fields keyed by label name from 'Get form fields' (for example Dateofjoining).
Without a loginwithout_logintrue/false: Optional. Add them as a profile that cannot sign in, and send no invitation.Default: false.

Outputs

The record that was saved.

messagetext: Zoho's confirmation message.
record_idtext: The record's id (Zoho's pkId).

Example output

{
  "message": "Successfully Added",
  "record_id": "412762000000123456"
}

Apply for leave

Apply for whole days of leave for an employee. It then follows the organization's approval process.

Inputs

EmployeeemployeetextRequired: The employee's Zoho id (record_id from 'List records' on the Employee form), email address, or Employee ID.
Leave typeleave_type_idtextRequired: The leave type. The list shows the employee's leave types once their Zoho id is entered.
Fromfrom_datedateRequired: The first day.
Toto_datedateRequired: The last day.
Reasonreasontext: Optional. Why the leave is needed.

Outputs

The leave request that was changed.

leave_idtext: The leave request's id.
messagetext: Zoho's confirmation message.

Example output

{
  "leave_id": "412762000000456789",
  "message": "Record(s) added successfully."
}

Cancel a leave request

Cancel a leave request.

Inputs

Leave request IDleave_idtextRequired: The leave request's id, from 'List leave requests' or 'Apply for leave'.
Reasonreasontext: Optional. Why it is cancelled.

Outputs

The leave request that was changed.

leave_idtext: The leave request's id.
messagetext: Zoho's confirmation message.

Example output

{
  "leave_id": "412762000000456789",
  "message": "Record(s) cancelled successfully."
}

Count records

Count the records in a form.

Inputs

Formform_link_nametextRequired: The form, for example Employee or Department. Pick it from the list or type its link name (formLinkName from 'List forms').

Outputs

How many records a form holds.

countnumber: The number of records.
form_link_nametext: The form's link name.

Example output

{
  "count": 42,
  "form_link_name": "employee"
}

Get a leave request

Get one leave request: its dates, leave type, employee and approval status.

Inputs

Leave request IDleave_idtextRequired: The leave request's id, from 'List leave requests' or 'Apply for leave'.

Outputs

A leave request.

approval_statustext: Approved, pending, rejected, cancelled and so on.
created_timetext: When it was created.
date_of_requesttext: When it was requested.
daysobject: Per day: the leave count and times.
employeeobject: The employee.
from_datetext: The first day, in the organization's date format.
leave_idtext: The leave request's id.
leave_typeobject: The leave type.
modified_timetext: When it was last modified.
to_datetext: The last day, in the organization's date format.

Example output

{
  "approval_status": "PENDING",
  "date_of_request": "30-Sep-2026",
  "days": {
    "07-Oct-2026": {
      "leave_count": 1
    }
  },
  "employee": {
    "avatar": "",
    "id": "EMP001",
    "name": "Ada Lovelace",
    "zoho_id": "412762000000123456"
  },
  "from_date": "07-Oct-2026",
  "leave_id": "412762000000456789",
  "leave_type": {
    "id": "412762000000011111",
    "name": "Casual Leave",
    "type": "PAID",
    "unit": "Days"
  },
  "to_date": "07-Oct-2026"
}

Get a record

Get one record of a form by its id, with every field.

Inputs

Formform_link_nametextRequired: The form, for example Employee or Department. Pick it from the list or type its link name (formLinkName from 'List forms').
Record IDrecord_idtextRequired: The record's id: record_id from 'List records' or 'Search records', or a Zoho People address that contains it.

Outputs

A record. Its fields are the form's own, keyed by label name.

AddedTimetext: When the record was added.
Dateofjoiningtext: Date of joining (employee form).
EmailIDtext: Email address (employee form).
EmployeeIDtext: The employee's Employee ID (employee form).
Employeestatustext: Employee status (employee form).
FirstNametext: First name (employee form).
LastNametext: Last name (employee form).
ModifiedTimetext: When the record was last modified.
Roletext: Role (employee form).
Zoho_IDtext: The record's Zoho id.
record_idtext: The record's id.

Example output

{
  "AddedTime": "01-Mar-2026 09:00:00",
  "EmailID": "ada@example.com",
  "EmployeeID": "EMP001",
  "Employeestatus": "Active",
  "FirstName": "Ada",
  "LastName": "Lovelace",
  "ModifiedTime": "02-Mar-2026 10:00:00",
  "Zoho_ID": "412762000000123456",
  "record_id": "412762000000123456"
}

Get an employee's leave summary

Get the leave types that apply to an employee, with how much of each is taken and available.

Inputs

Employee's Zoho idemployee_zoho_idtextRequired: The employee's Zoho id: record_id from 'List records' on the Employee form.
As ofto_datedate: Optional. Count up to this day; the end of the leave year by default.

Outputs

An employee's leave types with what is taken and available.

countnumber: How many leave types were returned.
employee_idtext: The employee's Employee ID.
employee_nametext: The employee's name.
employee_zoho_idtext: The employee's Zoho id.
leave_typeslist: The leave types.

Example output

{
  "count": 1,
  "employee_id": "EMP001",
  "employee_name": "Ada Lovelace",
  "employee_zoho_id": "412762000000123456",
  "leave_types": [
    {
      "available": 10,
      "color": "#3fbd54",
      "leave_type_id": "412762000000011111",
      "name": "Casual Leave",
      "taken": 2,
      "type": "Paid",
      "unit": "Day"
    }
  ]
}

Get form fields

Get a form's fields: each one's label name (the key to use when adding or updating), type, whether it is mandatory, and the choice ids of lookup fields.

Inputs

Formform_link_nametextRequired: The form, for example Employee or Department. Pick it from the list or type its link name (formLinkName from 'List forms').

Outputs

The fields of a form.

countnumber: How many fields were returned (outside tabular sections).
fieldslist: The fields.
form_link_nametext: The form's link name.
tabular_sectionslist: The tabular sections.

Example output

{
  "count": 1,
  "fields": [
    {
      "comptype": "Text",
      "displayname": "First Name",
      "ismandatory": true,
      "labelname": "FirstName",
      "maxLength": 100
    }
  ],
  "form_link_name": "employee",
  "tabular_sections": []
}

Get organization details

Get the organization's name, contact details, address, time zone and date format. Needs a Zoho People administrator.

Inputs

None.

Outputs

The Zoho People organization.

Addressobject: The organization's address.
Companytext: The organization's name.
ContactMailIdtext: The contact email address.
ContactNumbertext: The contact phone number.
ContactPersontext: The contact person.
DateFormattext: How dates are written, for example dd-MMM-yyyy.
TimeFormattext: How times are written.
TimeZonetext: The organization's time zone.
Websitetext: The organization's website.

Example output

{
  "Address": {
    "City": "London",
    "Country": "United Kingdom"
  },
  "Company": "Lodol Demo",
  "ContactMailId": "hr@example.com",
  "ContactNumber": "",
  "ContactPerson": "Ada Lovelace",
  "DateFormat": "dd-MMM-yyyy",
  "TimeFormat": "hh:mm a",
  "TimeZone": "Europe/London",
  "Website": "https://example.com"
}

Get the leave balance report

Get booked leave and balances per employee and leave type for a period, up to 30 employees a page.

Inputs

Fromfrom_datedateRequired: The first day.
Toto_datedateRequired: The last day.
Unitunittext: Optional. Count in days or hours; days by default.One of: Day (Days), Hour (Hours).
Employeesemployee_idslist: Optional. Zoho ids of up to 30 employees to include.
Leave typesleave_type_idslist: Optional. Ids of leave types to include (leave_type_id from 'Get an employee's leave summary').
Employee statusemployee_statuseslist: Optional. Only employees with these statuses.One or more of: ACTIVE_USERS (Active users), ACTIVE_EMPLOYEE_PROFILES (Active employee profiles), EX_EMPLOYEES (Former employees), LOGIN_DISABLED (Login disabled).
Start atstart_indexnumber: Optional. The position of the first employee, from 0.At least 0.
Page sizelimitnumber: Optional. How many employees, 1 to 30 (default 30).From 1 to 30.

Outputs

Booked and balance per employee and leave type.

countnumber: How many employee rows were returned.
employeeslist: The employee rows.
leave_typeslist: The leave types.

Example output

{
  "count": 1,
  "employees": [
    {
      "balances": [
        {
          "balance": 10,
          "booked": 2,
          "leave_type_id": "412762000000011111",
          "name": "Casual Leave"
        }
      ],
      "employee_id": "EMP001",
      "employee_zoho_id": "412762000000123456",
      "name": "Ada Lovelace",
      "totals": {
        "paidBalance": 10,
        "paidBooked": 2
      }
    }
  ],
  "leave_types": [
    {
      "code": "CL",
      "leave_type_id": "412762000000011111",
      "name": "Casual Leave",
      "type": "Paid",
      "unit": "Day"
    }
  ]
}

List announcements

List the organization's announcements, ten a page, newest first.

Inputs

Start atstart_indexnumber: Optional. The position of the first announcement, from 1.At least 1.
Pinned onlypinned_onlytrue/false: Optional. Only pinned announcements.Default: false.
Searchsearchtext: Optional. Only announcements containing this text.

Outputs

One page (ten) of announcements.

announcementslist: The announcements.
countnumber: How many are on this page.
has_nexttrue/false: Whether another page follows.

Example output

{
  "announcements": [
    {
      "announcementId": "412762000000777777",
      "emailList": "",
      "isActive": true,
      "isCommentDisable": false,
      "isNotify": false,
      "isSticky": false,
      "messageText": "The office is closed this Friday.",
      "notifyOthersEmailIds": "",
      "owner": "Ada Lovelace",
      "publishDate": "1790000000000",
      "subject": "Office closed Friday"
    }
  ],
  "count": 1,
  "has_next": false
}

List forms

List the organization's forms (Employee, Department, custom forms and so on) with the link name used to address each.

Inputs

None.

Outputs

The organization's forms.

countnumber: How many forms were returned.
formslist: The forms.

Example output

{
  "count": 1,
  "forms": [
    {
      "componentId": "412762000000035001",
      "displayName": "Employee",
      "formLinkName": "employee",
      "isVisible": true,
      "iscustom": false
    }
  ]
}

List holidays

List the organization's holidays, optionally between two dates or for chosen locations.

Inputs

Fromfrom_datedate: Optional. The first day.
Toto_datedate: Optional. The last day.
Locationslocation_idslist: Optional. Ids of locations whose holidays to list.
Shiftsshift_idslist: Optional. Ids of shifts whose holidays to list.
Holiday classificationsclassification_idslist: Optional. Ids of holiday classifications to include.
Start atoffsetnumber: Optional. The position of the first result to return, from 1.At least 1.
Page sizelimitnumber: Optional. How many to return, 1 to 200.From 1 to 200.

Outputs

Holidays in the date range.

countnumber: How many were returned.
holidayslist: The holidays.

Example output

{
  "count": 1,
  "holidays": [
    {
      "from_date": "01-Jan-2027",
      "holiday_id": "412762000000333333",
      "holiday_name": "New Year's Day",
      "is_restricted_holiday": false,
      "to_date": "01-Jan-2027"
    }
  ]
}

List leave requests

List leave requests between two dates, optionally for chosen employees, leave types or approval status.

Inputs

Fromfrom_datedateRequired: The first day.
Toto_datedateRequired: The last day.
Employeesemployee_idslist: Optional. Zoho ids of employees to include (record_id from 'List records' on the Employee form).
Leave typesleave_type_idslist: Optional. Ids of leave types to include (leave_type_id from 'Get an employee's leave summary').
Kind of leaveleave_kindslist: Optional. Only these kinds of leave.One or more of: PAID, UNPAID, ON_DUTY (On duty), RESTRICTED_HOLIDAY (Restricted holiday), COMPENSATORY_OFF (Compensatory off).
Employee statusemployee_statuseslist: Optional. Only employees with these statuses.One or more of: ACTIVE_USERS (Active users), ACTIVE_EMPLOYEE_PROFILES (Active employee profiles), EX_EMPLOYEES (Former employees), LOGIN_DISABLED (Login disabled).
Approval statusapproval_statustext: Optional. Only requests in this state; all by default.One of: ALL, APPROVED, PENDING, REJECTED, CANCELLED, CANCEL_PENDING (Cancellation pending).
Whose requestsdata_selecttext: Optional. Whose requests to include; everyone's by default.One of: ALL (Everyone), MINE, SUBORDINATES (My reportees), DIRECT_SUBORDINATES (My direct reportees), MINE,SUBORDINATES (Mine and my reportees).
Sort bysorttext: Optional. The order of the results.One of: from_date (Start date, oldest first), -from_date (Start date, newest first), to_date (End date, oldest first), -to_date (End date, newest first), employee (Employee, A-Z), -employee (Employee, Z-A), leave_type (Leave type, A-Z), -leave_type (Leave type, Z-A).
Start atoffsetnumber: Optional. The position of the first result to return, from 1.At least 1.
Page sizelimitnumber: Optional. How many to return, 1 to 200.From 1 to 200.

Outputs

Leave requests in the date range.

countnumber: How many were returned.
leave_requestslist: The leave requests.

Example output

{
  "count": 1,
  "leave_requests": [
    {
      "approval_status": "PENDING",
      "date_of_request": "30-Sep-2026",
      "days": {
        "07-Oct-2026": {
          "leave_count": 1
        }
      },
      "employee": {
        "avatar": "",
        "id": "EMP001",
        "name": "Ada Lovelace",
        "zoho_id": "412762000000123456"
      },
      "from_date": "07-Oct-2026",
      "leave_id": "412762000000456789",
      "leave_type": {
        "id": "412762000000011111",
        "name": "Casual Leave",
        "type": "PAID",
        "unit": "Days"
      },
      "to_date": "07-Oct-2026"
    }
  ]
}

List records

List a form's records, optionally only one employee's (by Employee ID or email) or only those changed since a time.

Inputs

Formform_link_nametextRequired: The form, for example Employee or Department. Pick it from the list or type its link name (formLinkName from 'List forms').
Find employee bysearch_columntext: Optional. Look up one employee by this column.One of: EMPLOYEEID (Employee ID), EMPLOYEEMAILALIAS (Email address).
Employee ID or emailsearch_valuetext: Optional. The value to look for in the chosen column.
Changed sincemodified_sincedate and time: Optional. Only records added or changed after this.
Start atstart_indexnumber: Optional. The position of the first record to return, from 1.At least 1.
Page sizelimitnumber: Optional. How many records to return, 1 to 200 (default 200).From 1 to 200.

Outputs

One page of records.

countnumber: How many records are on this page.
has_moretrue/false: Whether this page was full, so another may follow.
recordslist: The records.

Example output

{
  "count": 1,
  "has_more": false,
  "records": [
    {
      "AddedTime": "01-Mar-2026 09:00:00",
      "EmailID": "ada@example.com",
      "EmployeeID": "EMP001",
      "Employeestatus": "Active",
      "FirstName": "Ada",
      "LastName": "Lovelace",
      "ModifiedTime": "02-Mar-2026 10:00:00",
      "Zoho_ID": "412762000000123456",
      "record_id": "412762000000123456"
    }
  ]
}

Post an announcement

Post an announcement to the organization's feed.

Inputs

SubjectsubjecttextRequired: The subject.
MessagemessagetextRequired: The announcement.
Notify everyonenotifytrue/false: Optional. Also email it to the organization.Default: false.
Also emailnotify_emailslist: Optional. Other email addresses to send it to.
Pin itpinnedtrue/false: Optional. Keep it at the top of the feed.Default: false.
Turn off commentsdisable_commentstrue/false: Optional. Stop people commenting on it.Default: false.

Outputs

An announcement.

announcementIdtext: The announcement's id.
emailListtext: Addresses notified.
empNametext: The poster's name.
expireDatetext: When it expires.
isActivetrue/false: Whether it is active.
isCommentDisabletrue/false: Whether comments are turned off.
isNotifytrue/false: Whether people were notified.
isStickytrue/false: Whether it is pinned.
messagetext: The message (list).
messageTexttext: The message (when posted).
modifiedTimetext: When it was last modified.
notifyOthersEmailIdstext: Other addresses notified.
ownertext: Who posted it.
publishDatetext: When it was published (milliseconds since 1970).
subjecttext: The subject.

Example output

{
  "announcementId": "412762000000777777",
  "emailList": "",
  "isActive": true,
  "isCommentDisable": false,
  "isNotify": false,
  "isSticky": false,
  "messageText": "The office is closed this Friday.",
  "notifyOthersEmailIds": "",
  "owner": "Ada Lovelace",
  "publishDate": "1790000000000",
  "subject": "Office closed Friday"
}

Search records

Find a form's records where a field matches a condition, for example Employeestatus is Active.

Inputs

Formform_link_nametextRequired: The form, for example Employee or Department. Pick it from the list or type its link name (formLinkName from 'List forms').
Fieldsearch_fieldtextRequired: The field's label name, from 'Get form fields'.
Conditionsearch_operatortext: Optional. How to compare; Contains by default.One of: Is, Is_Not (Is not), Contains, Not_Contains (Not contains), Starts_With (Starts with), Ends_With (Ends with), Like, Is_Empty (Is empty), Is_Not_Empty (Is not empty), True, and 33 more.
Valuesearch_texttext: The value to compare with. Not needed for conditions such as Is empty or Today. For Between, separate the two values with a semicolon.
Start atstart_indexnumber: Optional. The position of the first record to return, from 1.At least 1.
Page sizelimitnumber: Optional. How many records to return, 1 to 200 (default 200).From 1 to 200.

Outputs

One page of records.

countnumber: How many records are on this page.
has_moretrue/false: Whether this page was full, so another may follow.
recordslist: The records.

Example output

{
  "count": 1,
  "has_more": false,
  "records": [
    {
      "AddedTime": "01-Mar-2026 09:00:00",
      "EmailID": "ada@example.com",
      "EmployeeID": "EMP001",
      "Employeestatus": "Active",
      "FirstName": "Ada",
      "LastName": "Lovelace",
      "ModifiedTime": "02-Mar-2026 10:00:00",
      "Zoho_ID": "412762000000123456",
      "record_id": "412762000000123456"
    }
  ]
}

Update a record

Change fields of a record in any form. Only the fields given are changed.

Inputs

Formform_link_nametextRequired: The form, for example Employee or Department. Pick it from the list or type its link name (formLinkName from 'List forms').
Record IDrecord_idtextRequired: The record's id: record_id from 'List records' or 'Search records', or a Zoho People address that contains it.
FieldsfieldsobjectRequired: Field values keyed by the field's label name from 'Get form fields' (for example FirstName). For a lookup or pick-list field, send the choice's id. Dates are written in your organization's date format.
Save as draftis_drafttrue/false: Optional. Save the record as a draft instead of submitting it.Default: false.

Outputs

The record that was saved.

messagetext: Zoho's confirmation message.
record_idtext: The record's id (Zoho's pkId).

Example output

{
  "message": "Successfully Updated",
  "record_id": "412762000000123456"
}

ActionsCopy Anchor Link

Add a recordCopy Anchor Link

Inputs

Outputs

Add an employeeCopy Anchor Link

Inputs

Outputs

Apply for leaveCopy Anchor Link

Inputs

Outputs

Cancel a leave requestCopy Anchor Link

Inputs

Outputs

Count recordsCopy Anchor Link

Inputs

Outputs

Get a leave requestCopy Anchor Link

Inputs

Outputs

Get a recordCopy Anchor Link

Inputs

Outputs

Get an employee's leave summaryCopy Anchor Link

Inputs

Outputs

Get form fieldsCopy Anchor Link

Inputs

Outputs

Get organization detailsCopy Anchor Link

Inputs

Outputs

Get the leave balance reportCopy Anchor Link

Inputs

Outputs

List announcementsCopy Anchor Link

Inputs

Outputs

List formsCopy Anchor Link

Inputs

Outputs

List holidaysCopy Anchor Link

Inputs

Outputs

List leave requestsCopy Anchor Link

Inputs

Outputs

List recordsCopy Anchor Link

Inputs

Outputs

Post an announcementCopy Anchor Link

Inputs

Outputs

Search recordsCopy Anchor Link

Inputs

Outputs

Update a recordCopy Anchor Link

Inputs

Outputs

On this page

Actions

Add a record

Add an employee

Apply for leave

Cancel a leave request

Count records

Get a leave request

Get a record

Get an employee's leave summary

Get form fields

Get organization details

Get the leave balance report

List announcements

List forms

List holidays

List leave requests

List records

Post an announcement

Search records

Update a record