What is an API?
An API is a "software development toolkit" that provides software developers with the ability to perform a very specific set of functions within a cloud based application. Almost all well known websites and applications have their own APIs available for use. Examples include: Google Maps, YouTube, Facebook, Twitter, and Salesforce.com.
What is the JazzHR API?
The JazzHR API is simply our API that we provide to all of our customers. It allows you to perform a very specific set of functions within your JazzHR account. In the hands of your software developers, they can write simple software programs to communicate with objects in your JazzHR account and automate tasks between other cloud based applications.
The JazzHR API is included with all subscription levels. The API documentation can be found here: http://www.resumatorapi.com/v1/
What is an API Key?
API access is secured for every customer of JazzHR. After all, you wouldn't want unauthorized users accessing the data in your account, right? An API Key is a complex alphanumeric string used to unlock the door and give only authorized users access to your account via the API.
Where can I find my API Key?
Your API Key can be found in the Integration tab under Settings. Only Super Administrators, Recruiting Administrators, or Developers have visibility of the API Key.
What sort of interactions can be performed using the JazzHR API?
Our API allows you to interact with various objects such as:
- Create new job postings
- Extract records of your existing job postings
- Add new candidates and resumes/files into your account
- Add notes/comments to candidate profiles
- Add categories to candidates
- Extract records of your existing candidates
- Add answers to a questionnaire
- Extract answers from a custom questionnaire
- Add files to a candidates profile
A full list of the functions and objects that can be interacted with can be found here: http://www.resumatorapi.com/v1/
What would someone use these interactions for?
That is the most exciting part of APIs! These functions can be programmed into a small software application that can be used to automate tasks by creating an integration or "bridge" between your JazzHR account and other cloud based software applications such as: CRMs, HRIS, onboarding, payroll, and skills assessment.
APIs enable you to choose the best software for your needs (ATS, CRM, HRIS, etc.) and integrate the systems together so that data can flow back and forth automatically without any manual work on the users of the system.
What would an example integration between JazzHR and another cloud based system look like?
The three examples below outline a the simplified logic that would be programmed into an integration with different cloud based systems.
Job Board Example
JazzHR's API can be used to syndicate job postings to job boards which are not directly integrated with JazzHR.
With the JazzHR API, your developers could build a software integration to syndicate jobs from your JazzHR account to another job board:
- Query the JazzHR API at some chosen interval (every day, once a week, etc.)
- Look for job records which have been recently created.
- If job records are found which match your criteria, extract the job fields (title, description, department, employment type, city, state, location, job_url, etc.)
- Make a call to the job board's API and create a new job posting using the job fields (title, description, department, employment type, city, state, location, job_url, etc.) that were extracted from JazzHR.
- Append the job_url with a tag denoting the source. For example: ?source=PAStateGovJobBoard
- As candidates apply to the job they will appear into your JazzHR account tagged with the job board's source for easy tracking.
Payroll* System Example
Let's pretend your company chose JazzHR as your ATS and ZenPayroll to manage payroll operations for new and existing employees.
As candidates apply to JazzHR, you can capture all of the pertinent application information needed to screen candidates and move them to a hiring decision. Once you've made a hiring decision, you will need to move those candidates (and their relevant information) into your payroll system.
With the JazzHR API, your developers could build a software integration between the JazzHR and ZenPayroll which performed the following functions:
- Query the JazzHR API at some chosen interval (every day, once a week, etc.)
- Look for candidate records which match certain criteria. Workflow Status = Hired
- If candidate records are found which match your criteria, extract the candidate records (first name, last name, email, address, phone, job title, etc.)
- Make a call to ZenPayroll's API and create new employee records (first name, last name, email, address, phone, job title, etc.) in your account using the data records that were extracted from JazzHR.
This is a very simplified version of an integration, but you can see how it automates the process of moving records of hired candidates into the payroll system.
*This same example process can be used for integrating with CRM, HRIS, and Onboarding systems.
Skills Assessment Example
Let's pretend your company chose JazzHR as your ATS and has chosen Classmarker to send out skills assessments to qualify and screen candidates.
As candidates apply to JazzHR, you may want to automatically create User accounts for them in Classmarker so you can send out skills assessments.
With the JazzHR API, your developers could build a software integration between the JazzHR and Classmarker which performed the following functions:
- Create 2 categories in JazzHR: "Test Passed" and "Test Failed"
- Query the JazzHR API at some chosen interval (twice a day, every day, etc.)
- Look for candidate records which match certain criteria. Workflow Status = New
- If candidate records are found which match your criteria, extract the candidate records (prospect_id, first name, last name, email)
- Make a call to Classmarker API which creates a new User record (user_id, first_name, last_name, email). The objects in JazzHR and Classmarker would be linked by key ids: prospect_id in JazzHR and user_id in Classmarker
- Once a User object has been created in Classmarker, email skills assessments/tests to the Users and wait for them to be completed.
- Once a test is completed, make a call to the Classmarker API to extract the test results records (user_id, test score, results)
- Evaluate the test results and determine if the User passed or failed the test
- Make a call to the JazzHR API to add either a "Test Passed" or "Test Failed" category to the candidate record in JazzHR
- Make a call to the JazzHR API to add the actual test results and score as a Note to the candidate profile
As your hiring managers or recruiters are working in JazzHR, they can filter candidates in bulk by searching for categories of "Test Passed" or "Test Failed". Once a filtered list of candidates are found, you can bulk move the candidates into the next appropriate workflow stage. If Test Passed, move to Phone Screen. If Test Failed, move to Not a Fit.
How long does it take to build one of these integrations?
This depends on the scope and complexity of the integration you are building. However, for a competent developer, one who is familiar with API development, a typical integration should take about 80 man hours.
Is it worthwhile to build one of these integrations?
JazzHR recommends building an integration for customers who are doing high volume recruiting. High volume recruiting is 15 or more hires a month. If your team isn't doing high volume recruiting, the cost of building the integration actually outweighs the gains that are achieved from it. Development resources can be expensive and wouldn't justify the time saved (a few minutes here and there) from having a team member manually performing the tasks you aim to automate using an API integration.
I don't have access to a developer. Can I pay JazzHR, to build one of these integrations for me?
Unfortunately, at this time, JazzHR does not offer custom development services to our customers. We can provide a list of known developers who have experience building integrations using the JazzHR API.
How would I know if an integration is possible between a certain software and JazzHR?
You would need to ask the software provider if they have an API available to their customers. Typically if a software provider offers an API, an integration between them and JazzHR is possible. See the question below for a list of known systems that have an API possible to integrate with.
What are some known examples of other cloud based systems that JazzHR can integrate with?
The list below provides known examples of cloud based applications with an API that are able to integrate with the JazzHR API.
- CRM: Microsoft Dynamics, Salesforce.com
- HRIS: Microsoft Great Plains (GP), Namely, tribehr, Workday
- Onboarding: SilkRoad RedCarpet
- Payroll: ADP Workforce Now, ZenPayroll
- Questionnaires/Skills Assessment: Berke Assessments, Classmarker, Hackerrank, Jotform, Smarterer
This is list is not all inclusive of every cloud based software we can integrate with, these are just known examples. If you don't see one on this list and want to know if the JazzHR API would integrate with them, email our support team at firstname.lastname@example.org
What is your API rate limit?
Can I delete or change objects/records using the API?
- The API does not contain any PUT (change a record) or DELETE (delete a record) methods.
- The only methods are GET (extract records) or POST (create a new record).
Does the API limit the number of records returned per call?
Yes, each API call is limited to 100 results per page, unless otherwise specified. If you need to page through more results, append "/page/#" to the end of the request URI, where # is the page number you wish to return, starting with 1 and incrementing until there are no additional results.
Returns first 100 applicants: https://api.resumatorapi.com/v1/applicants?apikey=your_secret_key
Returns next 100 applicants: https://api.resumatorapi.com/v1/applicants/page/2?apikey=your_secret_key
Returns next 100 applicants: https://api.resumatorapi.com/v1/applicants/page/3?apikey=your_secret_key
Returns next 100 applicants: https://api.resumatorapi.com/v1/applicants/page/4?apikey=your_secret_key
Is the API encrypted (SSL/HTTPS) and secure?
Yes. While the API documentation is hosted on an HTTP web page (http://www.resumatorapi.com/v1/), any calls to the API itself are done so through a different URI (https://api.resumatorapi.com/v1/) which is secured with SSL/HTTPS. Furthermore, to make any API call, the requestor must authenticate to the API using the 32 digit alphanumeric key found in their JazzHR account.
How do I access a candidate's resume via the API?
GET /applicants/applicant_id returns two different key value pairs depending on how a candidate submitted their resume.
- If they uploaded a file, the key is: resume_link. The value of this key is a URL to download the candidate resume.
- If they pasted resume text, the key is: resume_body. The value of this key contains the raw text content of the pasted resume.