Fetch Record API

Purpose

This API is used to fetch all the records of a form based on view name as well as you can get records based on predefined columns.

Request URL

https://people.zoho.com/people/api/forms/<viewname>/records?authtoken=<token>&sIndex=<sIndex>&rec_limit=<rec_limit>

https://people.zoho.com/people/api/forms/<viewname>/records?authtoken=<token>&searchColumn=<searchColumn>&searchValue=<searchValue>

Request Parameters

authtokenSpecify the authentication token
viewNameTo get the view name, use 'views' API.
sIndexStarting Index
rec_limitNumber of records to be fetched
searchColumnSearch any column like EMPLOYEEID, EMPLOYEEMAILALIAS etc
searchValueSearch any value like EmployeeId of the employee or Employee MailId
 

Example

Request URL:

https://people.zoho.com/people/api/forms/P_EmployeeView/records?authtoken=9c69640f94ebb37f50ca148734b2c5e4

https://people.zoho.com/people/api/forms/P_EmployeeView/records?authtoken=9c69640f94ebb37f50ca148734b2c5e4&searchColumn=EMPLOYEEMAILALIAS&searchValue=charless@zykler.com

XML response:

<Records>
<Record>
<field name="recordId">
173907000000228001</field>
<field name="Photo">
&lt;img class=&quot;ptB10&quot; src=&quot;/people/images/user.png&quot;&gt;</field>
<field name="EmployeeID">
335</field>
<field name="Reporting To">
</field>
<field name="First Name">
non</field>
<field name="Last Name">
user</field>
<field name="Email ID">
</field>
<field name="Nick Name">
</field>
<field name="Department">
</field>
<field name="Title">
</field>

<field name="Employee Role">
Team member</field>
<field name="Date of joining">

19-Nov-2016</field>

<field name="Work location">
</field>
<field name="Work phone">
</field>
<field name="Extension">
</field>
<field name="Other Email">
</field>
<field name="Birth Date">
</field>
<field name="Mobile Phone">
</field>
<field name="Address">
</field>
<field name="Tags">
</field>
<field name="Job Description">
</field>
<field name="Ask me about/Expertise">
</field> <field name="AbouMe"></field> <field name="Employee Type">
</field> <field name="Employee Status">
Active</field>
<field name="Source of Hire">
</field>
<field name="Marital Status">
</field>
<field name="Offer Letter">
</field>
<field name="ID Proof">
</field>
</Record>
<Record>

JSON response:

[ { "recordId": 173907000000181100,
"Date of joining": "",
"Employee Role": "Team member",
"Work phone": "",
"AbouMe": "",
"EmployeeID": "123",
"Extension": "",
"Nick Name": "",
"ID Proof": "",
"Department": "",
"Work location": "",
"createdTime": 1351588396243,
"modifiedTime": 1351588396243,
"Job Description": "",
"Employee Type": "",
"Mobile Phone": "",
"Photo": "",
"Title": "",
"Marital Status": "",
"Tags": "",
"Source of Hire": "",
"Offer Letter": "",
"Birth Date": "", "Address": "", "Reporting To": "", "Ask me about/Expertise": "", "Employee Status": "Active",
"Other Email": "",
"Email ID": "",
"Last Name": "",
"First Name": "dummy123" },
{ "recordId": 173907000000111000,
"Date of joining": "19-Nov-2016",
"Employee Role": "Team member",
"Work phone": "",
"AbouMe": "",
"EmployeeID": "HRM3",
"Extension": "",
"Nick Name": "",
"ID Proof": "" } ]

Fetch Single Record API

Purpose:

This API will display the record of a specific form indexed using a Record ID.

Request URL:

https://people.zoho.com/people/api/forms/department/getDataByID?authtoken=55edc91c2412037e6c9e14416b200a0d&recordId=261091000000049003

Note:

Request Parameters:

authtokenSpecify the authentication token
formLinkNameTo get formLinkName, you can use Fetch Forms API.
recordIdSpecifies the record Id of the record being fetched. The record Id can be identified using the fetch Records API.

Example URL

https://people.zoho.com/people/api/forms/department/getDataByID?authtoken=55edc91c2412037e6c9e14416b200a0d&recordId=261091000000049003

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/forms/department/getDataByID">
<status>0</status>
<message>Data fetched successfully</message>
<result>
<field name="Parent_Department.ID">177402000000969127</field>
<field name="Department_Lead">Karan John 1</field>
<field name="Department_Lead.ID">177402000000034203</field>
<field name="Email_1">test@g.com</field>
<field name="Parent_Department">Product Support</field>
<field name="Single_Line_2">test1</field>
<field name="Department">Chat Support</field>
<field name="MailAlias">chatsupport@example.com</field>
</result>
</response>

JSON response:

{
"response": {
"message": "Data fetched successfully",
"result": [
{ "Parent_Department.ID": 177402000000969127,
"Department_Lead": "Karan John 1",
"Department_Lead.ID": 177402000000034203,
"Email_1": "test@g.com",
"Parent_Department": "Product Support",
"Department": "Chat Support",
"Single_Line_2": "test1",
"MailAlias": "chatsupport@example.com"
}
], "status": 0,
"uri": "/api/forms/department/getDataByID"
} }

Fetch Single Record API by Section-Wise

Purpose:

This API will fetch all the record of a specific form indexed using a Record ID by section-wise.

Request URL:

https://people.zoho.com/people/api/forms/<formLinkName>/getRecordByID?authtoken=<token>&recordId=<recordId>

Note:

Request Parameters:

authtokenSpecify the authentication token
formLinkNameTo get formLinkName, you can use Fetch Forms API.
recordIdSpecifies the record Id of the record being fetched. The record Id can be identified using the fetch Records API.

Example URL

https://people.zoho.com/people/api/forms/department/getRecordByID?authtoken=7d985878998943g4j09h43dd0b167dda34b&recordId=6000000043063

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/forms/department/getRecordByID">
<status>0</status>
<message>Data fetched successfully</message>
<result>
<section name="Department Details">
<field name="Parent_Department.ID">177402000000969127</field>
<field name="Department_Lead">Karan John 1</field>
<field name="Department_Lead.ID">177402000000034203</field>
<field name="Parent_Department">Product Support</field>
<field name="Department">Chat Support</field>
<field name="MailAlias">chatsupport@example.com</field>
</section>
<section name="Dept members">
<field name="Email_1">test@g.com</field>
<field name="Single_Line_2">test1</field>
</section>
</result>
</response>

JSON response:

{ "response": {
"message": "Data fetched successfully",
"result": [
{ "Departtment members": {
"Email_1": "test@g.com",
"Single_Line_2": "test1"
},
"Department Details": {
"Parent_Department.ID": 177402000000969127,
"Department_Lead": "Karan John 1",
"Department_Lead.ID": 177402000000034203,
"Parent_Department": "Product Support",
"Department": "Chat Support",
"MailAlias": "chatsupport@example.com"
} }
], "status":
"uri": "/api/forms/department/getRecordByID"
}
}

Get Related Records API

Purpose:

This API will retrieve records based on lookup Record ID.

Request URL:

https://people.zoho.com/people/api/forms/<formLinkName>/getRelatedRecords?authtoken=<token>&sIndex=<sIndex>&limit=<limit>& parentModule=<parentModule>&id=<id>&lookupfieldName=<lookupfieldName>

Note:

  • Refer API Reference page to view the list of forms. Admin has to log in to view the page.
  • If lookupfieldName is not given, primary lookup of the form will be taken as input.

Request Parameters:

authtokenSpecify the authentication token
formLinkNameTo get formLinkName, you can use Fetch Forms API.
sIndexStarting index
limitNumber of records to be fetched
parentModuleRelated records to the parent module will be fetched
idGet related records based on record id
lookupfieldNameRecords will be retrieved related to this lookup field

Example URL

https://people.zoho.com/people/api/forms/employee/getRelatedRecords?authtoken=9c69640f94ebb37f50ca148734b2c5e4&parentModule=department&id=3000000032001

XML response:

<?xml version="1.0" encoding="UTF-8"?> <response uri="/api/forms/employee/getRelatedRecords">
<status>
0</status>
<message>
Data fetched successfully</message>
<result>
<3000000020481>
<tabularSections>
<section name="Education">
<row count="0">
<field name="Yearofgraduation">
2013</field>
<field name="Education_AdditionalNotes"></field> <field name="Degree">B.Tech</field>
<field name="Specialization">CSE</field> <field name="Interests">
</field>
<field name="College">
IIT</field>
</row>
</section>
<section name="Dependent">
<row count="0">
<field name="Name">
Abhi</field>
<field name="DependentDOB">
19-Sep-1997</field>
<field name="DependentRelationship">
Brother</field>
</row>
<row count="1">
<field name="Name">fatima</field>
<field name="DependentDOB">15-Oct-1989</field> <field name="DependentRelationship">
Sister</field>
</row>
</section>
</tabularSections>
<section name="Work">
<field name="Extension">
</field>
<field name="Work_location">
</field>
<field name="Role.ID">3000000015529</field>
<field name="Work_phone">
</field>
<field name="Role">
Admin</field>
<field name="Department">
People</field>
<field name="Employeestatus">
Active</field>
<field name="Department.ID">
3000000032001</field>
</section>
<section name="Basic Info">
<field name="Nick_Name">
</field>
<field name="EmployeeID">12</field> <field name="Decision_box_1">false</field> <field name="FirstName">
charless</field>
<field name="LastName">
charless@zohocorp.com</field>
</section> <section name="Summary">
<field name="Current_Job_Description">
</field>
<field name="Expertise">
</field>
<field name="Weddingday">
12-Oct-1985</field>
<field name="AboutMe">
</field>
</section>
<section name="Personal">
<field name="Tags">
</field>
<field name="Date_of_birth">04-Oct-1991</field>
<field name="Address">
</field>
<field name="Other_Email">
</field>
<field name="Mobile"></field> </section>
</3000000020481>
<3000000020509>
<tabularSections>
<section name="Education">
</section> <section name="Dependent">
</section> </tabularSections>
<section name="Work">
<field name="Reporting_To.ID">
3000000020481</field>
<field name="Extension"></field> <field name="Work_location">
</field>
<field name="Role.ID">
3000000015533</field>
<field name="Work_phone">
</field>
<field name="Role">
Team member</field>
<field name="Department">
People</field>
<field name="Employeestatus">
Active</field>
<field name="Reporting_To">charless charless 12</field>
<field name="Department.ID">3000000032001</field>
</section>
<section name="Basic Info">
<field name="Nick_Name">
</field>
<field name="EmployeeID">
2</field>
<field name="Decision_box_1">true</field>
<field name="FirstName">
charless</field> <field name="LastName">
charless.sp+sham_tst</field> <field name="EmailID">
charless@zohocorp.com</field>
</section>
<section name="Summary">
<field name="Current_Job_Description">
</field>
<field name="Expertise">
</field>
<field name="AboutMe">
</field>
</section> <section name="Personal">
<field name="Tags">
</field>
<field name="Date_of_birth">
11-Sep-1987</field> <field name="Address">
</field>
<field name="Other_Email">
</field>
<field name="Mobile"></field> </section>
</3000000020509> </result>
</response>

JSON response:

{"response":{"message":"Data fetched successfully","result":[{"tabularSections":{},"Department Details":{"Department_Lead":"charless charless 1","Parent_Department":"","Department":"People","MailAlias":"charless@zohocopr.com}}],"status":0,"uri":"/api/forms/department/getRecordByID"}}{
"response": {
"message": "Data fetched successfully",
"result": [
{ "3000000020481": [
{ "tabularSections": {
"Education": [
{ "Yearofgraduation": "2013",
"Education_AdditionalNotes": "",
"Degree": "B.Tech",
"Specialization": "CSE",
"Interests": "",
"College": "IIT"
} ], "Dependent": [
{ "Name": "Abhi",
"DependentDOB": "19-Sep-1997",
"DependentRelationship": "Brother"
}, { "Name": "fatima",
"DependentDOB": "15-Oct-1989",
"DependentRelationship": "Sister"
} ] }, "Basic Info": {
"EmployeeID": "12",
"Nick_Name": "",
"Decision_box_1": "false",
"FirstName": "charless",
"LastName": "charless",
"EmailID": "charless@zohocorp.com"
}, "Work": {
"Extension": "",
"Work_location": "",
"Role.ID": 3000000015529,
"Work_phone": "",
"Role": "Admin",
"Department": "People",
"Department.ID": 3000000032001,
"Employeestatus": "Active"
}, "Personal": {
"Tags": "",
"Date_of_birth": "04-Oct-1991",
"Address": "",
"Mobile": "",
"Other_Email": ""
}, "Summary": {
"Current_Job_Description": "",
"Expertise": "",
"Weddingday": "12-Oct-1985",
"AboutMe": ""
} } ] }, { "3000000020509": [
{ "tabularSections": {
"Education": [],
"Dependent": []
}, "Basic Info": {
"EmployeeID": "2",
"Nick_Name": "",
"Decision_box_1": "true",
"FirstName": "charless",
"LastName": "charless",
"EmailID":
"charless@zohocorp.com"
}, "Work": {
"Reporting_To.ID": 3000000020481,
"Extension": "",
"Work_location": "",
"Role.ID": 3000000015533,
"Work_phone": "",
"Role": "Team member",
"Department": "People",
"Department.ID": 3000000032001,
"Reporting_To": "charless charless 12",
"Employeestatus": "Active"
}, "Personal": {
"Tags": "",
"Date_of_birth": "11-Sep-1987",
"Address": "",
"Mobile": "",
"Other_Email": ""
}, "Summary": {
"Current_Job_Description": "",
"Expertise": "",
"AboutMe": ""
} } ] } ], "status": 0,
"uri": "/api/forms/employee/getRelatedRecords"
} }

Get Records based on Form name API

Purpose:

This API is used to fetch all the records of a form based on the form name as well as based on pre-defined columns.

Request URL:

https://people.zoho.com/people/api/forms/<formLinkName>/getRecords?authtoken=<token>&sIndex=<sIndex>&limit=<limit>

https://people.zoho.com/people/api/forms/<formLinkName>/getRecords?authtoken=<token>&searchColumn=<searchColumn>&searchValue=<searchValue>

Note:

Request Parameters:

authtokenSpecify the authentication token
formLinkNameTo get formLinkName, you can use Fetch Forms API.
sIndexStarting index
limitNumber of records to be fetched
searchColumnSearch any column like EMPLOYEEID or EMPLOYEEMAILALIAS
searchValueSeach any value like EmployeeId of the employee or Employee MailId

Example URL

https://people.zoho.com/people/api/forms/employee/getRecords?authtoken=9c69640f94ebb37f50ca148734b2c5e4

https://people.zoho.com/people/api/forms/employee/getRecords?authtoken=9c69640f94ebb37f50ca148734b2c5e4&searchColumn=EMPLOYEEID&searchValue=2

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/forms/employee/getRecords">
<status>0</status>
<message>Data fetched successfully</message>
<result>
<177402000000034203>
<field name="Role.ID">177402000000029631</field>
<field name="PAN_number"></field>
<field name="Bloodgroup">O +ve</field>
<field name="LastName">John</field>
<field name="Extension">1234</field>
<field name="LocationName">India</field>
<field name="Mobile">6547657454</field>
<field name="Work_phone"></field>
<field name="Passportexpirydate">2015/09/23</field>
<field name="Personal_Email"></field>
<field name="Skype_iD2"></field>
<field name="Marital_status">Single</field>
<field name="Expertise">Responsible for assisting java software engineer in designing and developing Java-based systems Handle the tasks of writing codes by following appropriate design patterns Perform responsibilities of maintaining and developing code under configuration control Handle the tasks of implementing the module in java ensuring compatibility in tools and interfaces with support from senior java software engineer</field>
<field name="Photo">{fileName=}</field>
<field name="Reporting_To"></field>
<field name="Nick_Name">Kare</field>
<field name="Tags">HR</field>
<field name="Gender"></field>
<field name="Designation.ID">177402000000969033</field>
<field name="Contract_Start_Date">2013/09/01</field>
<field name="Designation">HR Head</field>
<field name="Pan_Card"></field>
<field name="Visanumber"></field>
<field name="Date_of_birth">1986/01/23</field>
<field name="Eligible_for_rehire"></field>
<field name="LocationName.ID">177402000000053013</field>
<field name="Department.ID">177402000000969057</field>

JSON response:

{ "response": {
"message": "Data fetched successfully",
"result": [
{ "177402000000034203": [
{ "Role.ID": 177402000000029631,
"PAN_number": "",
"Bloodgroup": "O +ve",
"LastName": "John",
"Extension": "1234",
"LocationName": "India",
"Mobile": "6547657454",
"Work_phone": "",
"Passportexpirydate": "2015/09/23",
"Personal_Email": "",
"Skype_iD2": "",
"Marital_status": "Single",
"Expertise": "Responsible for assisting java software engineer in designing and developing Java-based systems\\\n\\\nHandle the tasks of writing codes by following appropriate design patterns\\\n\\\nPerform responsibilities of maintaining and developing code under configuration control\\\n\\\nHandle the tasks of implementing the module in java ensuring compatibility in tools and interfaces with support from senior java software engineer", "Photo": "{fileName=}",
"Reporting_To": "",
"Nick_Name": "Kare",
"Tags": "HR",
"Gender": "",
"Designation.ID": 177402000000969033,
"Contract_Start_Date": "2013/09/01",
"Pan_Card": "",
"Designation": "HR Head",
"Visanumber": "",
"Date_of_birth": "1986/01/23",
"Eligible_for_rehire": "",
"LocationName.ID": 177402000000053013,
"Department.ID": 177402000000969057 }

Note:

  • Lookup values of a record contains field name as key and their lookup id's key is fieldname.ID.

Search Records based on record values 

Purpose:

This API is used to fetch all the records of a form based on the record values.

Request URL:

https://people.zoho.com/people/api/forms/<formLinkName>/getRecords?authtoken=****&searchParams={searchField: '<fieldLabelName>', searchOperator: '<operator>', searchText : '<textValue>'}

Note:

  • Refer API Reference page to view the list of forms. Admin has to log in to view the page.

Request Parameters:

authtokenSpecify the authentication token
viewNameTo get the view name, use 'views' API.
sIndexStarting Index
rec_limitNumber of records to be fetched
searchFieldSearch any column using field label name
searchOperatorSearch any record using the operators (Eg- Is, Contains,)
searchTextSearch any text that belongs to the record 

Description:

The format to search through records is as follows:

searchParams : '|' separated JSONObjects with following keys and values

{

searchField : FieldName based on which search should be performed,

searchText : The value to be searched for,

searchOperator : Based on field type - True|False|Is|Is_Not|Is_Empty|Is_Not_Empty|Starts_With|Ends_With|Like|Contains|Not_Contains|Lesser_Than|Greater_Than|Lesser_than_or_equal_to|Before|Greater_than_or_equal_to|After|Between|Yesterday|Today|Tomorrow|Last_7_Days|Last_30_Days|Last_60_Days|Last_90_Days|Last_120_Days|Next_7_Days|Next_30_Days|Next_60_Days|Next_90_Days|Next_120_Days|Last_Month|This_Month|Next_Month|Current_and_Previous_Month|Current_and_Next_Month|Last_Year|This_Year|Next_Year|Last_2_Years|Next_2_Years|Current_and_Previous_Year|Current_and_Next_Year

searchCriteria : AND | OR

}

If no searchOperator is specified by default, we assume the search operation to be 'Contains' and similarly if no searchCriteria is specified, we assume it to be 'AND'. For operators like 'Between' which needs two search values to be specified, semi-colon separated values may be given.

Example URL

https://people.zoho.com/people/api/forms/employee/getRecords?authtoken=****&searchParams={searchField: 'Employeestatus', searchOperator: 'Is', searchText : 'Active'}

To search for records with two field values:

https://people.zoho.com/people/api/forms/employee/getRecords?authtoken=****&searchParams={searchField: 'Employeestatus', searchOperator: 'Contains', searchText : 'Active'}|{searchField: 'Role', searchOperator: 'Is', searchText: 'Team Member'}

To search between dates:

https://people.zoho.com/people/api/forms/employee/getRecords?authtoken=****&searchParams={searchField : 'Dateofjoining', searchOperator : 'Between', searchText : '18-Nov-2016;20-Nov-2016'}

XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response uri="/api/forms/employee/getRecords">
<status>0</status>
<message>Data fetched successfully</message>
<result>
<177402000000034203>
<field name="Role.ID">177402000000029631</field>
<field name="PAN_number"></field>
<field name="Bloodgroup">O +ve</field>
<field name="LastName">John</field>
<field name="Extension">1234</field>
<field name="LocationName">India</field>
<field name="Mobile">6547657454</field>
<field name="Work_phone"></field>
<field name="Passportexpirydate">2015/09/23</field>
<field name="Personal_Email"></field>
<field name="Skype_iD2"></field>
<field name="Marital_status">Single</field>
<field name="Expertise">Responsible for assisting java software engineer in designing and developing Java-based systems Handle the tasks of writing codes by following appropriate design patterns Perform responsibilities of maintaining and developing code under configuration control Handle the tasks of implementing the module in java ensuring compatibility in tools and interfaces with support from senior java software engineer</field>
<field name="Photo">{fileName=}</field>
<field name="Reporting_To"></field>
<field name="Nick_Name">Kare</field>
<field name="Tags">HR</field>
<field name="Gender"></field>
<field name="Designation.ID">177402000000969033</field>
<field name="Contract_Start_Date">2013/09/01</field>

<field name="Employeestatus">Active</field>

<field name="Employee Role">Team member</field>

<field name="Date of joining">19-Nov-2016</field>

<field name="Designation">HR Head</field>

<field name="Pan_Card"></field>
<field name="Visanumber"></field>
<field name="Date_of_birth">1986/01/23</field>
<field name="Eligible_for_rehire"></field>
<field name="LocationName.ID">177402000000053013</field>
<field name="Department.ID">177402000000969057</field>

JSON response:

{ "response": {
"message": "Data fetched successfully",
"result": [
{ "177402000000034203": [
{ "Role.ID": 177402000000029631,
"PAN_number": "",
"Bloodgroup": "O +ve",
"LastName": "John",
"Extension": "1234",
"LocationName": "India",
"Mobile": "6547657454",
"Work_phone": "",
"Passportexpirydate": "2015/09/23",
"Personal_Email": "",
"Skype_iD2": "",
"Marital_status": "Single",
"Expertise": "Responsible for assisting java software engineer in designing and developing Java-based systems\\\n\\\nHandle the tasks of writing codes by following appropriate design patterns\\\n\\\nPerform responsibilities of maintaining and developing code under configuration control\\\n\\\nHandle the tasks of implementing the module in java ensuring compatibility in tools and interfaces with support from senior java software engineer", "Photo": "{fileName=}",
"Reporting_To": "",
"Nick_Name": "Kare",

"Employeestatus": "Active",

"Role": "Team member",

​"Dateofjoining": "01-Mar-2016",

"Tags": "HR",
"Gender": "",
"Designation.ID": 177402000000969033,
"Contract_Start_Date": "2013/09/01",
"Pan_Card": "",
"Designation": "HR Head",
"Visanumber": "",
"Date_of_birth": "1986/01/23",
"Eligible_for_rehire": "",
"LocationName.ID": 177402000000053013,
"Department.ID": 177402000000969057 }

Note:

  • Lookup values of a record contains field name as key and their lookup id's key is fieldname.ID.

 

Error codes

Please refer Error codes.