Custom fields
Create Custom Field
Creates a new custom field definition.
POST /api/custom-fields
Requires the admin role (or a global admin). Editors and read-only users receive 403.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
organizationId | number | No | from session | Must match your own organization if given |
name | string | Yes | - | Display name, 1 to 100 characters |
fieldKey | string | No | auto from name | Unique key, max 100 characters (auto-normalized: lowercase, non-alphanumeric → _) |
fieldType | string | No | text | One of text, number, email, url, select |
isRequired | boolean | No | false | Whether the field is required |
displayOrder | number | No | 0 | Sort order, integer 0 to 10000 |
options | string[] | No | [] | Options for the select type, max 50 entries of max 100 characters each |
placeholder | string|null | No | null | Placeholder text, max 200 characters |
helpText | string|null | No | null | Help text below the field, max 500 characters |
showInTable | boolean | No | true | Show in table views |
Example (cURL)
curl -X POST "$BASE_URL/api/custom-fields" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"organizationId": 1,
"name": "Environment",
"fieldType": "select",
"options": ["production", "staging", "development"],
"isRequired": true,
"showInTable": true
}'Common errors
400 Bad Requestwhen the body fails validation (unknownfieldType,namemissing or over 100 characters, more than 50options)403 Forbiddenwhen your role is notadmin, or whenorganizationIdnames another organization409 ConflictwhenfieldKeyalready exists for the organization
Response
Returns the created custom field object. See Error Codes for error responses.