Passing applications to Personio

Description of the applicant endpoint of the Personio Recruiting API

📘

The API access token as well as the company ID can be found in your Personio account under Settings > API.

API post parameters

A POST containing a multipart/form-data payload must be sent to https://api.personio.de/recruiting/applicant. The request can contain the following parameters:

name

description

type

required

company_id

Your company ID (see above)

integer

yes

access_token

API Access token for your company account (see above)

string

yes

job_position_id

ID of the published job position that this application is for (from XML feed)

integer

yes

first_name

First name of the applicant

string (max:255)

yes

last_name

Last name of the applicant

string (max:255)

yes

email

Email address of the applicant

string (max:255)

yes

gender

Gender of the applicant

Enum (male | female | diverse | undefined)

no

recruiting_channel_id

ID of the recruiting channel that this applicant applied through recruiting_channel_id has to match the id of a channel you created in Personio

integer

no

external_posting_id

When using multiposting, this is the pid forwarded (usually as a query param) by the external job board site

integer

no

phone

Phone number of the applicant

string (max:255)

no

location

Current location of the applicant

string (max:255)

no

salary_expectations

Salary expectations of the applicant (Will not be parsed, so you can transfer values like "minimum 50k")

string (max:255)

no

available_from

Date from which this applicant is available from

string (max:100)

no

categorised_documents

Array of files and category names.

Each file in the array should be an upload stream.

Each category in the array should be a category name.

You can check a request example in the "A note on categorised documents" section.

[array of files]
allowed extensions are 'pdf', 'docx', 'doc', 'jpg', 'png', 'txt', 'jpeg', 'odt', 'ods','xlsx', 'rtf', 'xls', 'pptx', 'ppt', 'gif', 'tif', 'tiff', 'bmp', 'csv', 'rar', 'gz', 'zip', '7z'
filesize per document < 20M
total post size < 64M

[array of category names]
allowed values are 'cv', 'cover-letter', 'employment-reference', 'certificate', 'work-sample' or 'other'

no

documents

Array of documents that are attached to this application

[array of files]
allowed extensions are 'pdf', 'docx', 'doc', 'jpg', 'png', 'txt', 'jpeg', 'odt', 'ods','xlsx', 'rtf', 'xls', 'pptx', 'ppt', 'gif', 'tif', 'tiff', 'bmp', 'csv', 'rar', 'gz', 'zip', '7z'
filesize per document < 20M
total post size < 64M

no

documentn

Alternatively to an array (see above), documents can also be transferred individually numbered document1, document2, etc (the numbering starts at 1) with the absolute path to the document in an upload stream.

[file]
allowed extensions are 'pdf', 'docx', 'doc', 'jpg', 'png', 'txt', 'jpeg', 'odt', 'ods','xlsx', 'rtf', 'xls', 'pptx', 'ppt', 'gif', 'tif', 'tiff', 'bmp', 'csv', 'rar', 'gz', 'zip', '7z'
filesize per document < 20M
total post size < 64M

no

message

Initial message from the applicant

string

no

tags

Existing tags (new ones cannot be created via API)

[array of strings], e.g.
[“tag_1”, “tag_2"]

no

birthday

Birthday of the applicant

date according to ISO 8601 format
(YYYY-MM-DD)

no

custom_attribute_{id}

Custom attributes may be of "text", "date" or "list of options".

For more informations check the text below.

Custom attribute of "date" type:

date according to ISO 8601 format
(YYYY-MM-DD)

Custom attribute of "text" type:

string

Custom attribute of "list of options" type:

custom_option_{id}, for more information check the text below.

no

The custom candidate attributes, created in the recruiting settings, can be provided in the API.

You can find the unique field/option names of these attributes in your Personio account under https://{MY_COMPANY}.personio.de/configuration/recruiting/attributes as shown in the image below.

A note on categorised documents

Categorised documents are represented as a multidimensional array.
Each object has two fields: 'file' and 'category'. The 'file' field contains an upload stream. The 'category field' contains the category name, the allowed category names are listed in the table above. An example in pseudo code would be:

val request = HttpRequest()

// Example of a CV file
request.body["categorised_documents[0]['file']"] = UploadFile('path-to-cv-file')
request.body["categorised_documents[0]['category']"] = 'cv'

// Example of a cover letter file
request.body["categorised_documents[1]['file']"] = UploadFile('path-to-cover-letter')
request.body["categorised_documents[1]['category']"] = 'cover-letter'

A note on documents
Documents need to be submitted as an upload stream not just with a plain file path. An example in pseudo code would be:

val request = HttpRequest()
request.body['document1'] = 'path-to-file' ----> WRONG
request.body['document1'] = UploadFile('path-to-file') ----> CORRECT

A note on spamming
Please be aware that the access_token in company with your company_id allows the creation of applications in your account. When building your own career page, we would recommend that you call our endpoints from a backend service, rather than from your frontend directly, in order to avoid making the token publicly accessible. In addition to this, we recommend the inclusion of a captcha or similar into your own career page to avoid bot applications.

Rate limiting
Our applicant API is a rate limit of 100 applications in 60 seconds per IP address. After submitting this amount of applications, you will need to wait 60 seconds before you can submit more applications.

Validation and API responses

These are the possible API responses:

Response code

Cases

Message

200: Success

Everything went well and the application was created in Personio.

"Applicant successfully applied to the job position."

400: Bad Request

Something went wrong and the application was not created in Personio. Specifically, the following cases can lead to an error 400:

"The given data failed to pass validation."

File too large

"Unsupported extension or file greater than 20Mb."

Unsupported file extension

"Unsupported extension or file greater than 20Mb."

Required field empty (e.g. name, email)

"The {field_name} field is required."

Invalid custom attribute (custom attribute ID does not exist)

"Parameter {parameter_name} does not exist."

Invalid job position

"Could not find the job position."

Applicant already applied

"Applicant already applied to this position."

422: Unprocessable Entity

Something went wrong and the attachments could not be processed at this moment. Please try again.

"There was a problem while processing attachments. Try again later"

The job position was not published and thus the API cannot accept any applications for this position

"Job position not published"

403: Not Authorized

Something went wrong and the application was not created in Personio. In this case, the API access token provided doesn't match the company ID.

"This action is unauthorized."

500: Internal Server Error

Something went wrong and the application was not created in Personio. This particular case the transaction failed due to an issue on Personio's end, e.g. server error.

"Something went wrong, please try again later!"

503: Service Unavailable

The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.

Updated 3 days ago


What's Next

Embed an HTML form for applications into your jobsite

HTML form for Applications

Passing applications to Personio


Description of the applicant endpoint of the Personio Recruiting API

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.