Get Records APIs
A record is an entity that stores all the combined information of a particular contact or company, which is acquired from various sources. The information may be acquired from a web-form, social media services, advertisements, etc. The records API allows the user to get, create, update, delete, or search records.
Purpose
To get the list of available records from a module.
Request URL
https://recruit.zoho.com/recruit/v2/{module_api_name}
To get a specific record;
https://recruit.zoho.com/recruit/v2/{module_api_name}/{record_id}
module_api_name - The API name of the module
record_id - The unique Id of the record
Request Method
GET
Scope
scope=ZohoRECRUIT.modules.all
(or)
scope=ZohoRECRUIT.modules.{module_name}.{operation_type}
| Possible module names | Possible operation types |
|---|---|
| candidate, application, jobopening, interview, client, contact, review, department, task, event, vendor, campaign, submission and custommodule | ALL - Full access to the record READ - Get records from the module |
Parameters
| Parameter Name | Data Type | Description | Possible Values |
|---|---|---|---|
| fields (optional) | String | To list all the module records with respect to fields | Multiple field API names, comma-separated. For example Last_Name, Email |
| sort_order (optional) | String | To sort the available list of records in either ascending or descending order | asc - ascending order desc - descending order |
| sort_by (optional) | String | To sort the available list of records based on the given field | Field API name Example: Email |
| converted (optional) | String | To get the list of converted records. The default value is false | true - get only converted records false - get only non-converted records both - get all records |
| approved (optional) | String | To get the list of approved records. The default value is true. | true - get only approved records false - get only records that are not approved both - get all records |
| page (optional) | Integer | To get the list of records from the respective pages. The default value for the page is 1. | Positive Integer values only |
| per_page (optional) | Integer | To get the list of records available per page. The default value for the page is 200. | Positive Integer values only |
| cvid (optional) | Integer | To get the list of records based on custom views | {custom_view_id} |
| territory_id (optional) | Integer | To get the list of records based on the territory | {territory_id} |
| include_child (optional) | Boolean | To include records from the child territories. True includes child territory records. False does not include child territory records. The default value is false. | true (or) false |
| $state (optional) | String | If the value of this parameter is 'draft', then the response will only contain Draft records from the specified module. If the parameter's value is 'save', then the response will return saved records from the specified module. If this parameter is not included in your request body, then the response will only return saved records from the specified module. | draft (or) save |
Note:
- sort_order applies to the given sort_by field.
- If the sort_by field is not provided, then it applies to the system-defined field.
- The page and per_page parameter is used to fetch records according to their position in Recruit. Let's assume that the user has to fetch 400 records. The maximum number of records that one can get for an API call is 200. So, for records above the 200th position, they cannot be fetched. By using the page (1, 2, 3, and 4) and the per_page (100) parameter, the user can fetch all 400 records using 4 API calls.
Request Headers
| Header Name | Data Type | Description | Example |
|---|---|---|---|
| If-Modified-Since (optional) | DateTime (ISO 8601 format) | To get the list of recently modified records | 2019-07-25T15:26:49+05:30 |
Note:
- While retrieving multiple records, subform records are not retrieved. Only the records count in a subform is retrieved.
- To get the record details in a subform, you need to fetch the specific record information in a module.
- To get the list of territories enabled for your organization.
- Only admin users can fetch the records from the Notes module. The system throws an error when non-admin users try to fetch the records from the Notes module.
Possible Errors
| HTTP Status | Error Code | Message | Reason |
|---|---|---|---|
| 400 | INVALID_MODULE | The module name given seems to be invalid | Invalid module name or no tab permission, or the module could have been removed from the organized module |
| 400 | INVALID_MODULE | The given module is not supported in API | The modules such as Documents and Projects are not supported in the current API. (This error will not be shown, once these modules are supported.) |
| 400 | INVALID_MODULE | The territory is not supported for the given module | The given module is not territory-supported |
| 403 | NOT_SUPPORTED | This API is supported only for admin users | Only admin users can fetch records from the Notes module. |
Sample Attributes
| Attribute | Sample |
|---|---|
| Single Line | "Single_Line_1": "This is single line", |
| Multi-Line | "Multi_Line_1": "This is the first line \n Now for the second Line", |
| "Email_1": "p.boyle@zylker.com", | |
| Phone | "Phone_1": "9900000000", |
| Picklist | "Picklist_1" : "In Progress", |
| Multi-Select Picklist | "Multi-Select_Picklist" : [ "Option_1", "Option_2", "Option_3" ], |
| Date | "Date_1": "2017-08-16", |
| Date/time | "Date_Time": "2017-08-16T14:32:23+05:30", Date_Time is in ISO8601 format and the time zone is the current user's time zone. |
| Number | "Number_1": 575, |
| Currency | "Currency_1": 250000, |
| Decimal | "Decimal_1": 250000.50, |
| Percent | ""Percent_1": 25, |
| Long Integer | "Long_Integer_1": "250000000000000", |
| Checkbox | "Checkbox_1": false, |
| URL | URL_1": "https://www.zoho.com/recruit", |
| Lookup | "Lookup" : { "name" : "James" "id" : "425248000000104001" }, |
| Record Owner | "Owner": { "name" : "Patricia" "id": "425248000000104003" }, |
| Layout | "Layout": { "name" : "Custom Layout 1" "id": "425248000000404433" }, |
| Auto number | "Auto_Number_1": "CANDIDATE44N", Where CANDIDATE - Prefix, 44 - Assignment Number, and N - Suffix. |
Sample Request
Copiedcurl "https://recruit.zoho.com/recruit/v2/Clients"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"Sample Response
Copied{
"data": [
{
"$currency_symbol": "Rs.",
"No_of_Contacts_Associated": "0",
"Shipping_State": null,
"Website": null,
"Account_Manager": {
"name": "Thomas Shelby",
"id": "486812000000216003"
},
"Source": null,
"Last_Activity_Time": "2019-11-13T17:06:38+05:30",
"Industry": null,
"Modified_By": {
"name": "Thomas Shelby",
"id": "486812000000216003"
},
"$process_flow": false,
"Exchange_Rate": null,
"Currency": null,
"Billing_Country": null,
"Client_Name": "Juice",
"Contact_Number": null,
"id": "486812000001224088",
"$approved": true,
"$approval": {
"delegate": false,
"approve": false,
"reject": false,
"resubmit": false
},
"Modified_Time": "2019-11-13T17:06:38+05:30",
"Billing_Street": null,
"Last_Mailed_Time": null,
"Created_Time": "2019-11-13T17:06:38+05:30",
"$followed": false,
"$editable": true,
"Billing_Code": null,
"Parent_Account": null,
"About": null,
"Associated_Tags": [],
"Shipping_City": null,
"Shipping_Country": null,
"Shipping_Code": null,
"Billing_City": null,
"Billing_State": null,
"Created_By": {
"name": "Thomas Shelby",
"id": "486812000000216003"
},
"Fax": null,
"Is_Attachment_Present": false,
"Shipping_Street": null
}
],
"info": {
"per_page": 200,
"count": 1,
"page": 1,
"more_records": false
}
}
