Model your organization's hierarchy of sites, groups, and custom structure types, and manage who belongs to each.
Structures are the single model for your organization's hierarchy. A structure is any node you assign people to: a site, a group, or a type you define yourself. Every structure supports the same operations: create it, place it in a hierarchy, describe it with fields, and assign members to it.
Use these endpoints to provision your hierarchy from an external system of record, keep site and group membership in step with an HR platform, or read the hierarchy back to drive reporting.
Before you start
Sub-domains
| Sub-domain | What it covers |
|---|---|
| Structures | Create, read, replace, move, and search structures. |
Key concepts
Structure: A single node, such as one site or one group. Every structure has a name, a structure type, and an optional parent. Structures whose type supports hierarchy form a tree, and a structure's ancestors are returned ordered from the root down to its direct parent.
Structure type: The kind of node a structure is. Two types are built in and exist in every organization, which are SYSTEM_STRUCTURE_TYPE_SITE and SYSTEM_STRUCTURE_TYPE_GROUP. Your organization can define others. Endpoints that create or search structures identify a type either by one of these built-in values or by the type's UUID.
Field: A reusable attribute definition owned by the organization, such as "Region" or "Opening date". A field is created once, then mapped to the structure types it applies to. That mapping controls whether the field is required for a type and whether it displays on that type's profile. Find your organization's fields with the List fields endpoint, and set their values on a structure through the create and replace structure endpoints. Defining and editing fields is done in the web app, not through the API.
Field value: One field's value on one structure. The value is typed, and the field's type determines which value key is valid. A timestamp field accepts timestamp_value, a select field accepts the ID of one of its options, and so on. Reading a structure returns only the field values whose field is configured to display on profiles for that structure's type.
Membership and roles: A user is a member of a structure either directly, because they were assigned to it, or by inheritance from an ancestor structure. Every direct membership carries a role, which determines what the user can do within that structure. The membership endpoints operate on direct memberships only. Removing a user from a structure does not remove a membership they inherit from an ancestor.
Object relationships
| Object | Relates to |
|---|---|
| Structure type | The structures of that type, and the fields mapped to it |
| Structure | Its type, its parent and ancestors, its field values, and its memberships |
| Field | The structure types it is mapped to, and its values on structures |
| Field value | One field, on one structure |
| Membership | One user, one structure, and one role |
Ordering your calls
Creating a structure with field values takes two calls because field values are set by ID.
- Call the List fields endpoint to resolve the IDs of the fields you want to set, filtering by the structure type they apply to with
filter.applies_to. - Call the Create a structure endpoint, passing those IDs in
fields.
Adding members takes one further call to the Add users to a structure endpoint. Members are created with the default role for the structure's type. Changing a member's role is only available in the web app.
Replacing a structure is a full replacement, not a partial update. It clears any field value you do not send and an omitted description. Read the structure first and send its complete field set back.
Partial success
The Add users to a structure endpoint reports failures per assignment rather than the whole request. A response that created some memberships and rejected others is still a 200.
The memberships that were created are in structure_memberships and each rejected assignment appears in errors with a status code and a reason. Always inspect the errors. An empty array is the only signal that every assignment succeeded.
Migrate from the sites and groups APIs
Structures supersede the separate sites and groups models.
- Sites were managed through the folder endpoints in the Sites section. A site is now a structure whose type is
SYSTEM_STRUCTURE_TYPE_SITE. - Groups were managed through the endpoints in the Groups section. A group is now a structure whose type is
SYSTEM_STRUCTURE_TYPE_GROUP.
The legacy endpoints continue to work and operate on the same underlying data, so you can migrate one integration at a time. Use the Structures endpoints for new work. These are the only ones that expose custom fields, custom structure types, and roles on membership.
Structure IDs are UUIDs. If you are migrating an integration that stored legacy site or group identifiers, resolve them to structures before switching over.