Custom Fields

Custom fields allow you to extend test cases with additional metadata specific to your organization's needs. You can use custom fields to track information like automation status, test environment, component ownership, or any other project-specific attributes.

Types of Custom Fields

In QA Sphere, there are four types of custom fields:

Text: A plain string value.
Rich Text: Text supporting formatting, held as HTML (see HTML Support).
Dropdown: One value out of the field's list of options.
Checkbox: A boolean.
- Single option checkbox: the option holds the label of the checked value, and an unchecked field holds an empty value.
- Two option checkbox: option order is significant, the first option holds the label of the checked value and the second one that of the unchecked value. The field always holds one of the two.

Every custom field has a display name and a systemName. The display name can be changed at any time, the system name cannot.

Keep system names short and readable, such as automation or test_environment, since they appear in test case payloads and filters and cannot be changed later.

A field can be marked required and can carry a defaultValue, which is applied to test cases that do not provide a value of their own. A required field always has a default value. For a checkbox, both follow from its options instead of being configurable:

Single option checkbox: never required and has no default value.
Two option checkbox: always required, with its unchecked value as the default value.

Only fields with enabled: true are meant to be used, and a field applies either to all projects (allowAllProjects: true) or only to the projects listed in allowedProjectIds.

Using Custom Fields in Test Cases

Custom fields can be used when creating or updating test cases. Values are keyed by the field's systemName, not by its id.

Creating Test Cases with Custom Fields

When creating a test case, you can include custom field values using the customFields object:

{
  "type": "standalone",
  "folderId": 1,
  "title": "Login Test",
  "priority": "high",
  "customFields": {
    "automation": {
      "value": "Automated"
    },
    "test_environment": {
      "value": "production"
    },
    "regression": {
      "value": "Yes"
    },
    "notes": {
      "value": "<p>Covers the <strong>happy path</strong> only.</p>"
    }
  }
}

Custom Field Value Structure

Each custom field value in the customFields object should have:

value: The actual value for the field. For dropdown and checkbox fields it must match one of the option value strings from the field's options array. An empty value is accepted only by a field that is not required, which is why a single option checkbox always takes one and a two option checkbox never does. Richtext values are HTML and are sanitized server-side
isDefault: Boolean indicating whether to use the field's default value. When true, value must either be left out or match the field's default value, and the field must have a default value at all

Using Default Values

You can use the default value for a custom field by setting isDefault: true, leaving out value or setting it to the field's default value:

{
  "customFields": {
    "automation": {
      "isDefault": true
    }
  }
}

The flag ties the test case value to the field definition. Whenever the field's defaultValue changes afterwards, the new default is applied to every test case value carrying isDefault: true and to every test case that has no value for the field, while clearing the field's default value removes those values again.

Default values are also applied without the flag:

In a create request, a field left out of customFields takes the field's default value, if it has one, and is marked with isDefault: true. A required field does the same when an empty value is passed, while for a field that is not required an empty value is stored as an empty value.
In an update request, only the fields present in customFields are changed and no default value is filled in. A required field can therefore not be given an empty value, unless isDefault is set.

Filtering Test Cases by Custom Fields

Custom fields can also be used to filter test cases when listing them. Use the format cf_{systemName}=value in query parameters:

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  "https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase?cf_automation=Automated"

Multiple values for the same custom field can be specified:

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  "https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/tcase?cf_automation=Automated&cf_automation=In%20Progress"

List Project Custom Fields

GET/api/public/v0/project/{project_id}/custom-field

Returns all custom fields available for the project. This endpoint is useful when creating or updating test cases that include custom field values.

Path Parameters

project_id: The project identifier (can be either the project code or UUID)

Response

Status: 200 OK

{
  customFields: Array<{
    id: string // Unique custom field identifier
    type: 'text' | 'dropdown' | 'checkbox' | 'richtext' // Field type
    systemName: string // System identifier for the field (used in API requests)
    name: string // Display name of the field
    required: boolean // Whether the field is required for test cases
    enabled: boolean // Whether the field is currently enabled
    options?: Array<{
      // Available options, only for dropdown and checkbox fields
      id: string // Option identifier
      value: string // Option display value
    }>
    defaultValue?: string // Default value for the field, implied by the options for checkbox fields
    pos: number // Display position/order
    allowAllProjects: boolean // Whether the field is available to all projects
    allowedProjectIds?: string[] // List of project IDs if not available to all projects
    createdAt: string // ISO 8601 timestamp when the field was created
    updatedAt: string // ISO 8601 timestamp when the field was last updated
  }>
}

Example Request

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  https://your-company.your-region-code.qasphere.com/api/public/v0/project/BD/custom-field

Example Response

{
  "customFields": [
    {
      "id": "1customfield_1111111111111",
      "type": "dropdown",
      "systemName": "automation",
      "name": "Automation",
      "required": false,
      "enabled": true,
      "options": [
        {
          "id": "1customfieldoption_1111111111111",
          "value": "Planned"
        },
        {
          "id": "1customfieldoption_1111111111112",
          "value": "Cannot be Automated"
        },
        {
          "id": "1customfieldoption_1111111111113",
          "value": "In Progress"
        },
        {
          "id": "1customfieldoption_1111111111114",
          "value": "Automated"
        },
        {
          "id": "1customfieldoption_1111111111115",
          "value": "Broken"
        }
      ],
      "defaultValue": "Planned",
      "pos": 0,
      "allowAllProjects": true,
      "allowedProjectIds": [],
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "1customfield_1111111111112",
      "type": "text",
      "systemName": "test_environment",
      "name": "Test Environment",
      "required": true,
      "enabled": true,
      "options": [],
      "defaultValue": "staging",
      "pos": 1,
      "allowAllProjects": false,
      "allowedProjectIds": ["1project_1111111111111"],
      "createdAt": "2024-01-20T14:15:00Z",
      "updatedAt": "2024-01-20T14:15:00Z"
    },
    {
      "id": "1customfield_1111111111113",
      "type": "checkbox",
      "systemName": "regression",
      "name": "Regression",
      "required": true,
      "enabled": true,
      "options": [
        {
          "id": "1customfieldoption_1111111111116",
          "value": "Yes"
        },
        {
          "id": "1customfieldoption_1111111111117",
          "value": "No"
        }
      ],
      "defaultValue": "No",
      "pos": 2,
      "allowAllProjects": true,
      "allowedProjectIds": [],
      "createdAt": "2024-02-01T09:00:00Z",
      "updatedAt": "2024-02-01T09:00:00Z"
    },
    {
      "id": "1customfield_1111111111114",
      "type": "richtext",
      "systemName": "notes",
      "name": "Notes",
      "required": false,
      "enabled": true,
      "options": [],
      "pos": 3,
      "allowAllProjects": true,
      "allowedProjectIds": [],
      "createdAt": "2024-02-05T11:45:00Z",
      "updatedAt": "2024-02-05T11:45:00Z"
    }
  ]
}

Error Responses

Status Code	Description
401	Invalid or missing API key
403	Insufficient permissions or suspended tenant
404	Project not found
500	Internal server error

Test Cases - Create and manage test cases with custom fields
Authentication - Learn about API authentication

Custom Fields

On this page