Gravity Forms Personio Premium Add-on Setup Guide

The Gravity Forms Personio Premium Add-on sends job applications from your WordPress forms straight into Personio Recruiting. When someone applies through a form, the add-on creates the candidate and the application in Personio for the job position you choose, with the first name, last name, email, phone, message, tags and the applicant attributes you map, and it uploads the CV, the cover letter and other documents and attaches them to the application. Your hiring team works in Personio as usual; nobody downloads attachments from an inbox or retypes a candidate.

It uses the official Personio Recruiting API with your own credentials: either the Recruiting API key together with your company id, or API credentials (client id and secret). Both are created by a Personio administrator in a few clicks and need no partner program or contract. The key is stored encrypted on your site, and the add-on only ever talks to Personio. This guide walks through the setup, every feed option, documents, retries, notifications and what happens when something goes wrong.

What you need

• WordPress with Gravity Forms 2.9 or newer.
• PHP 7.4 or newer with the openssl extension (standard on almost every host).
• An active license key for this add-on.
• A Personio account with Recruiting, and a Personio administrator who can open Settings → Integrations → API credentials.
• At least one published job position in Personio Recruiting.

If Gravity Forms is missing or older than 2.9, the add-on shows a notice in the WordPress admin and does nothing else, so a form is never left half connected.

Get your Personio credentials

Personio offers two ways for your own website to create applications. Pick one; you can switch later without touching your feeds.

Option 1: Recruiting API key and company id (simplest)

1. In Personio, open Settings → Integrations → API credentials.
2. Copy the Recruiting API key. This key can create applications and upload application documents, nothing else, which makes it a safe key to give a website.
3. Note your company id, the number shown on the same page.

Option 2: API credentials (client id and secret)

1. On the same API credentials page, generate new credentials and give them a clear name such as “Website application form”.
2. Give them the Recruiting write scope so applications can be created. Add the Recruiting read scope if you want the Test connection button to list your job positions.
3. Copy the client id and the client secret. Personio shows the secret only once; treat it like a password.

With API credentials the add-on asks Personio for a short-lived access token (OAuth 2.0 client credentials), keeps it encrypted for its lifetime and gets a new one when it expires. Personio has announced this as the long-term way for applications, so it is a good choice for new setups; the Recruiting API key keeps working as well.

Install and connect

1. Upload and activate the add-on in Plugins → Add New → Upload Plugin.
2. Open Forms → Settings → Personio, paste your license key and activate it. The Personio fields appear once the license is active.
3. Choose Sign in with: the Recruiting API key and company id, or API credentials. Only the fields of your choice are shown.
4. Enter the company id and the key, or the client id and secret.
5. Optional: enter your career site name, for example acme for acme.jobs.personio.de. The add-on then reads your public job feed to list open positions with their ids.
6. Click Test connection, then Save Settings.

Test connection never creates an application. With the Recruiting API key it sends Personio an empty application request: Personio checks the key and company id first and then refuses the empty request, which proves the key works without adding anything to your pipeline. With API credentials it gets an access token and reads your job list. The result shows your company id and the job positions with their ids, for example “Backend Engineer (#1834562)”. You need those ids for the feed.

The key and the client secret are encrypted with AES-256-GCM before they are saved, using a key derived from your site’s WordPress salts. They are never shown again on the settings page, never written to logs or entry notes, and removed when you uninstall the add-on. If you prefer to keep them out of the database, define GFPS_API_KEY or GFPS_CLIENT_SECRET in wp-config.php; the settings page then says the value comes from the constant.

Build the application form

Any Gravity Form can be an application form. A typical one has a Name field (first and last), Email, Phone, a drop down for the position, a paragraph field for the motivation, and File Upload fields for the CV, the cover letter and work samples. Personio needs four things for every application: a job position, a first name, a last name and an email address.

To use one form for several jobs, add a drop down whose choice values are the Personio job position ids and whose labels are the job titles. Turn on show values in the field settings to type the ids. Visitors pick a title; the add-on sends the id.

Personio accepts documents up to 20 MB in these formats: pdf, doc, docx, odt, rtf, txt, xls, xlsx, ods, csv, ppt, pptx, png, jpg, gif, bmp, tif, zip, 7z, gz, rar, mp4, mov, avi, wmv and 3gp. Set the same limits on your File Upload fields (allowed file extensions and maximum file size) so applicants see a clear message before they submit.

Create a Personio feed

Open the form, go to Settings → Personio and click Add New. A feed describes how one form becomes an application. You can add several feeds to one form, each with its own condition.

Applicant

• Job position id (required): a fixed id such as 1834562, or the merge tag of your position drop down with the :value modifier, for example {Position:4:value}.
• First name and Last name: for example {Name (First):1.3} and {Name (Last):1.6}. If your form has a single name field, map it to First name and leave Last name empty: the last word becomes the last name.
• Email (required): the merge tag of your email field.
• Phone: sent as the phone attribute of the applicant.
• Message: the applicant message in Personio, usually the motivation field. You may write text around merge tags; {all_fields} becomes a plain list of every answer (file fields are left out because the files are attached as documents).

Documents

• CV: the File Upload field with the CV, attached in the CV category.
• Cover letter: attached in the cover letter category.
• Other documents: a File Upload field, multiple files allowed, for certificates, references or work samples. Choose their category with Other documents are: certificates, employment references, work samples or other.

The select lists show only the File Upload fields of the form. Each file is uploaded to Personio on its own and then attached to the application by its reference, exactly as the Personio API describes. Up to ten documents are sent per application. Files are read only from the Gravity Forms upload folder of your site.

More details

• Attributes: map form fields to Personio applicant attributes. Pick birthday, gender, location, available from or salary expectations, or choose “Add custom key” and type the API name of a custom attribute, for example custom_attribute_4821 (Personio shows it in Settings → Recruiting → Attributes when you open an attribute). Dates must be in the form YYYY-MM-DD; for option attributes the form value must be one of the options Personio knows.
• Recruiting channel id: the channel the application came from, so Personio reports show your website as the source.
• Tags: a comma-separated list, merge tags allowed, for example website, {How did you hear about us?:12:value}. New tags are created in Personio.
• Condition: send the application only when the condition is met, for example only for one position, or only when a consent box is ticked.

What applicants see

Applicants see your normal form and your normal confirmation. The application is sent after the entry is saved, so a slow or unreachable Personio never blocks a submission and never shows an error to a candidate.

Entry notes, merge tags and notifications

Every entry gets a note that says what happened, for example “Personio: application created for job position 1834562 with 2 document(s).” Files that could not be attached are named in the same note with the reason. Errors are saved as error notes with Personio’s answer.

The entry also stores the Personio status (sent, already applied or failed), the job position id and the number of documents attached. You can show them as columns in the entry list and use them in confirmations and notifications with these merge tags:

• {personio_status}: sent, already applied or failed.
• {personio_job_position}: the job position id the application was sent to.
• {personio_documents}: how many documents were attached.

Two notification events are added to forms with a Personio feed: Personio application sent and Personio application failed. Use the first to tell the hiring manager a new candidate is waiting, and the second to alert an administrator so nothing is lost.

Retries never apply twice

Networks fail at the worst moment: Personio may create the application while the answer to your site is lost. The add-on is built so that a retry or Resend Feeds never creates a second application:

• Once an entry has been sent, the result is kept on the entry, and later runs of the same feed send nothing again.
• Documents uploaded for an entry are remembered, so a retry attaches the same documents without uploading them a second time.
• Personio refuses a second application of the same email to the same position. The add-on reads that answer as “already applied”, marks the entry as done and does not count it as a failure.
• A lock stops two runs for the same entry from overlapping.

If a candidate applies for a second position with the same email, that is a new application for another job, and it is created as usual.

When something goes wrong

The submission is always saved and the applicant always sees the confirmation. The entry gets an error note with Personio’s reason, the status becomes failed and the “application failed” notification is sent. Fix the cause, then open the entry and use Resend Feeds.

• HTTP 401: the key or company id was not recognised. Copy them again from Personio and run Test connection.
• HTTP 403 feature.public-api.disabled or feature.recruiting.disabled: the Recruiting API is not part of your Personio plan or is switched off.
• errors.job-position.not-published: the job position id does not exist or the job is not published.
• errors.attribute-validation.unknown or unknown-attribute-option: an attribute id or option in your map does not exist in Personio.
• errors.attribute-validation.invalid-date-format: a date attribute is not YYYY-MM-DD; use a Date field with that format.
• HTTP 429: Personio allows 20 applications and 20 document uploads per minute per company. Resend the entry a minute later.
• A file was not attached: the note names the file and the reason (a type Personio does not accept, empty or over 20 MB, or not found on the site). The application is still created with the other files.

When an upload itself fails (for example Personio is briefly unavailable), no application is created yet, so the candidate is never added without their CV. A Resend completes it.

Privacy and security

• The add-on calls only api.personio.de and, if you set a career site, your public job feed on jobs.personio.de (which receives no key).
• All calls use https with certificate checks, and redirects are never followed, so a key cannot be sent anywhere else.
• Keys and secrets are encrypted at rest and removed from every error message.
• Only files uploaded with the entry, inside the Gravity Forms upload folder, are ever read and sent.
• Gravity Forms keeps its own copy of the entry and files as before; use its personal data tools and your retention settings for those.

For developers

• gfps_application_input (filter): change the application values before they are sent. Arguments: the input array, feed, entry and form.
• gfps_application_sent (action): after an application was created or found as already applied. Arguments: the payload, the status, entry, feed and form.
• gfps_failed (action): after a failure, with the error text, entry, feed and form.
• gfps_file_path and gfps_upload_root (filters): for sites that keep uploads in a custom folder.
• gfps_timeout (filter): the request timeout in seconds (default 30).

Frequently asked questions

Do I need to be a Personio partner?

No. The Recruiting API key and API credentials are self-service in your own Personio account. No partner program, marketplace listing or contract is involved.

Can one form send to different jobs?

Yes. Use a drop down whose values are the job position ids and map {Position:4:value}. You can also add several feeds with conditions.

Does it update a candidate who applied before?

The Personio Recruiting API creates applications; it does not edit existing candidates. A second application to the same position with the same email is refused by Personio and noted on the entry as already applied.

Will my existing applications keep working if I change the sign-in method?

Yes. Feeds do not depend on the sign-in method. Switch in the settings, run Test connection and save.