The Personio Recruiting API

 

This article contains useful information about the Recruiting API interface provided by Personio.

Please note that you should consult an IT expert for integrating the Recruiting API. Technical documentation on our API with all associated parameters and detailed information can be found in our Developer Hub.

 

The Basics of the API

Personio offers you the possibility to retrieve content from Personio via an XML feed in order to publish it on your own career page. Data from candidates who apply via your career page can be transmitted to Personio via the API interface. Click here to find out how to ensure that candidate data is continuously transmitted to your Personio account.

An API (application programming interface) is a set of commands located on a server. These commands are used to make data for various requests available to external, requesting programs. The Personio Recruiting API is a program provided by Personio that runs permanently on the Personio server.

When two systems are connected via an API, we call it an integration. In an integration there are two sides: the server (in this case Personio) and the client (your website), which is controlled by a user (e.g. your system administrator).

 

HTTP Communications Protocol 

Unlike people, who are able to make sense of different syntaxes and wordings, the server and client need unambiguous language in order to communicate with each other. This language is called HTTP (Hyper-Text Transfer Protocol). It is a set of rules that say how requests and responses must be configured so that a computer can read them.

For example, if you type the URL http://example.com into your browser to access a website, you are telling your browser to apply the rules of the HTTP protocol. The browser then communicates with the server hosting the website via this protocol and its rules.

 

Client Request

Communication in HTTP is structured by requests from the client and responses from the server. Both the retrieval of job details from the XML feed and the sending of an application to Personio constitute requests.

The client submits four request components to send a functioning request:

  • URL (Uniform Resource Locator)
  • Method
  • Header list
  • Body

The URL is a unique address where the API can be found.

The URL for transmitting applications to Personio is: https://api.personio.de/recruiting/candidate. The last part of the URL is the endpoint. The name of the endpoint can be freely chosen, but should give an idea of the actions it allows to be performed.

The URL for retrieving your jobs from Personio is youraccount.jobs.personio.co.de/xml.

The method tells the server what kind of action the client expects from the server. Personio allows the POST and GET methods. The POST method inserts applications into Personio, while the GET method allows you to retrieve jobs from Personio.

The header list provides meta data about each request, e.g. the user agent header, which informs the server about the kind of device the client request comes from. The server returns the data in a format suitable for the client based on the information received from the header.

The body of a request contains the parameters which the client tries to send or retrieve respectively. Find more detailed information about the parameters relevant for Personio further below in this article.

 

Server Response

After the server receives a request from the client, it sends back a response according to the rules of the HTTP protocol. The server's response includes a numeric status code, which shows whether the server was able to answer the request and if not, why not. If a response can be provided, its body contains the data which have been requested or sent respectively, while the header contains meta data such as information about the data format.

Common status codes include: 

  • 200: Success - everything worked out
  • 400: Bad Request - Something went wrong. The application has not been forwarded to Personio or data could not be retrieved from the XML feed. In addition to this status code, Personio also supplies a specific reason why the request failed.

Status codes are universal and can be universally interpreted. Click here for a list of all status codes output by Personio.

After a response is sent to the client, the communication is completed. The server then waits until it receives another request. When the client sends another request, the process starts again.
 
 

Data Formats

Requests and responses within the Personio API interface are based on the JSON and XML data formats.

JSON (JavaScript Object Notation) is a data format with a simple structure which is based on the Javascript programming language.

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

The example below shows a POST request, in which "company_id" is a key and "12345" the associated value.

{
"company_id":"12345",
"access_token":"234ec563407665bc23000",
[...]
"first_name": "Franz-Alois",
[...]
}
The XML data format meets similar requirements as JSON. For an informative example of the XML (Extensible Markup Language) programming language have a look at your Personio XML feed. 

Both client and server use the "content type" header to indicate the data format of the body of the message. The client uses the "accept" header to define the data format it needs to be able to accept or read responses from the server. If the server cannot supply the accepted data format, it returns an error message.

 

The Personio Recruiting API 

The Personio Recruiting API allows you to transmit applications to Personio (POST) and retrieve positions (GET). Your access data, which you need for each request, can be found at Settings > API > Credentials. You can find both your company ID and your recruiting API access token here:

rec-api-credentials_en-us.png

 

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 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/recruiting/applicant.

Mandatory parameters for the body of the POST request are: 

  • company_id (found at: Settings > API > Credentials
  • access_token (found at: Settings > API > Credentials
  • job_position_id (shown at: youraccount-jobs.personio.de/xml) – or for Personio accounts created on or after November 25, 2020, use the URL youraccount.jobs.personio.de/xml.
  • first_name (transferred via the candidate form)
  • last_name (transferred via the candidate form)
  • email (transferred via the candidate form)

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

Personio also accepts optional parameters such as: 

  • birthday (transferred via the candidate form) or
  • documents (transferred via the candidate form)

You can transmit candidate documents either in bulk in a so-called array or individually. Click here for further details. 

You can also use the API to import values for all of the candidate attributes you have individually created in Settings > 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

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

rec-api-recruiting-channels_en-us.png

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

Developers will need about 1–2 days to implement an API integration.

Further information about Personio's attendance API and personal data API can be found here:

Setting up Personio's Attendance API

Data Access for the Personal Data API

 

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