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.

General changes

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 Bearer authentication 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.

Applications endpoints

Create an application

We simplified the process of adding new applications through the API. It’s no longer necessary to supply candidate IDs.

Changes:

candidate field was removed
content fields was replaced by custom_data field to allow to post key-value array of custom data with the application. Fixed fields, e.g. education and experience have 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 vacancy_id property.

Retrieve an application

Similar to create endpoint, we tried to make the response simpler by removing the candidate object and including more fields.

Changes:

candidate property was removed. Its properties were moved to personal_info field, when appropriate.
content property was removed and it’s fixed values, e.g. education, have been moved to the main response. New property called custom_data was introduced to explicitly serve as a key-value store for properties non covered by Job Application object schema
stage object was added to indicate the hiring process stage of the applicant
job object was replaced by vacancy_id field to remove redundant information
optional notes list can be requested to retrieve note objects attached to the application
files property 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.

Notes endpoint

Creating notes

It’s now possible to create sensitive notes using the API.

Changes:

is_sensitivefield was added to allow using the Sensitive Notes feature
body field was renamed to note
name field was renamed to display_name

Listing notes

Is now possible through include parameter on the job application endpoint.

Candidates endpoint

Was removed to unburden you from differentiating between candidate and job application resources. Now you only deal with job application objects and endpoints.

Application files

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.

Jobs endpoint

List all jobs

Jobs are now referenced to as “vacancies” now (see data schema: Vacancy).

Changes:

tmp_departmentand tmp_location are replaced by optional department and location fields, 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. description containing a short description of the vacancy.
active_time field was removed
optionals stages list property was added

New endpoints

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 photo property.

How do I set up or change an application form?

How do I add multiple candidates?

How do I let applicants upload a resume, portfolio or cover letter?

Understanding the candidate profile

The difference between a trial and a paid Homerun account