Custom fields API

The Custom Fields API lets you work with custom fields in your Perk account — the business-specific data fields, such as project codes or client names, that your organization attaches to users and expenses. This API applies to select and multi-select custom fields. This article introduces the API and its key concepts, then explains how to use the endpoint for listing a custom field's select options.

When to use this

Use the Custom Fields API when your integration needs to read the configuration behind a custom field — for example, to validate or look up which values are currently valid before you submit a record that references that field. For example, before your system submits an expense with a project_code custom field, you can look up which option IDs are currently valid and check whether an option is active or archived.

Prerequisites

• A Perk account with a valid API key
• The custom field you want to query must already exist in the account, with its select options set up in Perk account settings

Key concepts

You need to understand these concepts before you call any Custom Fields API endpoint.

• Custom field: A business-specific data field, such as a project code or client name, attached to bookings or expenses in a Perk account.
• Select option: One of the predefined values a user can choose for a select or multi-select custom field. Every option is returned as a consistent, minimal shape — id, value, is_archived — the same shape used across all endpoints in this API, including the add and archive endpoints once they ship.
• Active vs. archived status: An active option is currently offered to end users. An archived option (is_archived: true) is no longer offered, but it can still appear on historical records, so you may need to include archived options when reconciling past data.
• Offset and limit pagination: List endpoints in this API paginate results using offset and limit query parameters. Responses don't include a total count or a has_more flag, so keep requesting until a page comes back with fewer items than limit, or empty.
• Value length limit: Option values are limited to 160 characters. This limit isn't enforced by the list endpoint since it's read-only, but it applies when options are created.

Authentication

Requests use API key authentication. Send your key in the Authorization header as apikey <your_api_key>, and include an Api-Version header set to 1.

List select options

GET /custom-fields/{custom_field_id}/select-options

Returns the select options for a custom field. Active options are returned by default; pass status=active,archived to include archived ones. Results are paginated with limit (one to 100, default 20) and offset (default 0); the response has no total count or has_more field, so keep requesting until a page comes back with fewer items than limit, or empty.

Next steps

• See the API reference for GET /custom-fields/{custom_field_id}/select-options for the full parameter list, request and response examples, and error codes.
• See Custom fields on Perk for how to create and manage custom fields in Perk.