Product Updates | Contact Support | System Status
Page Contents

    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)


    Page last updated on 24 Dec 2021