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

# Sintropix Organizations API: Group Entities for Access

> Create, rename, list, and delete Organizations, the groups of Entities that Organization Memberships grant access to, and list each Organization's members.

An Organization groups the Entities that a client runs as one business. Every Entity belongs to exactly one Organization. Users reach Entities through an Organization Membership, which carries one Role and covers every Entity of the Organization, including Entities added later. See [Access and roles](/api-reference/overview#access-and-roles) for what each Role allows.

Use this page to manage Organizations themselves. To grant, change, or revoke a User's Membership, use the [Onboarding API](/api-reference/onboarding). To move an Entity to another Organization, use [`PATCH /api/entities/:entityId/organization`](/api-reference/entities).

<Warning>
  Every route below except `GET /organizations` is restricted to Users with the global `role = staff`. Any other caller receives `403`.
</Warning>

## GET `/organizations`

List the Organizations you can create Entities in, each with the Entities it holds. Use it to pick the `organizationId` for [`POST /api/entities`](/api-reference/entities).

* Global `staff` Users see every Organization.
* Other Users see the Organizations where they hold the `staff` Role.
* An API key confined to one Entity receives an empty array.

**Response** `200`: an array of Organization summaries.

| Field      | Type   | Description                                       |
| ---------- | ------ | ------------------------------------------------- |
| `id`       | UUID   | Organization id                                   |
| `name`     | string | Organization name                                 |
| `entities` | array  | `{ id, name }` of each Entity in the Organization |

```bash theme={"system"}
curl https://api.sintropix.com/api/organizations \
  -H "x-api-key: $SINTROPIX_API_KEY"
```

```json theme={"system"}
[
  {
    "id": "7c1e4b2a-3d5f-4a6b-8c9d-0e1f2a3b4c5d",
    "name": "Grupo Acme",
    "entities": [
      { "id": "11111111-1111-4111-8111-111111111111", "name": "Acme SpA" },
      { "id": "22222222-2222-4222-8222-222222222222", "name": "Acme Inversiones SpA" }
    ]
  }
]
```

## POST `/organizations`

Create an empty Organization. Add Entities to it by creating them with its `organizationId` or by moving existing Entities into it.

**Body**

| Field  | Type   | Required | Description                                                                                                                              |
| ------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | Yes      | 1 to 200 characters after trimming surrounding whitespace. Must contain a visible character. Unique across Organizations, ignoring case. |

**Response** `201`

| Field       | Type         | Description                |
| ----------- | ------------ | -------------------------- |
| `id`        | UUID         | Organization id            |
| `name`      | string       | Organization name, trimmed |
| `createdAt` | ISO datetime | Creation timestamp         |

```bash theme={"system"}
curl -X POST https://api.sintropix.com/api/organizations \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SINTROPIX_STAFF_API_KEY" \
  -H "x-audit-actor: my-agent" \
  -H "x-audit-reason: New client group" \
  -d '{"name": "Grupo Acme"}'
```

```json theme={"system"}
{
  "id": "7c1e4b2a-3d5f-4a6b-8c9d-0e1f2a3b4c5d",
  "name": "Grupo Acme",
  "createdAt": "2026-09-26T12:00:00.000Z"
}
```

A name that another Organization already uses, in any case, returns `409` with `ORGANIZATION_NAME_ALREADY_EXISTS_ERROR`.

## GET `/organizations/:organizationId`

Get one Organization with the Entities it holds. The response has the same shape as one item of `GET /organizations`.

```bash theme={"system"}
curl https://api.sintropix.com/api/organizations/$ORGANIZATION_ID \
  -H "x-api-key: $SINTROPIX_STAFF_API_KEY"
```

## PATCH `/organizations/:organizationId`

Rename an Organization. The body and validation rules match `POST /organizations`.

**Response** `200`: the renamed Organization (`id`, `name`, `createdAt`).

```bash theme={"system"}
curl -X PATCH https://api.sintropix.com/api/organizations/$ORGANIZATION_ID \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SINTROPIX_STAFF_API_KEY" \
  -H "x-audit-actor: my-agent" \
  -H "x-audit-reason: Client renamed its group" \
  -d '{"name": "Grupo Acme Holding"}'
```

## DELETE `/organizations/:organizationId`

Delete an empty Organization. Deleting an Organization also removes every Membership in it.

An Organization that still holds an Entity can't be deleted. The request returns `409` with `ORGANIZATION_NOT_EMPTY_ERROR`. Move its Entities to another Organization first.

* **Status:** `204`.

```bash theme={"system"}
curl -X DELETE https://api.sintropix.com/api/organizations/$ORGANIZATION_ID \
  -H "x-api-key: $SINTROPIX_STAFF_API_KEY" \
  -H "x-audit-actor: my-agent" \
  -H "x-audit-reason: Duplicate group"
```

## GET `/organizations/:organizationId/members`

List the Users who hold a Membership in the Organization.

**Response** `200`: an array of members.

| Field    | Type   | Description                    |
| -------- | ------ | ------------------------------ |
| `userId` | UUID   | The member's User id           |
| `name`   | string | The member's display name      |
| `email`  | string | The member's email             |
| `role`   | enum   | `staff`, `client`, or `viewer` |

```bash theme={"system"}
curl https://api.sintropix.com/api/organizations/$ORGANIZATION_ID/members \
  -H "x-api-key: $SINTROPIX_STAFF_API_KEY"
```

```json theme={"system"}
[
  {
    "userId": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
    "name": "Ana Perez",
    "email": "ana.perez@example.com",
    "role": "client"
  }
]
```

## Domain error codes

| Code                                     | Status | Meaning                                                     |
| ---------------------------------------- | ------ | ----------------------------------------------------------- |
| `ORGANIZATION_NOT_FOUND_ERROR`           | `404`  | No Organization has this id.                                |
| `ORGANIZATION_NAME_ALREADY_EXISTS_ERROR` | `409`  | Another Organization already uses this name, ignoring case. |
| `ORGANIZATION_NOT_EMPTY_ERROR`           | `409`  | The Organization still holds at least one Entity.           |

## Status codes

| Status | Meaning                                                                                           |
| ------ | ------------------------------------------------------------------------------------------------- |
| `200`  | Success on `GET` and `PATCH`.                                                                     |
| `201`  | Organization created.                                                                             |
| `204`  | Success on `DELETE`.                                                                              |
| `400`  | Validation error, including a blank or too-long name, or an `:organizationId` that is not a UUID. |
| `403`  | Caller is not global `staff`.                                                                     |
| `404`  | Organization not found.                                                                           |
| `409`  | Duplicate name, or the Organization still holds an Entity.                                        |