In this article, you can read about how to retrieve, update, and delete custom field values on a project via the API, including all supported custom field types (number, date, text, single select, and multi select).
Note
Custom fields can be active or not active. A custom field is considered not active if it has been archived. If a custom field is not active, it cannot be modified — but its value(s) can still be deleted.
Get Custom Fields
GET
https://api.recman.io/v2/get/?key={{api_key}}
&scope=projectCustomField&projectId=238078Retrieving data about project custom fields is done through the GET method.
Additional query parameters
- onlyWithValue — retrieve only the fields on which the project has value(s) set.
- onlyActive — retrieve only active (not archived) fields.
Note
You can combine onlyWithValue and onlyActive to adjust your fetch requests more precisely.
Response details
- If the project has value(s) for a specific custom field item, the response item includes a
valuefield. If not, thevaluefield is excluded from the item's data structure. - The
valuefield can be a string or an array of integers, depending on the custom field type.
Available custom field types and their value format
| Type | Value field type |
|---|---|
| number | string |
| date | string |
| text | string |
| singleSelect | array of integer |
| multiSelect | array of integer(s) |
Type: number
The number type supports three formats, each identified by properties.format:
| Format | Description |
|---|---|
| currency | properties.data may contain decimal (limits the currency's decimal precision) and currencyCode. |
| number | properties.data may contain decimal (limits precision), plus min and max allowed values. |
| percentage | properties.data may contain decimal, limiting the percentage's decimal precision. |
Type: date
This type does not have a properties field. The date value uses the format Y-m-d (e.g. "2024-10-15").
Type: text
The value is a plain string.
Type: singleSelect and multiSelect
For these types, properties is an array of selectable items. Each option has an id (used for the update operation), a title, and a colorHexCode (the option's hexadecimal color code).
- singleSelect — the
valuearray contains a single option ID. - multiSelect — the
valuearray can contain multiple option IDs.
Get Custom Fields Parameters
| Fields | Description |
|---|---|
| projectId integer | Project ID. Required |
| onlyWithValue boolean | Optional. Default: false |
| onlyActive boolean | Optional. Default: false |
PARAMS
| key | {{api_key}} required, string |
| scope | projectCustomField required |
| projectId | 238078 required, integer |
| onlyWithValue | true optional, boolean. Default: false |
| onlyActive | true optional, boolean. Default: false |
Update Custom Field
POST
https://api.recman.io/v2/post/For updating a project custom field, use the POST method with the operation set to update and scope to projectCustomField. It's required to specify the projectId, customFieldId, and value fields.
Note
A custom field's value(s) cannot be modified if the custom field is not active (archived).
Note
Updating value(s) works as an override action — it removes existing value(s) and stores the new ones specified. For example, if a multiSelect field currently has options 430, 431, and 432, and you update it with 450 and 451, only 450 and 451 are saved. If you want to add new options to the existing ones, you must specify the existing options along with the new ones.
Update Custom Field Fields
| Fields | Description |
|---|---|
| projectId integer | Project ID. Required |
| customFieldId integer | Custom field ID. Required |
| value string, integer, double, or array of integer(s) | Value to update to. Required. For singleSelect and multiSelect types, must be an array of integer(s) — the IDs come from properties.id in the Get Custom Fields response.For number type, can be a string (e.g. "10.033"), integer, or double (e.g. 10.033). For date type, must be a string in Y-m-d format (e.g. "2024-10-15").For text type, must be a string. |
Examples of field value(s) update, by type
| Type | Example value |
|---|---|
| number | "47.333" (string) or 47.333 (double/integer) |
| date | "2024-10-15" |
| text | "This is just a dummy text as an example" |
| singleSelect | [429] — a single option ID from properties.id |
| multiSelect | [145, 432] — one or more option IDs from properties.id |
Delete Custom Field
POST
For deleting a project custom field's value(s), use the POST method with the operation set to delete and scope to projectCustomField. It's required to specify the projectId and customFieldId fields.
Delete Custom Field Fields
| Fields | Description |
|---|---|
| projectId integer | Project ID. Required |
| customFieldId integer | Custom field ID. Required |
What's next
Custom fields also exist on the Candidate and Booking scopes, following the same request structure (scope candidateCustomField and bookingCustomField respectively). Continue with the Company series of articles, or explore other sections such as Departments or Jobs.