TravelPerk User Management API Guide

Auth method: OAuth 2.0 (authorization code flow)

Setup steps

1. Register an OAuth application in the TravelPerk developer portal to obtain a client_id and client_secret.
2. Redirect the user to https://app.travelperk.com/oauth2/authorize with response_type=code, client_id, redirect_uri, and desired scopes.
3. Exchange the returned authorization code for an access token via POST to https://app.travelperk.com/oauth2/token.
4. Include the access token in all API requests as a Bearer token in the Authorization header.
5. Refresh the access token using the refresh_token grant type before expiry.

Required scopes

List Users

• Method: GET
• URL: https://app.travelperk.com/api/v2/users
• Watch out for: Pagination uses offset/limit; max limit is 200. Requests beyond total count return an empty results array.

Request example

GET /api/v2/users?limit=10&offset=0
Authorization: Bearer {access_token}

Response example

{
  "results": [{"id":"uuid","first_name":"Jane","last_name":"Doe","email":"jane@example.com"}],
  "total": 42,
  "offset": 0,
  "limit": 10
}

Get User

• Method: GET
• URL: https://app.travelperk.com/api/v2/users/{id}
• Watch out for: Returns 404 if the user does not belong to the authenticated OAuth app's organization.

Request example

GET /api/v2/users/user-uuid
Authorization: Bearer {access_token}

Response example

{
  "id": "user-uuid",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "role": "traveler",
  "is_active": true
}

Create User

• Method: POST
• URL: https://app.travelperk.com/api/v2/users
• Watch out for: Email must be unique within the organization; duplicate email returns 422.

Request example

POST /api/v2/users
Authorization: Bearer {access_token}
Content-Type: application/json

{"first_name":"Jane","last_name":"Doe","email":"jane@example.com","role":"traveler"}

Response example

{
  "id": "new-user-uuid",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "role": "traveler"
}

Update User

• Method: PATCH
• URL: https://app.travelperk.com/api/v2/users/{id}
• Watch out for: Only fields included in the request body are updated; omitted fields retain their current values.

Request example

PATCH /api/v2/users/user-uuid
Authorization: Bearer {access_token}
Content-Type: application/json

{"role":"travel_manager","cost_center":"CC-001"}

Response example

{
  "id": "user-uuid",
  "role": "travel_manager",
  "cost_center": "CC-001"
}

Delete User

• Method: DELETE
• URL: https://app.travelperk.com/api/v2/users/{id}
• Watch out for: Deletion is permanent. Consider setting is_active=false via PATCH to deactivate without data loss.

Request example

DELETE /api/v2/users/user-uuid
Authorization: Bearer {access_token}

Response example

HTTP 204 No Content

List Travel Policies

• Method: GET
• URL: https://app.travelperk.com/api/v2/travel_policies
• Watch out for: Policy IDs are needed when assigning travel_policy to a user during create or update.

Request example

GET /api/v2/travel_policies
Authorization: Bearer {access_token}

Response example

{
  "results": [{"id":"policy-uuid","name":"Economy Policy"}],
  "total": 3
}

List Groups (Departments)

• Method: GET
• URL: https://app.travelperk.com/api/v2/groups
• Watch out for: Groups map to departments; group membership is managed separately from user profile fields.

Request example

GET /api/v2/groups
Authorization: Bearer {access_token}

Response example

{
  "results": [{"id":"group-uuid","name":"Engineering"}],
  "total": 5
}

Add User to Group

• Method: POST
• URL: https://app.travelperk.com/api/v2/groups/{group_id}/members
• Watch out for: User must already exist before being added to a group; adding a non-existent user returns 404.

Request example

POST /api/v2/groups/group-uuid/members
Authorization: Bearer {access_token}
Content-Type: application/json

{"user_id":"user-uuid"}

Response example

HTTP 201 Created
{"group_id":"group-uuid","user_id":"user-uuid"}

• Rate limits: TravelPerk enforces rate limits per API token. The developer docs note limits but do not publish exact per-plan numbers publicly.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: The API returns HTTP 429 when rate limits are exceeded. Rate limit headers are present in responses per the developer docs, but specific header names and exact limits are not publicly documented. Retry-After behavior is not explicitly documented.
• Pagination method: offset
• Default page size: 10
• Max page size: 200
• Pagination pointer: offset / limit

• Webhooks available: No
• Webhook notes: TravelPerk's public developer documentation does not describe outbound webhook support for user management events as of the current documentation review.
• Alternative event strategy: Poll the GET /users endpoint periodically to detect changes, or use SCIM provisioning for IdP-driven sync.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Premium

• Endpoint: https://app.travelperk.com/api/scim/v2

• Supported operations: GET /Users (list users), GET /Users/{id} (get user), POST /Users (create user), PUT /Users/{id} (replace user), PATCH /Users/{id} (update user), DELETE /Users/{id} (delete/deprovision user), GET /Groups (list groups), POST /Groups (create group), PATCH /Groups/{id} (update group membership), DELETE /Groups/{id} (delete group)

Limitations:

• Requires Premium plan; not available on Starter or Pro plans.
• SCIM token is generated within TravelPerk settings and is separate from OAuth 2.0 tokens.
• IdP-specific connector setup (e.g., Okta, Azure AD) must be configured on the IdP side using the TravelPerk SCIM base URL and token.
• Not all user profile fields available via the REST API are writable via SCIM; travel-specific fields (e.g., travel policy) may require REST API calls.
• Group provisioning support may vary by IdP connector configuration.

Three scenarios cover the majority of programmatic user management needs.

For new-hire provisioning: POST to /api/v2/users with the required fields, then retrieve policy IDs via GET /api/v2/travel_policies and assign via a separate PATCH

travel policy cannot be guaranteed atomic in the creation POST.

For offboarding: prefer PATCH with is_active=false over DELETE;

the DELETE endpoint is irreversible and eliminates the audit trail.

For IdP sync via SCIM: generate a SCIM token in TravelPerk Settings, configure the IdP connector against the SCIM base URL, and map userName to email and name.givenName to first_name;

note that travel-specific fields such as travel policy are not writable via SCIM and require direct REST API calls post-sync.

Group membership is managed via a separate /api/v2/groups/{group_id}/members endpoint and is not part of the core user object.

Provision a new employee and assign a travel policy

1. POST /api/v2/users with first_name, last_name, email, and role=traveler to create the user.
2. GET /api/v2/travel_policies to retrieve available policy IDs.
3. PATCH /api/v2/users/{id} with the desired travel_policy ID to assign the policy.
4. Optionally POST /api/v2/groups/{group_id}/members to add the user to their department group.

Watch out for: Travel policy assignment requires a separate PATCH after creation; it cannot always be set atomically in the POST body depending on API version behavior.

Deprovision a departing employee

1. PATCH /api/v2/users/{id} with is_active=false to deactivate the account without permanent deletion.
2. Verify the user no longer appears in active user listings by checking GET /api/v2/users with an active filter if supported.
3. If permanent removal is required, follow with DELETE /api/v2/users/{id}.

Watch out for: DELETE is permanent and cannot be undone; deactivation via PATCH is preferred for audit trail retention.

Sync users from an IdP using SCIM

1. Confirm the TravelPerk account is on the Premium plan.
2. Navigate to TravelPerk Settings > Integrations > SCIM and generate a SCIM bearer token.
3. In the IdP (e.g., Okta or Azure AD), configure a new SCIM 2.0 application using base URL https://app.travelperk.com/api/scim/v2 and the generated token.
4. Map IdP user attributes to SCIM standard attributes (userName → email, name.givenName → first_name, etc.).
5. Enable provisioning actions (create, update, deactivate) in the IdP connector and perform a test sync.

Watch out for: SCIM token and OAuth token are distinct; do not use the OAuth access token for SCIM requests. Some travel-specific fields are not writable via SCIM and require direct REST API calls.

The primary integration trap is token confusion: the OAuth 2.0 access token and the SCIM bearer token are entirely separate credentials with no overlap - using the OAuth token against the SCIM endpoint will fail silently or return auth errors.

A second trap is the DELETE endpoint: it is permanent and undocumented for recovery, making it unsuitable for standard offboarding flows where audit retention is required.

Rate limits present a third risk - because exact limits and header names are not publicly documented, any bulk operation such as paginating all users or batch-updating cost centers must implement defensive backoff from the start rather than after hitting production errors. Finally, the API is scoped to a single organization per OAuth token;

multi-tenant or multi-workspace architectures require separate OAuth app registrations and token management per organization.