Position Green API - Organisational Units

Modified on Tue, 21 Jul at 9:29 AM

Get Organization Units

Get Organization Units from Position Green Platform by an external ID (PrettyId) or unique identifier (Id). Additionally, the IncludeSubunits parameter allows retrieving all sub-organizations under the specified unit.

Properties of Organization Unit object

Property	Data Type	Description
id	string (uuid)	Unique identifier of the Organization Unit
globalId	string (uuid)	Global ID of the Organization Unit
name	nullable string	Name of the Organization Unit
yearId	string (uuid)	ID of the year assigned to the Organization Unit
prettyId	nullable string	Pretty ID (external identifier) of the Organization Unit
parentId	nullable string (uuid)	Parent ID of the Organization Unit in the hierarchy
organizationId	string (uuid)	ID of the Tenant organization
description	nullable string	Optional description of the unit

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

Check the Organizational unit section on our Swagger UI page.

Query Parameters

Name	Type	Description
Id	string (uuid)	Optional unique identifier to filter by a specific organization unit.
PrettyId	string	Optional pretty ID to filter by.
IncludeSubunits	boolean	Optional flag to include child organization units in the results.
YearId	string (uuid)	Optional year identifier to filter organization units by specific year. Defaults to active year if omitted.

This API endpoint will return Organization Units in 3 specific ways:

All Organization Units of Tenant – if no request parameters are provided;
Specific Organization Unit – if Id or PrettyId is provided;
Specific Organization Unit with all sub-units – if Id or PrettyId is provided and IncludeSubunits is set to true.

Example response:

{
    "totalCount": 2,
    "items": [
        {
            "id": "346788a-fd74-fd74-fd74-fd74a1c08e8b",
            "globalId": "1234567-fd74-abcd-fd74-930fa1c18e8b",
            "name": "Organization Unit Name",
            "yearId": "3825cdbb-3795-4f0b-9854-21d9e3a0b50a",
            "prettyId": "Org Pretty Id",
            "parentId": null,
            "organizationId": "dfc751db-59ca-4ae7-878f-65fe1af0017e"
        },
        {
            "id": "2ca630f1-07d5-4ee4-9d29-ec95766732ec",
            "globalId": "8034bedf-1b7a-4e5e-96c7-0379622c6add",
            "name": "Org sub-unit Name",
            "yearId": "3825cdbb-3795-4f0b-9854-21d9e3a0b50a",
            "prettyId": "Org sub-unit Pretty Id",
            "parentId": "346788a-fd74-fd74-fd74-fd74a1c08e8b",
            "organizationId": "dfc751db-59ca-4ae7-878f-65fe1af0017e"
        }        
    ]
}

Create a new Organization Unit

Creates a new Organization Unit in Position Green Platform within the active year.

POST https://api.positiongreen.com/v1/OrganizationUnit

Request Body Parameters

Parameter	Required	Type	Description
name	No	nullable string	The name of the organization unit
parentId	No	nullable string (uuid)	Optional ID of parent unit in hierarchy
prettyId	No	nullable string	Pretty ID for the organization unit
complexData	No	CustomProperty[]	Optional array of custom properties (e.g. `[{"name": "culture", "data": "en", "type": "String"}]`)
supervisor	No	SupervisorDto	Supervisor object containing `id` (uuid), `firstName`, `lastName`, and `email`

Successful Response Example (200 OK)

{
    "id": "9620bd7d-8eb3-49a9-9ea2-19463d5aadd7",
    "globalId": "9620bd7d-8eb3-49a9-9ea2-19463d5aadd7",
    "name": "New organization",
    "yearId": "d338b2e8-eecc-476a-ba56-1853494a7ec9",
    "prettyId": "NewOrg 1",
    "parentId": "346788a-fd74-fd74-fd74-fd74a1c08e8b",
    "organizationId": "dfc751db-59ca-4ae7-878f-65fe1af0017e",
    "complexData": [
        {
            "name": "culture",
            "data": "en",
            "type": "String"
        }
    ],
    "supervisor": {
        "id": "6320ea4c-f274-4d0d-a249-3d23c15d0468",
        "firstName": "FirstName",
        "lastName": "lastName",
        "email": "lastName@example.com"
    }
}

Update Organization Unit

Updates an existing Organization Unit in Position Green Platform.

PUT https://api.positiongreen.com/v1/OrganizationUnit/{id}

Path Parameters

id*

string (uuid)

Required. The unique identifier of the organization unit to update.

Successful Response Example (200 OK)

{
    "id": "9620bd7d-8eb3-49a9-9ea2-19463d5aadd7",
    "globalId": "9620bd7d-8eb3-49a9-9ea2-19463d5aadd7",
    "name": "Updated organization",
    "yearId": "d338b2e8-eecc-476a-ba56-1853494a7ec9",
    "prettyId": "UpdOrgPretty 1",
    "parentId": "346788a-fd74-fd74-fd74-fd74a1c08e8b",
    "organizationId": "dfc751db-59ca-4ae7-878f-65fe1af0017e",
    "complexData": [
        {
            "name": "culture",
            "data": "en",
            "type": "String"
        }
    ],
    "supervisor": {
        "id": "6320ea4c-f274-4d0d-a249-3d23c15d0468",
        "firstName": "FirstName",
        "lastName": "lastName",
        "email": "lastName@example.com"
    }
}

Delete Organization Unit

Deletes an Organization Unit from the system.

DELETE https://api.positiongreen.com/v1/OrganizationUnit/{orgUnitId}

Path Parameters

orgUnitId*

string (uuid)

Required. The unique identifier of the organization unit to delete.

Responses

200 OK	Successfully deleted the organization unit.
401 Unauthorized	Authentication required.
404 Not Found	Organization unit not found with the specified ID.
500 Server Error	Internal server error occurred during deletion.