Custom fields API for Test Management

Create, list, update, and delete custom field definitions for test cases, test results, and test plans with the Test Management REST API.

A custom field definition belongs to one entity type. The entity_type value selects the entity when you create or list fields. The supported values are TestCase, TestResult, and TestPlan. When you omit entity_type, the API uses TestCase.

After you define a field, set its value on the entity it belongs to:

Test case values go in the custom_fields object of the test cases API.
Test result values go in the custom_fields object of the test results API.
Test plan values go in the custom_fields object of the test plans API and the sub test plans API.

Get custom fields

GET /api/v2/custom-fields

Pass entity_type to list the test result or test plan fields of your group. Without it, the response lists test case fields only.

The list is paginated. For details, see Pagination.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
"https://test-management.browserstack.com/api/v2/custom-fields?entity_type=TestPlan"

entity_type String

Entity whose custom fields are listed. Allowed values are TestCase, TestResult, and TestPlan. The lowercase forms test_case, test_result, and test_plan are also accepted. Defaults to TestCase.
p Integer

Page number to return. Defaults to 1.
count Integer

Number of custom fields per page. Defaults to 30. The maximum is 300.

An unsupported entity_type value returns 400 Bad Request with the message Invalid entity_type. Supported values: TestCase, TestResult, TestPlan.

Response attributes `200` `application/json`

Response

{
  "custom_fields": [
    {
      "id": 5678,
      "field_type": "dropdown",
      "field_name": "Severity",
      "entity_type": "TestPlan",
      "is_required": false,
      "default_value": null,
      "place_holder_text": "Select the severity"
    },
    {
      "id": 5679,
      "field_type": "string",
      "field_name": "Release",
      "entity_type": "TestPlan",
      "is_required": false,
      "default_value": null
    }
  ],
  "info": {
    "page": 1,
    "page_size": 30,
    "count": 2,
    "prev": null,
    "next": null
  },
  "success": true
}

custom_fields Array

List of custom field objects.

▶ SHOW VALUES
- id Integer
  
  Unique identifier of the custom field.
- field_type String
  
  Data type of the custom field, such as string, dropdown, multi_dropdown, text, user, boolean, url, date, or int.
- field_name String
  
  Name of the custom field.
- entity_type String
  
  Entity the custom field belongs to. One of TestCase, TestResult, or TestPlan.
- is_required Boolean
  
  Indicates whether the custom field is required.
- default_value String
  
  Default value of the field. null when no default is set.
- place_holder_text String
  
  Placeholder text of the field. Returned only when the field has one.
info Object

Pagination details for the list.

▶ SHOW VALUES
- page Integer
  
  Current page number.
- page_size Integer
  
  Number of items per page.
- count Integer
  
  Total number of items.
- prev Integer
  
  Previous page number, or null on the first page.
- next Integer
  
  Next page number, or null on the last page.
success Boolean

Indicates whether the request succeeded.

Create a custom field

POST /api/v2/custom-fields

Set entity_type in the request body to choose the entity the field belongs to. When you omit it, the API creates a test case field.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/custom-fields \
-H "Content-Type: application/json" \
-d '{
  "field_name": "Severity",
  "field_type": "dropdown",
  "entity_type": "TestPlan",
  "is_required": false,
  "place_holder_text": "Select the severity",
  "options": [
    {
      "is_default": false,
      "option_value": "High"
    },
    {
      "is_default": true,
      "option_value": "Medium"
    },
    {
      "is_default": false,
      "option_value": "Low"
    }
  ],
  "applies_to_all_projects": false,
  "link_to_future_projects": false,
  "assigned_projects": [
    "PR-2223"
  ]
}'

Request body

Request body

{
  "field_name": "Severity",
  "field_type": "dropdown",
  "entity_type": "TestPlan",
  "is_required": false,
  "place_holder_text": "Select the severity",
  "options": [
    {
      "is_default": false,
      "option_value": "High"
    },
    {
      "is_default": true,
      "option_value": "Medium"
    },
    {
      "is_default": false,
      "option_value": "Low"
    }
  ],
  "applies_to_all_projects": false,
  "link_to_future_projects": false,
  "assigned_projects": [
    "PR-2223"
  ]
}

field_name^* String

Name of the custom field. Maximum 256 characters. Reserved names return 400.
field_type^* String

Data type of the custom field. Allowed values are string, text, int, boolean, date, url, user, dropdown, and multi_dropdown. nested_dropdown is allowed for TestCase fields only.
entity_type String

Entity the custom field belongs to. Allowed values are TestCase, TestResult, and TestPlan. The lowercase forms test_case, test_result, and test_plan are also accepted. Defaults to TestCase. Any other value returns 400.
is_required^* Boolean

Whether a value is mandatory when the entity is created.
place_holder_text String

Placeholder text shown in the field. Maximum 256 characters.
Show 5 more
default_value String

Default value of the field. For boolean fields, true or false.
options Array

Options for dropdown and multi_dropdown fields.

▶ SHOW VALUES
- is_default Boolean
  
  Indicates whether this option is the default.
- option_value String
  
  Value of the option.
applies_to_all_projects Boolean

Whether the field applies to all projects. Defaults to false.
link_to_future_projects Boolean

Whether the field is linked to projects created later. Defaults to false.
assigned_projects Array

List of project identifiers, such as PR-2223, to assign the field to. An unknown identifier returns 400.

The API returns 400 Bad Request in the following cases:

entity_type is not TestCase, TestResult, or TestPlan. The message names the supported values.
field_type is nested_dropdown and entity_type is not TestCase.
field_name is a reserved name for the entity. See Validations for fields.
A project identifier in assigned_projects does not exist.

Response attributes `200` `application/json`

Response

{
  "custom_field": {
    "id": 5678,
    "field_type": "dropdown",
    "field_name": "Severity",
    "entity_type": "TestPlan",
    "is_required": false,
    "default_value": null,
    "place_holder_text": "Select the severity",
    "options": [
      {
        "is_default": false,
        "option_value": "High"
      },
      {
        "is_default": true,
        "option_value": "Medium"
      },
      {
        "is_default": false,
        "option_value": "Low"
      }
    ],
    "applies_to_all_projects": false,
    "assigned_projects": [
      "PR-2223"
    ],
    "link_to_future_projects": false
  },
  "success": true
}

custom_field Object

The created custom field.

▶ SHOW VALUES
- id Integer
  
  Unique identifier of the custom field.
- field_type String
  
  Data type of the custom field, such as string, dropdown, multi_dropdown, text, user, boolean, url, date, or int.
- field_name String
  
  Name of the custom field.
- entity_type String
  
  Entity the custom field belongs to. One of TestCase, TestResult, or TestPlan.
- is_required Boolean
  
  Indicates whether the custom field is required.
- default_value String
  
  Default value of the field. null when no default is set.
- place_holder_text String
  
  Placeholder text of the field. Returned only when the field has one.
- options Array
  
  Options sent in the request. Returned only for dropdown and multi_dropdown fields.
  
  ▶ SHOW VALUES
  - is_default Boolean
    
    Indicates whether this option is the default.
  - option_value String
    
    Value of the option.
- applies_to_all_projects Boolean
  
  Whether the field applies to all projects.
- assigned_projects Array
  
  Project identifiers the field is assigned to. Returned only when the request assigned projects.
- link_to_future_projects Boolean
  
  Whether the field is linked to projects created later.
success Boolean

Indicates whether the custom field was created.

Update a custom field

PATCH /api/v2/custom-fields/{custom_field_id}

Use this endpoint to update a custom field of any entity type. The entity type and the field type of an existing field cannot change. Leave entity_type out of the body and keep field_type unchanged.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X PATCH https://test-management.browserstack.com/api/v2/custom-fields/{custom_field_id} \
-H "Content-Type: application/json" \
-d '{
  "field_name": "Severity",
  "field_type": "dropdown",
  "is_required": true,
  "place_holder_text": "Select the severity",
  "applies_to_all_projects": false,
  "link_to_future_projects": false,
  "assigned_projects": [
    "PR-2223",
    "PR-2224"
  ]
}'

custom_field_id^* Integer

Unique identifier of the custom field.

Request body

Request body

{
  "field_name": "Severity",
  "field_type": "dropdown",
  "is_required": true,
  "place_holder_text": "Select the severity",
  "applies_to_all_projects": false,
  "link_to_future_projects": false,
  "assigned_projects": [
    "PR-2223",
    "PR-2224"
  ]
}

field_name String

Name of the custom field. Maximum 256 characters. Reserved names return 400.
field_type String

Data type of the custom field. Must match the existing type, because the type of a field cannot change.
is_required Boolean

Whether a value is mandatory when the entity is created.
place_holder_text String

Placeholder text shown in the field. Maximum 256 characters.
options Array

Options for dropdown and multi_dropdown fields. Replaces the options of the existing option set.

▶ SHOW VALUES
- is_default Boolean
  
  Indicates whether this option is the default.
- option_value String
  
  Value of the option.
applies_to_all_projects Boolean

Whether the field applies to all projects.
link_to_future_projects Boolean

Whether the field is linked to projects created later.
assigned_projects Array

List of project identifiers, such as PR-2223, to assign the field to.

Response attributes `200` `application/json`

Response

{
  "custom_field": {
    "id": 5678,
    "field_type": "dropdown",
    "field_name": "Severity",
    "entity_type": "TestPlan",
    "is_required": true,
    "default_value": null,
    "place_holder_text": "Select the severity",
    "applies_to_all_projects": false,
    "assigned_projects": [
      "PR-2223",
      "PR-2224"
    ],
    "link_to_future_projects": false
  },
  "success": true
}

custom_field Object

The updated custom field.

▶ SHOW VALUES
- id Integer
  
  Unique identifier of the custom field.
- field_type String
  
  Data type of the custom field, such as string, dropdown, multi_dropdown, text, user, boolean, url, date, or int.
- field_name String
  
  Name of the custom field.
- entity_type String
  
  Entity the custom field belongs to. One of TestCase, TestResult, or TestPlan.
- is_required Boolean
  
  Indicates whether the custom field is required.
- default_value String
  
  Default value of the field. null when no default is set.
- place_holder_text String
  
  Placeholder text of the field. Returned only when the field has one.
- options Array
  
  Options sent in the request. Returned only for dropdown and multi_dropdown fields.
  
  ▶ SHOW VALUES
  - is_default Boolean
    
    Indicates whether this option is the default.
  - option_value String
    
    Value of the option.
- applies_to_all_projects Boolean
  
  Whether the field applies to all projects.
- assigned_projects Array
  
  Project identifiers the field is assigned to. Returned only when the request assigned projects.
- link_to_future_projects Boolean
  
  Whether the field is linked to projects created later.
success Boolean

Indicates whether the custom field was updated.

Delete a custom field

DELETE /api/v2/custom-fields/{custom_field_id}

Use this endpoint to delete a custom field of any entity type. The field and its values are removed from every project it was assigned to.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X DELETE https://test-management.browserstack.com/api/v2/custom-fields/{custom_field_id}

custom_field_id^* Integer

Unique identifier of the custom field to delete.

Response attributes `200` `application/json`

Response

{
  "success": true
}

success Boolean

Indicates if the custom field was deleted successfully.

Validations for fields

Each parameter in a create or update request must meet the rules in the following table. A request that breaks a rule returns 400 Bad Request.

Field type values are lowercase, for example string and multi_dropdown. Entity type values use the exact casing shown, for example TestPlan. The lowercase forms test_case, test_result, and test_plan are also accepted for entity_type.

Field	Validation
`entity_type`	Optional. • Allowed values: `TestCase`, `TestResult`, `TestPlan`. • Default = `TestCase`. • Cannot change after creation. Leave it out of update requests.
`field_name`	Required on create. Optional on update. • Must be unique. • Max length: 256 characters. • Must not be a reserved name for the entity.
`field_type`	Required on create. Optional on update. • Allowed values for every entity: `string`, `text`, `int`, `boolean`, `date`, `url`, `user`, `dropdown`, `multi_dropdown`. • `nested_dropdown` is allowed for `TestCase` only. • Cannot change after creation.
`is_required`	Required on create. Optional on update. • `true` or `false`.
`place_holder_text`	Optional. • Max length: 256 characters.
`default_value`	Optional. • For `boolean` fields, `true` or `false`.
`options`	Optional. • Used by `dropdown` and `multi_dropdown` fields. • Each option needs `option_value`. `is_default` is optional.
`assigned_projects`	Optional. • An array of project identifiers, such as `PR-2223`. • An unknown identifier returns `400`.
`applies_to_all_projects`	Optional. • Default = `false`. • If `assigned_projects` is present, `applies_to_all_projects` cannot be `true`.
`link_to_future_projects`	Optional. • Default = `false`.

The following field names are reserved and cannot be used as custom field names:

Entity type	Reserved names
`TestCase` and `TestResult`	Title, Description, Preconditions, Steps, Result, Attachments, State, Owner, Priority, Type of Test Case, Automation Status, Tags, Jira Issues, Asana Issues, Review Status
`TestPlan`	Title, Description, Preconditions, Steps, Result, Attachments, State, Owner, Priority, Tags, Jira Issues, Asana Issues, Review Status

Did this page help you?

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Custom fields API for Test Management

Get custom fields

Request parameters

entity_type String

p Integer

count Integer

Response attributes 200 application/json

custom_fields Array

id Integer

field_type String

field_name String

entity_type String

is_required Boolean

default_value String

place_holder_text String

info Object

page Integer

page_size Integer

count Integer

prev Integer

next Integer

success Boolean

Create a custom field

Request parameters

Request body

field_name* String

field_type* String

entity_type String

is_required* Boolean

place_holder_text String

default_value String

options Array

is_default Boolean

option_value String

applies_to_all_projects Boolean

link_to_future_projects Boolean

assigned_projects Array

Response attributes 200 application/json

custom_field Object

id Integer

field_type String

field_name String

entity_type String

is_required Boolean

default_value String

place_holder_text String

options Array

is_default Boolean

option_value String

applies_to_all_projects Boolean

assigned_projects Array

link_to_future_projects Boolean

success Boolean

Update a custom field

Request parameters

custom_field_id* Integer

Request body

field_name String

field_type String

is_required Boolean

place_holder_text String

options Array

is_default Boolean

option_value String

applies_to_all_projects Boolean

link_to_future_projects Boolean

assigned_projects Array

Response attributes 200 application/json

custom_field Object

id Integer

field_type String

field_name String

entity_type String

is_required Boolean

default_value String

place_holder_text String

options Array

is_default Boolean

option_value String

applies_to_all_projects Boolean

Response attributes `200` `application/json`

field_name^* String

field_type^* String

is_required^* Boolean

Response attributes `200` `application/json`

custom_field_id^* Integer

Response attributes `200` `application/json`

custom_field_id^* Integer

Response attributes `200` `application/json`