The Personio Recruiting API

 

This article contains useful information on the Personio recruiting API interface.

Please note that the integration of the recruiting API should be carried out by an IT professional. The technical documentation for our API, including all parameters and detailed information, can be found in our developer hub.

 

Our API - The Basics

Personio offers you the option of accessing content from Personio via an XML feed in order to publish it on your own career page. Candidates who apply through your career page can be integrated into Personio via the API interface. You can find an article summing up how Personio can communicate with your career site here.

An API (application programming interface) is a set of commands located on a server. External programs can use these commands to gain access to data for various requests. The Personio recruiting API is made available by Personio, on the Personio server, on a permanent basis.

The connection of two systems via an API is known as an integration. An integration has two sides: the server (in this case Personio) and the client (your website), which is controlled by a user (for example your systems administrator).

 

The HTTP Communication Protocol

Unlike people, who can interpret the sense of different word orders and formulations, servers and clients require unambiguous terminology in order to communicate with each other. This is known as HTTP (Hypertext Transfer Protocol) and is a collection of rules that say how, for example, requests and responses must be configured in order to make them computer-readable.

If, for example, you enter the URL http://example.com into your browser in order to visit a website, you are specifying that your browser should follow the HTTP protocol rules. The browser then uses the protocol and its rules to communicate with the server that makes the website available.

 

The Client Request

Communication in HTTP is structured around client requests and server responses. Both calling up a position from the XML feed and sending an application constitute requests.

In order to send a valid request, the client transmits four request components:

  • URL (Uniform Resource Locator)
  • Method
  • List of headers
  • Body

The URL is a unique address at which the API can be reached.

The URL to submit applications in Personio is: https://api.personio.de/recruiting/applicant. The last part of the URL is the end point.

The naming of the end point is arbitrary, but should give some indication of the actions that can be carried out.

The URL to call up your positions from Personio is myaccount-jobs.personio.de/xml.

The method communicates to the server what type of action the client expects from it. Personio allows the methods POST and GET. The POST method enters applications into Personio, while GET allows positions in Personio to be called up.

The list of headers makes meta-information about the request available such as, for example, the header User-Agent. This tells the server what kind of device the requesting client is using. Based on the header information, the server can send the data back to the client in a suitable format.

The body of the request contains the parameters that the client is trying to send or call up. You will find more precise information on the parameters that are relevant for Personio later on in this article.

 

The Server Response

After the server has received the client’s request, it sends a response according to the rules of the HTTP protocol. The server’s response contains a numerical status code. This communicates whether or not the server can answer the request and if not, why not. If it can, the body of the response will contain the requested or sent data, while the header delivers meta-information, for example on the data format.

Common status codes include:

  • 200: Success – everything worked
  • 400: Bad Request – something went wrong. Either the application couldn’t be submitted to Personio or the data could not be called up from the XML feed. In addition to this code, Personio also gives a specific reason for the failure of the request.

Status codes are universal and can always be understood. You can find a list of all the Personio status codes here.

After a response has been sent to the client, the communication is complete. The server stops and waits until another request is received. If the client sends a further request, the process starts again from the beginning.

 
 

Data Formats

Requests and responses over the Personio API interface use the JSON and XML data formats.

JSON (JavaScript Object Notation) is a simply structured data format based on the JavaScript programming language.

JSON provides a simple standard for encoding data. The format saves data in a structured form that can be read by both humans and machines. To do so, it uses key-value pairs and formatting with curly brackets.

Below, you will see an example of a POST request, in which ‘company_id’ is a key and ‘12345’ is the associated value.

{
"company_id":"12345",
"access_token":"234ec563407665bc23000",
[...]
"first_name": "Franz-Alois",
[...]
}

The XML data format meets similar requirements to JSON. You can find a clear example of the XML (Extensible Markup Language) programming language in your Personio XML feed.

Both client and server use the ‘Content-Type’ header to communicate which data format the body is written in. The client uses the ‘Accept’ header to indicate the data formats it will accept or can read as responses from the server. If the server cannot deliver the accepted data format, it sends back an error message.

 

The Personio Recruiting API 

You can use the Personio recruiting API to submit applications over Personio (POST) and call up open positions (GET). You can find the access data that you will need for each request under Settings > API > Credentials. These include both your company ID and your recruiting API access token:

Recruiting_Credentials.png

 

Retrieving Positions from Personio

You can use a GET request to retrieve information on your published positions from your XML feed and embed them into your website. The underlying URL is meinaccount-jobs.personio.de/xml. Further information, including the benefits of and the technical background on the XML feed can be found here.

Once your positions are displayed on your career site, the incoming applications will need to be submitted to Personio via requests and responses:

Screen_Shot_2018-09-16_at_09.58.34.png

 

Submitting Applications to Personio

Use the following URL to send a POST request to Personio: https://api.personio.de/recruiting/applicant.

The required parameters for the POST request are:

  • company_id (located in: Settings > API > Credentials)
  • access_token (located in: Settings > API > Credentials)
  • job_position_id (located in: meinaccount-jobs.personio.de/xml)
  • first_name (submitted via the applicant screen)
  • last_name (submitted via the applicant screen)
  • email (submitted via the applicant screen)

We recommend automatically pulling the job_position_id from the activated XML feed (GET) and integrating it into the POST request.

In addition, Personio accepts optional parameters, e.g.:

  • birthday (submitted via the applicant screen) or
  • documents (submitted via the applicant screen)

The applicant’s documents can either be collected in what is known as an array or submitted individually. You can find further details on this here.

Additionally, you can use the API to submit values to Personio for all the applicant attributes that you created individually under Settings > Recruiting > Applicant. To do so, you link to the applicant attribute via the API attribute name. This can be found in the edit mode of the applicant attribute:

Applicant_attribute.png

In addition, you have the option of transmitting the channel the application was submitted over.

To do so, integrate the recruiting_channel_id parameter into your POST request. The channel ID can be found under Settings > Recruiting > Channels:

Recruiting_Channels.png

You can find a complete list of all parameters and additional information in our developer hub.

A developer needs approximately 1-2 days to implement an API integration.

 

Can't find what you're looking for?

We are happy to help you! Just write us a message with your questions and we will get back to you as soon as possible.

Submit a request

Comments

0 comments

Article is closed for comments.

    Topics of this article