Custom fields

Org-defined typed fields on positions — field types, settings UI, and how values appear on position forms.

Custom fields let each organization capture structured metadata on positions (candidates and applications are supported in the API schema for future surfaces). The feature is gated behind the custom_fields per-tenant grant.

Settings → Custom Fields (/dashboard/settings/custom-fields) appears only when trpc.customFields.capabilities returns enabled: true.

Feature gate behavior

Definition management and value writes require the grant. Value reads stay open so existing data renders gracefully if a grant is later revoked.

Field types

Each definition has a fieldType (immutable after creation) and a type-specific config bag:

Select types require at least one option (max 100). Options have separate internal value and display label.

Definition metadata

Field type is immutable after creation. To change type, archive the old definition and create a new one. Existing values remain tied to the archived definition.

Settings page workflow

1. Create field — choose type, label, required flag, and type-specific config (options, min/max, etc.).
2. Reorder — arrow buttons adjust sortOrder among active definitions.
3. Edit — update label, description, required, and config (not type).
4. Archive / restore — archive hides from position forms; restore brings it back.

The UI mirrors the assessment question editor pattern: conditional config panels per field type.

Position forms

When custom fields are enabled, position create and edit surfaces render a Custom fields section:

• Fields appear in sortOrder
• Required fields block save until filled
• Validation errors are field-labelled (e.g. "Department code": must be ≤ 100 characters)
• USER fields resolve to a team member picker

Values persist in custom_field_values keyed by (definitionId, entityId) — positions use the position ID as entityId.

Not retroactively required

Adding a new required field does not invalidate existing positions missing a value. Required enforcement applies on the next edit save. This prevents mass breakage when admins add fields mid-flight.

API namespace

All procedures live under trpc.customFields:

Relationship to job governance

Custom fields are the foundation for:

• Job templates — template snapshots include custom field defaults
• Intake forms — hiring managers fill governed fields before requisition approval
• Approval conditions — conditional approval steps can reference field values (via governance buildTargetFields)

Enable custom_fields before or alongside job_governance for the full template + intake workflow.

Audit trail

Definition create/update/archive actions log to the org activity feed via logActivity with actions like custom_field.created.

Troubleshooting

Related docs

• Job governance — templates and intake forms
• Platform feature flags — enable custom_fields
• First position — using fields when creating roles