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 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 job 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)

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

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

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. with the absolute path to the document.

[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

flags

Array of flags to attach to this application

[string]

no

birthday

Birthday of the applicant

date according to ISO 8601 format

no

custom_attribute_{id}

Custom applicant attribute (see below)

integer

no

Custom applicant attributes that were created individually can also be passed.

You can find the unique parameter names of these attributes in your Personio account under https://mycompany.personio.de/configuration/recruiting/applicants

Example of a custom applicant attribute with the unique name `custom_attribute_69`

Example of a custom applicant attribute with the unique name custom_attribute_69

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"

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.


What's Next

Embed an HTML form for applications into your jobsite

HTML form for Applications