Position Green API: Measures

Modified on Tue, 21 Jul at 9:34 AM

TABLE OF CONTENTS

Properties of a Measure object
Get all measures
- Query Parameters
- Example: getting the first 2 measures containing '201' in the name using curl

Measures in Position Green define the entire body of data you want to collect during a reporting year, this includes who will report the data, how often, and what organizational units. The measure is created by the Controller in Setup using Measure Builder.

To test the endpoints below, please visit our Swagger UI page.

Properties of a Measure object

Property	Data Type	Description
id	string (uuid)	Unique identifier of the measure
name	string	Name of the measure
prettyId	nullable string	Pretty ID (external identifier) of the measure
aspectName	string	The aspect it belongs to
globalId	string (uuid)	Global unique identifier of the measure

Get all measures

GET https://api.positiongreen.com/v1/measures

Retrieves a paginated list of measures filtered by year and optional name filter.

Query Parameters

Name	Type	Description
yearId*	string (uuid)	Required. The unique identifier of the year to filter measures by.
nameFilter	string	Optional filter to search for measures by name. Matches partial strings (e.g. `nameFilter`).
first	integer (int32)	The maximum number of measures to return in a single page. Default: `10`. Minimum: 1, Maximum: 500.
after	string	Optional cursor pointing to where to continue retrieving measures.
sortBy	string (enum)	The field to sort measures by. Options: `Name` (default).
sortDirection	string (enum)	Sort direction. Options: `Ascending` (default) or `Descending`.

Responses

200 OK Success	Returns the paginated list of measures.
400 Bad Request	Validation errors occurred (e.g., missing required `yearId`, invalid pagination parameters, invalid cursor).
401 Unauthorized	Authentication required.
500 Server Error	Internal server error occurred while retrieving measures.

Response Example

{
    "totalCount": 70,
    "pageInfo": {
        "hasNextPage": true,
        "startCursor": "aWR4OzA=",
        "endCursor": "aWR4Ozk="
    },
    "items": [
        {
            "cursor": "aWR4OzA=",
            "node": {
                "id": "da8e4c7d-5ffb-418b-ad3c-35c6be177fe7",
                "name": "Actual working hours",
                "prettyId": "actual-working-hours",
                "aspectName": "OH&S",
                "globalId": "1hfghdeac5-c297-7gfd-95ad-4b43543534552"
            }
        }
    ]
}

Example: getting the first 2 measures containing '201' in the name using curl

curl --location "https://api.positiongreen.com/v1/measures?yearId=<year_id>&first=2&nameFilter=201" \
  --header "Authorization: Bearer <access_token>"