The purpose of this document is to provide an overview of changes to our Public API. For more detailed information please consult our API documentation pages.
New authentication and authorisation mechanism requires to use new API keys, so your existing key will not work with the new API version. You will be able to continue using the old API version until it’s sunset on December 1st, 2023 or you’re ready to switch.
API now uses
Bearerauthentication scheme instead of Basic Auth.
API access can now be scoped with different endpoints requiring different scopes on the API key to function. Scopes allow you to limit access to your data with our API. Assigning all scopes to a key is possible, but not recommended if you can only limit it to the endpoint you want to use.
API now uses JSON format for requests as well as responses. The only exception are file upload endpoint that use multipart upload format.
All endpoints returning list of objects are now using a more intuitive pagination mechanism
All date-time fields are now in ISO 8601 UTC format and UNIX timestamp as before. We believe it makes them easier to read and just as easy to parse in your application.
Changes to endpoints
Following sections are named after endpoint names from the documentation of the first API version.
Create an application
We simplified the process of adding new applications through the API. It’s no longer necessary to supply candidate IDs.
candidatefield was removed
contentfields was replaced by
custom_datafield to allow to post key-value array of custom data with the application. Fixed fields, e.g.
experiencehave been promoted to main request fields
additional, optional fields have been added to allow you to store more data on the application
Update an application
All updates are now partial, so there’s no need to resend the entire job application object in the request payload. It is also possible to move the application to a different stage by changing the
stage property or to move the application to a different vacancy by updating the
Retrieve an application
Similar to create endpoint, we tried to make the response simpler by removing the candidate object and including more fields.
candidateproperty was removed. Its properties were moved to
personal_infofield, when appropriate.
contentproperty was removed and it’s fixed values, e.g.
education, have been moved to the main response. New property called
custom_datawas introduced to explicitly serve as a key-value store for properties non covered by Job Application object schema
stageobject was added to indicate the hiring process stage of the applicant
jobobject was replaced by
vacancy_idfield to remove redundant information
noteslist can be requested to retrieve note objects attached to the application
filesproperty was added. It contains an array of file objects with temporary download links to files associated with the application. Files now also includes files uploaded with assignments.
List all applications
Additional fields were added.
It’s now possible to create sensitive notes using the API.
is_sensitivefield was added to allow using the Sensitive Notes feature
bodyfield was renamed to
namefield was renamed to
Is now possible through
include parameter on the job application endpoint.
Was removed to unburden you from differentiating between candidate and job application resources. Now you only deal with job application objects and endpoints.
Creating a file
Additional validation and error messages were added. It is also now necessary to specify file type when uploading, which means you can upload more than just resume files.
List all files
Endpoint was replaced by
files property on the job application detail object.
Deleting a file
Endpoint was removed for the time being.
List all jobs
Jobs are now referenced to as “vacancies” now (see data schema: Vacancy).
tmp_locationare replaced by optional
locationfields, both of them are objects (see data schema for more details on their fields and request parameters on how to include them in results).
there are new fields, e.g.
descriptioncontaining a short description of the vacancy.
active_timefield was removed
stageslist property was added
Delete job application
It is now possible to remove job applications through the API. In case of a mistake, deleted applications will also be temporarily retrievable via the Recently deleted feature in the Homerun app.
Post job application photo
It’s now possible to upload an applicant photo. Only one can be attached to a job application at a time, so subsequent uploads will replace any previously uploaded photo. Uploading a photo will also automatically update job application’s