Provision custom fields via SCIM

Custom fields let you attach organisation-specific data to Perk user profiles — values like cost centres, markets, brands, or any attribute your team tracks. If you manage users through SCIM, you can provision these fields directly from your identity provider so they stay in sync automatically.

Prerequisites

Before mapping custom fields:

SCIM provisioning is enabled on your Perk account.
The custom fields you want to provision already exist in Perk (Account settings → Custom fields). SCIM cannot create new field definitions — it can only write values to existing ones.
You know the UUID of each custom field you want to provision (see Find your custom field UUID below).

How custom field attributes are named

Custom fields are sent inside a dedicated SCIM schema extension:

urn:ietf:params:scim:schemas:extension:perkcustomfields:2.0:User

Each field maps to a unique attribute key with the following format:

cf_{slug}_{uuid}

Where:

{slug} is the field name lowercased, with any non-alphanumeric characters replaced by underscores (e.g. Cost Center → cost_center).
{uuid} is the UUID of the custom field definition in Perk.

The full SCIM path used when configuring your IdP is the schema namespace followed by a colon and the attribute key:

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

Example — a field named Brand with UUID 138bcf1e-ce81-4eb6-b5f2-d62f8c817ac7:

urn:ietf:params:scim:schemas:extension:perkcustomfields:2.0:User:cf_brand_138bcf1e-ce81-4eb6-b5f2-d62f8c817ac7

Find your custom field UUID

The UUID appears in the URL when you open a custom field in Perk:

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

You can also retrieve all field definitions programmatically from the SCIM schema discovery endpoint:

GET {base_url}/scim/v2/Schemas

Each custom field is listed as an attribute under the urn:ietf:params:scim:schemas:extension:perkcustomfields:2.0:User schema, with its name set to the cf_{slug}_{uuid} key.

Attribute reference

Setting	Value
Schema namespace	`urn:ietf:params:scim:schemas:extension:perkcustomfields:2.0:User`
Attribute key format	`cf_{slug}_{uuid}`
Data type	String
Value constraints	1–160 characters

Example SCIM payload

Custom field values are sent in their own block alongside the standard User object. Include the schema namespace in the schemas array.

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:perkcustomfields:2.0:User"
  ],
  "userName": "[email protected]",
  "name": {
    "givenName": "Alex",
    "familyName": "Smith"
  },
  "urn:ietf:params:scim:schemas:extension:perkcustomfields:2.0:User": {
    "cf_brand_138bcf1e-ce81-4eb6-b5f2-d62f8c817ac7": "Lottoland",
    "cf_market_fc93b012-a592-4580-b551-39d78294d35f": "UK"
  }
}

📘
Concurrent provisioning
You can include as many custom field attributes as you need in a single request. Each attribute corresponds to one custom field definition in Perk

❗
Error behaviour
Unknown attribute keys are silently ignored. If the attribute key does not match a known custom field (wrong UUID or malformed key), the user is still created or updated but the custom field value is not written. No error is returned. Double-check the UUID against your field definitions if values are not appearing.

A value that exceeds 160 characters returns a 400 Bad Request.

Next steps