Position Green API: Lists

Modified on Tue, 21 Jul at 8:40 AM

A list in the API represents a structured master dataset or factor table managed within Position Green. The documentation for endpoints related to Lists is detailed below. To test the endpoints please go to our Swagger UI page.

Query lists

GET /lists

query parameters
first	integer (int32, default 100, max 1000)
after	nullable string

Request

const response = await fetch('/lists', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response Example

{
    "totalCount": 1,
    "pageInfo": {
        "hasNextPage": false,
        "startCursor": "aWs41zA=",
        "endCursor": "aWs41zA="
    },
    "items": [
        {
            "cursor": "aWs41zA=",
            "node": {
                "id": "1f1ec12f-edb6-425a-a2d4-o03bddg1d3c5",
                "name": "Business units",
                "prettyId": "business-units",
                "source": "ERP",
                "type": "Text",
                "createdAt": "2025-01-27T12:06:27.881Z"
            }
        }
    ]
}

This API will return metadata for each list and not its content. Content for a specific list can be fetched from https://api.positiongreen.com/v1/lists/{id}/items.

Create list

POST /lists

Creates a new tenant-managed list. Supported data type options: Text (default), Number, Json, Page, Unknown.

Request Body

{
  "name": "Business units",
  "prettyId": "business-units",
  "type": "Text"
}

Response (200 OK)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Get list details

GET /lists/{id}

Path Parameters

Name	Type	Description
id*	string (uuid)	The unique identifier of the list.

Response Example (200 OK)

{
  "id": "1f1ec12f-edb6-425a-a2d4-o03bddg1d3c5",
  "name": "Business units",
  "prettyId": "business-units",
  "source": "Manual",
  "type": "Text",
  "createdAt": "2025-01-27T12:06:27.881Z",
  "updatedAt": "2025-01-28T09:12:00.000Z"
}

Update list

PATCH /lists/{id}

Path Parameters

Name	Type	Description
id*	string (uuid)	The unique identifier of the list to update.

Request Body

{
  "name": "Updated business units",
  "prettyId": "updated-business-units",
  "type": "Text"
}

Response

Returns 200 OK on successful update. Null properties in the request body keep their current value.

Delete list

DELETE /lists/{id}

Path Parameters

Name	Type	Description
id*	string (uuid)	The unique identifier of the list to delete.

Response

Returns 200 OK on successful deletion.

Query list items

GET /lists/{id}/items

Path Parameters

Name	Type	Description
id*	string (uuid)	The unique identifier of the target list.

Query Parameters

Name	Type	Description
after	string	Cursor for pagination.
maxListItemValues	integer (int32)	Default: 50, Min: 1, Max: 100.
first	integer (int32)	Default: 100, Min: 1, Max: 1000.
expand	array	Available options: `Values`.

This API will return data for a specific list. An optional query parameter "expand" can be provided to retrieve values associated with each item.

Example of a response with "expand" set to "Values":

{
  "totalCount": 1,
  "pageInfo": {
    "hasNextPage": false,
    "startCursor": "aWR4OzA=",
    "endCursor": "aWR4OzA="
  },
  "items": [
    {
      "cursor": "aWR4OzA=",
      "node": {
        "id": "c951196e-827f-426e-b9c1-6de65519bf3d",
        "name": "Regional train, Green electricity",
        "prettyId": "Regional_train_Green_electricity",
        "externalId": "EXT-001",
        "sortOrder": 10,
        "createdAt": "2025-01-24T12:25:07.543Z",
        "listItemValues": [
          {
            "id": "2e0ea5ac-bc44-468d-8336-7c2fa240a3c0",
            "value": "{\"factor_scope_3\":1E-17,\"unit\":\"ton CO2e/p.km\"}",
            "validFrom": "2025-01-01T00:00:00Z",
            "createdAt": "2025-01-24T12:25:07.543Z"
          }
        ]
      }
    }
  ]
}

Create list item

POST /lists/{listId}/items

Path Parameters

Name	Type	Description
listId*	string (uuid)	The target list ID.

Request Body

{
  "name": "Stockholm",
  "prettyId": "stockholm",
  "sortOrder": 10
}

Response (200 OK)

{
  "id": "8ba12345-1234-468d-8336-7c2fa240a3c0"
}

Update list item

PATCH /lists/{listId}/items/{listItemId}

Path Parameters

Name	Type	Description
listId*	string (uuid)	The unique identifier of the list.
listItemId*	string (uuid)	The unique identifier of the item to update.

Request Body

{
  "name": "Updated Stockholm",
  "prettyId": "updated-stockholm",
  "sortOrder": 20
}

Response

Returns 200 OK on successful update. Null properties keep their current value.

Delete list item

DELETE /lists/{listId}/items/{listItemId}

Path Parameters

Name	Type	Description
listId*	string (uuid)	The unique identifier of the list.
listItemId*	string (uuid)	The unique identifier of the list item to delete.

Response

Returns 200 OK on successful item deletion.

Query list item values

GET /lists/{listId}/items/{listItemId}/values

Path Parameters

Name	Type	Description
listId*	string (uuid)	The list identifier.
listItemId*	string (uuid)	The list item identifier.

Query Parameters

Name	Type	Description
first	integer (int32)	Default: 100, Min: 1, Max: 1000.
after	string	Cursor for pagination.

Response Example (200 OK)

{
  "totalCount": 1,
  "pageInfo": {
    "hasNextPage": false,
    "startCursor": "aWR4OzA=",
    "endCursor": "aWR4OzA="
  },
  "items": [
    {
      "cursor": "aWR4OzA=",
      "node": {
        "id": "2e0ea5ac-bc44-468d-8336-7c2fa240a3c0",
        "value": "0.2675",
        "validFrom": "2026-01-01T00:00:00Z",
        "createdAt": "2026-01-01T10:00:00Z",
        "updatedAt": null
      }
    }
  ]
}

Create list item value

POST /lists/{listId}/items/{listItemId}/values

Path Parameters

Name	Type	Description
listId*	string (uuid)	The list identifier.
listItemId*	string (uuid)	The list item identifier.

Request Body

{
  "value": "0.2675",
  "validFrom": "2026-01-01T00:00:00Z"
}

Note: The value field supports text, numeric values, and structured JSON strings. If validFrom is omitted, it defaults to current timestamp.

Response (200 OK)

{
  "id": "2e0ea5ac-bc44-468d-8336-7c2fa240a3c0"
}

Update list item value

PATCH /lists/{listId}/items/{listItemId}/values/{listItemValueId}

Path Parameters

Name	Type	Description
listId*	string (uuid)	The list identifier.
listItemId*	string (uuid)	The list item identifier.
listItemValueId*	string (uuid)	The list item value identifier to update.

Request Body

{
  "value": "0.2800",
  "validFrom": "2026-06-01T00:00:00Z"
}

Response

Returns 200 OK on successful update. Null properties keep their current value.

Delete list item value

DELETE /lists/{listId}/items/{listItemId}/values/{listItemValueId}

Path Parameters

Name	Type	Description
listId*	string (uuid)	The list identifier.
listItemId*	string (uuid)	The list item identifier.
listItemValueId*	string (uuid)	The list item value identifier to delete.

Response

Returns 200 OK on successful value deletion.