---
title: "Create custom field definition"
method: POST
path: "/v1/custom-fields"
tags: ["Custom Field"]
---

# Create custom field definition

`POST /v1/custom-fields`

Create a typed custom-field definition. The definition is immediately usable.

## Request body

- object
  - `key` string, required
  - `name` string, required
  - `description` string
  - `kind` 'text' | 'integer' | 'decimal' | 'boolean' | 'date' | 'datetime' | 'url' | 'single_select' | 'multi_select' | 'user_reference' | 'resource_reference', required
  - `scope_id` string, required
  - `scope_type` 'Assignment' | 'Attachment' | 'Comment' | 'Document' | 'Issue' | 'IssueRelation' | 'Label' | 'Namespace' | 'Notification' | 'Organization' | 'Permission' | 'Project' | 'ResourceType' | 'Role' | 'Team' | 'Todo' | 'User' | 'UserToken' | 'Folder' | 'Installation' | 'CustomFieldDefinition', required
  - `target_type` 'Assignment' | 'Attachment' | 'Comment' | 'Document' | 'Issue' | 'IssueRelation' | 'Label' | 'Namespace' | 'Notification' | 'Organization' | 'Permission' | 'Project' | 'ResourceType' | 'Role' | 'Team' | 'Todo' | 'User' | 'UserToken' | 'Folder' | 'Installation' | 'CustomFieldDefinition', required
  - `required` boolean
  - `index_exact` boolean
  - `index_range` boolean
  - `index_fulltext` boolean
  - `order` integer
  - `schema` union, required
    - CustomFieldTextSchema
      - `kind` 'text', required
      - `min_length` integer
      - `max_length` integer
      - `pattern` string
    - CustomFieldIntegerSchema
      - `kind` 'integer', required
      - `min` integer
      - `max` integer
    - CustomFieldDecimalSchema
      - `kind` 'decimal', required
      - `min` string
      - `max` string
      - `scale` integer
    - CustomFieldBooleanSchema
      - `kind` 'boolean', required
    - CustomFieldDateSchema
      - `kind` 'date', required
      - `min` string, date
      - `max` string, date
    - CustomFieldDateTimeSchema
      - `kind` 'datetime', required
      - `min` string, date-time
      - `max` string, date-time
    - CustomFieldURLSchema
      - `kind` 'url', required
      - `allowed_schemes` string[], required
    - CustomFieldSelectSchema
      - `kind` 'single_select' | 'multi_select', required
      - `options` CustomFieldOption[], required
        - `key` string, required
        - `label` string, required
        - `color` string
        - `disabled` boolean, required
        - `order` integer
    - CustomFieldUserReferenceSchema
      - `kind` 'user_reference', required
      - `multiple` boolean
    - CustomFieldResourceReferenceSchema
      - `kind` 'resource_reference', required
      - `allowed_types` ResourceType[], required
      - `multiple` boolean

## Response `201`

Created

- CustomFieldDefinition
  - `id` string, required
  - `key` string, required
  - `name` string, required
  - `description` string
  - `kind` 'text' | 'integer' | 'decimal' | 'boolean' | 'date' | 'datetime' | 'url' | 'single_select' | 'multi_select' | 'user_reference' | 'resource_reference', required
  - `scope_id` string, required
  - `scope_type` 'Assignment' | 'Attachment' | 'Comment' | 'Document' | 'Issue' | 'IssueRelation' | 'Label' | 'Namespace' | 'Notification' | 'Organization' | 'Permission' | 'Project' | 'ResourceType' | 'Role' | 'Team' | 'Todo' | 'User' | 'UserToken' | 'Folder' | 'Installation' | 'CustomFieldDefinition', required
  - `target_type` 'Assignment' | 'Attachment' | 'Comment' | 'Document' | 'Issue' | 'IssueRelation' | 'Label' | 'Namespace' | 'Notification' | 'Organization' | 'Permission' | 'Project' | 'ResourceType' | 'Role' | 'Team' | 'Todo' | 'User' | 'UserToken' | 'Folder' | 'Installation' | 'CustomFieldDefinition', required
  - `required` boolean, required
  - `archived` boolean, required
  - `index_exact` boolean, required
  - `index_range` boolean, required
  - `index_fulltext` boolean, required
  - `order` integer, required
  - `owner_user_id` string, required
  - `registrar_client_id` string
  - `schema` union, required
    - CustomFieldTextSchema
      - `kind` 'text', required
      - `min_length` integer
      - `max_length` integer
      - `pattern` string
    - CustomFieldIntegerSchema
      - `kind` 'integer', required
      - `min` integer
      - `max` integer
    - CustomFieldDecimalSchema
      - `kind` 'decimal', required
      - `min` string
      - `max` string
      - `scale` integer
    - CustomFieldBooleanSchema
      - `kind` 'boolean', required
    - CustomFieldDateSchema
      - `kind` 'date', required
      - `min` string, date
      - `max` string, date
    - CustomFieldDateTimeSchema
      - `kind` 'datetime', required
      - `min` string, date-time
      - `max` string, date-time
    - CustomFieldURLSchema
      - `kind` 'url', required
      - `allowed_schemes` string[], required
    - CustomFieldSelectSchema
      - `kind` 'single_select' | 'multi_select', required
      - `options` CustomFieldOption[], required
        - `key` string, required
        - `label` string, required
        - `color` string
        - `disabled` boolean, required
        - `order` integer
    - CustomFieldUserReferenceSchema
      - `kind` 'user_reference', required
      - `multiple` boolean
    - CustomFieldResourceReferenceSchema
      - `kind` 'resource_reference', required
      - `allowed_types` ResourceType[], required
      - `multiple` boolean
  - `created_at` string, date-time
  - `updated_at` string, date-time, nullable

## Other responses

- `400` — Bad request
- `401` — Unauthorized request
- `403` — Forbidden
- `409` — Conflict
- `500` — Internal Server Error

## Changes

- **2026-09-02** `605ffe113d3d` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/opcotech/apis/elemo-api/changes/v1/custom-fields/post.md)

---

[API](https://skmtc.dev/opcotech/apis/elemo-api.md) · [All operations](https://skmtc.dev/opcotech/apis/elemo-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/opcotech/elemo-api/revisions/605ffe113d3d/schema)