API: Custom Fields
The custom fields endpoints return information about custom fields and — in the case of hierarchy custom fields — their items.
Methods
Get a custom field hierarchy item
Retrieves a single custom field item specified by its unique identifier.
id
integer
required path
The custom field item’s unique identifier
Example:42
200
OK
{
"_type": "HierarchyItem",
"id": 1338,
"label": "Stormtroopers",
"short": "ST",
"weight": null,
"formattedWeight": null,
"depth": 1,
"_links": {
"self": {
"href": "/api/v3/custom_field_items/1338",
"name": "Stormtroopers"
},
"parent": {
"href": "/api/v3/custom_field_items/1337",
"name": null
},
"branch": {
"href": "/api/v3/custom_field_items/1338/branch"
},
"children": [
{
"href": "/api/v3/custom_field_items/1340",
"name": "ST-377"
},
{
"href": "/api/v3/custom_field_items/1341",
"name": "ST-422"
}
]
}
}
HierarchyItemReadModel{
"type": "object",
"required": [
"_type",
"id",
"label",
"short",
"weight",
"formattedWeight",
"depth",
"_links"
],
"properties": {
"_type": {
"type": "string",
"enum": [
"HierarchyItem"
]
},
"id": {
"type": "integer",
"description": "Hierarchy item identifier"
},
"label": {
"type": [
"string",
"null"
],
"description": "The label of the hierarchy item"
},
"short": {
"type": [
"string",
"null"
],
"description": "The short name of the hierarchy item. If this attribute is set, the `weight` and\nthe `formattedWeight` are `null`."
},
"weight": {
"type": [
"string",
"null"
],
"description": "The accurate weight of the hierarchy item. As a decimal precision number it is written as a string to\nnot loose precision with conversion to a floating point number.\nIf this attribute is set, the `short` is null."
},
"formattedWeight": {
"type": [
"string",
"null"
],
"description": "The formatted weight of the hierarchy item. The standard formatting of the OpenProject server is used to\nconvert this number into a representable format - i.e. falling back to scientific notation for very small and\nvery big numbers.\nIf this attribute is set, the `short` is null."
},
"depth": {
"type": [
"integer",
"null"
],
"description": "The hierarchy depth. The root item has a depth of nil, the children of the root item have a depth of 0."
},
"_links": {
"type": "object",
"required": [
"self",
"children",
"branch"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This hierarchy item\n\n**Resource**: HierarchyItem"
}
]
},
"parent": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The hierarchy item that is the parent of the current hierarchy item\n\n**Resource**: HierarchyItem"
}
]
},
"children": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "A hierarchy item that is a child of the current hierarchy item\n\n**Resource**: HierarchyItem"
}
]
}
},
"branch": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The branch of the hierarchy item, ordered from root to node.\n\n**Resource**: HierarchyItemCollection"
}
]
}
}
}
}
}
403
Returned if the user is not logged in.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
404
Returned if the custom field item does not exist or the user lacks permission to see it.
The permission required to view the item depends on the custom field it belongs to.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
Get a custom field hierarchy item's branch
Retrieves the branch of a single custom field item specified by its unique identifier.
A branch is list of all ancestors, starting with the root item and finishing with the item itself.
id
integer
required path
The custom field item’s unique identifier
Example:42
200
OK
{
"_type": "Collection",
"total": 37,
"count": 37,
"_embedded": {
"elements": [
{
"_type": "HierarchyItem",
"id": 1337,
"label": null,
"short": null,
"weight": null,
"formattedWeight": null,
"depth": 0,
"_links": {
"self": {
"href": "/api/v3/custom_field_items/1337"
},
"branch": {
"href": "/api/v3/custom_field_items/1337/branch"
},
"children": [
{
"href": "/api/v3/custom_field_items/1338",
"name": "Stormtroopers"
},
{
"href": "/api/v3/custom_field_items/1339",
"name": "Dark Troopers"
}
]
}
},
{
"_type": "HierarchyItem",
"id": 1338,
"label": "Stormtroopers",
"short": "ST",
"weight": null,
"formattedWeight": null,
"depth": 1,
"_links": {
"self": {
"href": "/api/v3/custom_field_items/1338",
"name": "Stormtroopers"
},
"parent": {
"href": "/api/v3/custom_field_items/1337",
"name": "Imperial Troopers"
},
"branch": {
"href": "/api/v3/custom_field_items/1338/branch"
},
"children": [
{
"href": "/api/v3/custom_field_items/1340",
"name": "ST-377"
},
{
"href": "/api/v3/custom_field_items/1341",
"name": "ST-422"
}
]
}
},
{
"_type": "HierarchyItem",
"id": 1340,
"label": "ST-377",
"short": null,
"weight": null,
"formattedWeight": null,
"depth": 2,
"_links": {
"self": {
"href": "/api/v3/custom_field_items/1340"
},
"branch": {
"href": "/api/v3/custom_field_items/1340/branch"
},
"children": []
}
}
]
},
"_links": {
"self": {
"href": "/api/v3/custom_field/42/items"
}
}
}
HierarchyItemCollectionModel{
"allOf": [
{
"$ref": "#/components/schemas/CollectionModel"
},
{
"type": "object",
"required": [
"_links",
"_embedded"
],
"properties": {
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This hierarchy item collection\n\n**Resource**: HierarchyItemCollectionModel"
}
]
}
}
},
"_embedded": {
"type": "object",
"required": [
"elements"
],
"properties": {
"elements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HierarchyItemReadModel"
}
}
}
}
}
}
]
}
403
Returned if the user is not logged in.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
404
Returned if the custom field does not exist or the user lacks permission to view it.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
422
Returned if the custom field is not of type hierarchy.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:UnprocessableContent",
"message": "The requested custom field resource is of wrong type."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
Get custom field
Retrieves the custom field with the given ID.
id
integer
required path
The custom field’s unique identifier
Example:42
200
OK
CustomFieldModel{
"type": "object",
"required": [
"id",
"name",
"fieldFormat",
"isRequired",
"isMultiValue",
"createdAt",
"updatedAt",
"_links"
],
"properties": {
"id": {
"type": "integer",
"description": "The custom field ID.",
"readOnly": true
},
"name": {
"type": "string",
"description": "The human-readable name of the custom field."
},
"fieldFormat": {
"type": "string",
"description": "Defines which kind of values are allowed in the custom field.",
"enum": [
"bool",
"date",
"float",
"hierarchy",
"int",
"link",
"list",
"string",
"text",
"user",
"version",
"weighted_item_list"
]
},
"isRequired": {
"type": "boolean",
"description": "Whether the custom field must be filled out to save an object using it."
},
"isMultiValue": {
"type": "boolean",
"description": "Whether the custom field accepts more than one value."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Time of creation.",
"readOnly": true
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Time of the most recent change to the custom field.",
"readOnly": true
},
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "APIv3 self-reference of the custom field."
}
]
}
}
}
},
"example": {
"id": 42,
"name": "Celestial Body",
"fieldFormat": "hierarchy",
"isRequired": false,
"isMultiValue": false,
"createdAt": "2026-07-20T13:37:00Z",
"updatedAt": "2026-07-20T20:13:37Z",
"_links": {
"self": {
"href": "/api/v3/custom_fields/42",
"title": "Celestial Body"
}
}
}
}
403
Returned if the user is not logged in.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
404
Returned if the custom field does not exist or the user lacks the permission to view it.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
Get the custom field hierarchy items
Retrieves the hierarchy of custom fields.
The hierarchy is a tree structure of hierarchy items. It is represented as a flat list of items, where each item has a reference to its parent and children. The list is ordered in a depth-first manner. The first item is the requested parent. If parent was unset, the root item is returned as first element.
Passing the depth query parameter allows to limit the depth of the hierarchy. If the depth is unset, the full hierarchy tree is returned. If the depth is set to 0, only the requested parent is returned. Any other positive integer will return the number of children levels specified by this value.
This endpoint only returns, if the custom field is of type hierarchy.
id
integer
required path
The custom field’s unique identifier
Example:42
parent
integer
optional query
The identifier of the parent hierarchy item
Example:1337
depth
integer
optional query
The level of hierarchy depth
Example:1
200
OK
{
"_type": "Collection",
"total": 37,
"count": 37,
"_embedded": {
"elements": [
{
"_type": "HierarchyItem",
"id": 1337,
"label": null,
"short": null,
"weight": null,
"formattedWeight": null,
"depth": 0,
"_links": {
"self": {
"href": "/api/v3/custom_field_items/1337"
},
"branch": {
"href": "/api/v3/custom_field_items/1337/branch"
},
"children": [
{
"href": "/api/v3/custom_field_items/1338",
"name": "Stormtroopers"
},
{
"href": "/api/v3/custom_field_items/1339",
"name": "Dark Troopers"
}
]
}
},
{
"_type": "HierarchyItem",
"id": 1338,
"label": "Stormtroopers",
"short": "ST",
"weight": null,
"formattedWeight": null,
"depth": 1,
"_links": {
"self": {
"href": "/api/v3/custom_field_items/1338",
"name": "Stormtroopers"
},
"parent": {
"href": "/api/v3/custom_field_items/1337",
"name": "Imperial Troopers"
},
"branch": {
"href": "/api/v3/custom_field_items/1338/branch"
},
"children": [
{
"href": "/api/v3/custom_field_items/1340",
"name": "ST-377"
},
{
"href": "/api/v3/custom_field_items/1341",
"name": "ST-422"
}
]
}
},
{
"_type": "HierarchyItem",
"id": 1340,
"label": "ST-377",
"short": null,
"weight": null,
"formattedWeight": null,
"depth": 2,
"_links": {
"self": {
"href": "/api/v3/custom_field_items/1340"
},
"branch": {
"href": "/api/v3/custom_field_items/1340/branch"
},
"children": []
}
}
]
},
"_links": {
"self": {
"href": "/api/v3/custom_field/42/items"
}
}
}
{
"_type": "Collection",
"total": 3,
"count": 3,
"_embedded": {
"elements": [
{
"_type": "HierarchyItem",
"id": 1338,
"label": "Stormtroopers",
"short": "ST",
"weight": null,
"formattedWeight": null,
"depth": 1,
"_links": {
"self": {
"href": "/api/v3/custom_field_items/1338",
"name": "Stormtroopers"
},
"parent": {
"href": "/api/v3/custom_field_items/1337",
"name": null
},
"branch": {
"href": "/api/v3/custom_field_items/1338/branch"
},
"children": [
{
"href": "/api/v3/custom_field_items/1340",
"name": "ST-377"
},
{
"href": "/api/v3/custom_field_items/1341",
"name": "ST-422"
}
]
}
},
{
"_type": "HierarchyItem",
"id": 1340,
"label": "ST-377",
"short": null,
"weight": null,
"formattedWeight": null,
"depth": 2,
"_links": {
"self": {
"href": "/api/v3/custom_field_items/1340",
"name": "ST-377"
},
"parent": {
"href": "/api/v3/custom_field_items/1338",
"name": "Stormtroopers"
},
"branch": {
"href": "/api/v3/custom_field_items/1340/branch"
},
"children": [
{
"href": "/api/v3/custom_field_items/1480",
"name": "ST-377-200"
},
{
"href": "/api/v3/custom_field_items/1481",
"name": "ST-377-201"
}
]
}
},
{
"_type": "HierarchyItem",
"id": 1341,
"label": "ST-422",
"short": null,
"weight": null,
"formattedWeight": null,
"depth": 2,
"_links": {
"self": {
"href": "/api/v3/custom_field_items/1341",
"name": "ST-422"
},
"parent": {
"href": "/api/v3/custom_field_items/1338",
"name": "Stormtroopers"
},
"branch": {
"href": "/api/v3/custom_field_items/1341/branch"
},
"children": [
{
"href": "/api/v3/custom_field_items/1580",
"name": "ST-422-137"
},
{
"href": "/api/v3/custom_field_items/1581",
"name": "ST-422-138"
}
]
}
}
]
},
"_links": {
"self": {
"href": "/api/v3/custom_field/42/items?parent=1338&depth=1"
}
}
}
HierarchyItemCollectionModel{
"allOf": [
{
"$ref": "#/components/schemas/CollectionModel"
},
{
"type": "object",
"required": [
"_links",
"_embedded"
],
"properties": {
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This hierarchy item collection\n\n**Resource**: HierarchyItemCollectionModel"
}
]
}
}
},
"_embedded": {
"type": "object",
"required": [
"elements"
],
"properties": {
"elements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HierarchyItemReadModel"
}
}
}
}
}
}
]
}
403
Returned if the user is not logged in.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
404
Returned if the custom field does not exist or the user lacks the permission to view it.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
422
Returned if the custom field is not of type hierarchy.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:UnprocessableContent",
"message": "The requested custom field resource is of wrong type."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}