Box Developer Documentation
 
    Latest version

    Create metadata template

    post
    https://api.box.com/2.0
    /metadata_templates/schema

    This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.

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

    Request

    bearer [ACCESS_TOKEN]
    application/json

    Request Body

    booleanin bodyoptional
    true
    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.

    stringin bodyrequired
    "Product Info"
    4096

    The display name of the template.

    object arrayin bodyoptional

    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.

    stringin bodyconditionally required
    "string"

    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.

    Value is one of string,float,date,enum,multiSelect

    stringin bodyoptional
    "The category"
    4096

    A description of the field. This is not shown to the user.

    stringin bodyconditionally required
    "Category"
    4096

    The display name of the field as it is shown to the user in the web and mobile apps.

    booleanin bodyoptional
    true

    Whether this field is hidden in the UI for the user and can only be set through the API instead.

    stringin bodyconditionally required
    "category"
    256

    A unique identifier for the field. The identifier must be unique within the template to which it belongs.

    object arrayin bodyoptional

    A list of options for this field. This is used in combination with the enum and multiSelect field types.

    stringin bodyconditionally required
    "Category 1"

    The text value of the option. This represents both the display name of the option and the internal key used when updating templates.

    booleanin bodyoptional
    true
    false

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

    stringin bodyrequired
    "enterprise"

    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.

    stringin bodyoptional
    ^[a-zA-Z_][-a-zA-Z0-9_]*$
    "productInfo"
    64

    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.

    Response

    application/jsonMetadata template

    The schema representing the metadata template created.

    application/jsonClient error

    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.
    application/jsonClient error

    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.

    application/jsonClient error

    An unexpected client error.

    post
    Create metadata template
    You can now try out some of our APIs live, right here in the documentation.
    Log in

    Request Example

    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"}
              ]
            }
          ]
        }'

    Response Example

    {
      "id": "58063d82-4128-7b43-bba9-92f706befcdf",
      "type": "metadata_template",
      "copyInstanceOnItemCopy": true,
      "displayName": "Product Info",
      "fields": [
        {
          "description": "The category",
          "displayName": "Category",
          "hidden": true,
          "key": "category",
          "options": [
            {
              "key": "Category 1",
              "id": "45dc2849-a4a7-40a9-a751-4a699a589190"
            }
          ],
          "type": "string",
          "id": "822227e0-47a5-921b-88a8-494760b2e6d2"
        }
      ],
      "hidden": true,
      "scope": "enterprise_123456",
      "templateKey": "productInfo"
    }