Organisation Units

Org units let you break your members down into sub groups of your organisation (for example locations, regions or departments). They form a tree: a top level unit can have children, which can have their own children.

Members are assigned to org units through the OrgUnitLevels field when you create or update a user. The endpoints on this page manage the org unit tree itself.

All endpoints require a bearer token.

Method	Path	Purpose
GET	/v2/meta/OrgUnitLevels	Get the org unit tree
PATCH	/v2/meta/OrgUnitLevels	Add org units, leaving existing ones in place
POST	/v2/meta/OrgUnitLevels	Replace org units with the supplied tree

Org Unit Model

Every endpoint reads and/or returns a list of OrgUnits.

Field	Type	Description
Id	long (nullable)	The org unit Id. Omit or null to let the system assign one.
Name	string	The org unit name.
Children	array (nullable)	Child org units nested under this unit, using the same model.
Parent	object (nullable)	Optional, requests only. Only Parent.Id is used, to attach the unit to an existing parent. Never returned in responses.

There is no OrgUnitId field. Use Id.

Get Organizational Unit Levels

Returns every org unit configured for your partner as a tree, up to four levels deep.

[GET] /v2/meta/OrgUnitLevels

HTTP Response Values

    200 - Successful retrieval of organizational unit levels
    404 - Not Found

Example Response

HTTP/1.1 200 Ok

[
    {
        "Id": 101,
        "Name": "Locations",
        "Children": [
            {
                "Id": 102,
                "Name": "Leamington",
                "Children": []
            },
            {
                "Id": 103,
                "Name": "Leicester",
                "Children": []
            }
        ]
    }
]

Update Organizational Unit Levels

Adds org units that do not already exist. Existing units are left in place, they are not renamed, moved or removed, so this is safe to use when members or rewards are already attached.

[PATCH] /v2/meta/OrgUnitLevels?useIds=false

Query Parameters

Parameter	Type	Default	Description
useIds	boolean	false	false: an incoming unit is matched to an existing one by Name or Id; if neither matches it is created. true: units are matched by Id only, so a unit whose Id does not exist is created even if the name already exists. Use this to add a same-named unit under a different parent.

If your tree contains the same name more than once, use useIds=true, as matching by name cannot tell them apart.

Request Body

[
    {
        "Id": 0,
        "Name": "Locations",
        "Parent": { "Id": 0 },
        "Children": [
            {
                "Id": 0,
                "Name": "Leamington",
                "Children": []
            }
        ]
    }
]

Nesting is processed to three levels (unit, child, grandchild). Anything deeper is ignored.

HTTP Response Values

    200 - Successful update, the body is the full org unit tree
    404 - Incorrect or missing org units, the body contains the error message

Save Organizational Unit Levels

Replaces the org units whose Id appears in the request with the supplied tree.

[POST] /v2/meta/OrgUnitLevels

Use with care. Existing units that share an Id with the request are removed before the new tree is saved. If any of them already has members or rewards attached, nothing is removed and the call returns an error telling you to use PATCH instead.

Request Body

[
    {
        "Id": 0,
        "Name": "Locations",
        "Children": [
            {
                "Id": 0,
                "Name": "Leamington",
                "Children": []
            }
        ]
    }
]

Nesting is processed to five levels.

HTTP Response Values

    200 - Successful save, the body is the full org unit tree
    404 - Incorrect or missing org units, or members/rewards already on an org unit (the body contains the error message)

Error Response

Failures return a body in this shape. Note that the status code is 404 even though the Result text says 400.

{
    "Result": "400- NOT OK",
    "ResultDetails": "Users already on this orgunit, cannot change, use patch instead"
}

Assigning Members to Org Units

When creating or updating a user, OrgUnitLevels is a list of strings. Each entry is matched to one of your org units by name (case insensitive) or by numeric Id. Entries that match nothing are ignored. Supplying a list on an update replaces the member's existing org units, and supplying an empty or missing list clears them.