Perk SCIM for user provisioning

This guide explains how Perk implements the System for Cross-domain Identity Management (SCIM) standard and how Perk provisions users automatically.

ℹ️
Note
SCIM user provisioning is a Premium or Pro feature. To turn it on, open your plans page and upgrade.

What SCIM is

SCIM is an open standard (defined in RFC 7643 and RFC 7644) for managing user identities across cloud applications. It gives every application the same REST endpoints and data format for creating, updating, and deactivating users. That way, identity providers (IdPs) and HR systems can sync people to many tools without custom code for each one.

Perk supports SCIM 2.0. This guide doesn't repeat the full specification — it documents what is specific to Perk. For the standard itself, see the SCIM specification.

Because SCIM is a shared standard, Perk's SCIM API looks different from Perk's other REST APIs. It uses the resource paths, JSON schema format, and request and response structures defined by the specification — such as the /Users and /Schemas endpoints — rather than Perk's own API conventions. Perk follows the standard so that any SCIM-compatible identity provider works without custom integration. As a result, its endpoint URLs and behavior differ from the rest of the Perk API.

How Perk implements SCIM

Perk runs a SCIM 2.0 service that maps standard SCIM users to Perk user accounts. When your system sends a user to Perk's SCIM endpoints, Perk creates, updates, or deactivates the matching Perk account automatically — no one has to add or remove people by hand in the Perk web app.

You can provision users in one of two ways:

Through an identity provider (IdP). If you use Okta or Azure, the IdP calls Perk's SCIM API for you. You manage people in the IdP, and it syncs them to Perk.
Directly through the API. You call the SCIM endpoints from your own program using an API key. This suits custom HR integrations or scripts.

Either way, the same endpoints and data format apply. To enable provisioning, see Getting started with SCIM user provisioning.

Provisioning is automatic once enabled

You don't set up SCIM separately in the web app: the first authenticated call to any SCIM endpoint with a valid API key creates the integration for your organization. From then on, Perk applies every create, update, and deactivate request to your users in real time.

❗️
Warning
Only one user provisioning system can run at a time. If your account already syncs users using a HR integration such as BambooHR, an account admin must remove that integration before SCIM provisioning can run.

ℹ️
Note
User roles cannot be provisioned automatically. All users are provisioned as travelers. Any changes to the role must be done manually in Perk by updating their role using CSV.

Perk-specific user attributes

A standard SCIM user covers common fields such as name, email, and active status. Perk carries the extra information that travel and spend need by adding three schema extensions on top of the core schema (urn:ietf:params:scim:schemas:core:2.0:User):

Enterprise extension (urn:ietf:params:scim:schemas:extension:enterprise:2.0:User) — standard enterprise fields such as cost center and manager.
Custom Perk extension (urn:ietf:params:scim:schemas:extension:travelperk:2.0:User) — Perk travel fields such as travel policy, invoice profiles, travel documents, and line manager email.
Expense extension (urn:ietf:params:scim:schemas:extension:expense:2.0:User) — expense fields such as expense policy, creditor, legal entity, and approval threshold.

Some attributes do more than store data. For example, assigning a manager or lineManagerEmail also creates an approval process in Perk, with that person set as the user's approver. For every field and how it behaves, see the User model reference.

NOTE The custom extension keeps the identifier urn:ietf:params:scim:schemas:extension:travelperk:2.0:User for backward compatibility, even though the product is now called Perk. Send and read it exactly as shown.

Base URL and authentication

Every SCIM call starts from this base URL:

https://app.perk.com/api/v2/scim

All SCIM endpoints — /Users, /Schemas, /ResourceTypes, and /ServiceProviderConfig — are paths under this base URL. Authenticate each request with your API key in the Authorization header:

curl \
  --url "https://app.perk.com/api/v2/scim/Users" \
  --header "Authorization: apikey <your_api_key>"

To check which operations and features your account supports, call the discovery endpoints (/ServiceProviderConfig, /ResourceTypes, and /Schemas).

Next steps

Getting started with SCIM user provisioning — enable provisioning through an IdP or the API.
User model reference — every user attribute and extension.