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 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 | integer | no |
external_posting_id | When using multiposting, this is the | 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] [array of category names] | no |
documents | Array of documents that are attached to this application | [array of files] | 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] | no |
message | Initial message from the applicant | string | no |
tags | Existing tags (new ones cannot be created via API) | [array of strings], e.g. | no |
birthday | Birthday of the applicant | date according to ISO 8601 format | 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 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