Map custom attributes in Microsoft Entra ID

Use this guide to map extra user attributes from Microsoft Entra ID (previously named Azure Active Directory or Azure AD) to Perk. For the full attribute schema, see the SCIM user model reference.

Prerequisites

Before you start, make sure you have:

• A completed Microsoft Entra ID SCIM provisioning setup. For more information, see Get started with Microsoft Entra ID SCIM provisioning.
• Microsoft Entra ID administrator access.

Attribute mapping directory

The table below lists the Perk target attributes you can map from Microsoft Entra ID. Required attributes are marked.

Custom fields

Custom fields are account-specific attributes defined in Settings > Cost management > Custom fields. Unlike the attributes in the Supported attributes table, the target attribute path is unique to your account and must be constructed before you can map them in Entra ID.

The target attribute for each custom field follows this pattern:

urn:ietf:params:scim:schemas:extension:perkcustomfields:2.0:User:cf_{slug}_{uuid}

Where {slug} is the field name lowercased with non-alphanumeric characters replaced by underscores, and {uuid} is the field's UUID in Perk. To find the UUID, open the field in Perk (Settings > Cost management > Custom fields) — it appears in the URL:

https://app.perk.com/account/custom-fields/{uuid}

Because Microsoft Entra ID doesn't discover account-specific custom fields automatically, you need to register each one manually before mapping it. Follow the steps in Add target attributes manually below, using:

• Name: the full target attribute path (e.g. urn:ietf:params:scim:schemas:extension:perkcustomfields:2.0:User:cf_brand_138bcf1e-ce81-4eb6-b5f2-d62f8c817ac7)
• Type: String

Once registered, map it using the standard steps in Customize attribute mappings.

For a full walkthrough including payload examples, see Provision custom fields via SCIM.

Customize attribute mappings

To map a Perk attribute to a Microsoft Entra ID source attribute, follow these steps:

1. Go to your Perk app in Microsoft Entra ID.
2. Go to Provisioning > Settings > Mapping and select Provision Microsoft Entra ID Users.
3. Review the list of attribute mappings that appears.

To add a new mapping:

1. Select Add new mapping at the bottom-left of the screen.
2. Select the Source attribute from Microsoft Entra ID.
3. Select the Target attribute from Perk. For the full list, see the Attribute mapping directory above.

For example, the screenshot below maps Microsoft Entra ID's companyName source attribute to the target attribute urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter, which is the cost object in Perk.

To update an existing mapping:

1. Select Delete to remove the existing mapping.
2. Add the new mapping using the steps above.
3. Select Save to apply your changes.

Troubleshooting: add target attributes by hand

Sometimes the app instance in Microsoft Entra ID falls out of sync with the latest SCIM schema from Perk. When this happens, some target attributes are missing from the mapping list. You can register the missing attributes by hand:

1. Go to Microsoft Azure. The URL must end with forceSchemaEditorEnabled=true to allow these changes.
2. Open Enterprise Applications and select the existing TravelPerk app.
3. Go to Provisioning > Edit Provisioning > Mappings > Provision Microsoft Entra ID Users.
4. Scroll to the bottom and select Show advanced options > Edit attribute list for Perk.

5. Add a new attribute at the bottom of the list, using the name and type from the Attribute mapping directory above. Leave all other fields empty.
6. Select Save.
7. Map the new attribute using the Customize attribute mappings steps above.

Next steps

• Set up company syncing in Microsoft Entra ID
• Provision custom fields via SCIM
• SCIM user model reference