Manage travel approval processes through SCIM

This guide shows you how to set up Perk travel approval processes through the SCIM API, building on a working SCIM user-provisioning integration.

For the provisioning setup, see Create a custom app to manage your Perk user base.

📘

Note

New to approval processes? See Travel approval processes in Perk in the Perk Help Center for how they work.

Perk supports two types of approval process configuration:

• line manager-based
• approver-based

Line manager-based approval process

A line manager–based travel approval process sends trip approval requests directly to the traveler's assigned manager. Each user's direct manager, as defined in their Perk profile, approves their travel bookings.

To assign a line manager to a user through SCIM, set either the manager attribute (with the manager's Perk user ID) or the lineManagerEmail field (with the manager's email address), as described in the User model.

After you provision the manager, configure a line manager–based approval process in Perk. For step-by-step instructions, see Set line manager as the approver in the Perk Help Center.

Approvers-based approval process

⚠️

Warning

The approvers field is still supported but deprecated. It may be removed in a future release. For new integrations, use manager or lineManagerEmail with a line manager-based approval process instead.

To set up approvers, use the approvers field — see the User model for the full schema. Each entry has this format:

"approvers": [{ "value": "<approver-id>", "condition": "<condition>" }]

Where:

• value is the Perk ID of the approver, assigned when you created the user.
• condition is one of always, out_of_policy, or out_of_policy_and_notify_in_policy.

Assign approvers to a user

This example assumes you already have a way to determine who the approvers should be, based on your company's hierarchy and logic. Call this the approvers map:

user_approvers_map = {
    "11": [("21", "always"), ("22", "out_of_policy"), ("23", "always")],
    "12": [("21", "always")],
    "13": [("23", "out_of_policy")],
    # "<user-id>": [("<approver-id>", "<condition>"), ...]
}

To generate an approval process, send a PATCH request to the Modify a user endpoint, connecting each user to their assigned approvers. See Update a user for the endpoint reference.

The following Python function takes a user and a list of their approvers and conditions, then makes the call to Perk's API:

import requests
from typing import List, Tuple

base_url = "https://app.perk.com/api/v2/scim"

def set_approvers(api_key: str, user_id: str, approvers: List[Tuple[str, str]]) -> None:
    value = []
    # `approvers` follows the format used in user_approvers_map above
    for approver, condition in approvers:
        value.append({"value": approver, "condition": condition})

    patch_payload = {
        "schemas": "urn:ietf:params:scim:api:messages:2.0:PatchOp",
        "Operations": [
            {
                "op": "add",
                "path": "urn:ietf:params:scim:schemas:extension:travelperk:2.0:User:approvers",
                "value": value,
            }
        ],
    }
    requests.patch(
        f"{base_url}/Users/USER_ID",
        headers={"Authorization": f"apikey {api_key}"},
        json=patch_payload,
    )

You can also assign approvers with a single cURL request:

curl --request PATCH \
  --url "https://app.perk.com/api/v2/scim/Users/11" \
  --header "content-type: application/json" \
  --header "Authorization: apikey <your_api_key>" \
  --data '{
  "schemas": "urn:ietf:params:scim:api:messages:2.0:PatchOp",
  "Operations": [
    {
      "op": "add",
      "path": "urn:ietf:params:scim:schemas:extension:travelperk:2.0:User:approvers",
      "value": [
        { "value": "21", "condition": "always" },
        { "value": "22", "condition": "out_of_policy" }
      ]
    }
  ]
}'

Call set_approvers for each user to finish setting up your approval processes.