---
title: "Create metadata"
method: POST
path: "/metadata"
tags: ["Account"]
---

# Create metadata

`POST /metadata`

<small>Requires an API token with the **Metadata Manager** role.</small>

Creates a new account-level [metadata](/#metadata) field definition.

Note that the `name` and `value_type` sent in this request are fixed at the time of creation and cannot be
changed later.

## Request body

- StoreMetadataRequest
  - `value_type` 'id' | 'uuid' | 'bool' | 'date' | 'duration' | 'email' | 'list' | 'number' | 'currency' | 'currency_duration' | 'clause' | 'select' | 'multi_select' | 'text' | 'textarea' | 'timestamp' | 'array' | 'enum', required
  - `display_name` string, required — The display name shown in the UI.
  - `name` string, required — The programmatic name. Cannot be changed after creation. Must be lowercase alphanumeric with underscores only. Must be unique within the account and must not conflict with system metadata names.
  - `description` string, nullable — A description of the metadata field.
  - `prompt` string, nullable — An AI prompt used for metadata extraction.
  - `keywords` string, nullable — Keywords to help with metadata identification.
  - `is_contract_value` boolean, nullable — Whether this is a contract value field. Can only be `true` when `value_type` is `currency` or `currency_duration`.
  - `select_values` string[], nullable — The possible values when `value_type` is `select` or `multi_select`.
  - `relevant_document_type_uuids` string[], nullable — UUIDs of document types this metadata is relevant for. `null` means not relevant to any document types. `[]` (empty array) means relevant to all document types.

## Response `201`

`MetadataResource`

- object
  - `data` MetadataResource, required
    - `uuid` string, required
    - `type` 'system_autofilled' | 'system_computed' | 'system' | 'system_reference' | 'account', required
    - `value_type` 'id' | 'uuid' | 'bool' | 'date' | 'duration' | 'email' | 'list' | 'number' | 'currency' | 'currency_duration' | 'clause' | 'select' | 'multi_select' | 'text' | 'textarea' | 'timestamp' | 'array' | 'enum', required
    - `name` string, required
    - `display_name` string, required
    - `settings` MultiFieldSettingsResource, required
      - `currencies` string[], required — For `currency` or `currency_duration` fields, defines the currencies that can be assigned to the field's values
    - `select_values` string[], nullable, required — When `value_type` is `select`, defines the possible values for the metadata's value
    - `always_exists` boolean, required
    - `description` string, nullable, required
    - `keywords` string, nullable, required — Keywords to help with metadata identification.
    - `prompt` string, nullable, required — An AI prompt used for metadata extraction.
    - `is_contract_value` boolean, required — If true, this metadata will be included in the calculated "contract value" if it is present in a document. Only relevant when the value type is one of: `currency`, `currency_duration`
    - `relevant_document_type_uuids` string[], nullable, required — UUIDs of document types this metadata is relevant for. `null` means not relevant to any. `[]` means relevant to all.

## Other responses

- `401` — Unauthenticated
- `403` — Authorization error
- `422` — Validation error

---

[API](https://skmtc.dev/fynk/apis/fynk-api-reference.md) · [All operations](https://skmtc.dev/fynk/apis/fynk-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fynk/fynk-api-reference/revisions/9657a6757f59/schema)