---
title: "Bulk update metadata values"
method: PUT
path: "/documents/{document}/metadata-values"
tags: ["Document Operations"]
---

# Bulk update metadata values

`PUT /documents/{document}/metadata-values`

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

Sets or removes the values of one or more [metadata](/#metadata) fields for a [document](/#documents) in a single
request.

The `changes` parameter is a list of up to 20 objects, each identifying a metadata by its `uuid` or `name`, and
specifying an `operation`:

- `set`: adds the metadata to the document (if not already present) and sets its `value`. The `value` follows the
  same format as the [Add metadata value to document](/operations/v1.documents.metadata-values.store) endpoint.
- `unset`: removes the document's value for the metadata, equivalent to the [Delete metadata
  value](/operations/v1.documents.metadata-values.destroy) endpoint.

Returns the metadata values that were set; metadata values that were unset are not included in the response.

## Path parameters

- `document` string, required

## Request body

- BulkUpdateMetadataValueRequest
  - `changes` object[] — A list of up to 20 changes to apply to the document's metadata values.
    - `identifier` string, required — A metadata's `uuid` or `name`.
    - `operation` 'set' | 'unset', required — The operations that can be applied to a documents metadata value as part of a bulk change. | | |---| | `set` <br/> Create or update the metadata value | | `unset` <br/> Remove the metadata value (or, for always-exists metadata, detach it) |
    - `value` string, nullable — The new value, for a `set` operation. Follows the same format as the Add/Update metadata value endpoints.

## Response `200`

Array of `MetadataValueResource`

- object
  - `data` MetadataValueResource[], required
    - `uuid` string, required
    - `metadata` 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.
    - `reference_dynamic_field_uuid` string, nullable, required
    - `value_source` 'user' | 'ai_analysis' | 'computed' | 'autofilled' | 'dynamic_field' | 'linked_document', required
    - `value` union, required — The metadata's value
      - string
      - boolean
      - unknown[]
        - unknown
    - `value_currency_monthly` string, nullable, required
    - `value_currency_yearly` string, nullable, required
    - `computed_status` 'missing_information' | 'conflicting_information' | 'not_applicable' | 'computed', required
    - `computed_value` union, required
      - string
      - boolean
      - unknown[]
        - unknown
    - `is_attached` boolean, required
    - `computed_at` string, date-time, nullable, required

## Other responses

- `401` — Unauthenticated
- `403` — Authorization error
- `404` — Not found
- `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)