Hierarchy API - Technical implementation guide

This technical guide describes a proposed technical implementation for synchronizing an external organization hierarchy to Webcruiter. This workflow supports:

Creating organization nodes
Updating organization nodes properties such as name, primary address, and public organization number
Moving organization nodes within the hierarchy
Deactivating and activating organization nodes

Questions & Answers

What Id:s should be used in the Hierarchy endpoints?

The Id:s the Hierarchy API is operating on are the integrating partners hierarchy/organization node id:s. Within Webcruiter these id:s are referred to as the external Id of a hierarchy/organization node.

There is one exception. The endpoint PUT /hierarchy/mapping/{webcruiterId} is a utility endpoint that can be used to set the integrating partners hierarchy/organization node id for a node that is missing Id. Nodes created manually in Webcruiter Admin UI may be missing the external id.

What if we already have an Organization Hierarchy setup in Webcruiter?

For customers/partners that want to use the hierarchy API it is important that all their nodes have an external id. It is the external id that the API is operating on and in the API endpoint docs the parameter is simply called id .

The external id can either be set in the Webcruiter Admin UI or it can be assigned by using the following utility endpoints:

GET /hierarchy/mapping for fetching a flat list with all hierarchy/organization node

PUT /hierarchy/mapping/{webcruiterId} for assigning the (customer/external) id to a node

When `/v1/hierarchy/{id}/active` endpoint should be used?

The /v1/hierarchy/{id}/active endpoint is used for soft deletion when corresponding hierarchy node on a customers/partners side is deleted. For deactivation, hierarchy node needs to have no children nodes, no active recruitment processes and no active users.

Complete API Docs

All available endpoints are documented on our developer portal at