User object model

The user object represents a user within your Perk account, provisioned through the System for Cross-domain Identity Management (SCIM) API.

The user object

The object described on this page presents the schema used in the following API calls:

📘
Note
Some attributes below are marked Read-only or Required. Perk assigns read-only attributes automatically, and you can never update them. The Create user and Replace user payloads must contain required attributes.

Attribute	Type	Description
`schemas`	string	Contains URIs that indicate the namespaces of the SCIM schemas that define the attributes present in the current JSON structure.
`id`	string	A unique identifier for a SCIM resource as defined by the service provider. Read-only
`userName`	string	Perk's identifier. Used to authenticate to Perk. It must be a valid email address. Required
`externalId`	string	Identifier for the resource as defined by the provisioning client.
`name`	object	The components of the user's name. See the name object. Required
`preferredLanguage`	string	Indicates the user's preferred written or spoken languages. Used for selecting a localized user interface.
`locale`	string	A valid language tag as defined in RFC 5646. Perk uses it to deduce the following on user creation, when those values aren't otherwise specified (e.g., language by preferredLanguage): The currency. The time format (12-hour for English-speaking locale values: `en`, `en_gb`, and `en_au`). The language (defaults to English for unsupported languages). For more on how locale is used, see the list of available SCIM locale values.
`active`	boolean	Indicates the user's administrative status. It's `true` if the user is active, and `false` otherwise. Required
`title`	string	The user's title, such as "Software Engineer".
`emails`	array:object	List of email addresses for the user. Each object has the sub-attributes `value` (the email address), `type` (e.g., `work`), and `primary` (whether this is the user's primary email).
`phoneNumbers`	array	List of phone numbers for the user. See the sub-attributes in the phone number object below. Perk user profiles support only one phone number, so Perk accepts only the one with `type: work`.
`groups`	array	Perk doesn't currently support groups. Expect an empty list (`[]`) in the response.
`meta`	object	A complex attribute containing resource metadata.

Enterprise user extension

Perk supports the enterprise user schema extension as defined in the SCIM 2.0 specification.

Attribute	Type	Description
`costCenter`	string	Cost object the user belongs to in Perk (e.g., marketing). If the cost object doesn't already exist in Perk, Perk creates it and assigns the user.
`manager`	string	Used to assign a user's line manager. Perk supports it for both identity providers (IdPs) and direct API calls, depending on the account's SCIM configuration. The manager field must contain: `value` – the Perk ID of the manager `$ref` – the reference URL of the manager (`https://app.perk.com/api/v2/scim/Users/{manager_id}`; for the staging environment, use `app.staging-perk.com`) `displayName` – the human-readable name of the manager (first and last name). This sub-field is Read-only. The format must follow the SCIM 2.0 specification for the manager attribute, as described in RFC 7643 Section 4.3. Note: Some identity providers (like Okta) can't reference users by ID, so the `manager` attribute won't work. In those cases, use the `lineManagerEmail` field instead — See Custom user extension.
`employeeNumber`	string	The HR-assigned employee number for the user.
`company`	string	Company the user belongs to within your Perk account. The company must already exist in Perk, and the name must match it exactly. Only use this field if your Perk setup includes companies.

Custom user extension

Attribute	Type	Description
`gender`	string	Indicates the user's gender. Can be one of the following values: `M` for male `F` for female
`dateOfBirth`	string	Date of birth for the user, in the `YYYY-MM-DD` format.
`travelPolicy`	string	Travel policy the user is assigned to in Perk. The value should be the name of the policy. Create the policies in the Perk app before you use this field.
`invoiceProfiles`	array:object	List of payment profiles the user belongs to. Create the payment profiles in Perk before you use this field. Once assigned, a payment profile is visible only to the users assigned to it. If it isn't assigned to anyone, all users in the company that the payment profile belongs to can see it. Important: If you also use the Company field, Perk validates the payment profiles to ensure they belong to the same company as the user.
`emergencyContact`	object	Emergency contact for the user. It has two sub-attributes: `name`: name of the contact person `phone`: phone number for the contact person
`approvers`	array:object	List of approvers required for the approval process. Perk creates the approval process automatically. Each object contains the sub-values: `value`: Perk user ID `condition`: the condition under which this approver applies. One of: `always`, `out_of_policy`, or `out_of_policy_and_notify_in_policy`. `$ref`: the URL of the approver's object (set by Perk). This sub-field is Read-only. `displayName`: the human-readable name of the approver (first and last name). This sub-field is Read-only. For more information, see the Approvers object. Note: The approvers field is still supported but deprecated. Don't use it in new integrations — use the `manager` or `lineManagerEmail` field instead.
`countryOfResidence`	string	Country of residence of the user. Perk expects an ISO 3166-1 alpha-2 code (e.g., `ES`).
`travelDocuments`	array:object	List of travel documents of the user. A travel document has the following sub-attributes: `documentType`: the type of the document, either `passport` or `id` `documentNumber`: the number of the document `givenName`: the first name as stated in the travel document `middleName`: the middle name as stated in the travel document, if any `familyName`: the last name as stated in the travel document `gender`: the gender of the user, either `F` or `M` `issuingCountry`: country code of the country where the document was issued (e.g., `ES`) `issuingDate`: the date the document was issued, in the `YYYY-MM-DD` format (optional) `expirationDate`: the expiration date of the document, in the `YYYY-MM-DD` format `citizenship`: the country code of the citizenship of the user (e.g., `ES`)
`company`	string	Only use this field if your Perk setup includes companies. For more information, see Understanding the account structure in Perk. Used to assign a user to a given company within your Perk account. The company must already exist in Perk, and the provided name must match the exact name of the existing company.
`lineManagerEmail`	string	Used to assign a line manager by their login email (must be an active user in the same account). Serves the same purpose as the `manager` field, but supports provisioning users via identity providers (like Okta) that can't reference users by ID. You can use it alongside `manager`; if both are provided, `lineManagerEmail` takes precedence.
`uniqueId`	string	The unique code or identifier (e.g., employee number) for each employee.

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "urn:ietf:params:scim:schemas:extension:travelperk:2.0:User"
  ],
  "name": {
    "givenName": "Josh",
    "familyName": "Smith",
    "middleName": "",
    "honorificPrefix": "Mr."
  },
  "locale": "en",
  "preferredLanguage": "en",
  "title": "Manager",
  "externalId": "123455667",
  "id": "29",
  "groups": [],
  "active": true,
  "userName": "[email protected]",
  "emails": [
    {
      "value": "[email protected]",
      "type": "work",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "+34 1234567",
      "type": "work"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "costCenter": "Marketing",
    "manager": {
      "value": "123",
      "$ref": "https://app.perk.com/api/v2/scim/Users/123/",
      "displayName": "John Johnson"
    },
    "company": "My Company Name"
  },
  "urn:ietf:params:scim:schemas:extension:travelperk:2.0:User": {
    "dateOfBirth": "1980-02-02",
    "travelPolicy": "Associate policy",
    "gender": "M",
    "invoiceProfiles": [
      {
        "value": "MyCompany Ltd"
      }
    ],
    "emergencyContact": {
      "name": "Jane Goodie",
      "phone": "+34 9874637"
    },
    "countryOfResidence": "ES",
    "uniqueId": "A Unique ID",
    "company": "My Company Name",
    "travelDocuments": [
      {
        "documentType": "passport",
        "documentNumber": "abcedf12345",
        "givenName": "Josh",
        "middleName": "",
        "familyName": "Smith",
        "gender": "M",
        "issuingCountry": "ES",
        "issuingDate": "1999-12-05",
        "expirationDate": "2042-09-08",
        "citizenship": "ES"
      }
    ]
  },
  "meta": {
    "resourceType": "User",
    "created": "2020-04-01T22:24:44.137082+00:00",
    "lastModified": "2020-04-01T22:24:44.137082+00:00",
    "location": "https://app.perk.com/api/v2/scim/Users/29"
  }
}

Expense user extension

Schema: urn:ietf:params:scim:schemas:extension:expense:2.0:User

The Expense extension provides expense management attributes for users provisioned via SCIM.

Attribute	Type	Description
`policyId`	string	Identifies the expense policy assigned to the user.
`creditor`	string	The creditor associated with the user for expense purposes.
`legalEntityId`	string	Identifies the legal entity the user belongs to for expense purposes.
`approvalThreshold`	decimal	The approval threshold amount for the user's expense requests.
`ignoreManagerInRequests`	boolean	If `true`, Perk excludes the user's manager from the expense approval flow.

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:expense:2.0:User"
  ],
  "userName": "[email protected]",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "urn:ietf:params:scim:schemas:extension:expense:2.0:User": {
    "policyId": "pol_123",
    "creditor": "ACME Corp",
    "legalEntityId": "le_456",
    "approvalThreshold": 1000.00,
    "ignoreManagerInRequests": false
  }
}

name object

Attribute	Type	Description
`familyName`	string	The family name of the user, or last name in most Western languages (e.g., "Jensen" given the full name "Ms. Barbara Jane Jensen, III"). Required
`givenName`	string	The given name of the user, or first name in most Western languages (e.g., "Barbara" given the full name "Ms. Barbara Jane Jensen, III"). Required
`middleName`	string	The middle name(s) of the user (e.g., "Jane" given the full name "Ms. Barbara Jane Jensen, III").
`honorificPrefix`	string	The honorific prefix(es) of the user, or title in most Western languages (e.g., "Ms." given the full name "Ms. Barbara Jane Jensen, III").

meta object

Attribute	Type	Description
`resourceType`	string	The name of the resource type of the resource. For a user resource, this is `User`.
`created`	string	The date and time the resource was added to Perk.
`lastModified`	string	The most recent date and time the details of this resource were updated at Perk. If this resource has never been modified since its initial creation, the value is the same as the value of `created`.
`location`	string	The URI of the resource being returned (e.g., `https://app.perk.com/api/v2/scim/Users/29`).

phoneNumbers object

The phoneNumbers object is an array of objects, each of which should follow this format:

Attribute	Type	Description
`value`	string	Phone number of the user. Must be in the correct format: `+ {country_code} {phone_number}`. E.g., `+1 123456789` and `+42 99999999` are valid numbers.
`type`	string	A label indicating the attribute's function, such as `work`, `home`, or `mobile`. Perk accepts only the phone number of type `work`, and it must appear no more than once.

approvers object

The approvers field is an array of objects, each of which should follow this format:

Attribute	Type	Description
`value`	string	The Perk ID of the approver to assign. The user must already exist on the platform.
`condition`	string	The condition under which this approver is asked for approval. One of: `always`: Perk sends an approval request to this approver for all trips. `out_of_policy`: only trips outside the assigned travel policy trigger an approval request to this approver. `out_of_policy_and_notify_in_policy`: only trips outside the assigned policy trigger an approval request to this approver. Trips within policy trigger a notification to the approver instead. Note: If you were already using this field without the `condition` values, the setting you were using still applies across all users.