Box Developer Documentation

Join BoxWorks 2024 to discover what's possible with content and AI!

Register now!

Create metadata template

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

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

Request

bearer [ACCESS_TOKEN]
application/json

Request Body

booleanin bodyoptional
truefalse

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
truefalse

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"}
          ]
        }
      ]
    }'
TypeScript Gen
await client.metadataTemplates.createMetadataTemplate({
  scope: 'enterprise',
  displayName: templateKey,
  templateKey: templateKey,
  fields: [
    {
      key: 'firstName',
      displayName: 'First name',
      description: 'Person first name',
      type: 'string' as CreateMetadataTemplateRequestBodyFieldsTypeField,
    } satisfies CreateMetadataTemplateRequestBodyFieldsField,
    {
      key: 'lastName',
      displayName: 'Last name',
      description: 'Person last name',
      type: 'string' as CreateMetadataTemplateRequestBodyFieldsTypeField,
    } satisfies CreateMetadataTemplateRequestBodyFieldsField,
    {
      key: 'dateOfBirth',
      displayName: 'Birth date',
      description: 'Person date of birth',
      type: 'date' as CreateMetadataTemplateRequestBodyFieldsTypeField,
    } satisfies CreateMetadataTemplateRequestBodyFieldsField,
    {
      key: 'age',
      displayName: 'Age',
      description: 'Person age',
      type: 'float' as CreateMetadataTemplateRequestBodyFieldsTypeField,
    } satisfies CreateMetadataTemplateRequestBodyFieldsField,
    {
      key: 'hobby',
      displayName: 'Hobby',
      description: 'Person hobby',
      type: 'multiSelect' as CreateMetadataTemplateRequestBodyFieldsTypeField,
    } satisfies CreateMetadataTemplateRequestBodyFieldsField,
  ],
} satisfies CreateMetadataTemplateRequestBody);
Python Gen
client.metadata_templates.create_metadata_template(
    "enterprise",
    template_key,
    template_key=template_key,
    fields=[
        CreateMetadataTemplateFields(
            key="firstName",
            display_name="First name",
            description="Person first name",
            type=CreateMetadataTemplateFieldsTypeField.STRING.value,
        ),
        CreateMetadataTemplateFields(
            key="lastName",
            display_name="Last name",
            description="Person last name",
            type=CreateMetadataTemplateFieldsTypeField.STRING.value,
        ),
        CreateMetadataTemplateFields(
            key="dateOfBirth",
            display_name="Birth date",
            description="Person date of birth",
            type=CreateMetadataTemplateFieldsTypeField.DATE.value,
        ),
        CreateMetadataTemplateFields(
            key="age",
            display_name="Age",
            description="Person age",
            type=CreateMetadataTemplateFieldsTypeField.FLOAT.value,
        ),
        CreateMetadataTemplateFields(
            key="hobby",
            display_name="Hobby",
            description="Person hobby",
            type=CreateMetadataTemplateFieldsTypeField.MULTISELECT.value,
        ),
    ],
)
.NET Gen
await client.MetadataTemplates.CreateMetadataTemplateAsync(requestBody: new CreateMetadataTemplateRequestBody(scope: "enterprise", displayName: templateKey) { TemplateKey = templateKey, Fields = Array.AsReadOnly(new [] {new CreateMetadataTemplateRequestBodyFieldsField(key: "firstName", displayName: "First name", type: CreateMetadataTemplateRequestBodyFieldsTypeField.String) { Description = "Person first name" },new CreateMetadataTemplateRequestBodyFieldsField(key: "lastName", displayName: "Last name", type: CreateMetadataTemplateRequestBodyFieldsTypeField.String) { Description = "Person last name" },new CreateMetadataTemplateRequestBodyFieldsField(key: "dateOfBirth", displayName: "Birth date", type: CreateMetadataTemplateRequestBodyFieldsTypeField.Date) { Description = "Person date of birth" },new CreateMetadataTemplateRequestBodyFieldsField(key: "age", displayName: "Age", type: CreateMetadataTemplateRequestBodyFieldsTypeField.Float) { Description = "Person age" },new CreateMetadataTemplateRequestBodyFieldsField(key: "hobby", displayName: "Hobby", type: CreateMetadataTemplateRequestBodyFieldsTypeField.MultiSelect) { Description = "Person hobby" }}) });
Swift Gen (Beta)
try await client.metadataTemplates.createMetadataTemplate(requestBody: CreateMetadataTemplateRequestBody(scope: "enterprise", displayName: templateKey, templateKey: templateKey, fields: [CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.string, key: "testName", displayName: "testName")]))
Java
MetadataTemplate.Field metadataField = new MetadataTemplate.Field();
metadataField.setType("string");
metadataField.setKey("text");
metadataField.setDisplayName("Text");

List<MetadataTemplate.Field> fields = new ArrayList<MetadataTemplate.Field>();
fields.add(metadataField);

MetadataTemplate template = MetadataTemplate.createMetadataTemplate(api, "enterprise", "CustomField", "Custom Field", false, fields);

final JsonObject jsonObject = new JsonObject();
jsonObject.add("text", "This is a test text");

Metadata metadata = new Metadata(jsonObject);
boxFile.createMetadata("CustomField", metadata);
Python
from boxsdk.object.metadata_template import MetadataField, MetadataFieldType

fields = [
    MetadataField(MetadataFieldType.STRING, 'Name'),
    MetadataField(MetadataFieldType.DATE, 'Birthday', 'bday'),
    MetadataField(MetadataFieldType.ENUM, 'State', options=['CA', 'TX', 'NY'])
]
template = client.create_metadata_template('Employee Record', fields, hidden=True)
print(f'Metadata template ID {template.scope}/{template.templateKey} created!')
.NET
var templateParams = new BoxMetadataTemplate()
{
    TemplateKey = "marketingCollateral",
    DisplayName = "Marketing Collateral",
    Scope = "enterprise",
    Fields = new List<BoxMetadataTemplateField>()
    {
        new BoxMetadataTemplateField()
        {
            Type = "enum",
            Key = "audience",
            DisplayName = "Audience",
            Options = new List<BoxMetadataTemplateFieldOption>()
            {
                new BoxMetadataTemplateFieldOption() { Key = "internal" },
                new BoxMetadataTemplateFieldOption() { Key = "external" }
            }
        },
        new BoxMetadataTemplateField()
        {
            Type = "string",
            Key = "author",
            DisplayName = "Author"
        }
    }
};
BoxMetadataTemplate template = await client.MetadataManager.CreateMetadataTemplate(templateParams);
Node
// Create a new template, but hide it for now until it's ready for use
client.metadata.createTemplate(
		'Vendor Contract',
		[
			{
				type: 'date',
				key: 'signed',
				displayName: 'Date Signed'
			},
			{
				type: 'string',
				key: 'vendor',
				displayName: 'Vendor'
			},
			{
				type: 'enum',
				key: 'fy',
				displayName: 'Fiscal Year',
				options: [
					{key: 'FY17'},
					{key: 'FY18'},
					{key: 'FY19'}
				]
			}
		],
		{
			hidden: true,
			templateKey: 'vcontract',
			copyInstanceOnItemCopy: false
		}
	)
	.then(template => {
		/* template -> {
			id: '17f2d715-6acb-45f2-b96a-28b15efc9faa',
			templateKey: 'vcontract',
			scope: 'enterprise_12345',
			displayName: 'Vendor Contract',
			hidden: true,
			copyInstanceOnItemCopy: false,
			fields: 
			[ { type: 'date',
				key: 'signed',
				displayName: 'Date Signed',
				hidden: false },
				{ type: 'string',
				key: 'vendor',
				displayName: 'Vendor',
				hidden: false },
				{ type: 'enum',
				key: 'fy',
				displayName: 'Fiscal Year',
				options: 
					[ { key: 'FY17' },
					{ key: 'FY18' },
					{ key: 'FY19' } ],
				hidden: false } ] }
		*/
	});
iOS
var templateFields: [MetadataField] = []
templateFields.append(MetadataField(
    type: "string",
    key: "name",
    displayName: "Full Name"
))
templateFields.append(MetadataField(
    type: "date",
    key: "birthday",
    displayName: "Birthday"
))
templateFields.append(MetadataField(
    type: "enum",
    key: "department",
    displayName: "Department",
    options: [
        ["key": "HR"],
        ["key": "Sales"],
        ["key": "Marketing"],
    ]
))
client.metadata.createTemplate(
    scope: "enterprise",
    templateKey: "personnelRecord",
    displayName: "Personnel Record",
    hidden: false,
    fields: templateFields
) { (result: Result<MetadataTemplate, BoxSDKError>) in
    guard case let .success(template) = result {
        print("Error creating metadata template")
        return
    }

    print("Created metadata template with ID \(template.id)")
}

Response Example

{
  "id": "58063d82-4128-7b43-bba9-92f706befcdf",
  "type": "metadata_template",
  "copyInstanceOnItemCopy": true,
  "displayName": "Product Info",
  "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"
    }
  ],
  "hidden": true,
  "scope": "enterprise_123456",
  "templateKey": "productInfo"
}