List a custom dimension's values

Operation ID: listCustomDimensionValues

Group: Base › Reporting Tags

Open in the interactive reference

GET /base/custom-dimensions/{customDimensionUuid}/values

Read-only: Reads and returns; changes nothing.

Lists a custom dimension's values. Inactive values are left out unless includeInactive is true. Each value has the modelUuid that POST base/reporting-tags/resolve accepts.

This endpoint does not follow the standard collection rules in Pagination and querying.

This endpoint ignores any query parameter it does not declare, and returns no error. A request that follows the standard rules therefore gets the first page, unfiltered, every time.

Parameters

Name In Type Required Description
Api-Version header string · v1 yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
customDimensionUuid path string yes The unique identifier of the custom value dimension whose values you want to retrieve. Take it from the customDimensionUuid of a record from GET base/custom-dimensions.
includeInactive query boolean no Whether to include values that are no longer active. Defaults to false.
pageSize query number no The number of values per page, between 1 and 200. Defaults to 50. A value above 200 is treated as 200, not rejected.
cursor query string no The cursor from the previous response's data.pagination.nextCursor. Omit on the first request.

Response

200 Success

Under data (listCustomDimensionValuesOutput):

Field Type Required Description
items array<object> yes The values on this page. An empty array when the dimension holds none. A dimension identifier that matches nothing fails with NOT_FOUND instead.
items[].dimensionCode string yes The dimension this value belongs to. Always 'custom' on this endpoint.
items[].modelId number yes The numeric id of the value record, stored internally on a journal entry's allocation line.
items[].modelUuid string yes The unique identifier for the value record. Pass it as modelUuid to POST base/reporting-tags/resolve, paired with dimensionCode 'custom'.
items[].name string yes The display name of the value.
items[].isActive boolean yes Whether the value is currently active and can be assigned to new transactions.
items[].customDimensionUuid string no The unique identifier for the custom dimension this value belongs to. It is the same identifier given in the path.
items[].dimensionName string no The display name of the parent custom dimension.
pagination object yes The pagination cursor for this page.
pagination.nextCursor string no The cursor for the next page. Pass it as the cursor query parameter. Absent on the last page.
pagination.hasMore boolean yes True when more values remain beyond this page. 
{
  "data": {
    "items": [
      {
        "dimensionCode": "<dimensionCode>",
        "modelId": 0,
        "modelUuid": "<modelUuid>",
        "name": "<name>",
        "isActive": true,
        "customDimensionUuid": "<customDimensionUuid>",
        "dimensionName": "<dimensionName>"
      }
    ],
    "pagination": {
      "nextCursor": "<nextCursor>",
      "hasMore": true
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Errors

Code Status
NOT_FOUND 400
INVALID_CURSOR 400

Statuses