Skip to main content
POST
/
metadata_templates
/
schema
cURL
curl -i -X POST "https://api.box.com/2.0/metadata_templates/schema" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
      "scope": "enterprise",
      "displayName": "Customer",
      "fields": [
        {
          "type": "string",
          "key": "name",
          "displayName": "Name",
          "description": "The customer name",
          "hidden": false
        },
        {
          "type": "date",
          "key": "last_contacted_at",
          "displayName": "Last Contacted At",
          "description": "When this customer was last contacted at",
          "hidden": false
        },
        {
          "type": "enum",
          "key": "industry",
          "displayName": "Industry",
          "options": [
            {"key": "Technology"},
            {"key": "Healthcare"},
            {"key": "Legal"}
          ]
        },
        {
          "type": "multiSelect",
          "key": "role",
          "displayName": "Contact Role",
          "options": [
            {"key": "Developer"},
            {"key": "Business Owner"},
            {"key": "Marketing"},
            {"key": "Legal"},
            {"key": "Sales"}
          ]
        }
      ]
    }'
{
  "id": "58063d82-4128-7b43-bba9-92f706befcdf",
  "type": "metadata_template",
  "scope": "enterprise_123456",
  "templateKey": "productInfo",
  "displayName": "Product Info",
  "hidden": true,
  "fields": [
    {
      "type": "string",
      "key": "category",
      "displayName": "Category",
      "description": "The category",
      "hidden": true,
      "options": [
        {
          "key": "Category 1",
          "id": "45dc2849-a4a7-40a9-a751-4a699a589190"
        }
      ],
      "id": "822227e0-47a5-921b-88a8-494760b2e6d2"
    }
  ],
  "copyInstanceOnItemCopy": true
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json
​
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.

Example:

"enterprise"

​
displayName
string
required

The display name of the template.

Maximum string length: 4096
Example:

"Product Info"

​
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.

Maximum string length: 64
Example:

"productInfo"

​
hidden
boolean
default:false

Defines if this template is visible in the Box web app UI, or if it is purely intended for usage through the API.

Example:

true

​
fields
Metadata Field (Write) · 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.

​
copyInstanceOnItemCopy
boolean
default:false

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.

Example:

true

Response

The schema representing the metadata template created.

A template for metadata that can be applied to files and folders.

​
id
string
required

The ID of the metadata template.

Example:

"58063d82-4128-7b43-bba9-92f706befcdf"

​
type
enum<string>
required

The value will always be metadata_template.

Available options:
metadata_template
Example:

"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.

Example:

"enterprise_123456"

​
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.

Maximum string length: 64
Example:

"productInfo"

​
displayName
string

The display name of the template. This can be seen in the Box web app and mobile apps.

Maximum string length: 4096
Example:

"Product Info"

​
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.

Example:

true

​
fields
Metadata Field (Read) · 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.

​
copyInstanceOnItemCopy
boolean

Whether or not to include the metadata when a file or folder is copied.

Example:

true