Managing Custom Fields Using the CMS API

This topic explains how to use the CMS API to manage the custom fields for an account.

Introduction

Custom fields allow you to add custom metadata to your videos to service the needs of the your organization. They can useful for organizing videos, grouping them for playlists, and many other things. You can use the CMS API to create, update, delete, and list the custom fields for an account, which is particularly helpful if you are integrating Video Cloud with a CMS or some other system.

Create custom fields

To create a custom field, you send a POST request with the custom field details.

Request URL

https://cms.api.brightcove.com/v1/accounts/{{account_id}}/video_fields/custom_fields

Method

POST

Sample request body

{
        "id": “internal_name”,
        "display_name" : "Display name",
        "description" : "Custom field description",
        "type" : "enum",
        "required" : true,
        "enum_values" : ["EnumValue1", "EnumValue2"]
        }
Sample response (success status code: 201) 
{
          "id" : "internal_name",
          "display_name" : "Display name",
          "description" : "Custom field description",
          "type" : "enum",
          "required" : true,
          "enum_values" : ["EnumValue1", "EnumValue2"]
          }
Request Body Fields
Field Type Description
id string Internal name for the field. Can be updated. Note that updating it will trigger an internal process to update the id in any videos that have the custom field.

Requirements:

  • all lowercase
  • no spaces (use underscore [_] instead)
  • letters and numbers only - no special characters
  • max length: 128 single-byte characters
  • must be unique among all custom fields for the account
  • must not be one of the Reserved names
display_name string Display name for UIs. Can be updated.

Requirements:

  • max length: 128 single-byte characters
description string Description of the field. Can be updated.

Requirements:

  • max length: 500 single-byte characters
type enum (string) The type of field. Cannot be updated.

Requirements:

  • allowed values are: string or enum (not case-sensitive)
required boolean Whether the field is required for the video to be activated. Can be updated..

Default: false
enum_values array (strings) Allowed values for an enum field. Can be updated.

Requirements:

  • up to 150 items (note: this maximum value can be increased up to 1000 - create a Support Request if you wish to increase it)
  • each item has a maximum length of 100 single-byte characters
  • required for enum type fields
  • not allowed for string type fields

Get custom fields

Get a list of all custom fields

To get an array of all custom fields, you send a GET request with the custom field details.

Request URL

https://cms.api.brightcove.com/v1/accounts/{{account_id}}/video_fields/custom_fields

Method

GET
Sample response (success status code: 200) 
[{
          "id" : "display_name_1",
          "display_name" : "Display name 1",
          "description" : "Custom field description",
          "type" : "enum",
          "required" : true,
          "enum_values" : ["EnumValue1", "EnumValue2"]
          },
          {
          "id" : "display_name_2",
          "display_name" : "Display name 2",
          "description" : "Custom field description",
          "type" : "enum",
          "required" : true,
          "enum_values" : ["EnumValue1", "EnumValue2"]
          }]

Get one custom field

To get an array of all custom fields, you send a GET request with the custom field details.

Request URL

https://cms.api.brightcove.com/v1/accounts/{{account_id}}/video_fields/custom_fields/{custom_field_id}

Method

GET
Sample response (success status code: 200) 
{
          "id" : "internal_name",
          "display_name" : "Display name",
          "description" : "Custom field description",
          "type" : "enum",
          "required" : true,
          "enum_values" : ["EnumValue1", "EnumValue2"]
          }
Response Fields
Field Type Description
id string Internal name for the field. Can be updated.
display_name string Display name for UIs. Can be updated.
description string Description of the field. Can be updated.
type enum (string) The type of field (string or enum). Cannot be updated.
required boolean Whether the field is required for the video to be activated. Can be updated..
enum_values array (strings) Allowed values for an enum field. Can be updated.

Update custom fields

To update a custom field, you send a PATCH request with the custom field details.

Request URL

https://cms.api.brightcove.com/v1/accounts/{{account_id}}/video_fields/custom_fields/{custom_field_id}

Method

PATCH

Sample request body

Enum type

{
        "id": “internal_name”,
        "display_name" : "Display name",
        "description" : "Custom field description",
        "required" : true,
        "enum_values" : ["EnumValue1", "EnumValue2"]
        }
Sample response (success status code: 201) 
{
          "id" : "internal_name",
          "display_name" : "Display name",
          "description" : "Custom field description",
          "type" : "enum",
          "required" : true,
          "enum_values" : ["EnumValue1", "EnumValue2"]
          }

String type

{
        "id": “internal_name”,
        "display_name" : "Display name",
        "description" : "Custom field description",
        "required" : true,
        }
Sample response (success status code: 201) 
{
          "id" : "internal_name",
          "display_name" : "Display name",
          "description" : "Custom field description",
          "type" : "string",
          "required" : true
          }
Request Body Fields
Field Type Description
id string Internal name for the field. Can be updated.Note that updating it will trigger an internal process to update the id in any videos that have the custom field.

Requirements:

  • all lowercase
  • no spaces (use underscore [_] instead)
  • letters and numbers only - no special characters
  • max length: 128 single-byte characters
  • must be unique among all custom fields for the account
display_name string Display name for UIs. Can be updated.

Requirements:

  • max length: 128 single-byte characters
description string Description of the field. Can be updated.

Requirements:

  • max length: 500 single-byte characters
required boolean Whether the field is required for the video to be activated. Can be updated..

Default: false
enum_values array (strings) Allowed values for an enum field. Can be updated.

Requirements:

  • up to 150 items
  • each item has a maximum length of 100 single-byte characters
  • required for enum type fields
  • not allowed for string type fields

Delete custom fields

To create a custom field, you send a Delete request with the custom field details.

Request URL

hhttps://cms.api.brightcove.com/v1/accounts/{{account_id}}/video_fields/custom_fields/{custom_field_id}

Method

DELETE

Request body: none

Response: 204 (no content)