REST API for Organization

Updated by Leigh Hutchens

You can manage an organisation via REST API.

Organisation API

We have implemented a basic REST api for managing your organisation. The API's is relying on Quinyx internal id:s and a separate api for requesting the internal Id based on customer specific external id's will be implemented.

The general name for a organisational entity is Group and currently it can be set to different types: District, Unit or Section.

There is a fourth type: Domain that is reserved for the top level of the organisation and can only be added when the customer is created.

The creation of the different group types will allow for/require different input parameters

Api-docs for rc : https://api-rc.quinyx.com/v2/docs

Api-docs : https://api.quinyx.com/v2/docs

  • As a user of the customer-facing REST API, I want to be able to handle an organization the same way I do through the GUI. This means I can:
    • Create, read, update, and delete a group so that I, through the API, can handle creation and changes in my organization.
    • Retrieve all child groups belonging to a specific group *
    • Retrieve all groups if a specific type (all units on the customer, all sections belonging to the customer)
    • Be able to update a group defined as a unit to be a child group to a district and "above" so that if a unit changes district or district manager
*A group in this case is defined as a District, Unit, or Section with the current "mapping to Classic.

Access rights

To be able to send requests to the apis you need to add access rights for Groups on your integration credentials in account settings:

Get group/:groupid

This endpoint will return the details of a specific group.

Groupid is the internal id in Quinyx. The internal Id's is retrieved via Quinyx Mapping API (Add link to mapping doc).

The response object will contain some general attributes but also specific objects depending on the type of group that is returned.

For details, see our swagger documentation

Type: Domain

This is the top level group and hence it does not return parentGroupID

{
  "id": 0,
  "name": "string",
  "groupType": "domain",
  "parentGroupId": 0
}
Type: District
districtAttributesDto": {
    "managerId": 0
  }
Type: Unit
"unitAttributesDto": {
    "address": {
      "country": "string",
      "address": "string",
      "zipCode": "string",
      "city": "string",
      "municipality": "string",
      "timeZone": "string"
    },
    "costCentre": 0,
    "managerId": 0,
    "currency": "string",
    "publishedTo": "2023-10-13",
    "blockPasswordLogin": true,
    "shiftRules": {
      "maxHoursPerDay": 0,
      "maxHoursPerWeek": 0,
      "minRest": 0,
      "numberOfBreaks": 0
    },
    "shiftRulesDto": {
      "maxHoursPerDay": 0,
      "maxHoursPerWeek": 0,
      "minRest": 0,
      "numberOfBreaks": 0
    }
  }
Type: Section
"sectionAttributesDto": {
    "managerGroupId": 0,
    "costCentre": 0,
    "managerId": 0
  }

POST group/

To create a new group in the organisation tree you call POST on the Group -endpoint. Depending on what type of group you would like to create you send different parameter setts in the request body: districtAttributesDto, unitAttributesDto or sectionAttributesDto.

{
  "name": "string",
  "groupType": "string",
  "parentGroupId": 0,
  "districtAttributesDto": {
    "managerId": 0
  },
  "sectionAttributesDto": {
    "managerGroupId": 0,
    "costCentre": 0,
    "managerId": 0
  },
  "unitAttributesDto": {
    "address": {
      "country": "string",
      "address": "string",
      "zipCode": "string",
      "city": "string",
      "municipality": "string",
      "timeZone": "string"
    },
    "costCentre": 0,
    "managerId": 0,
    "currency": "string",
    "publishedTo": "2023-10-13",
    "blockPasswordLogin": true,
    "shiftRules": {
      "maxHoursPerDay": 0,
      "maxHoursPerWeek": 0,
      "minRest": 0,
      "numberOfBreaks": 0
    },
    "shiftRulesDto": {
      "maxHoursPerDay": 0,
      "maxHoursPerWeek": 0,
      "minRest": 0,
      "numberOfBreaks": 0
    }
  }
}

PUT /groups/{groupId}

To update a group the same rules about group type apply and the api expects different group type data objects depending on the type updated.

See post for data object structure per group type above.

DELETE /groups/{groupId}

Delete the group with the specified groupId

GET /groups/{groupId}/children

Get children groups related to a given groupId. The endpoint supports pagination and sorting.

Pagination & Sorting

Use the pageable object to specify the settings for pagination: Add following parameters to the call :

?page=0&size=10&sort=name

The Response
{
        "content": [
            {
                "id": 236610,
                "name": "Product Communication",
                "groupType": "section",
                "parentGroupId": 170306
            },
            {
                "id": 195226,
                "name": "Product Design",
                "groupType": "section",
                "parentGroupId": 170306
            },
            {
                "id": 195225,
                "name": "Product Leaders",
                "groupType": "section",
                "parentGroupId": 170306
            },
            {
                "id": 195224,
                "name": "Product Owners",
                "groupType": "section",
                "parentGroupId": 170306
            }
        ],
        "pageable": {
            "sort": {
                "empty": false,
                "unsorted": false,
                "sorted": true
            },
            "offset": 0,
            "pageNumber": 0,
            "pageSize": 20,
            "paged": true,
            "unpaged": false
        },
        "totalElements": 4,
        "totalPages": 1,
        "last": true,
        "size": 20,
        "number": 0,
        "sort": {
            "empty": false,
            "unsorted": false,
            "sorted": true
        },
        "numberOfElements": 4,
        "first": true,
        "empty": false
    }

How Did We Do?