Insert Records

Purpose

To add new entities to a module.

Request URL

https://recruit.zoho.com/recruit/v2/{module_api_name}

module_api_name - The API name of the module

Supported Modules
Candidates, Applications, Job Openings, Interviews, Clients, Contacts, Departments, Tasks, Events, Vendors, and Custom Modules.

Note:

To insert a single record, send only one JSON object in the input with the necessary keys and values.

Request Method

POST

Scope

scope=ZohoRECRUIT.modules.all
(or)
scope=ZohoRECRUIT.modules.{module_name}.{operation_type}

Possible module namesPossible operation types
candidate, application, jobopening, interview, client, contact, department, task, event, vendor, and custommoduleALL - Full access to the record
WRITE - Edit records in the module
CREATE - Create records in the module

Note:

  • An error is thrown if the field value length is more than the maximum length defined for that field.
  • If an API is used inside a Function and the field value length exceeds the limit, then that function receives an error response from the API. For example: If the max length for a "Text field" is defined as 10, then the value given for it in API cannot be "12345678901", as it has 11 characters.
  • Duplicates are checked for every insert record API call based on unique fields.
  • A maximum of 100 records can be inserted per API call.
  • The trigger input can be workflow, approval, or blueprint. If "trigger" is not mentioned, the workflows, approvals, and blueprints related to the API will get executed. Enter the trigger value as [] to not execute the workflows.
  • $approved key is used to set the records to be created in approval mode. It is mostly used for candidates and contacts procured from web forms.
  • To insert the record as a draft, pass the following information along with the record's JSON details.

    JSON Key Name

    Data Type

    Description

    Possible Values

    $state
    (optional)

    String

    If the value of this parameter is 'draft', then the record will be added as a draft record in the specified module. If the value of this parameter is 'save', then the record will be added as a normal record in the specified module. 

    If this parameter is not included in your request body, then the record will be added as a normal record in the specified module.

    draft (or) save

Sample Attributes

The following table gives you specific details about each field type in Zoho Recruit and their limitations.
JSON type - Tells in what format the field should be passed in request-body or will be received in response.
Data type - Tells the type of data that can be stored in the corresponding field-type. It is mentioned below each Attribute.

AttributeJSON TypeLimitationsSample
Single Line
Text
StringAccepts up to 255 characters.
Accepts alphanumeric and special characters.
"Last_Name": "Mike O'Leary",
Multi-Line
Textarea
StringSmall - accepts up to 2000 characters.
Large - accepts up to 32000 characters.
You will not be able to use this field to create custom views, reports, or other filters.
Accepts alphanumeric and special characters.
"Multi_Line_1": "This is the first line \n Now for the second Line",
Email
Email
StringAccepts valid email IDs."Email_1": "p.boyle@zylker.com",
Phone
Phone
StringAccepts up to 30 characters. This limit may vary based on the value configured in 'Number of characters allowed' in the properties pop-up of the field, in UI.
Accepts only numeric characters and '+' (to add extensions).
The regex pattern in Zoho Recruit to validate this field's value is "[0-9a-zA-Z!#;%\\*\\^\\(\\)=\\{\\}\\[\\]\\?`~_\\-\\.\\$@\\?\\,\\:\\'\\/\\!\\P{InBasicLatin}\\|\\\\\\s\\+]+"
"Phone_1": "9900000000",
Picklist
Picklist
StringYou can either pass an existing picklist value or add a new one.
The picklist value accepts all alphanumeric and special characters.
"Industry": "automobile"
Multi-Select Picklist
Multi-select Picklist
JSON arrayYou can either pass existing picklist values or add a new one.
The picklist value accepts all alphanumeric and special characters.
"Courses_Opted": [
"Analytics",
"Big data"
],
Date
Date in ISO 8601 format
StringAccepts date in yyyy-MM-dd format"Date_1": "2017-08-16",
Date/time
DateTime in ISO 8601 format
StringAccepts date and time in yyyy-MM-ddTHH:mm:ss±HH:mm ISO 8601 format"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
Integer
IntegerAccepts numbers up to 9 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI.
Accepts only numeric values.
"No_of_Employees": 350,
Currency
Currency
DoubleBefore decimal point - accepts numbers up to 16 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI.
After decimal point - accepts precision up to 9 digits. This limit may vary based on the value configured in 'Number of decimal paces' in the properties pop-up of the field, in UI.
Accepts only numeric values.
"Annual_Revenue": 250000.90,
Decimal
Double
DoubleBefore decimal point - accepts numbers up to 16 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI.
After decimal point - accepts precision up to 9 digits. This limit may vary based on the value configured in 'Number of decimal places' in the properties pop-up of the field, in UI.
Accepts only numeric values.
"Decimal_1": 250000.50,
Percent
Double
DoubleAccepts numbers up to 5 digits.
Accepts only numeric values.
"Percentage": 25,
Long Integer
BigInt
StringAccepts numbers up to 18 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI.
Accepts only numeric values.
"EAN_Code":"0012345600012",
Checkbox
Boolean
BooleanAccepts only Boolean values(true,false)."Email_Opt_Out": true,
URL
Website
StringAccepts valid URLs. The regex pattern in Zoho Recruit to validate this field's value is "^(http:\\/\\/www.|https:\\/\\/www.|ftp:\\/\\/www.|www.|http:\\/\\/|https:\\/\\/|ftp:\\/\\/|){1}[^\\x00-\\x19\\x22-\\x27\\x2A-\\x2C\\x2E-\\x2F\\x3A-\\x40\\x5B-\\x5E\\x60\\x7B\\x7D-\\x7F]+(\\.[^\\x00-\\x19\\x22\\x24-\\x2C\\x2E-\\x2F\\x3C\\x3E\\x40\\x5B-\\x5E\\x60\\x7B\\x7D-\\x7F]+)+(\\/[^\\x00-\\x19\\x22\\x3C\\x3E\\x5E\\x7B\\x7D-\\x7D\\x7F]*)*$""URL": "https://www.zylker.com",
Lookup
Lookup
JSON objectAccepts valid name and unique ID of the record, which you can get through meta data API."Lookup" : {
"name" : "James",
"id" : "425248000000104001"
},
Multi-select lookup
Multi-Select Lookup
JSON arrayAccepts valid record names and unique IDs."Accounts":[
{
"Account_Name":"Zylker1",
"id":"4150868000000420069"
},
{
"Account_Name":"Zylker",
"id":"4150868000000420046"
}
]
User
User Lookup
JSON objectThis is a default look-up field to users in Zoho Recruit."User":
{
"name":"Patricia Boyle",
"id":"4150868000000623001"
}

Possible Errors

HTTP StatusError CodeMessageReason"Details" Key Values
400INVALID_MODULEThe module name given seems to be invalidInvalid module name or no tab permission, or the module could have been removed from the organized module---
400INVALID_MODULEThe given module is not supported in APIThe modules such as Documents and Projects are not supported in the current API. (This error will not be shown, once these modules are supported.)---
403NO_PERMISSIONpermission denied to create '{modulename}'No permission to insert records---
400MANDATORY_NOT_FOUNDRequired field not found.If the data key isn't available{
"api_name": "data"
}
400INVALID_DATAInvalid DataIf the data key has the invalid data type{ "expected_data_type":"jsonarray",
"api_name": "data"
},
202INVALID_DATA (at the record index)Invalid DataIf the record passed isn't a JSON object{
"expected_data_type":"jsonobject",
"index": 0
}
202MANDATORY_NOT_FOUNDRequired field not foundIf the mandatory fields are not available{
"api_name":"Last_Name"
}
202INVALID_DATAInvalid DataIf the data type is mismatched{
"expected_data_type":"double",
"api_name":"Decimal_1"
}

Sample Request

Copiedcurl "https://recruit.zoho.com/recruit/v2/Candidates"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-X POST

Sample Input - Candidates

Copied{
    "data": [{
        "Last_Name": "Christina",
        "First_Name": "Thomas",
        "Email": "Christhom@zmail.com",
        "Mobile": "555-555-5555",
        "City": "San Antonio"
    }]
}

Sample Input - Job Openings

Copied{
    "data": [{
        "Job_Opening_Name": "Software Engineer",
        "Number_of_Positions": "1",
        "Department_Name": {
            "id": "486812000001279230",
            "name": "My department"
        },
        "Assigned_Recruiter": "486812000001279007,486812000001460004,486812000001967077",
        "Target_Date": "2024-03-30",
        "Job_Opening_Status": "In-progress",
        "Job_Type": "Full time",
        "Required_Skills": "swift, mysql, rest apis",
        "Remote_Job": false
    }]
}

Sample Input - Clients

Copied{
    "data": [{
        "Client_Name": "Avon Group",
        "Billing_City": "Burbank",
        "Billing_State": "California",
        "Billing_Country": "USA",
        "Contact_Number": "7436947075",
        "Industry": "Television",
        "Source": "Meetup",
        "Website": "https://www.avongroup.com/about-us.html",
        "Territories": "T1"
    }]
}

Sample Input - Interviews

Copied{
    "data": [{
        "Client_Name": {
            "id": "486812000001693001",
            "name": "Avon Group"
        },
        "Candidate_Name": {
            "name": "Josh Fleck",
            "id": "486812000001389001"
        },
        "Location": "Burbank",
        "Interviewer": "486812000001410003",
        "Interview_Name": "Level 1 Interview",
        "Start_DateTime": "2024-11-12T11:00:00+03:00",
        "Reminder": "1 day before",
        "Job_Opening_Name": {
            "name": "Data Analyst",
            "id": "486812000001074022"
        },
        "End_DateTime": "2024-11-12T12:00:00+03:00"

    }]
}

Sample Response

Copied{
    "data": [{
        "code": "SUCCESS",
        "details": {
            "Modified_Time": "2020-08-21T12:41:11+05:30",
            "Modified_By": {
                "name": "Aaron Brown",
                "id": "486812000000216003"
            },
            "Created_Time": "2020-08-21T12:41:11+05:30",
            "id": "486812000001660001",
            "Created_By": {
                "name": "Patricia Boyle",
                "id": "486812000000216003"
            }
        },
        "message": "record added",
        "status": "success"
    }]
}