The Personio Recruiting API

This article explains what a Public Application Programming Interface (API) is, what can you use the Recruiting API for, and how to generate API credentials for it.

 

What is a Public API in Personio?

APIs allow data to be exchanged between Personio and another service or tool. This way, you can build connections between Personio and your own databases, or set up integrations with third-party providers that are available in the Personio Marketplace. Personio offers three Public APIs: Recruiting, Personnel Data and Custom Reports

Note
To integrate the Recruiting API, you should consult an IT expert.


What can you do with the Personio Recruiting API?

The Personio Recruiting API, in particular, allows the exchange of data concerning positions and candidates:

▶︎ Retrieving positions from Personio (no credentials required): You can pull data from positions that you published in Personio via XML, and display it on your own company career page. Learn more about integrating positions from Personio into your company website via XML.

▶︎ Transmitting applications to Personio (credentials required): Automatically transfer applications and candidate data (such as candidate name, application date, documents, …) from your own application form, into Personio and create a candidate profile. Learn more about transmitting candidate data to your Personio account.

 

Get your API credentials

For this Public API, your credentials are generated by the system and are available in your account. You will find them in Settings > Integrations > API Credentials > Recruiting API key. There, you can find both your company ID and your recruiting API access token.

 

Retrieving positions from Personio

Use a GET request to retrieve information about your published positions from your XML feed and integrate this information into your website. The URL for doing this is youraccount.jobs.personio.de/xml.

Once your jobs are displayed on your career page, incoming applications need to be transmitted to Personio via the Personio Recruiting API (in the form of requests and responses):

rec-api-overview_en-us.png

 

Transmitting applications to Personio

To send a POST request to Personio, use the following URL: https://api.personio.de/v1/recruiting/applications

 

Mandatory parameters for the body of the POST request 

Parameter Notes
company_id Can be found at: Settings > Integrations > API Credentials
access_token Can be found at: Settings > Integrations > API Credentials
job_position_id Can be found at: youraccount.jobs.personio.de/xml
first_name Transferred via the application form
last_name Transferred via the application form
email Transferred via the application form
application_date Transferred via the application form
phase Can be system or custom phases

 

Tip
We recommend that you retrieve the job_position_id automatically from the activated XML feed (GET) and integrate it into the POST request.

 

Optional parameters for the body of the POST request

Personio also accepts the following optional parameters: 

Parameter Notes
birthday Transferred via the application form
documents Transferred via the application form

 

Notes
▶︎ You can transmit candidate documents either in bulk in a so-called array or individually. Learn more about this in our Developer Hub.
▶︎ The maximum size per document received via the Recruiting API is 20 MB.
▶︎ The following formats are supported : pdf, docx, doc, png, jpg, jpeg, txt, odt, ods, xlsx, rtf, xls, pptx, ppt, gif, tif, tiff, bmp, csv, rar, gz, zip, 7z, mp4, 3gp, mov, avi, wmv.

 

Transmit custom attributes

You can also use the API to add values for all of the candidate attributes you have individually created in Settings > Recruiting > Recruiting > Attributes into Personio.

To do this, you need to link the candidate attribute via the API attribute name. You can find this name in the edit mode for the candidate attribute:

rec-api-applicant-attribute_en-us.png

 

Transmit the application channel

You can also transmit the channel from which the application was received.

To do this, integrate the parameter recruiting_channel_id into your POST request. You can find the channel ID at Settings > Recruiting > Recruiting > Channels:

rec-api-recruiting-channels_en-us.png

Note
If you are posting a position on an external job board, you will need to add the parameter external_posting_id into your POST request. This will allow you to track from which job board the application comes from. You can find more information in our Developer Hub: Creating applications in Personio

 

Technical documentation

A full list of all parameters and further relevant information can be found in our Developer Hub.

 

Comments

0 comments

Article is closed for comments.

    Topics of this article