Background

Calven synchronizes with your directory via the SCIM protocol to keep information immediately up to date. While provisioning groups via user attributes is preferred (allowing Calven to automatically infer hierarchy), this API endpoint is required for organizations with matrix structures or users in multiple groups within the same level.

This endpoint allows you to explicitly define parent-child group relationships that cannot be inferred from user attributes alone.

Note: This endpoint expects a complete payload. Every successful PUT request will fully replace the existing hierarchy information in Calven.

Authentication

This API supports both Basic Auth and HMAC authentication. You must use the method that corresponds to how your API key is configured.

Ensure your endpoint path matches your auth type (e.g., /basic for Basic Auth).

Request Body Schema

The request payload must be sent as application/json and contain a single groupRelationships array.

Field	Type	Required	Description
`groupRelationships`	`array`	Yes	An array of objects defining the group structure.
`group`	`string`	Yes	The name of the child group (e.g., "Channel Marketing").
`groupType`	`string`	Yes	The attribute or category name for the group (e.g., "Department").
`parent`	`string`	`null`	Yes
`parentType`	`string`	`null`	Yes

Example group relationship information:

{
    "group": "Channel Marketing",
    "groupType": "Department",
    "parent": "Marketing",
    "parentType": "Division"
}

Validation Rules

To ensure successful processing, your payload must adhere to the following rules:

No Circular References: Group A cannot be the parent of Group B if Group B is the parent of Group A.

Single Parent Limit: One group cannot have multiple parent references.

Null Top Levels: Top-level groups must send null for both parent and parentType.

Process

Because this API fully replaces the previous state, you can send this data as often as required. When the next directory management report runs in Calven, the hierarchy information provided by your most recent API call will be utilized to structure the group relationships.

Org Hierarchy Information Overview

Background#

Authentication#

Request Body Schema#

Example group relationship information:#