Skip to main content

​
Overview

A user is any individual who can sign in to your organization’s Partoo account.
This guide explains how to configure the Partoo User API so every change in your source-of-truth database; new hires 👋, role changes 🔄, or departures 🚪 automatically syncs to Partoo.

​
Prerequisites

  • Partoo API key with permission to manage users.
  • User data prepared in your system (email, role, group/business assignments).
  • Familiarity with the Partoo User API reference — Create, Update, Delete endpoints.

​
Define your integration scope

The right approach depends on your company size and employee turnover:
  • High-change environments
    Automate the full lifecycle: create, update, and delete. This ensures permissions are always up to date.
  • Low-change environments
    Automate only critical routes (e.g., create and delete) and handle rare updates manually.
There is no mandatory minimum: implement the full set or just a subset.
The choice depends on your organization’s risk tolerance and operational overhead.

​
User lifecycle

Here is the user lifecycle we expect:
StageTriggerActionAPI Route
👋 JoinerNew hire appears in HR/IdP systemProvision accountPOST /user
🔄 MoverRole, team, or scope changeUpdate permissionsPOST /user/{user_id}
🚪 LeaverDeparture or access no longer requiredRevoke accessDELETE /user/{user_id}
Automated calls keep Partoo perfectly aligned with your source-of-truth at every step.

​
Joiner, Mover, Leaver — API specification

This section consolidates all requirements for create, update, and delete routes in a single reference.

​
1. Create — POST /users (Joiner)

​
Define access

You can skip this section if every user in your organization is an ORG_ADMIN.
Admins automatically receive full access to all features, establishments, and groups.
The details that follow apply only to GROUP_MANAGER (GM) and BUSINESS_MANAGER (BM) roles.
  • GROUP_MANAGER → populate the accesses array with the IDs of groups they must have. Example:
"accesses": [
  ["1", "2"],   // businesses present in BOTH group 1 AND group 2
  ["3"]         // PLUS every business from group 3
]
  • BUSINESS_MANAGER → populate the business_ids array with the IDs of the businesses they oversee. Example:
"business_ids": ["5409c35a97bbc544d8e26737", "5409c35a97bbc544d8e26738"]

​
Password setup and user status.

  • Let them choose
  • You choose
  • Invite later
  • Omit password
  • Set send_invitation: true Result : status invited → email sent to create a password → becomes active after password setup

​
SSO-only users

Use when your organization already has Single Sign-On (SSO) configured:
  • Send sso_only: true in payload
  • Login flow:
    1. User clicks Sign in with your enterprise
    2. Enters email
    3. Redirects to your Identity Provider (IdP)
    4. No Partoo password accepted
If the user attempts SSO before their Partoo record exists, login fails. Provision the user first.

​
2. Update — POST /users/{user_id} (Mover & Joiner corrections)

Use to adjust roles, group/business scope, sidebar visibility, or to toggle sso_only.
Every account has two identifiers:
  • email (mutable)
  • user_id (immutable, required for update/delete)
Options to obtain user_id:
  1. Store it at creation time.
  2. Lookup later via GET /user/search.
    • Supports exact or fuzzy match.
    • URL-encode special characters in the query string (e.g., + → %2B).
A successful update returns the full user object with refreshed permissions in real time.

​
3. Delete — DELETE /users/{user_id} (Leaver)

  • Permanently removes the user record.
  • Possibility to just disable the user, via the update route with "disabled":"true"
Deletion is irreversible. To reinstate access, create a brand-new user.

​
End-to-End account activation flow

The diagram below visualizes the complete journey from employee creation in your source-of-truth to account activation (including mover and leaver events).

​
👋 Joiner — Create

​
🔄 Mover — Update

​
🚪 Leaver — Delete

​
Next steps

  • Decide if you’ll automate create → update → delete or a subset
  • Choose a strategy for handling user_id (store vs. lookup)
  • Validate your integration in the Sandbox environment