The Productboard REST API v2 uses types to represent structured data in a more organized way. Understanding these types is essential for effectively working with the API since they are frequently used in the configuration endpoints.

We will review the types available for "field values". These types are used to represent the values of various fields in Productboard entities and notes.

Where can you find type information?

Types are referenced from the configuration endpoints. After calling these endpoints, a response will include a data object that contains many fields. Each of these fields will contain a schema key and value.

Here's an example after calling GET /v2/entities/configuration?type=feature. The data shown has been truncated for brevity.

Within this example, you can see that the schema key contains values such as RichTextFieldValue, TextFieldValue, and StatusFieldValue. These values will map to different types.

{
  "data": {
    "type": "feature",
    "fields": {
      "description": {
        "id": "description",
        "name": "Description",
        "path": "/fields/description",
        "schema": "RichTextFieldValue",
        "lifecycle": {
          "create": {
            "set": true
          },
          "update": {
            "set": true,
            "clear": true
          },
          "patch": {
            "set": true,
            "clear": true
          }
        },
        "constraints": {
          "maxLength": 1048576
        },
        "links": {
          "self": null
        }
      },
      "name": {
        "id": "name",
        "name": "Name",
        "path": "/fields/name",
        "schema": "TextFieldValue",
        "lifecycle": {
          "create": {
            "set": true
          },
          "update": {
            "set": true
          },
          "patch": {
            "set": true
          }
        },
        "constraints": {
          "required": true,
          "maxLength": 255
        },
        "links": {
          "self": null
        }
      },
      "status": {
        "id": "status",
        "name": "Status",
        "path": "/fields/status",
        "schema": "StatusFieldValue",
        "lifecycle": {
          "create": {
            "set": true
          },
          "update": {
            "set": true
          },
          "patch": {
            "set": true
          }
        },
        "links": {
          "self": null
        }
      }
    }
  }
}

What are all the types used in the API?

Basic types

The following map to strings:

UUIDFieldValue
TextFieldValue
RichTextFieldValue e.g., "<p>This is <b>rich</b> text.</p>"
DateFieldValue, using ISO 8601 format without time (e.g., "2023-10-01")
DateTimeFieldValue, using ISO 8601 format (e.g., "2023-10-01T12:00:00Z")
URLFieldValue
NameFieldValue

The following map to numbers:

NumberFieldValue, integers or floats, including negative numbers

The following map to booleans:

BooleanFieldValue

The following map to enumerations:

GranularityFieldValue - year, quarter, month, day

Complex types

The following map to more complex JSON objects, and are explained more thoroughly in following sections.

Status:

StatusFieldAssign
StatusFieldAssignById
StatusFieldAssignByName
StatusFieldValue

Member:

MemberFieldValue
MemberFieldAssign
MemberAssignById
MemberAssignByEmail

Teams:

TeamsFieldValue
TeamFieldValue
TeamFieldAssign
TeamAssignById
TeamAssignByName
TeamsFieldAssign

Time:

TimeframeFieldValue

Choice fields:

SingleSelectFieldValue
SingleSelectFieldAssign
SingleSelectFieldAssignById
SingleSelectFieldAssignByName
MultiSelectFieldValue
MultiSelectFieldAssign

Health:

HealthFieldValue
HealthUpdateFieldValue
HealthStatusEnum
HealthModeEnum

Progress:

ProgressFieldValue
WorkProgressFieldValue

`FieldValue` vs `FieldAssign`

Many of the types used have the suffix FieldValue or FieldAssign. For example, SingleSelectFieldValue and SingleSelectFieldAssign.

The difference between these two types of fields is:

FieldValue types are used when retrieving data from the API. These types represent the current value of a field.
FieldAssign types are used when sending data to the API. These types represent how you want to set or update the value of a field.

Name vs ID assignments

When a field has a FieldAssign type, it often means that there are multiple ways to specify the value. For example, with choice fields, you can assign a value by its id or by its name i.e., SingleSelectFieldAssign can be either type SingleSelectFieldAssignById or SingleSelectFieldAssignByName.

We recommend using IDs when possible, as names can change over time. However, using names can be more user-friendly in some cases. Our general guidance is use IDs in automated systems and names in manual processes.

Status fields

StatusFieldAssign can be either type StatusFieldAssignById or StatusFieldAssignByName.

StatusFieldAssignById has an id property:

{
    "id": "UUID"
}

StatusFieldAssignByName has a name property of type NameFieldValue:

{
    "name": "In progress"
}

StatusFieldValue has the following properties:

id of type UUID
name of type NameFieldValue

{
    "id": "UUID",
    "name": "In progress"
}

Member fields

MemberFieldAssign can be either type MemberAssignById or MemberAssignByEmail.

MemberAssignById has an id property:

{
    "id": "UUID"
}

MemberAssignByEmail has an email property:

{
    "email": "user@example.com"
}

MemberFieldValue has the following properties:

id of type UUID
email of type NameFieldValue

{
    "id": "UUID",
    "email": "user@example.com"
}

Teams fields

TeamFieldValue has the following properties:

id of type UUID
name of type NameFieldValue

{
    "id": "UUID",
    "name": "Team Name"
}

TeamsFieldValue is an array of TeamFieldValue objects:

[
    {
        "id": "UUID1",
        "name": "Team Name 1"
    },
    {
        "id": "UUID2",
        "name": "Team Name 2"
    }
]

TeamFieldAssign can be either type TeamAssignById or TeamAssignByName.

TeamAssignById has an id property:

{
    "id": "UUID"
}

TeamAssignByName has a name property:

{
    "name": "Team Name"
}

TeamsFieldAssign is an array of either TeamAssignById or TeamAssignByName objects:

[
    {
        "id": "UUID1"
    },
    {
        "name": "Team Name 2"
    }
]

Date-Time fields

TimeframeFieldValue has startDate, endDate, and granularity properties. These properties are of the following types:

startDate is of type DateFieldValue
endDate is of type DateFieldValue
granularity is of type GranularityFieldValue

{
    "startDate": "2023-10-01",
    "endDate": "2023-12-31",
    "granularity": "month"
}

Choice fields

SingleSelectFieldValue has id, name, and color properties:

{
    "id": "UUID",
    "name": "Option Name",
    "color": "blue"
}

SingleSelectFieldAssign can be either type SingleSelectFieldAssignById or SingleSelectFieldAssignByName.

SingleSelectFieldAssignById has an id property:

{
    "id": "UUID"
}

SingleSelectFieldAssignByName has a name property:

{
    "name": "Option Name"
}

MultiSelectFieldValue is an array of SingleSelectFieldValue objects:

[
    {
        "id": "UUID1",
        "name": "Option Name 1",
        "color": "blue"
    },
    {
        "id": "UUID2",
        "name": "Option Name 2",
        "color": "red"
    }
]

MultiSelectFieldAssign is an array of either SingleSelectFieldAssignById or SingleSelectFieldAssignByName objects:

[
    {
        "id": "UUID1"
    },
    {
        "name": "Option Name 2"
    }
]

Health fields

HealthFieldValue has the following properties:

id of type UUID
mode of type HealthModeEnum
status of type HealthStatusEnum
previousStatus of type HealthStatusEnum
lastUpdatedAt of type DateTimeFieldValue
comment of type RichTextFieldValue
createdBy of type MemberFieldValue

{
    "id": "UUID",
    "mode": "manual",
    "status": "onTrack",
    "previousStatus": "atRisk",
    "lastUpdatedAt": "2023-10-01T12:00:00Z",
    "comment": "<p>Health is looking good!</p>",
    "createdBy": {
        "email": "user@example.com"
    }
}

HealthUpdateFieldValue has the following properties:

mode of type HealthModeEnum
status of type HealthStatusEnum
comment of type RichTextFieldValue
createdBy of type MemberFieldAssign

{
    "mode": "manual",
    "status": "onTrack",
    "comment": "<p>Health is looking good!</p>",
    "createdBy": {
        "id": "UUID"
    }
}

HealthStatusEnum is an enumeration of:

notSet
onTrack
atRisk
offTrack

HealthModeEnum is an enumeration of:

manual
calculated

Progress fields

ProgressFieldValue has the following properties:

startValue of type number, format float
targetValue of type number, format float
currentValue of type number, format float

{
    "startValue": 0.0,
    "targetValue": 100.0,
    "currentValue": 45.5
}

WorkProgressModeEnum is an enumeration of:

manual
statusBased
calculated

WorkProgressFieldValue has the following properties:

value of type number, format integer, between 0 and 100
mode, of type WorkProgressModeEnum. Supported modes by entity types:
- Subfeature: manual, statusBased
- Feature: manual, statusBased, calculated
- Initiative: manual, calculated
- Objective: manual, calculated

{
    "value": 45,
    "mode": "manual"
}