Loading Guardian Developer...



Please Wait...

GET/ managements

In Guardian, one is able to define a hierarchy which represents the organizational structure of a company, allowing management responsibilities to be distributed among regional managers, branch managers, human resources specialists, etc—in fact, a company’s hierarchy can be defined to any level of specificity required for a given organization.

A management enables additional user permissions by extending user scope. Specifically, defining a management associates a set of employees with a user, allowing him or her to view and modify the employees’ cases. A management scope is defined by first creating a group, and then associating the manager’s user account with that group.

Requesting GET /v1/managements returns a list containing the associations between each user and the employees within their organizational level. The groups which can be assigned are restricted only by the structure of a Company’s hierarchy.

Although this API call returns a list, management groups logically describe a tree structure, mirroring the organization of the company. A group is identified by a unique path from the root of the hierarchy to the desired node. Multiple managements can exist for the same group node, differing only by the assigned manager.

    • Note: Although the meaning of a company hierarchy is defined by the organization during the provisioning process, there is a limitation that the hierarchy must be no more than 5 levels deep. This 5 level maximum excludes the root level, which exists for every company.
    • An organization may define levels for: locations, legal entities, and custom fields. These must be defined in Guardian before using them in a group or a management.

    In the response of a call to GET /v1/managements, each entry defines a user’s relationship to a defined employee group. The group is represented by an array of attribute values (the array of attribute values is equivalent to the node path described above). The attribute values are listed in hierarchical order; the first element in the list is the first level of the hierarchy below the company node in the tree, and subsequent elements traverse the tree from top to bottom. The more attributes defined in the group parameter, the lower in the hierarchy/smaller the employee population.

    When the group parameter is [] (an explicit empty list, not null), the associated user is assigned to the entire company (root node) and has access to all employees.

    Results are unordered, and should be processed individually. Results can be narrowed by including filters with the request. Optional root, group and userId filter parameters can be included in the request to retrieve management records for the specified group level and/or user. The options root and group are mutually exclusive.

    Method

    GET

    Resource Information

    Requires authentication? YES
    Response formats JSON

    Parameters

    Parameter Required Description
    id No The ID of the managements relationship of the user to a specific employee group
    root No Utilize root=true to return the management assigned to the entire company; note that this will not additionally return child group nodes
    group No The ordered list (i.e. hierarchical order or node path) of integer and/or string attributes that identify the employee group within the hierarchy for which to return employee group assignment results. Location and Legal Entity hierarchical attributes are defined by integer value (ID) while Custom Field hierarchical attributes are defined by string
    userId No The ID of the user for whom to return employee group assignments

    Example

    Request Example

    GET https://sandbox.perfectcompliance.com/v1/managements

    Response Example

    {
        "searchResult": [
            {   "userId": 34434,
                "group": [
                    27546,
                    894,
                    "custom 10"
                ],
                "id": 1206
            },
            {   "userId": 34434,
                "group": [
                   27550
                ],
                "id": 560
            },
            {
                "userId": 34434,
                "group": [
                    27549
                ],
                "id": 559
            },
            {
                "userId": 34434,
                "group": [
                    27548
                ],
                "id": 558
            },
            {
                "userId": 34434,
                "group": [
                    27547
                ],
                "id": 557
            }
        ]
    }

    Single Record Request Example

    GET https://sandbox.perfectcompliance.com/v1/managements/<management_id>

    Single Record Response Example

    {
        "userId": 34434,
        "group": [
            27546,
            894,
            "custom 10"
        ],
        "id": 1206
    }

    Additional Examples

    Request:
    GET https://sandbox.perfectcompliance.com/v1/managements?root=true
    
    Response:
    {
        "userId": 34433,
        "group": [
        ],
        "id": 1563
    }
    
    
    Request:
    GET https://sandbox.perfectcompliance.com/v1/managements?group=<level_1_id>
    
    Response:
    {
        "userId": 34434,
        "group": [
            27547
        ],
        "id": 557
    }
    
    
    Request:
    GET https://sandbox.perfectcompliance.com/v1/managements?group=<level_1_id>?group=<level_2_id>
    
    Response:
    {
        "userId": 34434,
        "group": [
            27546,
            894,
        ],
        "id": 1206
    }
    
    
    Request:
    GET https://sandbox.perfectcompliance.com/v1/managements?userId=<userId>
    
    Response:
    {
        "userId": 34434,
        "group": [
            27546,
            894, 
            "custom 10"
        ],
        "id": 1206
    },
    {
        "userId": 34434,
        "group": [
            27550
        ],
        "id": 560
    },
    {
        "userId": 34434,
        "group": [
            27549
        ],
        "id": 559
    },
    {
        "userId": 34434,
        "group": [
            27548
        ],
        "id": 558
    },
    {
        "userId": 34434,
        "group": [
            27547
        ],
        "id": 557
    }
    
    
    Request:
    GET https://sandbox.perfectcompliance.com/v1/managements?userId=<userId>&group=<level_1_id>
    
    Response:
    {
        "userId": 34434,
        "group": [
            27547
        ],
        "id": 557
    }