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

# Groups

> Create, update, retrieve, and delete groups/departments.

<Tabs>
  <Tab title="v2">
    ## What is the Groups API?

    The **Groups API** allows you to manage user-defined groups within your organization. These groups can represent teams, departments, or any custom segmentation of users, and are useful for assigning policies, budgets, or approval rules.

    This API enables you to:

    * Create and update groups
    * Retrieve details of individual or all groups
    * Delete groups when no longer needed

    <br />

    ## Available Endpoints

    | Operation            | Endpoint            | Method |
    | :------------------- | :------------------ | :----- |
    | Retrieve all groups  | `/v2/groups`        | GET    |
    | Retrieve group by ID | `/v2/groups/{uuid}` | GET    |
    | Create group         | `/v2/groups`        | POST   |
    | Update group         | `/v2/groups/{uuid}` | PATCH  |
    | Delete group         | `/v2/groups/{uuid}` | DELETE |

    <br />

    ## Retrieve All Groups

    List all groups defined in your organization.

    ### Endpoint

    `GET /v2/groups`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X GET \
    "https://public-api.mx.clara.com/api/v2/groups" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```

    ### Sample JSON Response

    ```json JSON theme={null}
    [
      {
        "uuid": "group-123",
        "name": "Finance",
        "description": "Handles all financial operations",
        "status": "ACTIVE"
      },
      {
        "uuid": "group-456",
        "name": "Engineering",
        "description": "Software and product development",
        "status": "ACTIVE"
      }
    ]

    ```

    <br />

    ## Retrieve Group by UUID

    Get full details of a specific group by its UUID.

    ### Endpoint

    `GET /v2/groups/{uuid}`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X GET \
    "https://public-api.mx.clara.com/api/v2/groups/group-123" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```

    ### Sample JSON Response

    ```json JSON theme={null}
    {
        "uuid": "group-123",
        "name": "Finance",
        "description": "Handles all financial operations",
        "status": "ACTIVE"
    }

    ```

    <br />

    ## Create a Group

    Create a new user group by specifying a name and optional description.

    ### Endpoint

    `POST /v2/groups`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X POST \
    "https://public-api.mx.clara.com/api/v2/groups" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Operations",
      "description": "Logistics and supply chain team"
    }'
    ```

    ### Sample JSON Response

    ```json JSON theme={null}
    {
      "uuid": "group-789",
      "name": "Operations",
      "description": "Logistics and supply chain team",
      "status": "ACTIVE"
    }

    ```

    <br />

    ## Update a Group

    Edit the name or description of an existing group.

    ### Endpoint

    `PATCH /v2/groups/{uuid}`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X PATCH \
    "https://public-api.mx.clara.com/api/v2/groups/group-789" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Ops",
      "description": "Updated name for Operations team"
    }'
    ```

    <br />

    ## Delete a Group

    Remove a group from your organization by UUID. Use with caution, as this may impact user-role associations or policy rules.

    ### Endpoint

    `DELETE /v2/groups/{uuid}`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X DELETE \
    "https://public-api.mx.clara.com/api/v2/groups/group-789" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```

    <br />

    \*\*💡 Tip: \*\* Groups can be used to assign policies, budgets, or approval flows in a centralized way.

    \*\*⚠️ Note: \*\* Deleting a group does not affect users, but it may disrupt processes tied to that group such as approval chains or spend limits.

    ***

    ## Endpoint Reference

    ### `GET /api/v2/groups`

    Find all groups

    **Parameters:**

    | Parameter | In    | Type    | Required | Description                         |
    | --------- | ----- | ------- | -------- | ----------------------------------- |
    | `page`    | query | integer |          | Zero-based page index (0..N)        |
    | `size`    | query | integer |          | The size of the page to be returned |

    ### `PUT /api/v2/groups`

    Update group details

    ### `POST /api/v2/groups`

    Create Group

    ### `GET /api/v2/groups/{uuid}`

    Find group by UUID

    **Parameters:**

    | Parameter | In   | Type   | Required | Description |
    | --------- | ---- | ------ | -------- | ----------- |
    | `uuid`    | path | string | ✅        | Group UUID  |

    ### `DELETE /api/v2/groups/{uuid}`

    Delete a single group by UUID

    **Parameters:**

    | Parameter | In   | Type   | Required | Description                 |
    | --------- | ---- | ------ | -------- | --------------------------- |
    | `uuid`    | path | string | ✅        | UUID of the group to delete |
  </Tab>

  <Tab title="v1">
    <Warning>v1 is legacy and read-only. Migrate to v2 for full group management.</Warning>

    ## What is the Transactions API?

    The **Groups API v1** allows you to retrieve information about the user groups defined in your Clara account. Groups are typically used to organize users into departments, business units, or approval chains.

    This API can be used to:

    * Display group options when assigning users or policies
    * Link transactions or cards to internal teams
    * Build internal reporting dashboards by group

    🆚 Note: This version of the API is **read-only**. To create, update, or delete groups, use [Groups API v2](#).

    <br />

    ## Available Endpoints

    | Operation          | Endpoint            | Method |
    | ------------------ | ------------------- | ------ |
    | Find all groups    | `/v1/groups`        | GET    |
    | Find group by UUID | `/v1/groups/{uuid}` | GET    |

    <br />

    ## Find all groups

    Use this endpoint to **retrieve the list of all groups** configured in your organization. Each group includes metadata such as name, status, and unique ID.

    ### Endpoint

    `GET /v1/groups`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X GET \
    "https://public-api.mx.clara.com/api/v1/groups" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```

    ### Sample JSON Response

    ```json JSON theme={null}
    [
      {
        "uuid": "group-001",
        "name": "Finance",
        "status": "ACTIVE"
      },
      {
        "uuid": "group-002",
        "name": "Sales",
        "status": "ACTIVE"
      }
    ]
    ```

    <br />

    ## Find group by UUID

    Use this endpoint to fetch details for a specific group by its UUID.

    ### Endpoint

    `GET /v1/groups/{uuid}`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X GET \
    "https://public-api.mx.clara.com/api/v1/groups/group-001" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```

    ### Sample JSON Response

    ```json JSON theme={null}
    {
      "uuid": "group-001",
      "name": "Finance",
      "status": "ACTIVE"
    }
    ```

    <br />

    \*\*💡 Tip: \*\*Use the uuid of a group to associate users, approval flows, or reporting filters with that group.

    \*\*⚠️ Note: \*\*The v1 API does not allow modifying groups — it is read-only and intended for lookup operations.

    ***

    ## Endpoint Reference

    ### `GET /api/v1/groups`

    Find all groups

    **Parameters:**

    | Parameter | In    | Type    | Required | Description                         |
    | --------- | ----- | ------- | -------- | ----------------------------------- |
    | `page`    | query | integer |          | Zero-based page index (0..N)        |
    | `size`    | query | integer |          | The size of the page to be returned |

    ### `GET /api/v1/groups/{uuid}`

    Find group by UUID

    **Parameters:**

    | Parameter | In   | Type   | Required | Description |
    | --------- | ---- | ------ | -------- | ----------- |
    | `uuid`    | path | string | ✅        | Group UUID  |
  </Tab>
</Tabs>