Choose where you’d like to start

Get Records from Zoho People

Overview

The zoho.people.getRecords task is used to fetch records from the specified Zoho People form.

Syntax

<response> = zoho.people.getRecords(<form_name>, [<from_index>] ,[<count>], [<search_criteria>], [<connection>]);

where:

ParamsData typeDescription

<response> 

KEY-VALUE

The details of the records fetched from Zoho People.

<form_name>

TEXT

The label name of the form from which the records need to be fetched.

Note: Click here for the instructions to get the form names in Zoho People.

<from_index>

(optional)

NUMBER

The index number of the first record that needs to be fetched.

Note:
  • The index number begins with 1.
  • Default value: 1

<count>

(optional)

NUMBER

The total number of records that need to be fetched.

Note:
  • The maximum number of records that can be fetched is 200.
  • Default value: 20

<search_value> 

(optional)

KEY-VALUE/ LIST

The search condition that needs to be satisfied.

Note:
  • To specify this param, you must first specify the <from_index> and <count> params.
  • Click here to learn about the keys and values that can be supplied to this parameter.

<connection>

(optional)*

TEXT

The name of the connection.

Note: This param is not applicable to Zoho Creator and mandatory in Zoho Cliq.

Example 1: Fetch all the records from Zoho People

The following script fetches all the records from the form - Department in Zoho People:

response = zoho.people.getRecords("P_Department");

where:

"P_Department"
The TEXT that represents the label name of the form from which the records need to be fetched.

Example 2: Fetch all the records that fall within a range

The following script fetches the first 50 records from the form - Employee for which the value of the field - Dateofjoining is between 01-Mar-2018 and 01-Mar-2019:

//Create a map to hold the search condition 
searchMap = Map(); 
searchMap.put("searchField", "Dateofjoining"); 
searchMap.put("searchOperator", "Between"); 
searchMap.put("searchText", "01-Mar-2018;01-Mar-2019"); 
 
//Execute the get records task to fetch the search result 
response = zoho.people.getRecords("P_Employee", 0, 50, searchMap); 

where:

response
The KEY-VALUE variable that holds the details of the records fetched from Zoho People.
"P_Employee"
The TEXT that represents the Zoho People form from which the records need to be fetched.
0
The NUMBER that represents the index number of the first record that needs to be fetched.
50
The NUMBER that represents the total number of records that need to be fetched.
searchMap 
The KEY-VALUE variable that holds the search condition.
"searchField" 
"searchOperator" 
"searchText"
The TEXT that represents the keys as specified in Zoho People API.
Dateofjoining 
The TEXT that represents the field link name.

Example 3: Fetch records that satisfy criteria

The following script fetches the list of employees whose experience is more than 5 years or role is manager and work location is Texas:

//Create map to hold search condition 1 
searchMap1 = Map(); 
searchMap1.put("searchField", "Experience"); 
searchMap1.put("searchOperator", "Greater_than_or_equal_to"); 
searchMap1.put("searchText", "5"); 
 
//Create map to hold search condition 2 
searchMap2 = Map(); 
searchMap2.put("searchField", "Role"); 
searchMap2.put("searchOperator", "Contains"); 
searchMap2.put("searchText", "Manager"); 
searchMap2.put("searchCriteria", "OR"); 
 
//Create map to hold search condition 3 
searchMap3 = Map(); 
searchMap3.put("searchField", "LocationName"); 
searchMap3.put("searchOperator", "Contains"); 
searchMap3.put("searchText", "Texas"); 
searchMap3.put("searchCriteria", "AND"); 
 
//Create list to hold all the search conditions 
searchList = List(); 
searchList.add(searchMap1); 
searchList.add(searchMap2); 
searchList.add(searchMap3); 
 
//Execute the get records task to fetch the search result 
response = zoho.people.getRecords("P_Employee", 0, 200, searchList); 

where:

searchList
The LIST variable that holds the list of all search conditions.
searchMap1 
searchMap2 
searchMap3
The KEY-VALUE variables that hold the individual search conditions.
 
What is searchCriteria key and how does it work?

If the records are searched with multiple conditions, the <search_value> param is supplied with a LIST of KEY-VALUE data. Each KEY-VALUE data holds an individual condition whose keys and values are supplied according to the Zoho People API. Among the keys that you can supply, the searchCriteria key decides the logical operation to be applied between the conditions. 

Applicable values for searchCriteria key:

  • AND
  • OR
Default value: AND 

The logical operator supplied to the searchCriteria key is applied on the current and the previous conditions (KEY-VALUE data) in the order they are added to the LIST. Hence, the searchCriteria will be applied in the following order:

((<condition_in_map_1><searchCriteria_in_map_2><condition_in_map_2>)<searchCriteria_in_map_3><condition_in_map_3>)...

In Example 3, the searchCriteria will be executed in the following order:

  • The searchCriteria specified in searchMap2 ("OR") will be applied between searchMap2 and searchMap1
  • The searchCriteria specified in searchMap3 ("AND") will be applied between searchMap3 and, the result of the "OR" operation performed between searchMap2 and searchMap1.

Response Format

Success Response

  • The success response will be returned in the following format:
    {  
       "Current_Job_Description":"",
       "EmailID":"richard@zylker.com",
       "CreatedTime":"1500373226190",
       "Address":"",
       "Date_of_birth":"",
       "Dateofexit":"",
       "Photo":"https://contacts.zoho.com/file?ID=-1&fs=thumb",
       "Marital_status":"",
       "Gender":"",
       "Other_Email":"",
       "ApprovalStatus":"Approval Not Enabled",
       "Work_location":"",
       "LocationName":"",
       "Department":"",
       "Nick_Name":"",
       "ModifiedTime":"1500373226190",
       "Reporting_To.MailID":"",
       "Zoho_ID":"4163000000170001",
       "LocationName.ID":"",
       "Designation.ID":"",
       "tabularSections":"{\"Education\":[{\"Specialization\":\"\",\"Education_AdditionalNotes\":\"\",\"Degree\":\"\",\"College\":\"\",\"Yearofgraduation\":\"\",\"Interests\":\"\"}],\"Work experience\":[{\"Jobtitle\":\"\",\"Employer\":\"\",\"Previous_JobDesc\":\"\",\"FromDate\":\"\",\"Todate\":\"\"}],\"Dependent\":[{\"DependentDOB\":\"\",\"Name\":\"\",\"DependentRelationship\":\"\"}]}",
       "Source_of_hire":"",
       "Tags":"",
       "Reporting_To":"",
       "Photo_downloadUrl":"https://contacts.zoho.com/file?ID=-1&fs=thumb",
       "Designation":"",
       "FirstName":"Richard",
       "Dateofjoining":"",
       "AboutMe":"",
       "Mobile":"",
       "Employeestatus":"Inactive",
       "Extension":"",
       "Role":"Team member",
       "Employee_type":"",
       "Reporting_To.ID":"",
       "Work_phone":"",
       "Role.ID":"4163000000019635",
       "LastName":"Patrick",
       "Department.ID":"",
       "EmployeeID":"12311",
       "Expertise":""
    },
    {  
       "Current_Job_Description":"",
       "EmailID":"peter@zylker.com",
       "CreatedTime":"1497694216150",
       "Address":"",
       "Date_of_birth":"",
       "Dateofexit":"",
       "Photo":"https://contacts.zoho.com/file?ID=-1&fs=thumb",
       "Marital_status":"",
       "Gender":"",
       "Other_Email":"",
       "ApprovalStatus":"Approval Not Enabled",
       "Work_location":"",
       "LocationName":"",
       "Department":"",
       "Nick_Name":"",
       "ModifiedTime":"1497694241328",
       "Reporting_To.MailID":"",
       "Zoho_ID":"4163000000165017",
       "LocationName.ID":"",
       "Designation.ID":"",
       "tabularSections":"{\"Education\":[{\"Specialization\":\"\",\"Education_AdditionalNotes\":\"\",\"Degree\":\"\",\"College\":\"\",\"Yearofgraduation\":\"\",\"Interests\":\"\"}],\"Work experience\":[{\"Jobtitle\":\"\",\"Employer\":\"\",\"Previous_JobDesc\":\"\",\"FromDate\":\"\",\"Todate\":\"\"}],\"Dependent\":[{\"DependentDOB\":\"\",\"Name\":\"\",\"DependentRelationship\":\"\"}]}",
       "Source_of_hire":"",
       "Tags":"",
       "Reporting_To":"",
       "Photo_downloadUrl":"https://contacts.zoho.com/file?ID=-1&fs=thumb",
       "Designation":"",
       "FirstName":"Peter",
       "Dateofjoining":"",
       "AboutMe":"",
       "Mobile":"",
       "Employeestatus":"Inactive",
       "Extension":"",
       "Role":"Team member",
       "Employee_type":"",
       "Reporting_To.ID":"",
       "Work_phone":"",
       "Role.ID":"4163000000019635",
       "LastName":"Balaji",
       "Department.ID":"",
       "EmployeeID":"000001110",
       "Expertise":""
    }
   

To fetch all the record IDs from the success response obtained, execute the following script:

 for each var in <response_variable>
 {
 info var.get("Zoho_ID");
 }
   

Failure Response

  • The failure response for incorrect or non-existent form name will be returned in the following format:
    {  
       "message":"Form name 'csc' is invalid",
       "code":7011
    }

Related Links

Get Started Now

Execute