TABLE OF CONTENTS
A registration is the data that a reporter has submitted given the structure of a measure. Given the customizable properties of a measure, the registration contains a graph of answers for the values corresponding to the questions in a measure.
Swagger UI
Below you will find the documentation details for Registrations. To test the endpoint, please go to our Swagger UI page.
Properties of a registration object
| Property | Data Type | Description |
| id | string (uuid) | ID of the registration. |
| organizationUnit | string | The organization unit the data belongs to. |
| measureName | string | Name of the measure. |
| responsibleUser | nullable string | The reporter responsible for reporting the data. |
| confirmedAt | nullable string (date-time) | If the registration is confirmed, contains the ISO 8601 timestamp. |
| period | nullable string (read-only) | The period type moniker (e.g. "M4"). |
| periodStart | nullable string | Start date of the period. |
| periodEnd | nullable string | End date of the period. |
| data | nullable Value (object) | Polymorphic data structure containing the registration answers. |
The period property contains a code and a number. For example "M4": M for month and 4 for April. It is a way of identifying the periodicity if needed. If the measure is configured to be year-to-date, the start date is always the year's start date.
The registration data is a graph object containing the values. The graph's structure is defined by how the measure is set up. It is up to the Controller to configure the measure for the reporter to fill in.
The root object in the data property is always a ListValue, a collection of values.
Value
The base of all value types, contains general information available in all value types.
| Property | Description |
| id | Id of the data. Unique within each registration. |
| name | System name; it can be set in the measure builder to identify the control. |
| label | The display name shown to the reporter. |
| type / valueType* | Required discriminator string indicating the value subtype. |
| tags | A list of tags. Set in Measure Builder and recommended for identifying controls. |
To identify a subtype of Value the property valueType / type is used. All common properties are omitted in the descriptions of each value below.
List
A collection of values. The root object in data is always a list. It can contain other lists. The id and name of a root list is always null.
| Property | Description |
| value | Array of Value objects |
| isIterativeValue | boolean indicating if list is an iterative value container |
Example
Example of a list with two values.
{
"value": [
{
"type": "numeric",
"value": 4,
"unit": "Trips",
"id": "measure_1",
"name": "measure_1",
"label": "Number of flights",
"tags": []
},
{
"type": "numeric",
"value": 2000,
"unit": "km",
"id": "measure_2",
"name": "measure_2",
"label": "Distance by airplane 2",
"tags": []
}
],
"type": "list"
}Repeatable
A repeatable control in a measure allows the reporter to add and remove rows in Position Green when reporting data. Every row in the repeatable is represented as a list in the data structure.
| Property | Description |
| value | Array of rows (List objects) |
Example
An example of a registration where the measure contains a repeatable that allows for the reporter to add one or more rows and indicate a source and energy used.
Every row in the repeatable is assigned a unique id but the name of each control will still be the same.
{
"value": [
{
"type": "repeatable",
"value": [
{
"value": [
{
"type": "dropdown",
"value": [
{
"name": "Wind"
}
],
"id": "measure_fc2t!!repeatable_q3gn!!15862358690400",
"name": "measure_fc2t",
"label": "Source",
"tags": []
},
{
"type": "numeric",
"value": 65000,
"unit": "kWh",
"id": "measure_dnkl!!repeatable_q3gn!!15862358690400",
"name": "measure_dnkl",
"label": "Energy used",
"tags": []
}
],
"type": "list"
},
{
"value": [
{
"type": "dropdown",
"value": [
{
"name": "Solar"
}
],
"id": "measure_fc2t!!repeatable_q3gn!!15862359182380",
"name": "measure_fc2t",
"label": "Source",
"tags": []
},
{
"type": "numeric",
"value": 250000,
"unit": "kWh",
"id": "measure_dnkl!!repeatable_q3gn!!15862359182380",
"name": "measure_dnkl",
"label": "Energy used",
"tags": []
}
],
"type": "list"
},
{
"value": [
{
"type": "dropdown",
"value": [
{
"name": "Nuclear"
}
],
"id": "measure_fc2t!!repeatable_q3gn!!15862359243871",
"name": "measure_fc2t",
"label": "Source",
"tags": []
},
{
"type": "numeric",
"value": 3000000,
"unit": "kWh",
"id": "measure_dnkl!!repeatable_q3gn!!15862359243871",
"name": "measure_dnkl",
"label": "Energy used",
"tags": []
}
],
"type": "list"
}
],
"id": "repeatable_q3gn",
"name": "repeatable_q3gn"
}
],
"type": "list"
}Numeric
Contains a numeric value and a unit.
| Property | Description |
| value | Decimal number (double) |
| unit | The unit of the value |
| control | The associated control identifier |
Example
The value is 9000 and the unit is in kilometers.
{
"type": "numeric",
"value": 9000,
"unit": "km",
"id": "measure_2_copy1",
"name": "measure_2_copy1",
"label": "Distance by train",
"tags": []
}Text
Text value where the reporter fills in a qualitative answer.
| Property | Description |
| value | Text value string |
{
"type": "text",
"id": "info",
"name": "info",
"label": "Additional info",
"tags": [],
"value": "Qualitative text response"
}Bool
A boolean value where the reporter has chosen between Yes and No when filling in the answers.
| Property | Description |
| value | Boolean value (true/false) |
Example
{
"type": "bool",
"id": "renewable",
"name": "renewable",
"label": "Is the source renewable?",
"tags": [],
"value": true
}Date
A value that contains a date in ISO 8601 (yyyy-MM-dd) format.
| Property | Description |
| value | Date in ISO 8601 format |
Example
{
"type": "date",
"value": "2024-01-24",
"id": "registration_date",
"name": "registration_date",
"label": "Date",
"tags": []
}Dropdown
A dropdown value which contains one or many selected options by a reporter.
| Property | Description |
| value | An array of SelectedOption objects (properties: name, prettyId, value) |
The dropdown has a configuration setting that indicates if the reporter is allowed to select many values. The dropdown value is always an array in the data structure.
Example
Here is an example of three different values from dropdowns:
- The value contains a JSON encoded string
- The value contains a simple value
- There is no value associated with the selected option
{
"type": "repeatable",
"value": [
{
"value": [
{
"type": "dropdown",
"value": [
{
"name": "Wind",
"prettyId": "wind-option",
"value": "{\"renewable\":true}"
}
],
"id": "measure_fc2t!!repeatable_q3gn!!15862358690400",
"name": "measure_fc2t",
"label": "Source",
"tags": []
},
{
"type": "numeric",
"value": 65000,
"unit": "kWh",
"id": "measure_dnkl!!repeatable_q3gn!!15862358690400",
"name": "measure_dnkl",
"label": "Energy used",
"tags": []
}
],
"type": "list"
}
],
"id": "repeatable_q3gn",
"name": "repeatable_q3gn"
}File
A value that represents uploaded files by the reporter. The reporter can upload one or many files. Each item contains a name and a link URL path to download the attachment.
| Property | Description |
| value | An array of File objects (properties: name, link) |
Example
{
"type": "file",
"value": [
{
"name": "Invoice ACME.pdf",
"link": "/attachment/get/3ef994e5-81ee-4958-bb99-3812be0d305a"
},
{
"name": "Invoice FOO.xlsx",
"link": "/attachment/get/ba602707-0055-48b2-b6ed-879eabfa217b"
}
],
"id": "measure_gtby",
"name": "measure_gtby",
"label": "Upload source materials",
"tags": []
}Get registrations
GET https://api.positiongreen.com/v1/registrations
Retrieves a paginated list of registrations (journal entries) for the specified criteria.
Query Parameters
| Name | Type | Description |
|---|---|---|
| yearId* | string (uuid) | Required. Year identifier to retrieve registrations from. |
| measureIds | string[] (uuid) | Optional array of measure IDs to filter registrations |
| measurePrettyIds | string[] | Optional array of measure pretty IDs to filter registrations |
| orgUnitIds | string[] (uuid) | Optional array of organization unit IDs to filter registrations |
| includeChildren | boolean | Whether to include child organization units in the filter. Default = false |
| startDate | string | Optional start date filter (format: yyyy-MM-dd) |
| endDate | string | Optional end date filter (format: yyyy-MM-dd) |
| first | integer (int32) | Number of registrations to return. Default = 10, Minimum 1, Maximum 100. |
| after | string | Cursor to where to continue getting next page of registrations |
| sortBy | string (enum) | Field to sort results by: Period (default) |
| sortDirection | string (enum) | Sort direction: Ascending (default) or Descending |
Responses
| 200: OK Success | Returns the paginated list of registrations matching the criteria. |
| 400: Bad Request | Validation errors, missing required yearId parameter, or missing tenant header. |
| 401: Unauthorized | Authentication required. |
| 500: Server Error | Internal server error occurred while retrieving registrations. |
Response Example
{
"totalCount": 178,
"pageInfo": {
"hasNextPage": true,
"startCursor": "cGFnZTsw",
"endCursor": "cGFnZTs5"
},
"items": [
{
"cursor": "cGFnZTs0MTQ=",
"node": {
"id": "715117fd-a8c5-4cf7-9a4b-8cc7aafee0f4",
"organizationUnit": "Björn Johansson",
"measureName": "Report energy usage",
"responsibleUser": "Björn Johansson",
"confirmedAt": "2024-02-01T10:00:00Z",
"data": {
"value": [
{
"type": "repeatable",
"value": [
{
"value": [
{
"type": "dropdown",
"value": [
{
"name": "Wind",
"value": "{\"renewable\":true}"
}
],
"id": "measure_fc2t!!repeatable_q3gn!!15862358690400",
"name": "measure_fc2t",
"label": "Source",
"tags": []
},
{
"type": "numeric",
"value": 65000,
"unit": "kWh",
"id": "measure_dnkl!!repeatable_q3gn!!15862358690400",
"name": "measure_dnkl",
"label": "Energy used",
"tags": []
}
],
"type": "list"
}
],
"id": "repeatable_q3gn",
"name": "repeatable_q3gn"
},
{
"type": "file",
"value": [
{
"name": "ReportTest.pdf",
"link": "/attachment/get/3ef294e5-81ee-4958-bb99-3812be0d305a"
}
],
"id": "measure_gtby",
"name": "measure_gtby",
"label": "Filuppladdning",
"tags": []
}
],
"type": "list"
},
"periodStart": "2024-01-01",
"periodEnd": "2024-12-31",
"period": "Y0"
}
}
]
}Querying using startDate and endDate will return registrations where the registration period intersects with the specified date range. For example, if you filter on startDate as '2019-12-01', you will retrieve all registrations where the period end date is later than 2019-12-01.
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article