Resolve reporting tag references

Operation ID: resolveReportingTags

Group: Base › Reporting Tags

Open in the interactive reference

POST /base/reporting-tags/resolve

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Resolves reporting tag references into their display names. Each reference is a dimensionCode and modelUuid pair. A modelUuid is unique only within its dimension, so you need both to identify a tag.

References that don't resolve are left out of the response, so match results by the pair, not by position. Send at most 100 references per request.

Use it when you hold many references at once, such as the tags on a list of journal entries. It doesn't list tag values. To find a custom dimension's values, use GET base/custom-dimensions/:customDimensionUuid/values.

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.

Request body

Required, application/json: resolveReportingTagsInput.

Field Type Required Description
reportingTags array<object> yes The references to decode, as dimensionCode and modelUuid pairs. At most 100 per call. More than 100 fails with TOO_MANY_REFERENCES. An empty array returns an empty items array rather than an error. Duplicate references are collapsed, so each distinct reference appears at most once in the response.
reportingTags[].dimensionCode string yes The dimension the reference points into. Accepted values: 'department', 'businessUnit', 'team', 'location', 'region', 'employee', 'vendor', 'customer', 'valueCenter', 'custom'. An unknown code fails the whole call with UNSUPPORTED_DIMENSION_CODE.
reportingTags[].modelUuid string yes The unique identifier of the dimension record the reference points at. It is unique within its dimension but not across dimensions, so dimensionCode is required with it. A value that resolves to nothing is dropped from the response, unlike an unknown dimensionCode. Obtain it from the document that carries the tag, or for custom values from GET base/custom-dimensions/:customDimensionUuid/values. 
{
  "reportingTags": [
    {
      "dimensionCode": "<dimensionCode>",
      "modelUuid": "<modelUuid>"
    }
  ]
}

Response

200 Success

Under data (resolveReportingTagsOutput):

Field Type Required Description
items array<object> yes The resolved rows, in no guaranteed order and possibly shorter than the input, since references that did not resolve are absent. Match on the dimensionCode and modelUuid pair, never on position.
items[].dimensionCode string yes The dimension this value belongs to. Possible values: 'department', 'businessUnit', 'team', 'location', 'region', 'employee', 'vendor', 'customer', 'valueCenter', 'custom'.
items[].modelId number yes The numeric id of the dimension record, stored internally on a journal entry's allocation line. Output only. References are made by modelUuid.
items[].modelUuid string yes The unique identifier of the dimension record this tag references. Present on every row.
items[].name string yes The display name of the tag value.
items[].isActive boolean yes Whether the tag value is currently active and can be assigned to new transactions. A deactivated value still resolves, so existing references keep working.
items[].customDimensionUuid string no The unique identifier for the custom dimension this value belongs to. Present only when dimensionCode is 'custom'. Absent, not null, on the nine system dimensions.
items[].dimensionName string no The display name of the parent custom dimension. Present only when dimensionCode is 'custom'. Absent, not null, on the nine system dimensions.
unresolvedCount number yes How many of the requested references did not resolve. Zero when every reference resolved. Duplicates in the request are collapsed before this is counted. 
{
  "data": {
    "items": [
      {
        "dimensionCode": "<dimensionCode>",
        "modelId": 0,
        "modelUuid": "<modelUuid>",
        "name": "<name>",
        "isActive": true,
        "customDimensionUuid": "<customDimensionUuid>",
        "dimensionName": "<dimensionName>"
      }
    ],
    "unresolvedCount": 0
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Errors

Code Status
UNSUPPORTED_DIMENSION_CODE 400
TOO_MANY_REFERENCES 400

Statuses