API: Case Fields - TestRail

API: Case Fields

Use the following API methods to request details about custom fields for test cases.


Returns a list of available test case custom fields.

GET index.php?/api/v2/get_case_fields

Response content

The response includes an array of custom field definitions. Please see below for a typical response:

		"configs": [
			"context": {
				"is_global": true,
				"project_ids": null
			"id": "..",
			"options": {
				"default_value": "",
				"format": "markdown",
				"is_required": false,
				"rows": "5"
		"description": "The preconditions of this test case. ..",
		"display_order": 1,
		"id": 1,
		"label": "Preconditions",
		"name": "preconds",
		"system_name": "custom_preconds",
		"type_id": 3

A custom field can have different configurations and options per project which is indicated by the configs field. To check if a custom field is applicable to a specific project (and to find out the field options for this project), the context of the field configuration must either be global (is_global) or include the ID of the project in project_ids.

Also, the following list shows the available custom field types (type_id field):

Type ID Name
1 String
2 Integer
3 Text
5 Checkbox
6 Dropdown
7 User
8 Date
9 Milestone
10 Steps
12 Multi-select


Response codes

200 Success, the available custom fields are returned as part of the response


Creates a new test case custom field.

POST index.php?/api/v2/add_case_field

Request fields

The following POST fields are supported (system fields):

Name Type Description
type string

The type identifier for the new custom field (required). The following types are supported:

  • String
  • Integer
  • Text
  • URL
  • Checkbox
  • Dropdown
  • User
  • Date
  • Milestone
  • Steps
  • Multiselect

You can pass the number of the type as well as the word, e.g. “5”, “string”, “String”, “Dropdown”, “12”. The numbers must be sent as a string e.g {type: “5”} not {type: 5}, otherwise you will get a 400 (Bad Request) response.

name string The name for new the custom field (required)
label string The label for the new custom field (required)
description string The description for the new custom field
include_all boolean Set flag to true if you want the new custom field included for all templates. Otherwise (false) specify the ID’s of templates to be included as the next parameter (template_ids)
template_ids array ID’s of templates new custom field will apply to if include_all is set to false
configs object An object wrapped in an array with two default keys, ‘context’ and ‘options’ (required)


When creating new custom fields, use simple names without the “custom_” prefix since this will be added automatically. E.g. “my_int” will be prefixed with “custom_my_int”.

Custom fields with configs require the ‘context’ and ‘options’ default keys:

    "configs": [
        "context":{"is_global": true, "project_ids": []},
        "options":{"is_required": false, "default_value": "1", "items": "1, First\n2, Second"}

To apply a custom field to specific projects, change the context:

    "context":{"is_global": false, "project_ids": [5, 10]}

Some custom field types have different options. “is_required” (boolean) is common for all fields. Most of the types have the option to set “default_value” with exception for types Multiselect, Milestone and Date, where this option is not allowed..

Dropdown and Text have special options. For dropdown it is items:

    "items": "1, First\n2, Second"

For text, use format and rows:

    "format": "plain", "rows": "5"

For “format” choose between “plain” or “markdown” values. The “rows” option specifies the initial size of the field when the user loads a form. The valid values for it are e.g. “3”, “4”, …, “10” or “” (empty string).

    "options": {
        "is_required": false,
        "default_value": "The default text.",
        "format": "markdown",
        "rows": "3"

Request example

        "type": "Multiselect",
        "name": "my_multiselect",
        "label": "My Multiselect",
        "description": "my custom Multiselect description",
        "configs": [
                "context": {
                    "is_global": true,
                    "project_ids": ""
                "options": {
                    "is_required": false,
                    "items": "1, One\n2, Two"
        "include_all": true

Response content

If successful, this method returns the new custom field.

        "label":"My Multiselect",
        "description":"my custom Multiselect description",
        "configs":"[{\"context\":{\"is_global\":true,\"project_ids\":\"\"},\"options\":{\"is_required\":false,\"items\":\"1, One\\n2, Two\"},\"id\":\"9f105ba2-1ed0-45e0-b459-18d890bad86e\"}]",

Response codes

200 Success, the new custom field is returned in the response
400 Bad request, check the error message for diagnostics
404 Not found, bad parameter passed