addRecords Method

Purpose

You can use the addRecords method to insert records into the required Zoho Recruit module.

Important: Use the POST method to pass these parameters instead of GET method.

Request URL

XML Format:

https://recruit.zoho.com/recruit/private/xml/Module/addRecords?authtoken=AuthToken&scope=recruitapi&version=2&xmlData=Your XML Data

Note: Module refers to Candidates, JobOpenings, Clients, Interviews, Contacts, CustomModule1, CustomModule2, CustomModule3, CustomModule4, and CustomModule5.

Request Parameters

ParameterData TypeDescription
authtoken*StringEncrypted alphanumeric string to authenticate your Zoho credentials.
scope*StringSpecify scope as recruitapi
xmlData*XMLThis is an XML string and the format should be same as of getRecords in XML format of fetched records.
wfTriggerBooleanSet value as true to trigger the workflow rule while inserting record into Recruit account. By default, this parameter is false.
duplicateCheckIntegerSet value as "1" to check the duplicate records and throw an error response or "2" to check the duplicate records, if exists, update the same.
isApprovalBooleanBy default, records are inserted directly.To keep the records in approval mode, set valueas true.You can use this parameter for Candidates, Contacts
newFormatIntegernewFormat=1: To exclude fields with "null" values while inserting data from your Recruit account.
newFormat=2: To include fields with "null" values while inserting data from your Recruit account.
version*Integerversion = 1: (Default Value) This will fetch responses based on the earlier API implementation i.e prior to the enhancements made.
version = 2: This will fetch responses based on the latest API implementation
version = 4: To add multiple records in a single API method call and will trigger duplicate check functionality for multiple records.

* - Mandatory parameter

Duplicate Check Fields

Module NameDuplicate Check Field
CandidatesEmail
ContactsEmail
ClientsClient Name
Job OpeningsPosting Title
InterviewsInterview Name

Additional Notes

While inserting data in your Zoho Recruit account, role-based security (Roles, Profiles, Field-level security and Data sharing rules) is applied. Hence, use the user ID with highestrole(Ex: Recruiter Admin) and profile (Ex: Administrator). Also, make sure all fields are enabled in the Field-level security settings. For role-based security settings, see Security Administration while generating Auth Token.

While inserting data, make sure the date and time are in the MM/dd/yyyy and yyyy-MM-dd HH:mm:ss formats respectively.

Examples

Insert records in Zoho Recruit from third-party applications

URL Format:

https://recruit.zoho.com/recruit/private/xml/Candidates/addRecords?authtoken=AuthToken&scope=recruitapi&duplicateCheck=( 1 OR 2 )&version=4&xmlData=

XMLDATA sample:

<Candidates>
<row no="1">
<FL val="Source">Web Download</FL>
<FL val="Current employer">Your Company</FL>
<FL val="First Name">Hannah</FL>
<FL val="Last Name">Smith</FL>
<FL val="Email">testing@testing.com</FL>
<FL val="Phone">1234567890</FL>
<FL val="Home Phone">0987654321</FL>
<FL val="Other Phone">1212211212</FL>
<FL val="Fax">02927272626</FL>
<FL val="Mobile">292827622</FL>
</row>
</Candidates >

Sample Candidate XMLDATA

<Candidates>
<row no="1">
<FL val="SMOWNERID">2000000016714</FL>
<FL val="Candidate Owner">Scott@zohotest.com</FL>
<FL val="Source">John</FL>

<FL val="Current employer"><![CDATA[VS&Co]]>

</FL><FL val="First Name">John</FL>

<FL val="Last Name">Gossling</FL>

<FL val="Email">john@zohocorp.com</FL>

<FL val="Phone">1234567890</FL>

<FL val="Candidate Status">Qualified</FL>

<FL val="Is Hot Candidate">true</FL>

<FL val="Salutation">Mr.</FL>
<FL val="Street">Street One</FL>
<FL val="City">Chennai</FL>
<FL val="State">Tamil Nadu</FL>
<FL val="Zip Code">6000001</FL>
<FL val="Country">India</FL>
</row>
</Candidates>

Sample Task XMLDATA with Contact and Client lookup

<Tasks>
<row no="1">
<FL val="SMOWNERID">2000000016714</FL>
<FL val="Task Owner">Scott@zohotest.com</FL>
<FL val="Subject">Demo Call</FL>
<FL val="Due Date">11/23/2009</FL>
<FL val="CONTACTID">2000000018443</FL>
<FL val="SEID">2000022218013</FL>
<FL val="SEMODULE">Clients</FL>
<FL val="Status">In Progress</FL>
<FL val="Priority">Highest</FL>
<FL val="Send Notification Email">false</FL>
<FL val="Description">Sample Desc</FL>
</row>
</Tasks>

Sample Task XMLDATA with Contact and Client lookup

<Tasks>
<row no="1">
<FL val="SMOWNERID">2000000016714</FL>
<FL val="Task Owner">Scott@zohotest.com</FL>
<FL val="Subject">Demo Call</FL>
<FL val="Due Date">11/23/2009</FL>
<FL val="CONTACTID">2000000018443</FL>
<FL val="SEID">2000022218013</FL>
<FL val="SEMODULE">Accounts</FL>
<FL val="Status">In Progress</FL>
<FL val="Priority">Highest</FL>
<FL val="Send Notification Email">false</FL>
<FL val="Description">Sample Desc</FL>
</row>
</Tasks>

Insert notes and relate to the primary module

 

XML Format:
https://recruit.zoho.com/recruit/private/xml/Notes/addRecords?authtoken=Auth Token&scope=recruitapi&version=2

XMLDATA  sample:

<Notes>

<row no="1">

<FL val="entityId">6000000119069</FL><FL val="Note Type">Meeting</FL><FL val="Type Id">6000000021005</FL><FL val="Note Content"><![CDATA[hello]]></FL><FL val="Parent Module">Candidates</FL>

</row>

</Notes>

Here the entityID is the unique ID of the primary record (Candidate, Client, Contact etc.)

Type Id is the Note Type Id which you can get from the getNoteTypes API.

Assign owner to the record

While inserting a record through API, make sure you are specifying the email address or userID of the record owner. If you use the record owner's name, the record will be assigned to the default login credential used in the Auth Token. If you want to use the userID to specify the record owner, then add <FL val="SMOWNERID">userID</FL> tag to your xmlData.

Note: In the following examples, replace the values for 'authtoken' and 'scope' with those generated by you.

Tasks

https://recruit.zoho.com/recruit/private/xml/Tasks/addRecords?authtoken=Auth Token&scope=recruitapi
&version=2&
xmlData=

<Tasks>
<row no="1">
<FL val="Subject">Call</FL>
<FL val="Due Date">2009-04-20</FL>
<FL val="Status">Deferred</FL>
<FL val="CONTACTID">2000000017017</FL>
</row>
</Tasks>

Events

https://recruit.zoho.com/recruit/private/xml/Events/addRecords?authtoken=Auth Token&scope=recruitapi
&version=2
&xmlData=

<Events>
<row no="1">
<FL val="Subject">Conference</FL>
<FL val="Start DateTime">2009-08-04 01:00:00</FL>
<FL val="End DateTime">2009-08-05 01:00:00</FL>
<FL val="Venue">United States</FL>
<FL val="Send Notification Email">True</FL>
</row>
</Events>

Events with Contacts and Client Mapping

https://recruit.zoho.com/recruit/private/xml/Events/addRecords?authtoken=Auth Token&scope=recruitapi
&version=2
&xmlData=

<Events>
<row no="1">
<FL val="Subject">Conference</FL>
<FL val="Start DateTime">2009-09-24 01:00:00</FL>
<FL val="End DateTime">2009-09-25 01:00:00</FL>
<FL val="Venue">Chennai</FL>
<FL val="CONTACTID">2000000055003</FL>
<FL val="SEID">2000000055007</FL>
<FL val="SEMODULE">Clients</FL>
</row>
</Events>

Clients

https://recruit.zoho.com/recruit/private/xml/Clients/addRecords?authtoken=Auth Token&scope=recruitapi
&version=2
&xmlData=

<Clients>
<row no="1">
<FL val="Client Name"><![CDATA[V3 Client]]></FL>

<FL val="Parent Client"><![CDATA[Client 2]]></FL>

<FL val="Client Manager">john@zohocorp.com</FL>

<FL val="Website">www.zillum.com</FL>

<FL val="Industry">Real estate</FL>

<FL val="Fax">99999999</FL>

</row>
</Clients>

Contacts

https://recruit.zoho.com/recruit/private/xml/Contacts/addRecords?authtoken=Auth Token&scope=recruitapi
&version=2
&xmlData=

<Contacts>
<row no="1">
<FL val="First Name">Scott</FL>
<FL val="Last Name">James</FL>
<FL val="Email">test@test.com</FL>
<FL val="Department">CG</FL>
<FL val="Phone">999999999</FL>
<FL val="Fax">99999999</FL>
<FL val="Mobile">99989989</FL>
</row>
</Contacts>

Insert Calls with Contacts and Clients Lookup

<Calls>
<row no="1">
<FL val="SMOWNERID">2000000018005</FL>
<FL val="Subject">Product Support</FL>
<FL val="Call Type">Inbound</FL>
<FL val="Call Purpose">Prospecting</FL>
<FL val="CONTACTID">2000000018001</FL>
<FL val="SEID">2000000018003</FL>
<FL val="SEMODULE">Clients</FL>
<FL val="Call Start Time">2011-06-10 22:10:00</FL>
<FL val="Call Duration">60:00</FL>
<FL val="Description">Required Product Demo</FL>
<FL val="Billable">true</FL>
<FL val="Call Result">Successful</FL>
</row>
</Calls>

Insert Calls with Candidates Lookup

<Calls>
<row no="1">
<FL val="SMOWNERID">2000000018005</FL>
<FL val="Subject">Demo</FL>
<FL val="Call Type">Inbound</FL>
<FL val="Call Purpose">Prospecting</FL>
<FL val="SEID">2000000017201</FL>
<FL val="SEMODULE">Candidates</FL>
<FL val="Call Start Time">2011-06-10 22:10:00</FL>
<FL val="Call Duration">60:00</FL>
<FL val="Description">Demo Call</FL>
<FL val="Billable">true</FL>
<FL val="Call Result">Successful</FL>
</row>
</Calls>

Usage of 'CDATA'

Purpose: To consider Special Characters as plain text and NOT XML Data

URL Format:
https://recruit.zoho.com/recruit/private/xml/Contacts/addRecords?version=2&authtoken=Auth Token&scope=recruitapi

Sample XML Data:

as POST:

<Contacts>
<row no="1">
<FL val="First Name">Amy</FL>
<FL val="Last Name">Dawson</FL>
<FL val="Email">testing@testing.com</FL>
<FL val="Job Title">Manager</FL>
<FL val="Phone">1234567890</FL>
<FL val="Mobile">292827622</FL>
<FL val="Account Name"> <![CDATA["A & A"]]> </FL>
</row>
</Contacts>

 

Insert Multiple Records

URL Format: https://recruit.zoho.com/recruit/private/xml/Candidates/addRecords?version=2&authtoken=Auth Token&scope=recruitapi

XMLDATA sample:

<Candidates>
    <row no="1"><FL val="Last Name">testing</FL><FL val="Email">test1@test.com</FL></row>
    <row no="2"><FL val="Last Name">testing</FL><FL val="Email">test2@test.com</FL></row>
    <row no="3"><FL val="Last Name">testing</FL><FL val="Email">test3@test.com</FL></row>
    <row no="4"><FL val="Last Name">testing</FL><FL val="Email">test4@test.com</FL></row>
    <row no="5"><FL val="Last Name">testing</FL><FL val="Email">test5@test.com</FL></row>
    <row no="6"><FL val="Last Name">testing</FL><FL val="Email">test6@test.com</FL></row>
    <row no="7"><FL val="Last Name">testing</FL><FL val="Email">test7@test.com</FL></row>
    <row no="8"><FL val="Last Name">testing</FL><FL val="Email">test8@test.com</FL></row>
    <row no="9"><FL val="Last Name">testing</FL><FL val="Email">test9@test.com</FL></row>
    <row no="10"><FL val="Last Name">testing</FL><FL val="Email">test10@test.com</FL></row>
 :
 :
 :
 
    <row no="100"><FL val="Last Name">testing</FL><FL val="Email">test100@test.com</FL></row>
</Candidates >

Notes:

  1. When inserting multiple records with the addRecords method:
  2. We support duplicate check for multiple records in version 2
  3. Workflow Rules will not be triggered for records that meet the criteria
  4. Only the first 100 records will be considered when inserting multiple records.

Duplicate Check for Multiple Records

Purpose: You can use addRecords to trigger duplicate check functionality for multiple records. Please note that version=4 is a mandatory parameter.

We have introduced three new codes that will represent the API result status for each record. The codes are as given below:

2000 = Record Added Successfully
2001 = Record Updated Successfully
2002 = Record Already Exists

URL Format:

https://recruit.zoho.com/recruit/private/xml/Candidates/addRecords?authtoken=AuthToken&scope=recruitapi&duplicateCheck=( 1 OR 2 )&version=4&xmlData=

Sample XML Data

<Candidates>
    <row no="1">
<FL val="Current Employer">Company1</FL>
<FL val="Last Name">Last Name1</FL>
<FL val="Email">automation@recruit.com1</FL>
    </row>
    <row no="2">
<FL val="Current Employer">Company2</FL>
<FL val="Last Name">Last Name2</FL>
<FL val="Email">automation@recruit.com2</FL>
    </row>
</Candidates

Sample Response

If duplicateCheck=1 , version=4, some records exist with the email address and some records don't exist, the functionality and response will be as given below:

<response uri=/recruit/private/xml/Candidates/addRecords>
                <result>
                    <row no=1>
                        <success>
                            <code>2000</code>
                            <details>
                                <FL val=Id>2000000120006</FL>
                                <FL val=Created Time>2013-02-11 17:55:04</FL>
                                <FL val=Modified Time>2013-02-11 17:55:04</FL>
                                <FL val=Created By>
                                <![CDATA[ aghil123 ]]>
                                </FL>
                                <FL val=Modified By>
                                <![CDATA[ aghil123 ]]>
                                </FL>
                            </details>
                        </success>
                    </row>
                    <row no=2>
                        <success>
                            <code>2002</code>
                            <details>
                                <FL val=Id>2000000120007</FL>
                                <FL val=Created Time>2013-02-11 17:55:04</FL>
                                <FL val=Modified Time>2013-02-11 17:55:04</FL>
                                <FL val=Created By>
                                <![CDATA[ aghil123 ]]>
                                </FL>
                                <FL val=Modified By>
                                <![CDATA[ aghil123 ]]>
                                </FL>
                            </details>
                        </success>
                    </row>
                </result>
            </response>

If duplicateCheck=1 , version=4 , no records exist with the email address, the functionality and response will be as given below:

<response uri=/recruit/private/xml/Candidates/addRecords>
                <result>
                    <row no=1>
                        <success>
                            <code>2000</code>
                            <details>
                                <FL val=Id>2000000120006</FL>
                                <FL val=Created Time>2013-02-11 17:55:04</FL>
                                <FL val=Modified Time>2013-02-11 17:55:04</FL>
                                <FL val=Created By>
                                <![CDATA[ aghil123 ]]>
                                </FL>
                                <FL val=Modified By>
                                <![CDATA[ aghil123 ]]>
                                </FL>
                            </details>
                        </success>
                    </row>
                    <row no=2>
                        <success>
                            <code>2000</code>
                            <details>
                                <FL val=Id>2000000120007</FL>
                                <FL val=Created Time>2013-02-11 17:55:04</FL>
                                <FL val=Modified Time>2013-02-11 17:55:04</FL>
                                <FL val=Created By>
                                <![CDATA[ aghil123 ]]>
                                </FL>
                                <FL val=Modified By>
                                <![CDATA[ aghil123 ]]>
                                </FL>
                            </details>
                        </success>
                    </row>
                </result>
            </response>

If duplicateCheck=1 , version=4 , records exist with the email address, the functionality and response will be as given below:

<response uri="/recruit/private/xml/Candidates/addRecords">
                <result>
                    <row no="1">
                        <success>
                            <code>2002</code>
                            <details>
                                <FL val="Id">2000000120006</FL>
                                <FL val="Created Time">2013-02-11 17:55:04</FL>
                                <FL val="Modified Time">2013-02-11 17:55:04</FL>
                                <FL val="Created By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                                <FL val="Modified By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                            </details>
                        </success>
                    </row>
                    <row no="2">
                        <success>
                            <code>2002</code>
                            <details>
                                <FL val="Id">2000000120007</FL>
                                <FL val="Created Time">2013-02-11 17:55:04</FL>
                                <FL val="Modified Time">2013-02-11 17:55:04</FL>
                                <FL val="Created By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                                <FL val="Modified By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                            </details>
                        </success>
                    </row>
                </result>
            </response>

If duplicateCheck=2 , version=4 , no records exist with the email address, the functionality and response will be as given below:

<response uri="/recruit/private/xml/Candidates/addRecords">
                <result>
                    <row no="1">
                        <success>
                            <code>2000</code>
                            <details>
                                <FL val="Id">2000000120006</FL>
                                <FL val="Created Time">2013-02-11 17:55:04</FL>
                                <FL val="Modified Time">2013-02-11 17:55:04</FL>
                                <FL val="Created By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                                <FL val="Modified By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                            </details>
                        </success>
                    </row>
                    <row no="2">
                        <success>
                            <code>2000</code>
                            <details>
                                <FL val="Id">2000000120007</FL>
                                <FL val="Created Time">2013-02-11 17:55:04</FL>
                                <FL val="Modified Time">2013-02-11 17:55:04</FL>
                                <FL val="Created By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                                <FL val="Modified By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                            </details>
                        </success>
                    </row>
                </result>
            </response>

If duplicateCheck=2 , version=4 , records exist with the email address, the functionality and response will be as given below:

<response uri="/recruit/private/xml/Candidates/addRecords">
                <result>
                    <row no="1">
                        <success>
                            <code>2001</code>
                            <details>
                                <FL val="Id">2000000120006</FL>
                                <FL val="Created Time">2013-02-11 17:55:04</FL>
                                <FL val="Modified Time">2013-02-11 17:55:04</FL>
                                <FL val="Created By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                                <FL val="Modified By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                            </details>
                        </success>
                    </row>
                    <row no="2">
                        <success>
                            <code>2001</code>
                            <details>
                                <FL val="Id">2000000120007</FL>
                                <FL val="Created Time">2013-02-11 17:55:04</FL>
                                <FL val="Modified Time">2013-02-11 17:55:04</FL>
                                <FL val="Created By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                                <FL val="Modified By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                            </details>
                        </success>
                    </row>
                </result>
            </response>

If duplicateCheck=2 ,version=4 , some records exist with the email address and some records don't, the functionality and response will be as given below:

<response uri="/recruit/private/xml/Candidates/addRecords">
                <response uri="/recruit/private/xml/Candidates/addRecords">
                <result>
                    <row no="1">
                        <success>
                            <code>2001</code>
                            <details>
                                <FL val="Id">2000000120006</FL>
                                <FL val="Created Time">2013-02-11 17:55:04</FL>
                                <FL val="Modified Time">2013-02-11 17:55:04</FL>
                                <FL val="Created By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                                <FL val="Modified By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                            </details>
                        </success>
                    </row>
                    <row no="2">
                        <success>
                            <code>2000</code>
                            <details>
                                <FL val="Id">2000000120007</FL>
                                <FL val="Created Time">2013-02-11 17:55:04</FL>
                                <FL val="Modified Time">2013-02-11 17:55:04</FL>
                                <FL val="Created By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                                <FL val="Modified By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                            </details>
                        </success>
                    </row>
                </result>
            </response>

If version=4, some records contain error and some don't, the functionality and response will be as given below:

<response uri="/recruit/private/xml/Candidates/addRecords">
                <result>
                    <row no="1">
                        <success>
                            <code>2001</code>
                            <details>
                                <FL val="Id">2000000120006</FL>
                                <FL val="Created Time">2013-02-11 17:55:04</FL>
                                <FL val="Modified Time">2013-02-11 17:55:04</FL>
                                <FL val="Created By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                                <FL val="Modified By">
                                <![CDATA[ aghil123 ]]>
                                </FL>
                            </details>
                        </success>
                    </row>
                    <row no="2">
                        <error>
                            <code>4832</code>
                                          <details>You have given a wrong value for the field : Annual Revenue</details>
                        </error>
                    </row>
                </result>
            </response>

Note:

  • Email Address is the duplicate check field for Candidates module. For other modules, the duplicate check field varies. To learn more, please read - https://www.zoho.com/recruit/help/api/addrecords.html#Duplicate_Check_Field
  • Developers can now easily identify the record id, since the record detail in the response, is given the same way the user requests in the xml data.
  • You have to pass version=2 in the parameter URL for duplicate check in multiple records.