> ## Documentation Index
> Fetch the complete documentation index at: https://developers.partoo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# User Provisioning with Partoo API

> Learn how to integrate the Partoo User API to automatically manage user lifecycles create, update, and delete accounts based on your source-of-truth system.

## 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](/guides/api/resources/user/user) — 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.

<Info>
  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.
</Info>

## User lifecycle

Here is the user lifecycle we expect:

| Stage         | Trigger                                | Action             | API Route                                                    |
| ------------- | -------------------------------------- | ------------------ | ------------------------------------------------------------ |
| 👋 **Joiner** | New hire appears in HR/IdP system      | Provision account  | [`POST /user`](/api-reference/users/create-user)             |
| 🔄 **Mover**  | Role, team, or scope change            | Update permissions | [`POST /user/{user_id}`](/api-reference/users/update-user)   |
| 🚪 **Leaver** | Departure or access no longer required | Revoke access      | [`DELETE /user/{user_id}`](/api-reference/users/delete-user) |

<Check>
  Automated calls keep Partoo perfectly aligned with your source-of-truth at every step.
</Check>

## 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

<Warning>
  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.
</Warning>

* `GROUP_MANAGER` → populate the `accesses` array with the **IDs of groups** they must have. Example:

```json theme={null}
"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:

```json theme={null}
"business_ids": ["5409c35a97bbc544d8e26737", "5409c35a97bbc544d8e26738"]
```

#### Password setup and user status.

<Tabs>
  <Tab title="Let them choose">
    * Omit `password`
    * Set `send_invitation: true`

      Result : status **invited** → email sent to create a password → becomes **active** after password setup
  </Tab>

  <Tab title="You choose">
    * Provide a password (e.g., `"TempPwd#2025"`)
    * Omit `send_invitation`

      Result : status **active** immediately
  </Tab>

  <Tab title="Invite later">
    * Set `status: "invited"`
    * Omit password and `send_invitation`
    * Call [**Invite User**](/api-reference/users/invite-user) endpoint later
  </Tab>
</Tabs>

#### 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

<Warning>
  If the user attempts SSO before their Partoo record exists, login fails. Provision the user first.
</Warning>

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

Use to adjust roles, group/business scope, sidebar visibility, or to toggle `sso_only`.

<Info>
  Every account has two identifiers:

  * `email` (mutable)
  * `user_id` (immutable, required for update/delete)
</Info>

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`).

<Check>
  A successful update returns the full user object with refreshed permissions in real time.
</Check>

### 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"`

<Warning>
  Deletion is irreversible. To reinstate access, create a brand-new user.
</Warning>

## 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

<div align="center">
  ```mermaid theme={null}
  flowchart TB
    %% ─────────────
    %% STYLE
    %% ─────────────
    classDef joiner fill:#E8FEE8,stroke:#2ECC40,stroke-width:2px,color:#064F1C;
    classDef system fill:#F4F4F4,stroke:#979797,stroke-dasharray:4 2,color:#333;

    %% ─────────────
    %% NODES
    %% ─────────────
    A["🗄️ Source-of-truth<br/>(new hire)"]:::system
    B["POST /users<br/>"]:::joiner
    C{"Sending <br/> an invitation ?"}:::joiner
    D["📧 User receives invite"]:::joiner
    E["🔑 User sets password"]:::joiner
    F["✅ Account status: active"]:::joiner
    G["You set <code style="color:blue">password</code> "]:::joiner
    H["You set <br><code style="color:blue">send_invite:true</code> "]:::joiner
    
    %% ─────────────
    %% EDGES
    %% ─────────────
    A --> B
    B --> C
    C -- "Yes" --> H --> D --> E --> F
    C -- "No" --> G --> F
  ```
</div>

### 🔄 Mover — Update

```mermaid theme={null}
flowchart LR
  %% ─────────────
  %% STYLE
  %% ─────────────
  classDef mover  fill:#E8F5FE,stroke:#1E90FF,stroke-width:2px,color:#0B3A63;
  classDef system fill:#F4F4F4,stroke:#979797,stroke-dasharray:4 2,color:#333;

  %% ─────────────
  %% NODES
  %% ─────────────
  G["🗄️ Source-of-truth<br/>(role/team change)"]:::system
  H["POST /users/{user_id}"]:::mover
  I["⚡ Permissions updated"]:::mover

  %% ─────────────
  %% EDGES
  %% ─────────────
  G --> H --> I
```

### 🚪 Leaver — Delete

```mermaid theme={null}
flowchart LR
  %% ─────────────
  %% STYLE
  %% ─────────────
  classDef leaver fill:#FFEDEE,stroke:#FF4136,stroke-width:2px,color:#66060B;
  classDef system fill:#F4F4F4,stroke:#979797,stroke-dasharray:4 2,color:#333;

  %% ─────────────
  %% NODES
  %% ─────────────
  J["🗄️ Source-of-truth<br/>(departure)"]:::system
  K["DELETE /users/{user_id}"]:::leaver
  L["🚫 Access revoked"]:::leaver
  A["POST /users/{user_id}"]:::leaver

  %% ─────────────
  %% EDGES
  %% ─────────────
  J --> K --> L
  J --> A -- <code>disabled:true</code> --> L
```

## 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**