Sample - Box Platform API
POST/metadata_templates/schema

Create metadata template

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

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

6 body fields
scopestringrequired
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.
templateKeystringoptional
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`.
displayNamestringrequired
The display name of the template.
hiddenbooleanoptional
Defines if this template is visible in the Box web app UI, or if it is purely intended for usage through the API.
Default:false
fieldsarray<MetadataFieldWrite>optional
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.
copyInstanceOnItemCopybooleanoptional
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.
Default:false

4 status codes
201The schema representing the metadata template created.
idstringrequired
The ID of the metadata template.
typestringrequired
The value will always be `metadata_template`.
Allowed:metadata_template
scopestringoptional
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.
templateKeystringoptional
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.
displayNamestringoptional
The display name of the template. This can be seen in the Box web app and mobile apps.
hiddenbooleanoptional
Defines if this template is visible in the Box web app UI, or if it is purely intended for usage through the API.
fieldsarray<object>optional
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.
copyInstanceOnItemCopybooleanoptional
Whether or not to include the metadata when a file or folder is copied.
400Returned 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.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
403Returned 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.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.
defaultAn unexpected client error.
typestringoptional
The value will always be `error`.
Allowed:error
statusintegeroptional
The HTTP status of the response.
codestringoptional
A Box-specific error code.
Allowed:createdacceptedno_contentredirectnot_modifiedbad_requestunauthorizedforbiddennot_foundmethod_not_allowedconflictprecondition_failed
messagestringoptional
A short message describing the error.
context_infoobjectoptional
A free-form object that contains additional context about the error. The possible fields are defined on a per-endpoint basis. `message` is only one example.
help_urlstringoptional
A URL that links to more information about why this error occurred.
request_idstringoptional
A unique identifier for this response, which can be used when contacting Box support.

Error handling

A 400 is returned: 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. A 403 is returned: 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. Any other status is an error: An unexpected client error.