API: Case Fields - TestRail

API: Case Fields

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

On this page:

    API Rate Limit

    Please note that the API is rate-limited on TestRail Cloud to ensure optimal performance for all users and may throttle requests. TestRail might also return a 429 Too Many Requests response, which you are expected to handle. Such a response also includes a Retry-After header indicating how many seconds to wait before you are allowed to submit the next request.

    To avoid rate limits on TestRail Cloud, try using bulk API endpoints (e.g. using as add_results_for_cases instead of add_results_for case), build a time delay into your API calls, or upgrade to TestRail Enterprise Cloud.

    Rate limits for TestRail Cloud are as follows:

    • 180 Requests per instance, per minute for TestRail Cloud Professional subscriptions.
    • 300 Requests per instance, per minute for TestRail Cloud Enterprise subscriptions.

    No API rate limits are built into TestRail Server installations.


    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
    4 URL
    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