Introduction

Required Headers

In Recruiting API we used a token based Authorization.

The token can be found under Settings > Integrations > API Credentials > Recruiting API Key.

This token allows creation of applications in your account. When building your own career page, you should make requests to our endpoints from a backend service rather than from your frontend directly so as not to expose this token. Doing this from a browser is not supported and will result in CORS errors.

Authorization: Bearer our-token

Each endpoint also requires the company id to be passed explicitly as a header

X-Company-Id: 123

You can find this information for your own company at the following url:

https://{YOUR_COMPANY}.personio.de/configuration/api/credentials/management

Please substitute {YOUR_COMPANY} with your assigned hostname.

We also strongly recommend the usage of the Partner/Application ID headers described in this section

Uploading documents

To include documents in an application, you must first upload them one by one using the documents endpoint. Each response will contain a uuid that you can later use in the request body of the applications endpoint. Example:

You upload the file via de documents endpoint and get the following response:

{
  "extension": "pdf",
  "mimetype": "application/pdf",
  "original_filename": "My_CV.pdf",
  "uuid": "66121e48-2a2d-4158-a21d-f36c3453df1a",
  "size": 39710
}

You use the uuid from this response in the request body of the applications endpoint to attach this document to the application you want to create. Here you must also specify the category for each document:

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "job_position_id": 123,
  "files": [
    {
      "uuid": "66121e48-2a2d-4158-a21d-f36c3453df1a",
      "original_filename": "My_CV.pdf",
      "category": "cv"
    }
  ]
}

Rate limiting

Both the documents and the applications endpoints have a rate limit of 20 requests in 60 seconds per company. After reaching this limit, you will need to wait 60 seconds before you can submit more requests.