Skip to main content
POST
/
files
/
{file_id}
/
metadata
/
{scope}
/
{template_key}
cURL
curl -i -X POST "https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "audience": "internal",
       "documentType": "Q1 plans",
       "competitiveDocument": "no",
       "status": "active",
       "author": "Jones",
       "currentState": "proposal"
     }'
{
  "$parent": "folder_59449484661,",
  "$template": "marketingCollateral",
  "$scope": "enterprise_27335",
  "$version": 1,
  "$canEdit": true,
  "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
  "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
  "$typeVersion": 2
}
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.

Path Parameters

​
file_id
string
required

The unique identifier that represents a file.

The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL https://*.app.box.com/files/123 the file_id is 123.

​
scope
enum<string>
required

The scope of the metadata template.

Available options:
global,
enterprise
​
template_key
string
required

The name of the metadata template.

Body

application/json
​
{key}
any

A value for each of the fields that are present on the metadata template. For the global.properties template this can be a list of zero or more fields, as this template allows for any generic key-value pairs to be stored stored in the template. For a taxonomy field, the value should be a list of the node identifiers of the selected taxonomy nodes, since taxonomy fields support multi-select. If a single select taxonomy field is being set, the list should contain a single node identifier.

Example:

"Aaron Levie"

Response

Returns the instance of the template that was applied to the file, including the data that was applied to the template.

An instance of a metadata template, which has been applied to a file or folder.

​
$parent
string

The identifier of the item that this metadata instance has been attached to. This combines the type and the id of the parent in the form {type}_{id}.

Example:

"folder_59449484661,"

​
$template
string

The name of the template.

Example:

"marketingCollateral"

​
$scope
string

An ID for the scope in which this template has been applied. This will be enterprise_{enterprise_id} for templates defined for use in this enterprise, and global for general templates that are available to all enterprises using Box.

Example:

"enterprise_27335"

​
$version
integer

The version of the metadata instance. This version starts at 0 and increases every time a user-defined property is modified.

Example:

1

​
$canEdit
boolean

Whether the user can edit this metadata instance.

Example:

true

​
$id
string<uuid>

A UUID to identify the metadata instance.

Maximum string length: 36
Example:

"01234500-12f1-1234-aa12-b1d234cb567e"

​
$type
string

A unique identifier for the "type" of this instance. This is an internal system property and should not be used by a client application.

Example:

"properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0"

​
$typeVersion
integer

The last-known version of the template of the object. This is an internal system property and should not be used by a client application.

Example:

2

​
{key}
any

A value for each of the fields that are present on the metadata template. For the global.properties template this can be a list of zero or more fields, as this template allows for any generic key-value pairs to be stored stored in the template.

Example:

"Aaron Levie"