Perk Custom fields API
Retrieve select options for custom fields in your Perk account.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/perk:perk-custom-fields-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Perk Custom fields API
version: '1.0'
description: 'Operations tagged Custom fields across 2 of this provider''s published API definitions: perk-custom-fields-openapi.yml, perk-custom-fields-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.perk.com
tags:
- name: Custom Fields
description: Retrieve select options for custom fields in your Perk account.
paths:
/custom-fields/{custom_field_id}/select-options:
post:
summary: Create select options
description: ''
operationId: create-custom-field-select-options
tags:
- Custom Fields
parameters:
- name: custom_field_id
in: path
required: true
description: The unique ID of the custom field. Must be a select or multi-select field with target 'BOOKING'.
schema:
type: string
- name: Authorization
in: header
required: true
description: Your Perk API key, using the format 'ApiKey <your_api_key>'
schema:
type: string
- name: Api-Version
in: header
required: true
description: The API version for this request. Must be '1'.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- select_options
properties:
select_options:
type: array
minItems: 1
description: The options to create as an array, in the order they should be returned in the response.
items:
type: object
required:
- value
properties:
value:
type: string
description: The option's display value. Must not be empty or whitespace-only, and must not exceed 160 characters.
erp_code:
type:
- string
- 'null'
description: The option's ERP code. Optional when the custom field does not have cost allocation enabled. Required when cost allocation is enabled. An empty or whitespace-only value counts as missing.
example:
select_options:
- value: Engineering
erp_code: ENG-01
- value: Sales
responses:
'200':
description: Returns 200 OK and the list of options created (or revived from archived), in the same order as the request.
content:
application/json:
schema:
type: object
properties:
select_options:
type: array
description: The options that were created or revived from an archived option, in submitted order
items:
type: object
properties:
id:
type: string
description: The unique ID of the select option. When a submitted value matched an archived option, this is that option's existing ID.
value:
type: string
description: The option's display value
is_archived:
type: boolean
description: Always false in this response
erp_code:
type:
- string
- 'null'
description: The option's ERP code, or null if none was provided
example:
select_options:
- id: 26711955-d42e-4bf0-941e-99972881fa80
value: Engineering
is_archived: false
erp_code: ENG-01
- id: 89024c2f-df49-40f9-9225-e2124b045fd1
value: Sales
is_archived: false
erp_code: null
'400':
description: Returns '400 Bad Request' when custom_field_id is missing or not a valid ID, the custom field isn't a select/multi-select BOOKING field, a value is empty/whitespace-only or exceeds 160 characters, erp_code is missing on a cost-allocation-enabled field, or any value already exists as an active option (including duplicates within the same request) — in which case the offending values are listed in conflicting_values.
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
description: The HTTP status code
errors:
type: array
description: A list of human-readable error messages
items:
type: string
conflicting_values:
type: array
description: Present only when the request failed due to duplicate/existing values. Lists the specific values that already exist as active options or were repeated in the request.
items:
type: string
example:
status_code: 400
errors:
- Option values already exist or are duplicated in the request
conflicting_values:
- Sales
'401':
description: Returns '401 Unauthorized' when the Authorization header is missing or the API key is invalid. This response has no body.
'404':
description: Returns '404 Not Found' when custom_field_id doesn't exist, or doesn't belong to the account associated with your API key.
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
description: The HTTP status code
errors:
type: array
description: A list of human-readable error messages
items:
type: string
example:
status_code: 404
errors:
- Custom field does not exist.
'405':
description: Returns '405 Method Not Allowed' when the request uses any HTTP method other than GET or POST.
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
description: The HTTP status code
errors:
type: array
description: A list of human-readable error messages
items:
type: string
example:
status_code: 405
errors:
- 'Unsupported HTTP method: PUT'
get:
summary: List all select options
description: ''
operationId: list-custom-field-select-options
tags:
- Custom Fields
parameters:
- name: custom_field_id
in: path
required: true
description: The unique ID of the custom field
schema:
type: string
- name: Authorization
in: header
required: true
description: Your Perk API key, using the format 'ApiKey <your_api_key>'
schema:
type: string
- name: Api-Version
in: header
required: true
description: The API version for this request. Must be '1'.
schema:
type: string
- name: limit
in: query
required: false
description: The number of options to return, from 1 to 100. Defaults to 20.
schema:
type: integer
- name: offset
in: query
required: false
description: The number of options to skip before returning results. Defaults to 0.
schema:
type: integer
- name: query
in: query
required: false
description: Filters options to those whose value contains this substring.
schema:
type: string
- name: status
in: query
required: false
description: Comma-separated list of statuses to include. Accepts 'active' and 'archived'. Defaults to 'active'.
schema:
type: string
responses:
'200':
description: Returns 200 OK and a list of select options for the custom field, along with total_count, limit and offset
content:
application/json:
schema:
type: object
properties:
select_options:
type: array
description: The list of options matching the request
items:
type: object
properties:
id:
type: string
description: The unique ID of the select option
value:
type: string
description: The option's display value
is_archived:
type: boolean
description: Indicates whether the option is archived
total_count:
type: integer
description: Total number of options matching the filter, across all pages
limit:
type: integer
description: Effective page size used (echoes the request's limit, default 20)
offset:
type: integer
description: Effective offset used (echoes the request's offset, default 0)
example:
select_options:
- id: 3568837f-6072-4773-afd6-6aa8e61e844f
value: Test
is_archived: false
total_count: 153
limit: 20
offset: 0
'400':
description: Returns '400 Bad Request' when custom_field_id is missing or not a valid ID, or when limit or offset is out of range.
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
description: The HTTP status code
errors:
type: array
description: A list of human-readable error messages
items:
type: string
example:
status_code: 400
errors:
- 'limit: Input should be less than or equal to 100'
'401':
description: Returns '401 Unauthorized' when the Authorization header is missing or the API key is invalid. This response has no body.
'404':
description: Returns '404 Not Found' when custom_field_id doesn't exist, or doesn't belong to the account associated with your API key.
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
description: The HTTP status code
errors:
type: array
description: A list of human-readable error messages
items:
type: string
example:
status_code: 404
errors:
- Custom field does not exist.
'405':
description: Returns '405 Method Not Allowed' when the request uses any HTTP method other than GET.
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
description: The HTTP status code
errors:
type: array
description: A list of human-readable error messages
items:
type: string
example:
status_code: 405
errors:
- 'Unsupported HTTP method: POST'
servers:
- url: https://api.perk.com
/custom-fields/{custom_field_id}/select-options/{option_id}/{archive_action}:
post:
summary: Archive or unarchive a select option
description: ''
operationId: archive-custom-field-select-option
tags:
- Custom Fields
parameters:
- name: custom_field_id
in: path
required: true
description: The unique ID of the custom field the option belongs to.
schema:
type: string
- name: option_id
in: path
required: true
description: The unique ID of the select option to archive or unarchive.
schema:
type: string
- name: archive_action
in: path
required: true
description: The action to perform. Must be 'archive' or 'unarchive'.
schema:
type: string
enum:
- archive
- unarchive
- name: Authorization
in: header
required: true
description: Your Perk API key, using the format 'ApiKey <your_api_key>'
schema:
type: string
- name: Api-Version
in: header
required: true
description: The API version for this request. Must be '1'.
schema:
type: string
responses:
'200':
description: Returns 200 OK and the option's resulting state.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The unique ID of the select option
value:
type: string
description: The option's display value
is_archived:
type: boolean
description: Whether the option is archived after this request
example:
id: 26711955-d42e-4bf0-941e-99972881fa80
value: Engineering
is_archived: true
'400':
description: Returns '400 Bad Request' when custom_field_id or option_id is missing or not a valid ID, or archive_action is not 'archive' or 'unarchive'.
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
description: The HTTP status code
errors:
type: array
description: A list of human-readable error messages
items:
type: string
example:
status_code: 400
errors:
- 'archive_action: Input should be ''archive'' or ''unarchive'''
'401':
description: Returns '401 Unauthorized' when the Authorization header is missing or the API key is invalid. This response has no body.
'404':
description: Returns '404 Not Found' when custom_field_id doesn't exist or doesn't belong to the account associated with your API key, or when option_id doesn't exist on that custom field.
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
description: The HTTP status code
errors:
type: array
description: A list of human-readable error messages
items:
type: string
examples:
custom_field_not_found:
summary: Custom field not found
value:
status_code: 404
errors:
- Custom field does not exist.
option_not_found:
summary: Select option not found
value:
status_code: 404
errors:
- Custom field option does not exist.
'409':
description: Returns '409 Conflict' when unarchiving an option whose value (case-insensitive) matches an already-active option on the same custom field.
content:
application/json:
schema:
type: object
properties:
status_code:
type: integer
description: The HTTP status code
errors:
type: array
description: A list of human-readable error messages
items:
type: string
example:
status_code: 409
errors:
- An active option with this value already exists.
servers:
- url: https://api.perk.com
x-refined-from:
- perk-custom-fields-openapi.yml
- perk-custom-fields-api-openapi.yml
x-provenance:
method: searched
source: https://developers.perk.com/reference
harvested: '2026-10-14'
tool: harvest-readme-openapi.py
note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
assembled_from:
- https://developers.perk.com/reference/archive-custom-field-select-option.md
- https://developers.perk.com/reference/create-custom-field-select-options.md
merge:
pages: 2
deduped: 0
conflicts_kept_first: 0