---
title: "Create metadata template"
method: POST
path: "/metadata_templates/schema"
tags: ["Metadata templates"]
---

# Create metadata template

`POST /metadata_templates/schema`

Creates a new metadata template that can be applied to
files and folders.

## Request body

- object
  - `scope` string, required — The scope of the metadata template to create. Applications can only create templates for use within the authenticated user's enterprise. This value needs to be set to `enterprise`, as `global` scopes can not be created by applications.
  - `templateKey` string — A unique identifier for the template. This identifier needs to be unique across the enterprise for which the metadata template is being created. When not provided, the API will create a unique `templateKey` based on the value of the `displayName`.
  - `displayName` string, required — The display name of the template.
  - `hidden` boolean — Defines if this template is visible in the Box web app UI, or if it is purely intended for usage through the API.
  - `fields` object[] — An ordered list of template fields which are part of the template. Each field can be a regular text field, date field, number field, as well as a single or multi-select list.
    - `type` 'string' | 'float' | 'date' | 'enum' | 'multiSelect' | 'taxonomy', required — The type of field. The basic fields are a `string` field for text, a `float` field for numbers, and a `date` field to present the user with a date-time picker. Additionally, metadata templates support an `enum` field for a basic list of items, and `multiSelect` field for a similar list of items where the user can select more than one value. Metadata taxonomies are also supported as a `taxonomy` field type with a specific set of additional properties, which describe its structure.
    - `key` string, required — A unique identifier for the field. The identifier must be unique within the template to which it belongs.
    - `displayName` string, required — The display name of the field as it is shown to the user in the web and mobile apps.
    - `description` string — A description of the field. This is not shown to the user.
    - `hidden` boolean — Whether this field is hidden in the UI for the user and can only be set through the API instead.
    - `options` object[] — A list of options for this field. This is used in combination with the `enum` and `multiSelect` field types.
      - `key` string, required — The text value of the option. This represents both the display name of the option and the internal key used when updating templates.
    - `taxonomyKey` string — The unique key of the metadata taxonomy to use for this taxonomy field. This property is required when the field `type` is set to `taxonomy`.
    - `taxonomyId` string — The unique ID of the metadata taxonomy to use for this taxonomy field. This property is required when the field `type` is set to `taxonomy`.
    - `namespace` string — The namespace of the metadata taxonomy to use for this taxonomy field. This property is required when the field `type` is set to `taxonomy`.
    - `optionsRules` object — An object defining additional rules for the options of the taxonomy field. This property is required when the field `type` is set to `taxonomy`.
      - `multiSelect` boolean — Whether to allow users to select multiple values.
      - `selectableLevels` integer[] — An array of integers defining which levels of the taxonomy are selectable by users.
  - `copyInstanceOnItemCopy` boolean — Whether or not to copy any metadata attached to a file or folder when it is copied. By default, metadata is not copied along with a file or folder when it is copied.

## Response `201`

The schema representing the metadata template created.

- MetadataTemplate — A template for metadata that can be applied to files and folders.
  - `id` string, required — The ID of the metadata template.
  - `type` 'metadata_template', required — The value will always be `metadata_template`.
  - `scope` string — The scope of the metadata template can either be `global` or `enterprise_*`. The `global` scope is used for templates that are available to any Box enterprise. The `enterprise_*` scope represents templates that have been created within a specific enterprise, where `*` will be the ID of that enterprise.
  - `templateKey` string — A unique identifier for the template. This identifier is unique across the `scope` of the enterprise to which the metadata template is being applied, yet is not necessarily unique across different enterprises.
  - `displayName` string — The display name of the template. This can be seen in the Box web app and mobile apps.
  - `hidden` boolean — Defines if this template is visible in the Box web app UI, or if it is purely intended for usage through the API.
  - `fields` object[] — An ordered list of template fields which are part of the template. Each field can be a regular text field, date field, number field, as well as a single or multi-select list.
    - `type` 'string' | 'float' | 'date' | 'enum' | 'multiSelect' | 'taxonomy' | 'integer', required — The type of field. The basic fields are a `string` field for text, a `float` field for numbers, and a `date` fields to present the user with a date-time picker. Additionally, metadata templates support an `enum` field for a basic list of items, and `multiSelect` field for a similar list of items where the user can select more than one value. Metadata taxonomies are also supported as a `taxonomy` field type with a specific set of additional properties, which describe its structure. **Note**: The `integer` value is deprecated. It is still present in the response, but cannot be used in the POST request.
    - `key` string, required — A unique identifier for the field. The identifier must be unique within the template to which it belongs.
    - `displayName` string, required — The display name of the field as it is shown to the user in the web and mobile apps.
    - `description` string — A description of the field. This is not shown to the user.
    - `hidden` boolean — Whether this field is hidden in the UI for the user and can only be set through the API instead.
    - `options` object[] — A list of options for this field. This is used in combination with the `enum` and `multiSelect` field types.
      - `key` string, required — The text value of the option. This represents both the display name of the option and the internal key used when updating templates.
      - `id` string — The internal unique identifier of the option.
    - `taxonomyKey` string — The unique key of the metadata taxonomy to use for this taxonomy field. This property is required when the field `type` is set to `taxonomy`.
    - `taxonomyId` string — The unique ID of the metadata taxonomy to use for this taxonomy field. This property is required when the field `type` is set to `taxonomy`.
    - `namespace` string — The namespace of the metadata taxonomy to use for this taxonomy field. This property is required when the field `type` is set to `taxonomy`.
    - `optionsRules` object — An object defining additional rules for the options of the taxonomy field. This property is required when the field `type` is set to `taxonomy`.
      - `multiSelect` boolean — Whether to allow users to select multiple values.
      - `selectableLevels` integer[] — An array of integers defining which levels of the taxonomy are selectable by users.
    - `id` string — The unique ID of the metadata template field.
  - `copyInstanceOnItemCopy` boolean — Whether or not to include the metadata when a file or folder is copied.

## Other responses

- `400` — Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing.
- `403` — Returned when the user does not have the permission to create the metadata template. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the application tries to create a template with the `global` scope.
- `default` — An unexpected client error.

---

[API](https://skmtc.net/box/apis/platform-api.md) · [All operations](https://skmtc.net/box/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/box/platform-api/revisions/ba8f087e1a4d/schema)