Skip to main content

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.

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"     // 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 fields)
      id: string                  // Option identifier
      value: string               // Option display value
    }>
    defaultValue?: string         // Default value for the field
    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"
    }
  ]
}

Error Responses​

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

Using Custom Fields in Test Cases​

Custom fields returned by this endpoint can be used when creating or updating test cases. The systemName property is used as the key when specifying custom field values.

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"
    }
  }
}

Custom Field Value Structure​

Each custom field value in the customFields object should have:

  • value: The actual value for the field
    • For text fields: any string value
    • For dropdown fields: must match one of the option value strings from the field's options array
  • isDefault: Boolean indicating whether to use the field's default value (if true, the value should be omitted)
Field Requirements
  • Required fields: Custom fields with required: true must be included when creating test cases
  • Enabled fields: Only custom fields with enabled: true should be used
  • Dropdown values: Values for dropdown fields must exactly match one of the option values
  • Project availability: Only custom fields where allowAllProjects: true or the current project ID is in allowedProjectIds are available for use

Using Default Values​

You can use the default value for a custom field by setting isDefault: true:

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

This will use the defaultValue specified in the custom field definition.

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"
Best Practices
  • Check field availability: Always verify that a custom field is enabled and available for your project before using it
  • Validate dropdown values: Ensure dropdown values match exactly (case-sensitive) with the options returned by this endpoint
  • Use system names: Always use the systemName property as the key when referencing custom fields in API requests
  • Handle required fields: Include all required custom fields when creating test cases to avoid validation errors
System Names

The systemName is a unique identifier for the custom field that remains constant even if the display name changes. Always use systemName when referencing custom fields in API requests, not the name or id.