Zoho Recruit | addRecords Method

addRecords

Purpose

You can use the addRecords method to insert records into the required Zoho Recruit module.
Note: Use the POST method to pass these parameters instead of the 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.

For OAuth Authentication

Header Name
Value
Authorization
Zoho-oauthtoken {access_token}

Scopes

Scope=ZohoRecruit.modules.all
(or)
Scope=ZohoRecruit.modules.{scope_name}.{operation_type}
Possible Scope Names (Case Sensitive)
Operation Types
candidate, jobopening, client, department, interview, contact & custom (for all Custom Modules)ALL - Full access to the record
READ - Get records from the module

For Authtoken Authentication

Parameter
Data Type
Description
authtoken*
String
Encrypted alphanumeric string to authenticate your Zoho credentials. 
scope*
String
Specify the value as recruitapi

Request Parameters

Parameter
Data Type
Description
xmlData*
XML
This is an XML string and the format should be same as of getRecords in XML format of fetched records.
wfTrigger
Boolean
Set value as true to trigger the workflow rule while inserting record into Recruit account. By default, this parameter is false.
duplicateCheck
Integer
Set 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.
isApproval
Boolean
By default, records are inserted directly.To keep the records in approval mode, set valueas true.You can use this parameter for Candidates, Contacts
newFormat
Integer
newFormat=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*
Integer
version = 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.
Note: Parameters marker with * are mandatory.

Duplicate Check Fields

Module Name
Duplicate Check Field
Candidates
Email
Contacts
Email
Clients
Client Name
Job Openings
Posting Title
Interviews
Interview 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.
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=AuthToken&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 an 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=AuthToken&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=AuthToken&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=AuthToken&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

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've 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:
  1. Email Address is the duplicate check field for Candidates module. For other modules, the duplicate check field varies.
  2. 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.
  3. You have to pass version=2 in the parameter URL for duplicate check in multiple records.

    Zoho CRM Training Programs

    Learn how to use the best tools for sales force automation and better customer engagement from Zoho's implementation specialists.

    Zoho CRM Training
      Redefine the way you work
      with Zoho Workplace

        Zoho DataPrep Personalized Demo

        If you'd like a personalized walk-through of our data preparation tool, please request a demo and we'll be happy to show you how to get the best out of Zoho DataPrep.

        Zoho CRM Training

          Create, share, and deliver

          beautiful slides from anywhere.

          Get Started Now


            Get started with Zoho Sign

            in a few quick steps!

            Download Help Guide





                      Still can't find what you're looking for?

                      Write to us: support@zohoforms.com


                            




                            

                        Zoho Marketing Automation

                          Zoho Sheet Reources

                           




                              Zoho Forms Resources


                                Secure your business
                                communication with Zoho Mail


                                Mail on the move with
                                Zoho Mail mobile application

                                  Stay on top of your schedule
                                  at all times


                                  Carry your calendar with you
                                  Anytime, anywhere




                                        Zoho Sign Resources

                                          Sign, Paperless!

                                          Sign and send business documents on the go!

                                          Get Started Now


                                              Zoho SalesIQ Resources



                                                  Zoho TeamInbox Resources



                                                          Zoho DataPrep Resources



                                                            Zoho DataPrep Demo

                                                            Get a personalized demo or POC

                                                            REGISTER NOW


                                                              Design. Discuss. Deliver.

                                                              Create visually engaging stories with Zoho Show.

                                                              Get Started Now











                                                                                    • Related Articles

                                                                                    • Record Origin

                                                                                      The Origin value of a record indicates how it entered your system. Origin is the precursor to a record's source, and is used to group various source values into broader categories. For example, under the origin value of “Sourced”, you’ll see the ...
                                                                                    • API Methods

                                                                                      Method Name Purpose getRecords To retrieve all users data specified in the API request getRecordById To retrieve individual records by record ID addRecords To insert records into the required Zoho Recruit module updateRecords To update or modify the ...
                                                                                    Wherever you are is as good as
                                                                                    your workplace

                                                                                      Resources

                                                                                      Videos

                                                                                      Watch comprehensive videos on features and other important topics that will help you master Zoho CRM.



                                                                                      eBooks

                                                                                      Download free eBooks and access a range of topics to get deeper insight on successfully using Zoho CRM.



                                                                                      Webinars

                                                                                      Sign up for our webinars and learn the Zoho CRM basics, from customization to sales force automation and more.



                                                                                      CRM Tips

                                                                                      Make the most of Zoho CRM with these useful tips.



                                                                                        Zoho Show Resources