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.
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)
- Header list
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.
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.
Requests and responses within the Personio API interface are based on the JSON and XML data formats.
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.
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:
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:
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:
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:
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:
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