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):

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 

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: 

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:

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:

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.