Web Services
Content
Jobvite Data Services
Version 3.0 – June 18, 2014
prepared by:
Marcin Bebel
CS – Technical Account Manager
CONFIDENTIAL - Jobvite Data Services
1
Contents
Executive Summary ………………………….
3
Accessing Our Services ………………………..
3
Candidate API……………………………………
4
Employee API…………………………………….
12
Requisition API…………………………………...
16
Job Feed………………………………………….
21
Contact Import API………………………………
26
Appendices……………………………………….
29
CONFIDENTIAL - Jobvite Data Services
2
Executive Summary
Jobvite provides access to your company’s account in several ways.
1. Using our secure application-programming interface, RESTful services can be called via
HTTP GET or POST (depending upon the action). You may interact with three sets of
data:!·
a. Candidate – This service can be used to get information about candidates and
new hires with the following actions. We will return up to 500 candidates.
Please note that this API returns HR-XML
i. getNewHires – Get information about new hires for a given time period.
ii. getCandidates – Get information about candidates.!
iii. updateCandidates – Update the status for a set of candidates.
b. Requisition – This service can be used to create new requisitions in Jobvite, or
synchronize/update requisitions in Jobvite from your external system.
c. Employee – This service is used to keep your employee roster in Jobvite up to
date. This is a scheduled task that runs nightly and an email confirmation will be
received upon completion after 24 hours.
2. We also provide a job feed of your requisitions that you can use to power your career
site, an intranet career site, or to feed your data into another system.
Accessing Our Services
In order to access the services you will need to be issued an API key and secret key by the Jobvite
Customer Success team. Please file a request here: http://recruiting.jobvite.com/support/customer
You may also give us the IP address of the server that will be calling our service to increase
security.
What we need from you:!
•
The IP address of the server accessing our services.
What you need from us:
•
•
API key – This will give you access to a service to get data related to your company.
Secret key – This will be used to validate your API key.
Best Practices: Calling the API:
CONFIDENTIAL - Jobvite Data Services
3
•
Jobvite recommends calling our API on an “as needed” basis. Should customers need to
call the API more frequently than once a day, it is required that parameters be set on one of
the following:
o Dates at which candidates hit a desired workflow state.
o # of candidates per candidate list page (last 100, last 500 etc.)
o Candidates specific to a given requisition.
o Requisitions that have only seen changes
Candidate API
REST service end point: Via HTTP GET
Production: https://api.jobvite.com/v1/candidate?parameters
Staging: https://api-stg.jobvite.com/v1/candidate?parameters
Parameters:
api
Required
The API key issued by Jobvite.
secret
Required
The secret for this service, issued by Jobvite
action
Required
The action to perform. “getNewHires”, “getCandidates” ,
format
Required
The format of the data (HRXML)
wflowstate
Optional
The Jobvite candidate state name of candidates you are searching
for (only applicable to getCandidates)
datestart
Optional
The date after which the candidate was last updated for filtering
purposes.
dateend
Optional
The date before which the candidate was last updated for filtering
purposes.
dateformat
Optional
The format of the dates. The supported defaults are:
"MM/dd/yyyy", "MM-dd-yyyy”, “MM-dd-yyyy’THH:mm:ssZ”
The API can only call up to 500 candidates at a time. To retrieve more than 500 at once, leverage
the "count" and a "start" parameter you can specify in the URL.
For example, if you already get the first 500 records and you want the next 500 records, you would
add start=501&count=500 in the URL. The count means how many you want (maximum 500). The
start means from where you want the next set of candidates.
CONFIDENTIAL - Jobvite Data Services
4
Please reference the “Best Practices: Calling the API” bullet in the Executive Summary for more
information on how frequently to call the Jobvite API.
Sample:
https://api.jobvite.com/v1/candidate?api=jobvite&secret=test&action=getNewHires&format=hrxml&
datestart= 08-01-2009&dateend=2009-08-15T11:21:33-0700
https://api.jobvite.com/v1/candidate?api=jobvite&secret=test&action=getCandidates&format=hrxm
l&wflowsta te=New
updateCandidates
Via HTTP POST!Production: https://api.jobvite.com/v1/candidate?parameters
Staging: https://api-stg.jobvite.com/v1/candidate?parameters
Parameters:
Api
Required
The API key is issues by Jobvite.
Secret
Required
The secret for this service, issued by Jobvite
action
Required
“updateCandidates”
Format – Required – hrxml/json/csv
POST Data:
The json should be sent as a post parameter with name “data”. The data format should look like
this:
[{
"applicationId": "xyz123",
"wflowstate": "Offer Accepted"
}, {
"applicationId": "xyz456",
"wflowstate": "Rejected"
}]
Results HRXML
The results returned will be XML with the following formats. If there are any errors processing the
request, only the Errors data will be returned, this will allow rapid assessment of any problems.
The exact new hire data and error codes will be provided in a revision of this document.
CONFIDENTIAL - Jobvite Data Services
5
New Hires:
<?xml version="1.0" encoding="UTF-8"?>
<Results xmlns="http://api.jobvite.com/action/api/v1" action="getNewHires" version="1.0">
<NewHires first="1" count="1" total="1">
<ns:NewHire xmlns:ns="http://ns.hr-xml.org/2007-04-15">
<ns:EmployeeInfo>
<ns:PersonName>
<ns:GivenName>Tony</ns:GivenName>
<ns:FamilyName>Stark</ns:FamilyName>
</ns:PersonName>
<ns:ApplicantId idOwner="Jobvite">
<ns:IdValue name="applicationId">p0MIXgwc</ns:IdValue>
</ns:ApplicantId>
<ns:ContactMethod>
<ns:Use>personal</ns:Use>
<ns:Location>home</ns:Location>
<ns:Telephone>
<ns:FormattedNumber>614.429.7689</ns:FormattedNumber>
</ns:Telephone>
<ns:Mobile>
<ns:FormattedNumber>9535054265</ns:FormattedNumber>
</ns:Mobile>
<ns:InternetEmailAddress>[email protected]</ns:InternetEmailAddress>
<ns:PostalAddress>
<ns:CountryCode>US</ns:CountryCode>
<ns:PostalCode>94085</ns:PostalCode>
<ns:Region />
<ns:Municipality>Sunnyvale</ns:Municipality>
<ns:DeliveryAddress>
<ns:AddressLine>2 of 2</ns:AddressLine>
</ns:DeliveryAddress>
</ns:PostalAddress>
</ns:ContactMethod>
<ns:PersonDescriptors>
<ns:DemographicDescriptors>
<ns:Race />
</ns:DemographicDescriptors>
<ns:BiologicalDescriptors>
<ns:GenderCode>1</ns:GenderCode>
</ns:BiologicalDescriptors>
</ns:PersonDescriptors>
</ns:EmployeeInfo>
<ns:ApplicationInfo>
<ns:ApplicationHistory>
<ns:HiringProcessActivity>
<ns:Type>dateSubmitted</ns:Type>
<ns:Date>2013-01-09-08:00</ns:Date>
</ns:HiringProcessActivity>
CONFIDENTIAL - Jobvite Data Services
6
</ns:ApplicationHistory>
<ns:CandidateSupplier>
<ns:SupplierId idOwner="Jobvite">
<ns:IdValue name="sourcedBy">snV9Vfw6</ns:IdValue>
</ns:SupplierId>
<ns:EntityName />
<ns:SourceType>
<ns:NonStandardValue>Internal</ns:NonStandardValue>
</ns:SourceType>
</ns:CandidateSupplier>
</ns:ApplicationInfo>
<ns:PositionInfo>
<ns:ReferenceInfo>
<ns:RequisitionId idOwner="Jobvite">
<ns:IdValue name="requisitionId">533</ns:IdValue>
</ns:RequisitionId>
<ns:JobId idOwner="Jobvite">
<ns:IdValue name="jobId">ocQ2WfwK</ns:IdValue>
</ns:JobId>
</ns:ReferenceInfo>
<ns:OfferInfo>
<ns:NegotiatedPositionTitle>Prod Patch 09.Jan.2013</ns:NegotiatedPositionTitle>
<ns:DateJobAccepted>2013-01-07-08:00</ns:DateJobAccepted>
<ns:EmploymentStartDate>2013-02-01-08:00</ns:EmploymentStartDate>
</ns:OfferInfo>
<ns:OrganizationalUnit typeOfGroup="Department">
<ns:WorkSite>
<ns:WorkSiteName>Atlanta</ns:WorkSiteName>
<ns:UserArea>
<Regions>
<Region>BABA</Region>
</Regions>
</ns:UserArea>
</ns:WorkSite>
</ns:OrganizationalUnit>
<ns:ManagerInfo role="Manager">
<ns:ContactInfo>
<ns:PersonName>
<ns:GivenName>Kaushal</ns:GivenName>
<ns:FamilyName>Secondary</ns:FamilyName>
</ns:PersonName>
</ns:ContactInfo>
<ns:ManagerId idOwner="Jobvite">
<ns:IdValue name="userName">[email protected]</ns:IdValue>
</ns:ManagerId>
</ns:ManagerInfo>
</ns:PositionInfo>
<ns:UserArea>
<CustomFields>
<Field type="Candidate" name="Email address">[email protected]</Field>
CONFIDENTIAL - Jobvite Data Services
7
<Field type="Candidate" name="Candidate status">Experianced</Field>
<Field type="Candidate" name="CTC">0</Field>
<Field type="Job" name="Approval Chain">Kaushal Secondary
sxyajfwi</Field>
<Field type="Job" name="HRReqsthis">86543</Field>
<Field type="Job" name="SHL Package Id">7C61EF27-67A8-4FE2-B5DDC9E832CCFA71</Field>
</CustomFields>
</ns:UserArea>
</ns:NewHire>
</NewHires>
</Results>
Candidates:
<?xml version="1.0" encoding="UTF-8"?>
<Results xmlns="http://api.jobvite.com/action/api/v1" action="getCandidates" version="1.0">
<Candidates first="1" count="3" total="3">
<ns:Candidate xmlns:ns="http://ns.hr-xml.org/2007-04-15">
<ns:CandidateRecordInfo>
<ns:Id idOwner="Jobvite">
<ns:IdValue name="applicationId">p3zjJfwo</ns:IdValue>
</ns:Id>
<ns:Status>Approved</ns:Status>
</ns:CandidateRecordInfo>
<ns:RelatedPositionPostings>
<ns:PositionPosting>
<ns:Id idOwner="Jobvite">
<ns:IdValue name="requisitionId">1</ns:IdValue>
</ns:Id>
<ns:Title>Member Technical Staff</ns:Title>
</ns:PositionPosting>
</ns:RelatedPositionPostings>
<ns:CandidateSupplier>
<ns:SupplierId idOwner="Jobvite">
<ns:IdValue name="sourcedBy">sQnJafwQ</ns:IdValue>
</ns:SupplierId>
<ns:EntityName>Karthikeyan Seetharam</ns:EntityName>
<ns:SourceType>
<ns:NonStandardValue>Hiring Manager</ns:NonStandardValue>
</ns:SourceType>
</ns:CandidateSupplier>
<ns:CandidateProfile>
<ns:PersonalData>
<ns:PersonId idOwner="Jobvite">
<ns:IdValue name="candidateId">euHfxfwH</ns:IdValue>
</ns:PersonId>
<ns:PersonName>
<ns:GivenName>12345</ns:GivenName>
<ns:FamilyName>12345</ns:FamilyName>
CONFIDENTIAL - Jobvite Data Services
8
</ns:PersonName>
<ns:ContactMethod>
<ns:Use>personal</ns:Use>
<ns:Location>home</ns:Location>
<ns:InternetEmailAddress>[email protected]</ns:InternetEmailAddress>
</ns:ContactMethod>
</ns:PersonalData>
</ns:CandidateProfile>
<ns:Resume>
<ns:NonXMLResume>
<ns:TextResume>asdasds</ns:TextResume>
</ns:NonXMLResume>
</ns:Resume>
<ns:UserArea>
<CustomFields>
<Field type="Candidate" name="TestingOne">12</Field>
<Field type="Candidate" name="Email address">[email protected]</Field>
<Field type="Candidate" name="Candidate status">Experianced</Field>
<Field type="Candidate" name="CTC">121</Field>
</CustomFields>
</ns:UserArea>
</ns:Candidate>
<ns:Candidate xmlns:ns="http://ns.hr-xml.org/2007-04-15">
<ns:CandidateRecordInfo>
<ns:Id idOwner="Jobvite">
<ns:IdValue name="applicationId">pzSJPfwJ</ns:IdValue>
</ns:Id>
<ns:Status>Approved</ns:Status>
</ns:CandidateRecordInfo>
<ns:RelatedPositionPostings>
<ns:PositionPosting>
<ns:Id idOwner="Jobvite">
<ns:IdValue name="requisitionId">30092012</ns:IdValue>
</ns:Id>
<ns:Title>Android Web App Developer</ns:Title>
</ns:PositionPosting>
</ns:RelatedPositionPostings>
<ns:CandidateSupplier>
<ns:SupplierId idOwner="Jobvite">
<ns:IdValue name="sourcedBy">snV9Vfw6</ns:IdValue>
</ns:SupplierId>
<ns:EntityName />
<ns:SourceType>
<ns:NonStandardValue>Internal</ns:NonStandardValue>
</ns:SourceType>
</ns:CandidateSupplier>
<ns:CandidateProfile>
<ns:PersonalData>
<ns:PersonId idOwner="Jobvite">
<ns:IdValue name="candidateId">eXojCfw0</ns:IdValue>
CONFIDENTIAL - Jobvite Data Services
9
</ns:PersonId>
<ns:PersonName>
<ns:GivenName>James</ns:GivenName>
<ns:FamilyName>Morgan</ns:FamilyName>
</ns:PersonName>
<ns:ContactMethod>
<ns:Use>personal</ns:Use>
<ns:Location>home</ns:Location>
<ns:InternetEmailAddress>[email protected]</ns:InternetEmailAddress>
</ns:ContactMethod>
</ns:PersonalData>
</ns:CandidateProfile>
<ns:Resume>
<ns:NonXMLResume>
<ns:TextResume>test</ns:TextResume>
<ns:SupportingMaterials>
<ns:AttachmentReference>test</ns:AttachmentReference>
<ns:Description>CoverLetter</ns:Description>
</ns:SupportingMaterials>
</ns:NonXMLResume>
</ns:Resume>
<ns:UserArea>
<CustomFields>
<Field type="Candidate" name="Test Cand">One</Field>
<Field type="Candidate" name="Test Cand 2">1348684200000</Field>
<Field type="Candidate" name="TestingOne">w</Field>
<Field type="Candidate" name="Job G131">35643</Field>
<Field type="Candidate" name="Initial Submission Date">3456345</Field>
<Field type="Candidate" name="Email address">[email protected]</Field>
<Field type="Candidate" name="Candidate status">Experianced</Field>
<Field type="Candidate" name="CTC">12121212</Field>
</CustomFields>
</ns:UserArea>
</ns:Candidate>
<ns:Candidate xmlns:ns="http://ns.hr-xml.org/2007-04-15">
<ns:CandidateRecordInfo>
<ns:Id idOwner="Jobvite">
<ns:IdValue name="applicationId">prMKUfwB</ns:IdValue>
</ns:Id>
<ns:Status>Approved</ns:Status>
</ns:CandidateRecordInfo>
<ns:RelatedPositionPostings>
<ns:PositionPosting>
<ns:Id idOwner="Jobvite">
<ns:IdValue name="jobId">o1fiVfwd</ns:IdValue>
</ns:Id>
<ns:Title>bug1310w/Agency</ns:Title>
</ns:PositionPosting>
</ns:RelatedPositionPostings>
CONFIDENTIAL - Jobvite Data Services
10
<ns:CandidateSupplier>
<ns:SupplierId idOwner="Jobvite">
<ns:IdValue name="sourcedBy">snV9Vfw6</ns:IdValue>
</ns:SupplierId>
<ns:EntityName />
<ns:SourceType>
<ns:NonStandardValue>Career Site</ns:NonStandardValue>
</ns:SourceType>
</ns:CandidateSupplier>
<ns:CandidateProfile>
<ns:PersonalData>
<ns:PersonId idOwner="Jobvite">
<ns:IdValue name="candidateId">eoCiGfwI</ns:IdValue>
</ns:PersonId>
<ns:PersonName>
<ns:GivenName>TestAji3443edd</ns:GivenName>
<ns:FamilyName>TestAji3443edd</ns:FamilyName>
</ns:PersonName>
<ns:ContactMethod>
<ns:Use>personal</ns:Use>
<ns:Location>home</ns:Location>
<ns:InternetEmailAddress>[email protected]</ns:InternetEmailAddress>
</ns:ContactMethod>
</ns:PersonalData>
</ns:CandidateProfile>
<ns:Resume>
<ns:NonXMLResume>
<ns:TextResume>dfadf sdaf asd fadsf asdfasdfadf ads fasdf</ns:TextResume>
</ns:NonXMLResume>
</ns:Resume>
<ns:UserArea>
<CustomFields>
<Field type="Candidate" name="Candidate status">Experianced</Field>
<Field type="Candidate" name="CTC">1111</Field>
</CustomFields>
</ns:UserArea>
</ns:Candidate>
</Candidates>
</Results>
Errors:
<?xml version="1.0" encoding="UTF-8"?>
<Results xmlns="http://api.jobvite.com/action/api/v1" action="getNewHires" version="1.0">
<Errors>
<Error code="100">No candidates or new hires found for the given query.</Error>
</Errors>
</Results>
CONFIDENTIAL - Jobvite Data Services
11
Employee API
This service is used to keep your employee roster in Jobvite up to date. This API supports both xml
and JSON formats as shown below. This operation is not incremental. If there are any employee
information missing in subsequent feeds, that employee information is removed from the system.
Via HTTP POST
!Production: https://api.jobvite.com/v1/employee
Staging: https://api-stg.jobvite.com/v1/employee
!Note: This is a scheduled task that runs nightly and an email confirmation will be received upon
completion after 24 hours.
!Data and Parameters
•
•
•
•
•
Required fields are first name <FirstName>, last name <LastName> and email address
<Name>
Organizational data. You may have a field called Reports To which contains the email
address of each !employee’s immediate manager. You can put any number of
organizational fields in the spreadsheet that we can then use for approval chains or
reporting. For instance, you could import the HR Business Partner for each employee.
If you import a field called Role, we will overwrite all employees’ existing roles in Jobvite. If
you do not include that field, we will preserve whatever roles your employees currently
have.
o If leveraging role mapping, employees must be mapped to one of the following
Jobvite roles:
§ Recruiter
§ Administrator
§ SuperUser
§ HR
§ Scheduler
§ HiringManager
§ Research
§ JobApprover
§ Employee (default if no role is provided for that specific employee)
Include more information to help you organize groups of employees when you send
Jobvites. Department and location are examples but you can put in whatever groups you
like. After you sync, go to Admin/Employees and select the fields you’d like to use.
If you need to add an employee to Jobvite that is not part of the Employee Sync file, you
CONFIDENTIAL - Jobvite Data Services
12
•
•
•
•
•
•
•
•
•
can file a support ticket (support.jobvite.com) to add he/she to the Exclusions List. Agency
users (not being employees) do not need to be added to this list, as they are automatically
excluded from the sync.
If you use employee ID, we will use that as the identifier for the employee, otherwise we use
the employee’s email address.
You can find your companyid by going to Admin/Profile and looking at the URL under your
career site. The c=XXX at the end will show your ID.
ImporterEmail is the email address of the person who is recorded as the one who
added/update/deleted/invited the employees. This has to be the email address of someone
who has accepted their invitation into Jobvite.
ReportEmail is the email address of the person who will receive the reports after each sync.
DoNotSyncOnWarnings. If you set this to false, we will complete your sync whether or not
there are !warnings. You will receive a report showing what your warnings are so you know
what information was !not uploaded. Please note – we never sync if there are errors.
OverwriteEmployeeNamesAndEmail. This is the same functionality as the checkbox in step
1 of the !manual employee sync. In order to use this, please first enable this in
Admin/Profile: Prevent Self Service Name or Email Change
DoNotRestoreDeleted: Previously deleted/removed employees will not be stored in this
import.
IgnoreExcludes: No removals or additions to those that are excluded
DoNotPerformEmployeeUpdates: No updates to existing employees
Please reference the “Best Practices: Calling the API” bullet in the Executive Summary for more
information on how frequently to call the Jobvite API.
JSON format: !
{
"CompanyId": "qoV9Vfw7",
"ImporterEmail": "[email protected]",
"ReportEmail": "[email protected]",
"DoNotSyncOnWarnings": false,
"OverwriteEmployeeNamesAndEmail": false,
"Employees": [{
"FirstName": "Mary995",
"LastName": "Doe",
"Name": "[email protected]",
"DepartmentName": "",
"LocationName": "Burlingame",
"RegionName": "",
"SubsidiaryName": "",
"Role": "Administrator",
"Title": "Architect",
"EmployeeId": "",
"Reports To": “[email protected]”,
"Address": "Mehboob Nagar",
"Address2": "",
"City": "Latur",
"State": "MH",
CONFIDENTIAL - Jobvite Data Services
13
"PostalCode": "413512",
"Country": "India",
"HomePhone": "023995252111",
"WorkPhone": "0999581995492",
"Mobile": "",
"CustomFields": [{
"Key": "VP",
"Value": "[email protected]"
}, {
"Key": "Approver 1",
"Value": "[email protected]"
}]
},
{
"FirstName": "Mose995",
"LastName": "Doe",
"Name": "[email protected]",
"LocationName": "Burlingame"
}, {
"FirstName": "Mane995",
"LastName": "Doe",
"Name": "[email protected]",
"LocationName": "Burlingame"
}
]
}
XML format: !
<?xml version="1.0"?>!<SyncData xmlns:i="http://www.w3.org/2001/XMLSchema-instancetest">
<CompanyId>qoV9Vfw7</CompanyId>
<ImporterEmail>[email protected]</ImporterEmail> <ReportEmail>[email protected]</ReportEmail>
<DoNotSyncOnWarnings>false</DoNotSyncOnWarnings>
<OverwriteEmployeeNamesAndEmail>false</OverwriteEmployeeNamesAndEmail>
<Employees>
<Employee> <FirstName>Mary996</FirstName> <LastName>Doe</LastName>
<Name>[email protected]</Name> <DepartmentName></DepartmentName>
<LocationName>Burlingame</LocationName> <RegionName></RegionName>
<SubsidiaryName></SubsidiaryName> <Role>Administrator</Role>
<Title>Architect</Title> <EmployeeId></EmployeeId>
<ReportsTo>[email protected]</ReportsTo>
<Address>Mehboob Nagar</Address>
<Address2></Address2>!<City>Latur</City>!<State>MH</State>
<PostalCode>413512</PostalCode> <Country>India</Country>
<HomePhone>023996252111</HomePhone>
<WorkPhone>0999681996492</WorkPhone> <Mobile></Mobile>!<CustomFields>
<CustomField>!<Key>VP</Key> <Value>[email protected]</Value>
</CustomField> <CustomField>
CONFIDENTIAL - Jobvite Data Services
14
<Key>VP</Key>
<Value>[email protected]</Value> </CustomField>
</CustomFields> </Employee> <Employee>
<FirstName>Mose996</FirstName> <LastName>Doe</LastName>
<Name>[email protected]</Name> <LocationName>Burlingame</LocationName>
</Employee> <Employee>
<FirstName>Mane996</FirstName> <LastName>Doe</LastName>
<Name>[email protected]</Name> <LocationName>Burlingame</LocationName>
</Employee> </Employees>
</SyncData>
Sample Java Client Code
public static void main(final String[] args) throws Exception
{
String xml =
"<?xml version=\"1.0\"?>"+
"<SyncData xmlns:i=\"http://www.w3.org/2001/XMLSchema-instance-test\">"+
"<CompanyId>qlb9Vfwk</CompanyId>"+
"<ImporterEmail>[email protected]</ImporterEmail>"+
"<ReportEmail>[email protected]</ReportEmail>"+
"<DoNotSyncOnWarnings>false</DoNotSyncOnWarnings>"+
"<OverwriteEmployeeNamesAndEmail>false</OverwriteEmployeeNamesAndEmail>"+
"<Employees>"+
"<Employee>"+
"<FirstName>Karthik</FirstName>"+
"<LastName>Kyle</LastName>"+
"<Name>[email protected]</Name>"+
"</Employee>"+
"</Employees>"+
"</SyncData>";
String url = "http://api-stg.jobvite.com/v1/employee";
HttpClient client = new HttpClient(new MultiThreadedHttpConnectionManager());
PostMethod method = new PostMethod(url);
method.addParameter("xml", xml);
method.addParameter("api", "API KEY");
method.addParameter("sc", "API SECRET KEY");
method.addParameter("companyId","COMPANY IDk");
client.executeMethod(method);
System.out.println(method.getResponseBodyAsString());
}
CONFIDENTIAL - Jobvite Data Services
15
Requisition API
This service can be used to create new requisitions in Jobvite, or synchronize/update requisitions
in Jobvite from your external system.
Before starting development, please file a support ticket with the Jobvite Customer Success team
asking that the “Jobs API” be enabled for your company. This can be done at the same time the
customer requests their company specific API Key, API Secret, and Company ID.
Each time you update a requisitions, we will overwrite any fields that are different – unless you
manually update the requisition in Jobvite. In that case, we will stop overwriting the information. We
will close the requisition when it’s no longer in your feed. Manually updating requisitions includes
all fields within the requisition form.
Changing the Status of the Requisition will not affect the API post updates.
All manual changes must be saved in order for changes to stop being overwritten.
Please reference the “Best Practices: Calling the API” bullet in the Executive Summary for more
information on how frequently to call the Jobvite API.
This API supports both xml and JSON formats. The details are as follows.
Via HTTP POST
Production: https://api.jobvite.com/v1/job
Staging: https://api-stg.jobvite.com/v1/job
XML format:
<jobs>
<companyName>Jobvite</companyName>
<siteUrl />
<recruiterEmail>[email protected]</recruiterEmail>
<closeMissingReqs>true</closeMissingReqs>
<job>
<requiredFields>
<applyLink/>
<briefDescription/>
<description/>
<isPrivate>true</isPrivate>
<internalOnly>true</internalOnly>
<category/>
CONFIDENTIAL - Jobvite Data Services
16
<jobId/>
<jobLink/>
<locationName/>
<locationCity/>
<locationState/>
<locationCountry/>
<recruiterEmail/>
<evaluationFormName>Evaluation Form Name</evaluationFormName>
<preInterviewFormName>Candidate Form Name</preInterviewFormName>
<title/>
<jobState/>
<eeoCategory/>
<positionCount/>
<locationPostalCode/>
<departmentName/>
<agencyAccessEmail>[email protected];[email protected]</agencyAccessEmail>
<hiringManagerEmail/>
<creatorEmail/>
<jobType/>
</requiredFields>
<customFields>
<openings>23</openings>
<!-- For Reqs that can have multiple openings against it -->
</customFields>
</job>
</jobs>
JSON format:
{
"companyName": “Jobvite”,
"siteUrl": "http://url.to/job/list/page/",
"recruiterEmail": "",
"closeMissingReqs": true,
"requisitions": [{
"applyLink": "",
"briefDescription": "",
"description": "",
"category": "",
"jobId": "",
"jobLink": "",
“preInterviewFormName”:””,
"locationName": "",
"locationCity": "",
"locationState": "",
"locationCountry": "",
“evaluationFormName”:””,
"recruiterEmail": "",
“agencyAccessEmail”:””,
"title": "",
CONFIDENTIAL - Jobvite Data Services
17
"jobState": "",
"eeoCategory": "",
"positionCount": "",
"locationPostalCode": "",
"departmentName": "",
"hiringManagerEmail": "",
"creatorEmail": "",
"jobType": "",
"customFields": {
"openings": "",
"CustomField1": "custom field 1 value",
"customfields2": "custom field 2 value"
}
}, ],
}
Sample Java Client Code
public static void main(final String[] args) {
String xml = "<jobs>" +
"<closeMissingReqs>true</closeMissingReqs>" +
"<companyName>Oneco</companyName>" +
"<siteUrl>www.jobvite.com</siteUrl>" +
"<recruiterEmail>[email protected]</recruiterEmail>" +
"<job>" +
"<requiredFields><applyLink>link</applyLink>" +
"<briefDescription></briefDescription>" +
"<description>this is a job</description>" +
"<category>Domestic</category>" +
"<jobId>jobid 20</jobId>" +
"<jobLink></jobLink>" +
"<locationName>Redmond, WA</locationName>" +
"<locationCity>Redmond</locationCity>" +
"<locationState>WA</locationState>" +
"<locationCountry>United States</locationCountry>" +
"<jobType></jobType>" +
"<title>Technical Writer</title>" +
"</requiredFields>" +
"<customFields></customFields>" +
"</job>" +
"</jobs>";
String url = "https://api.jobvite.com/v1/job";
HttpClient client = new HttpClient(new MultiThreadedHttpConnectionManager());
PostMethod method = new PostMethod(url);
method.addParameter("xml", xml);
method.addParameter("api", "your_company_key");
method.addParameter("sc", "your_secret");
CONFIDENTIAL - Jobvite Data Services
18
client.executeMethod(method);
System.out.println(method.getResponseBodyAsString(
Job Feed
We have two feeds we support, an XML feed with a set of standard fields and a more flexible
JSON feed where you can filter your jobs. The latter supports both internal and external jobs.
XML Feed
Please contact Customer Support for the XML feed URL.
You can find your company ID by looking in Admin/Profile and looking under the Career Site
section. The company ID is the numbers and letters after the c= in the url. The standard fields
included are:
<id>!
<title>
<requisitionid>
<category>
<jobtype>
<location>!
<date>
<detail-url>
<apply-url>
<description>
<briefdescription>
If you want to pick up more fields than just the standard, you’ll need to get a key and secret from
us. You’ll also need to go to Admin/Custom Fields and check off any fields you want to include in
your XML feed.
CONFIDENTIAL - Jobvite Data Services
19
If you do not want the data encrypted, use cf=a in the url:
http://hire.jobvite.com/CompanyJobs/Xml.aspx?c= YOUR_COMPANY_ID
&cf=a&key=YOUR_KEY&sc=YOUR_SECRET
If you want the data encrypted, use cf=e in the url:
http://hire.jobvite.com/CompanyJobs/Xml.aspx?c= YOUR_COMPANY_ID
&cf=e&key=YOUR_KEY&sc=YOUR_SECRET
JSON Feed
This feed supports these features:
•
Pagination: user can provide the start and end count to view the jobs.
•
Filter: user can use a combination of criteria to filter the jobs.
•
o
Jobs by category!
o
Jobs by department
o
Jobs by location!
o
Jobs by region!
o
Jobs by type
Support to view Internal and External jobs.
CONFIDENTIAL - Jobvite Data Services
20
Via HTTP GET
Production: https://api.jobvite.com/v1/jobFeed
Staging: https://api-stg.jobvite.com/v1/jobFeed
API Query Parameters
•
•
•
•
•
API key: we will provide
Secret key: we will provide
CompanyId: You can find your company ID by looking in Admin/Profile and looking under
the Career Site !section. The company ID is the numbers and letters after the c= in the
URL. !Pagination Options
Start: denotes the starting index. Default start index: 1
Count: Denotes the number of jobs from the starting index.
o Default count: 100; !Posting Limit per call: 1000
o If more requisitions are sent via the feed than the listed count, the following error will
be received:
Filter Options
Filter
Description
type
Job type, configured in Admin
availableTo
Publishing settings for your
jobs – on your career site or
only available internally.
External by default.
The categories used on your
career site, configured in
Admin
City, state, Country
Region, configured in Admin
category
location
region
Sample Values (configured in
your instance)
Contractor, Full-time, Intern,
Part-time
External, Internal
Accounting, Engineering,
Human Resources
Burlingame, CA, USA
Europe, Asia
Sample Request
CONFIDENTIAL - Jobvite Data Services
21
https://api.jobvite.com/v1/jobFeed?companyId=dah4p0sl&api=<api_key>&sc=<secret>&start=10
&count=100&t ype=full-time&availableTo=internal&category=Finance&department=Human
Resource&location=Burlingame, CA, USA®ion=Europe
Sample Response
{
"total": 2,
"jobs": [{
"hiringManager": "manzoor symphony",
"preInterviewForm": "Test Form",
"location": "Klaus, United States",
"jobState": "Open",
"salaryHigh": "0",
"jobSource": "0",
"endDate": "12/31/9999",
"primaryHiringManagerId": "",
"city": "Klaus",
"approvalRequired": "0",
"salaryLow": "0",
"recruiterAccess": "0",
"description": "<p>Position Responsibilities:<br />Enter invoices in QAD<br />Obtain
appropriate invoice payment approvals<br />Resolve any AP issues (receiving
quantity/price discrepancy, etc.)<br />Organize and file all AP documents (invoices,
checks, etc.)<br />1099 filing<br />Maintain AP accrual account<br />Perform all other
duties as assigned<br />Minimum Requirements:<br />Accounting/Finance
background<br />2 years of AP experience<br />Experience in accounting software and
proficient in the use of EXCEL<br />Ability to analyze the nature of an invoice for proper
coding, spot errors, and inconsistencies<br /> <\/p>",
"agencyHiringManager": "",
"userName": "",
"notified": "0",
"eEOCategory": "Professionals",
"doNotCall": "false",
"openings": "0",
"companyName": "Oneco",
"country": "USA",
"category": "Accounting",
"parsed": "1",
"createdBy": "1215684",
"carrerSiteScrapeUrl": "",
"clientsDepartmentId": "",
"bonus": "",
"clientsRegionId": "",
"recruiter": "manzoor ahmed",
"applyUrl": "https://hirestg.jobvite.com//CompanyJobs/Apply.aspx?c=qQX9VfwB&j=oVCQVfw2",
"availableTo": "External",
"region": "BABA",
CONFIDENTIAL - Jobvite Data Services
22
"startDate": "12/31/9999",
"jobType": "Full-Time",
"department": "Engineering",
"state": "",
"date": "12/21/2012",
"subsidiaryName": "",
"private": "false",
"holdTimeSpan": "0",
"id": "oVCQVfw2",
"referalBonus": "0",
"title": "ABC Accounts Payable Clerk - No Eval",
"briefDescription": "<p>Position Responsibilities:<br />Enter invoices in QAD<br />Obtain
appropriate invoice payment approvals<br />Resolve any AP issues (receiving
quantity/price discrepancy, etc.)<br />Organize and file all AP documents (invoices,
checks, etc.)<br />1099 filing<\/p>",
"filledOn2": "",
"approveDate": "12/21/2012",
"notification": "true",
"workFlowTitle": "General",
"careerSite": "true",
"showSalary": "0",
"clientsLocationId": "",
"detailUrl": "https://hirestg.jobvite.com//CompanyJobs/Job.aspx?c=qQX9VfwB&j=oVCQVfw2",
"zip": "0",
"jobLinkUrl": "",
"contactInformation": "",
"customFields": {
"1_SP_DP": "",
"Approval Chain": "manzoor ahmed\nsbaf0fwk",
"HRReqsthis": "d",
"Job Code": "",
"SP_DP": ""
},
"areaCode": "",
"closeDate": "12/31/9999",
"approval": "<i>If you reply to this message, it will go to (name).<\/i>\n\nDear
<NAME*>,\r\n\r\nPlease review the attached job requisition information and either approve
or reject the requisition.\r\n\r\nhttps://hire.jobvite.com/uniqueid\r\n\r\nThank
you.\r\n\r\nmanzoor ahmed",
"jobType2": "",
"filledOn": "",
"putOnHoldDate": "",
"agencyCompany": "",
"interviewEvaluation": "",
"filledBy": "0",
"sentdate": "07/25/2011",
"companyId": "qQX9VfwB",
"needsRequired": "0",
CONFIDENTIAL - Jobvite Data Services
23
"requisitionId": "",
"eQuest": ""
}, {
"hiringManager": "manzoor symphony",
"preInterviewForm": "Test Form",
"location": "Klaus, United States",
"jobState": "Open",
"salaryHigh": "0",
"jobSource": "0",
"endDate": "",
"primaryHiringManagerId": "",
"city": "Klaus",
"approvalRequired": "0",
"salaryLow": "0",
"recruiterAccess": "0",
"description": "<p>Position Responsibilities:<br />Enter invoices in QAD<br />Obtain
appropriate invoice payment approvals<br />Resolve any AP issues (receiving
quantity/price discrepancy, etc.)<br />Organize and file all AP documents (invoices,
checks, etc.)<br />1099 filing<br />Maintain AP accrual account<br />Perform all other
duties as assigned<br />Minimum Requirements:<br />Accounting/Finance
background<br />2 years of AP experience<br />Experience in accounting software and
proficient in the use of EXCEL<br />Ability to analyze the nature of an invoice for proper
coding, spot errors, and inconsistencies<br /> <\/p>",
"agencyHiringManager": "",
"userName": "",
"notified": "0",
"eEOCategory": "Professionals",
"doNotCall": "false",
"openings": "0",
"companyName": "Oneco - QA",
"country": "USA",
"category": "Accounting",
"parsed": "0",
"createdBy": "1215684",
"carrerSiteScrapeUrl": "",
"clientsDepartmentId": "",
"bonus": "",
"clientsRegionId": "",
"recruiter": "manzoor ahmed",
"applyUrl": "https://hirestg.jobvite.com//CompanyJobs/Apply.aspx?c=qQX9VfwB&j=oNDfXfwm",
"availableTo": "External",
"region": "BABA",
"startDate": "",
"jobType": "Full-Time",
"department": "Engineering",
"state": "",
"date": "04/25/2013",
"subsidiaryName": "",
"private": "false",
CONFIDENTIAL - Jobvite Data Services
24
"holdTimeSpan": "0",
"id": "oNDfXfwm",
"referalBonus": "0",
"title": "Accounts - Payable Associate",
"briefDescription": "<p>Position Responsibilities: Enter invoices in QAD Obtain
appropriate invoice payment approvals Resolve any AP issues (receiving quantity/price
discrepancy, etc.) Organize and file all AP documents (invoices, checks, etc.) 1099
filing<\/p>",
"filledOn2": "",
"approveDate": "04/25/2013",
"notification": "true",
"workFlowTitle": "General",
"careerSite": "true",
"showSalary": "0",
"clientsLocationId": "",
"detailUrl": "https://hirestg.jobvite.com//CompanyJobs/Job.aspx?c=qQX9VfwB&j=oNDfXfwm",
"zip": "0",
"jobLinkUrl": "",
"contactInformation": "",
"customFields": {
"TestCand": "123",
"New 3350": "3456",
"Salary Range": "50,000 \u2013 60,000",
"sudeep test": "manzoor ahmed\nsbaf0fwk",
"SP_Txt": "33",
"1_SP_DP": "BRAZIL",
"1_SP_Txt": "Professional Services",
"Approval Chain": "manzoor ahmed\nsbaf0fwk",
"Grade": "8",
"HRReqsthis": "d",
"Salary": "123",
"SHL Package Id": "7C61EF27-67A8-4FE2-B5DD-C9E832CCFA71",
"Test 3686": "No\nMay Be",
"Job Code": "123",
"SP_DP": "Adam Hayder"
},
"areaCode": "",
"closeDate": "12/30/9999",
"approval": "<i>If you reply to this message, it will go to manzoor ahmed.<\/i>\n\nDear
<NAME*>,\r\n\r\nPlease review the attached job requisition information and either approve
or reject the requisition.\r\n\r\nhttps://hire.jobvite.com/uniqueid\r\n\r\nThank
you.\r\n\r\nmanzoor ahmed",
"jobType2": "",
"filledOn": "",
"putOnHoldDate": "",
"agencyCompany": "",
"interviewEvaluation": "Default",
"filledBy": "0",
"sentdate": "03/13/2013",
CONFIDENTIAL - Jobvite Data Services
25
"companyId": "qQX9VfwB",
"needsRequired": "0",
"requisitionId": "577",
"eQuest": ""
}],
"filterCriteria": {
"region": "",
"availableTo": "External",
"category": "Accounting",
"count": 2,
"location": "",
"start": 1,
"department": "Engineering",
"type": ""
}
}
Contact Import API
Use the Contact Import API to allow authenticated Jobvite users to import talent profiles as
Contact records into their Jobvite Engage CRM. The Contact API import and response format is in
JSON (JavaScript Object Notation, not available in other formats). JSON is a simple machinereadable data-interchange format. For more information about JSON, visit json.org. This API is only
available to Jobvite Engage Customers.
Staging API End Points:
http://api-stg.jobvite.com/v1/contacts
https://api-stg.jobvite.com/v1/contacts
CONFIDENTIAL - Jobvite Data Services
26
Production API End Points:
http://api.jobvite.com/v1/contacts
https://api.jobvite.com/v1/contacts
API Required Parameters:
api: API Key !
sc: API Secret
Example API Invocation: !
http://api.jobvite.com/v1/contacts?api=<apikey>&sc=<secret>
Request JSON Body Fields (*required):
PARAMETER
userEm ail*
Im portDuplicates
notes
tags
Contacts*
DESCRIPTION
The email address used to log into Jobvite.
Allows the logged in user to import contacts that are already in their Jobvite
CRM.
Allows logged in user to add a note across all imported contacts.
Allows logged in user to add tags across all imported profiles [as a
JSONArray].
List of contacts to import [as a JSONArray].
CONFIDENTIAL - Jobvite Data Services
27
Request JSON Individual Contact Parameters:
PARAMETER
firstName
middleName
lastName
company
jobTitle
tags
notes
resume
coverLetter
sourceType
sourceName
emails
homePhone
workPhone
cellPhone
address
address2
city
state
zip
country
urls
assigneTo
customFields
DESCRIPTION
First name of the contact.
Middle name of the contact.
Last name of the contact being imported.
Name of current employer for the contact.
Job title at current company for the contact.
Tags associated with the contact [as a JSONArray].
Notes associated with the contact [as a JSONArray].
Text resume for the contact.
Text cover letter for the contact.
Source of the contact.
Source details of the contact.
Email addresses for the contact [as a JSONArray].
Home phone number for the contact.
Work phone number for the contact.
Mobile phone number for the contact.
Street address for the contact.
Street address for the contact.
City address for the contact.
State address for the contact.
Zip code address for the contact.
Country address for the contact.
Web URLs associated with the contact [as a JSONArray].
Facebook profile URL for the contact.
LinkedIn profile URL for the contact.
Twitter profile URL for the contact.
Employee this contact is assigned to.
Custom data associated with the contact [as a JSONArray].
Custom Array Json input:
Name:
Value:
Curl Example:
curl -H "Content-Type: application/json" -H "Accept: application/json" -X POST -!d '<importJson>'
http://localhost:8080/backend/action/api/v1/contacts?api=<apikey>&s c=<secret>
Where json:body could be:
{!
userEmail: '[email protected]', //required
importDuplicates: true, // defaults to false!
notes: "blahblahblah",!
ags: ["sons","vkags",""],!
CONFIDENTIAL - Jobvite Data Services
28
contacts: [{ //required
firstName: "Jane",!
middleName: "X.",!
lastName: "Do",!
company: "Jobvite",!
jobTitle: "Engineer",!
ags: ["Programmer","Java"],!
notes: ["Looking for a career Change","specializes in cloud technologies"],
resume: ,
coverLetter: ,!
sourceType: "Web Search",!
sourceName: "LinkedIn",!
emails: ["[email protected]","[email protected]"],
homePhone: ,!
workPhone: ,!
cellPhone: ,!
address: ,!
address2: ,!
city: ,!
state: ,!
zip: ,!
country: ,!
urls: ["www.google.com","www.yahoo.com"],
facebook: ,!
linkedin: ,!
twitter: ,!
assignedTo: '[email protected]',
customFields: [{name: 'blah', value: 'blah'},{name:'blah2',value: 'blah2'} ,
{ ...}]!
}
Appendices
A. http://www.hr-xml.org
B. Error codes:
101 API key & secret could not be validated.
102 format is required.
*
103 Unable to parse datestart=
*
104 Unable to parse dateend=
105 An error occurred retrieving candidates.
106 Unknown format requested.
107 Error preparing candidate information.
108 Unrecognized candidate state (parameter wflowstate) in the request.
updateCandidates errors:
201 Cannot load the company from the json.
202 The data in the request is not a JSON array.
CONFIDENTIAL - Jobvite Data Services
29
203
204
205
206
207
208
*
“applicationId” item is missing from the JSON.
Cannot find the application from the “applicationId”.
Cannot find the candidate.
Candidate is not a candidate for this company.
Cannot determine a workflow state from the “wflowstate” item.
Error updating the candidate’s record in the database.
Incorrect format value.
CONFIDENTIAL - Jobvite Data Services
30
