The steps below explain how to find the custom fields that already exist for a company. This is useful when you need to obtain a customFieldId for a field you did not create yourself or change the order in which those custom fields are presented.
| Step | Name | Endpoint | Details |
|---|---|---|---|
| List custom fields | POST /v3/companies/{companyId}/custom-fields/list | List the custom fields that apply to a company, including the ones inherited from a parent level. URL path requires: companyId retrieved from the get company API.Query parameter requires: companyRole, which sets the level the list is read at.Request body requires: paginationParams, which accepts offset (default 0) and limit (default 100). You can optionally add searchText to filter by name, and a filter object that accepts definedAtList, enabled, customFieldIds, and tripUsageTypes.Response will contain: paginationParams and a fields array. Each entry carries the custom field id, name, description, definedAt, enabled, createdAt, and parentInfos, which identifies the parent level field that this field was inherited from.Other APIs will use: the id of the custom field you want to read or modify, which every other endpoint takes as the customFieldId path parameter. | |
| Get custom field (optional) | GET /v3/companies/{companyId}/custom-fields/{customFieldId} | Retrieve a single custom field. URL path requires: companyId and customFieldId from Step 1.Response will contain: the custom field id, name, description, includeLocations, managementTags, and respondOnlyOnceLevel.Note: The arms are not included in this response. Use the list arms endpoint to retrieve them. | |
| Reorder custom fields | POST /v3/companies/{companyId}/custom-fields/reorder | Change the order in which the custom fields are presented to the traveler at checkout. URL path requires: companyId.Request body requires: targetFieldId, which is the custom field that the others are moved relative to, direction set to BEFORE or AFTER, and fieldIdsToMove, an array of at least one custom field id taken from Step 1.Response will contain: a 200 status code indicating the order was updated. |