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

# Org structure and branches over the API

> The org tree, branches and who sits where — the surfaces the OrgStructure and Branches pages manage. Reads take org:view, shaping the tree and branches takes

The org tree, branches and who sits where — the surfaces the OrgStructure and
Branches pages manage. Reads take `org:view`, shaping the tree and branches takes
`org:configure`, placing users on nodes takes `org:assign`.

| Call                                                             | What it does                                                                    |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `GET /v1/org-nodes`                                              | The whole tree as a flat list with `parent_id` links (`?node_type=` to filter). |
| `GET /v1/org-nodes/{id}`                                         | One node with `children` ids and `members`.                                     |
| `POST /v1/org-nodes`                                             | Create (`name`, `node_type`, optional `parent_id`, `branch_id`, `team_id`).     |
| `PATCH /v1/org-nodes/{id}`                                       | Rename, re-parent, change type or links.                                        |
| `DELETE /v1/org-nodes/{id}?cascade=true`                         | Delete; a node with children needs the explicit cascade.                        |
| `GET /v1/org-nodes/{id}/members`                                 | Users placed on the node with their `visibility_scope`.                         |
| `PUT /v1/org-nodes/{id}/members/{user_id}`                       | Place a user (or change their scope: `full` / `own`).                           |
| `DELETE /v1/org-nodes/{id}/members/{user_id}`                    | Remove the placement.                                                           |
| `GET /v1/branches`, `POST`, `GET/PATCH/DELETE /v1/branches/{id}` | Branch CRUD (`name`, `address`, `phone`).                                       |

## The tree

Node types and the ladder they hang on: `region` → `country` → `branch` → `team`
→ `agent`. A branch may hang directly under a region, an agent under anything, and
any node may be a root. A `branch` node can be linked to a branch record
(`branch_id`, one node per branch) and a `team` node to a team (`team_id`).

Re-parenting is checked for cycles (`409 CONFLICT`, `details.reason: cycle`) and
re-validated against the ladder. Deleting a node with children is refused
(`409 CONFLICT`, `details.reason: has_children`) unless you pass `cascade=true`;
the response then lists every `deleted_ids` entry, since the database takes the
whole subtree and its memberships in one go.

## Placement is reach

A membership (`PUT …/members/{user_id}`) is how a user gets `team` or `branch`
reach in the visibility engine: with `visibility_scope: full` they see the whole
subtree under that node, with `own` only their own records there. The same rules
narrow an API key's reads to what its owner may see, so moving a subtree or a
member changes what both the UI and the API return for them. Role-level reach per
module is read from [`GET /v1/visibility-scopes`](/api-reference/access-control).

A user's `branch_id` (set on `POST`/`PATCH /v1/users`) is the branch they *work
in*; an org-node membership is where they sit in the *tree*. Both matter: the
branch on a record is matched against the user's accessible branches, and the
record's `org_node_id` against their subtree.

## Branches

Deleting a branch is refused while anything still references it: the response
carries `details.reason: in_use` and `details.references` with counts of users,
org nodes, teams, leads, deals and accounts. Reassign or remove those first.

Every write records an `auditlog` row naming the API key that acted.