addRecords

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

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
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

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:
<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:
<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:
<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:
<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:
<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
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
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.

    • Related Articles

    • 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 ...