Migrate core attributes – Personio

If you've been using Personio for a while, you likely have custom attributes set up like birthday, civil status, or nationality — fields you translate and update yourself to track employee data.

Personio is now introducing core attributes: standardised versions of these common attributes, defined and maintained by Personio. For each attribute, the input is validated according to industry standards. Our migration interface gives you a guided, controlled way to move from your custom attributes to core attributes at your own pace and without risk of data loss.

Migrating to core attributes provides you with a consistent structure that works seamlessly across integrations, reports, and product features. It is self-service and you decide which attributes to migrate, when to do it, and which of your existing employee data to carry over. Nothing changes on your account until you confirm.

This article walks you through the migration process: what to prepare, how to run it, and what to do afterwards.

New Core Attributes

The attributes available to you depend on your account setup. Gender is already a core attribute on every account and will only appear here if you also have an integration-specific gender attribute to migrate. Date of Birth is already a core attribute on most accounts, so it usually won't appear either.

Attribute	Universal ID	Definition and details
Citizenship	citizenship	The citizenship of the person Data type: Option list field Used to replace the former attribute "Nationality" Personio maintains and translates the list of available citizenships
Marital Status	marital_status	A person's marital status Data type: Option list field Used to replace former attributes like "Married? (civil status)" or "Civil status" Personio maintains and translates the list of available statuses
Personal Email	personal_email	A personal email address that belongs to the person and can be used to contact the person directly when required Data type: Email Max. 255 characters Built-in format validation to ensure the email is valid
Mobile Phone Number	personal_mobile_phone_number	The mobile phone number that can be used for logging in or receiving important notifications Data type: Phone Number Country specific formatting and validation: enforces international phone number format with a + followed by 2-15 digits, where the first digit can't be 0.
Employee ID	company_employee_id	A company's internal identifier for each employee Data type: Text field Max. 255 characters
Gender	gender	The official gender as recognized by authorities and used in legal documents Data type: Option list field Personio maintains and translates the list of available genders
Date of birth	date_of_birth	A person's birthdate as shown on official identification documents Data type: Date

Before you start

Who can perform the migration

To access it, you need Administrator rights or permission to Personal information settings in Personio.

Hinweis:
Migration is opt-in. Nothing changes on your account until you choose to act. You can migrate one attribute now and others later, at a time that suits your team.

What to prepare

The migration is a significant, one-time action that cannot be undone or re-run for the same attribute.

Personio provides you with a list of tasks to review before and after the migration. Most updates should be done after the migration. Before the migration we recommend that you review the following tasks:

Approve or reject any pending employee data changes to the attributes you plan to migrate. Pending (proposed but not yet approved) changes are lost during migration — only approved values are carried over.
Download a backup of members and permissions of all employee roles under Settings > Roles & permissions, if you are using them to define role members or custom permission rules.

Open the migration tool

Go to Settings and open the Personal Information section.
Under Setup, select Migrate to core attributes.
The migration tool opens and shows the list of available core attributes, each with a status (Not started, Progress saved, or Completed) and a Start or Continue button. Find the attribute you want to set up and select Start.

01 Improve_employee_data_EN.png

Step 1: Set up attribute

When you open a migration, you first see a preview of the core attribute, its label and description as Personio defines it.

Choose how to set up the attribute values:

Migrate values (recommended): Copy values from one or more of your existing compatible attributes. Attribute history and scheduled changes will also be migrated.
Add as an empty attribute: Create the core attribute with no data. You can fill it in manually going forward.

Option 1 (recommended): Select "Migrate values" if you want to copy values from one or more existing attributes:

Under Which existing attributes should we copy values from?, open the dropdown and select a source attribute. Only attributes that are compatible with the core attribute are shown. For Marital status, Citizenship and Gender this is restricted to ensure the option values can be copied over successfully.
To add more sources, select + Add attribute. Arrange them in order of preference using the drag handle on the left. For each employee, Personio uses the first attribute in the list that has a value. If that attribute has no value for a given employee, it moves to the next one.
Under Where should this attribute appear?, choose which section the new core attribute will be placed in. Users with access to that section will also have access to the newly added core attribute and its migrated employee data values.
Select View tasks to continue to Step 2.

Note:
The source attribute's current section(s) are shown for reference. If you place the new attribute in a different section, a task will be added in the next step to help you review access rights.

Warning:
Data format may change. Core attributes use a standardised format. For option list attributes like Gender and Citizenship, compatible values are migrated automatically. In case a value of the source attribute cannot be mapped to a valid core attribute value, the original value is carried over. After the migration it needs to be updated to a valid value manually in the employee profile for individual updates or people list for bulk updates. Find more details about updating employee data here.

Option 2: Choose "Add as an empty attribute" if you want to manually add values later:

Under Where should this attribute appear?, choose which section the new core attribute will be placed in. Users with access to that section will also have access to the newly added core attribute.
Select View tasks to continue to Step 2.

Note:
If you choose Add as an empty attribute in Step 1, no existing attributes are archived and no values are copied. The new core attribute is created in the section you selected and is immediately available on employee profiles. You can start capturing data in it going forward.

02 Set_up_attribute_EN.png

Step 2: Complete tasks

This step shows everything you need to review and action before and after migration. The list stays available even after you've confirmed and you can come back to it at any time.

Tasks before migration

You should complete the tasks below before the migration is confirmed as a backup:

Access rights (Roles & permissions): If you are using them to define custom permission rules, download a backup of permissions of all employee roles under Settings > Roles & permissions > Three dot menu > Export permissions for all roles (CSV).
Review section access rights: Access to the new section may differ from the source section. If you need to update access, first download a backup of your employee roles, then migrate the attributes, then update the access rights. This is shown only when the new attribute is in a different section than the source attribute.

Make sure to review the tasks below before the migration is confirmed as existing report configuration or employee data approval requests affected will be lost during the migration:

Attribute updates (proposed changes): Any pending proposed changes to the source attribute will be lost after migration. Review them now and approve or reject each one so nothing gets missed.
Reports: If you have any reports that include the source attribute, it won't appear after the migration and you need to update them to reference the new attribute.

Tasks after migration

For some areas, Personio can detect exactly where your source attribute is used and will list the specific items you need to update. For other areas, Personio cannot detect usage automatically, these appear as general checks you should complete if the area is relevant to your setup.

You can complete the tasks below once the migration is done and the new core attribute exists.

Required tasks:

These will be displayed if they apply to your account setup.

Workflows: The source attribute is used in a workflow. The link in the task takes you directly to the affected workflow, so you can review and update the workflow configuration to use the new core attribute.
Custom permissions in roles: The source attribute is used in one or more custom filters for permission scopes. You need to update the role configuration with the newly created core attribute. The link in the task takes you directly to the affected role, so you can review and edit the permissions where needed.
Role member conditions: The source attribute was used in a custom condition to assign role members. You need to update the role configuration under Settings > Roles & permissions > Edit members with the new core attribute after the migration.
Integrations readable employee attributes: The source attribute is enabled for one or more custom integrations under Settings > API Credentials with the Employees scope. The task lists the affected integration by name. After migration, the new core attribute appears under API Credentials > Access rights > Readable employee attributes for each custom integration, but access is not enabled automatically. While reads of the archived source attribute keep working exactly as before, writes to the archived source attribute will fail. Make sure to disable access for the source attribute and enable access to the new core attribute before updating your scripts so your integration continues to work going forward.
Compensation cycles: The source attribute is used in a compensation cycle that hasn't started yet. The task lists the affected cycle by name, so you can update the cycle settings and worksheets to use the new core attribute.
Preliminary payroll table: The source attribute was added as a column on your payroll table. After the migration, the archived source attribute will not be visible anymore and you need to add the new core attribute under Payroll > Manage > Payroll data.
Payroll groups: The source attribute is used to define one or more Payroll groups. The task lists the affected legal entities, so you can go to Preliminary payroll > Manage and select the new core attribute in the "Group by" dropdown for each one.

Generic tasks:

These are always displayed. Check if they apply to your account setup and complete where needed.

Document templates: If any of your document templates use the source attribute, they will stop working after migration. Download the template, update the attribute name, then re-upload it.
Surveys: If any survey reports use the source attribute, they may show incomplete results. Update those surveys to use the new core attribute.

03 Complete_tasks_EN.png

What is updated automatically

Onboarding and offboarding steps: If you use the source attribute in an onboarding or offboarding step or email template, it is updated automatically.
People List: If you use the source attribute in a Saved View in the People List, it is updated automatically.
Reminders: If you use source attribute in any reminder configurations, the reminder is updated automatically.

Step 3: Review setup and migrate

This screen shows a summary of your migration:

The source attributes and the order they will be used
The section the new core attribute will be placed in

Review the summary carefully. When you're ready, select Migrate.

The migration runs in the background. You can leave the page and your progress is saved and the task list remains available.

After migration

Once migration is complete, a confirmation screen is displayed showing:

Which values were migrated and from which source attributes
The section the new core attribute was added to
The task list for any remaining steps

Your source attributes are now archived. They no longer appear on employee profiles, but their data is preserved. Administrators can restore them at any time from Personal information if needed.

Work through any remaining tasks in the task list to finish your setup.

04 New_core_attributes_EN.png

05 Tasks_EN.png

FAQ

What are core attributes, and why would I migrate to them?

Core attributes are standardised employee data fields that Personio defines and maintains for you. Compared to your existing custom attributes, they're ready to work with all your integrations, come with names, descriptions and help-text in 18 languages, and automatically flag invalid data. Standardising on them also unlocks more reliable reporting and product features that depend on these fields being present and consistently structured.

Do I have to migrate? Is it mandatory?

No. Migration is opt-in and you stay in control of when it happens. New core attributes will appear in your settings as available to set up, but nothing changes until you choose to act. You can migrate one attribute now and others later, whenever your team is ready.

What happens when I migrate an attribute?

You set up the new core attribute and choose how to fill it: either migrate the values from one or more of your existing attributes, or add it as an empty attribute and fill it later. If you migrate values, Personio copies them into the new core attribute, and your original (source) attribute is archived to avoid duplication. You'll see a review step summarising what will happen before anything is applied.

Where is the new attribute created, and who can access it?

During setup you choose which section the new attribute is created in. The attribute then takes on the access rights assigned to that section — so the people who can see and edit the section can see and edit the new attribute. Place it in the section that gives you the access setup you want.

Can any attribute be used as a source attribute?

No — only attributes that are compatible with the core attribute are offered. When you start, Personio filters the list to show only compatible attributes (for example, only the ones whose type and shape can map to the new field). In some cases there may be no compatible attribute at all, in which case you can still add the core attribute as empty.

How are values copied if I select multiple source attributes?

You can pick more than one source attribute to fill a single core attribute, and the order you place them in matters. For each employee, Personio uses the first available value in your ordered list: if your first source attribute has no value for that employee, it tries the next one, and so on, until it finds a value to fill the field. This lets you set your preferred attribute first and use the others as fallbacks for employees where it's blank.

What if I don't have any compatible attribute to migrate from?

You can add the core attribute as an empty attribute. This provisions the new, standardised field on your account without copying any existing values, so you can start capturing data in it going forward. Nothing is archived in this case because there's no source attribute involved.

What's the difference between "migrating values" and "adding as an empty attribute"?

Migrating values copies data from your existing attribute(s) into the new core attribute and then archives the source to prevent duplicate fields. Adding as empty simply creates the new core attribute with no data and leaves your existing attributes untouched. Choose "migrate values" when you want to bring your current data across; choose "empty" when you're starting fresh or no compatible source exists.

Will I need to make changes myself before or after migrating?

Yes — almost certainly. Migrating is a significant step and will usually require some manual work on your side, especially if you use the API (PAPI), custom workflows, or integrations that reference the attribute. Personio shows you the specific actions to take in the migration flow, but treat this as a deliberate change to plan for, not a one-click switch — proceed with caution and work through the listed actions.

Do I have to migrate all attributes at once?

No. Migration is opt-in and you stay in control of when it happens. You can migrate one attribute now and others later, whenever your team is ready.

What do I need to do before migrating?

Before you start, review the pre-migration checklist shown in the flow. Most importantly, approve or reject any pending (proposed but not yet approved) changes to the attributes involved — these are lost during migration, and only approved changes are carried over. Also check where your source attribute is used across Personio (see the next question) so you can plan any follow-up updates.

Will migrating break my integrations, exports, or document templates?

Some areas update automatically and some need a manual update from you. People List saved views are updated automatically with the new attribute. You will need to update places that reference the old attribute by name, including: your PAPI integrations, document templates (which otherwise stop working), Compensation cycles that haven't started yet, Surveys reports (which may show incomplete results), and any groups, roles, workflows, reminders or Calendar Access Control List that use the attribute. The migration flow lists exactly which of your configurations are affected.

Can I undo an attribute migration?

You can't undo the migration itself — it's a one-time action performed when the core attribute is set up, and you can't re-run it or run it partially for the same attribute. You can, however, unarchive your source attribute: its values become available again exactly as they were before, so no data is lost. Note that the old and new attributes will then both exist and won't be kept in sync automatically, which is a messy state to be in — so work through the checklist and confirm the review step before you proceed.

What happens to my old attribute after I migrate its values?

It's archived. Archiving keeps your historical record intact while removing the old field from active use, so you don't end up with two attributes holding the same information. You can still access the list of migrated attributes afterwards to see what was moved and check for any remaining data to handle. (If you need the old values back, you can unarchive the source attribute — see Q12.)

The new attribute uses a different format than my old one (e.g. country as an ISO code) — will my data still work?

Compatible values are migrated for you, but because core attributes use a standardised format, the way a value is stored or displayed may change after migration (for example, a free-text country becomes a three-letter ISO country code). Values that can't be mapped automatically may need a manual fix, and you may see validation prompts where data doesn't meet the new format. The review step and post-migration task list highlight anything that needs your attention.

Is my data still translated, and what about historical values?

Yes — core attributes come with names, options, descriptions and help-text in 18 languages, maintained by Personio. Your historical values are preserved as part of the migration wherever possible.

Find the answers you need