Organization

The organization structure is part of the always-on platform core. Everything supports externalId, so an HR system or POS integration can sync its store, region and department IDs with PUT …/external/{externalId}.

With a reach narrower than Everyone, organization.manage only lets someone edit and archive their own locations' profiles. See Organization & locations.

Webhook events: org_unit.created, org_unit.updated, org_unit.archived, location.created, location.updated, location.archived, department.created, department.updated, department.archived.

All paths are relative to /api/v1. Key is the scope an integration key needs, People the permission a signed-in person or personal key needs, and Feature the feature switch the endpoint belongs to. See how to read this reference.

• GET/org-units

  List org units (regions, districts…); parentId filters

  Keyorganization:read

  Peopleanyone
• POST/org-units

  Create an org unit

  Keyorganization:write

  Peopleorganization.manage (Everyone)
• GET/org-units/{id}

  Get an org unit

  Keyorganization:read

  Peopleanyone
• PATCH/org-units/{id}

  Update an org unit (e.g. move it under another parent)

  Keyorganization:write

  Peopleorganization.manage (Everyone)
• DELETE/org-units/{id}

  Archive an org unit (only once it contains no active units or locations)

  Keyorganization:write

  Peopleorganization.manage (Everyone)
• GET/org-units/external/{externalId}

  Get an org unit by external ID

  Keyorganization:read

  Peopleanyone
• PUT/org-units/external/{externalId}

  Create or replace an org unit by external ID

  Keyorganization:write

  Peopleorganization.manage (Everyone)
• GET/locations

  List locations; orgUnitId, status and includeArchived filter

  Keyorganization:read

  Peopleanyone
• POST/locations

  Create a location

  Keyorganization:write

  Peopleorganization.manage (Everyone)
• GET/locations/{id}

  Get a location

  Keyorganization:read

  Peopleanyone
• PATCH/locations/{id}

  Update a location's profile

  Keyorganization:write

  Peopleorganization.manage
• DELETE/locations/{id}

  Archive (close) a location; history is kept

  Keyorganization:write

  Peopleorganization.manage
• GET/locations/external/{externalId}

  Get a location by external ID

  Keyorganization:read

  Peopleanyone
• PUT/locations/external/{externalId}

  Create or replace a location by external ID

  Keyorganization:write

  Peopleorganization.manage (Everyone)
• GET/departments

  List departments

  Keyorganization:read

  Peopleanyone
• POST/departments

  Create a department

  Keyorganization:write

  Peopleorganization.manage (Everyone)
• GET/departments/{id}

  Get a department

  Keyorganization:read

  Peopleanyone
• PATCH/departments/{id}

  Update a department

  Keyorganization:write

  Peopleorganization.manage (Everyone)
• DELETE/departments/{id}

  Archive a department

  Keyorganization:write

  Peopleorganization.manage (Everyone)
• GET/departments/external/{externalId}

  Get a department by external ID

  Keyorganization:read

  Peopleanyone
• PUT/departments/external/{externalId}

  Create or replace a department by external ID

  Keyorganization:write

  Peopleorganization.manage (Everyone)
• GET/roles

  List roles and their permissions

  Keyorganization:read

  Peopleusers.read
• GET/roles/{id}

  Get a role

  Keyorganization:read

  Peopleusers.read
• GET/users

  List user accounts with their role and assignments

  Keyorganization:read

  Peopleusers.read
• GET/users/{id}

  Get a user

  Keyorganization:read

  Peopleusers.read