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

# Managing User Permissions with Custom Roles

> Learn about Partoo's Custom Roles feature, how to use it in order to manage permissions, including migration notes from our previous system, and examples of REST API usage.

## What are Custom Roles?

Partoo's Custom Roles feature enables organizations to create granular permission systems that go beyond traditional user roles. This powerful feature allows you to define precisely what features and data each user can access and modify within your organization.

With Custom Roles, you can:

* Create tailored user roles with specific permission sets
* Control access to individual features and data fields
* Assign roles to users through the Partoo app or REST API
* Maintain fine-grained security and access control

### Quick Navigation

* [Breaking Changes](#breaking-changes) - Breaking changes from the legacy system using "Business Fields" and "Sidebar Pages"
* [Before Custom Roles](#before-custom-roles) - Legacy permission system overview
* [Using Custom Roles](#using-the-new-custom-roles-feature) - New system overview
* [Migration Guide](#migration-guide) - How to migrate your organization from the legacy system of permissions to the new Custom Role system
* [REST API Examples](#rest-api-examples) - Practical implementation examples
* [Best Practices](#best-practices) - Security and management recommendations
* [Troubleshooting](#troubleshooting) - Common issues and solutions

## Breaking Changes

For a list of breaking changes, please refer to the [Partoo API Changelog](/changelogs/api/changelogs#20th-october-2025).

## Before Custom Roles

This section describes how things worked before the release of Custom Roles.

### Business Fields

Before Custom Roles, "Business Field" permissions were limited and could only be configured for specific user roles:

* **Business Manager**
* **Group Manager**

These permissions controlled which business data fields users could edit, for example: the "name" or "description" field of a business.

**Inspection Endpoints:**

* Organization-level: `GET /org/{org_id}/business_fields`
* Business-level: `GET /business/{business_id}/business_fields`

<Frame caption="Business Fields Configuration - Here, Business Managers have been restricted from editing any fields in the category 'Main Description' of a business">
  <img src="https://mintcdn.com/partoo/P_Jb4Af_6Al7QkYi/assets/images/guides/api/guides/custom-roles-and-permissions/business_fields.png?fit=max&auto=format&n=P_Jb4Af_6Al7QkYi&q=85&s=95dfbdd968c0a159b62543f941a8c0bb" alt="Business Fields Configuration" width="2720" height="1638" data-path="assets/images/guides/api/guides/custom-roles-and-permissions/business_fields.png" />
</Frame>

### Sidebar Pages

**Sidebar Pages** represent feature-level permissions that control access to entire application sections. These permissions are broader than Business Fields and determine which features users can access.

**Available Sidebar Pages:**

* `DIFFUSION`
* `BULK_MODIFICATION`
* `POSTS`
* `REVIEW_MANAGEMENT`
* `REVIEW_INVITE`
* `MESSAGES`
* `PRESENCE_ANALYTICS`
* `REVIEW_ANALYTICS`
* `FEEDBACK_MANAGEMENT`

<Info>
  If a user lacks access to a Sidebar Page (e.g., `REVIEW_MANAGEMENT`), they
  won't see the corresponding navigation link in the app sidebar, and cannot
  access that feature.
</Info>

**Inspection Endpoint:** `GET /user/{user_id}`

<Frame caption="In the screenshot above, the user John Smith will not have access to any analytics features, since 'Analytics' has been toggled off.">
  <img src="https://mintcdn.com/partoo/P_Jb4Af_6Al7QkYi/assets/images/guides/api/guides/custom-roles-and-permissions/user-edit-sidebar-pages.png?fit=max&auto=format&n=P_Jb4Af_6Al7QkYi&q=85&s=30002d267a18ce74e2c562e100d6928e" alt="User Edit Page - Sidebar Pages Selection" width="2300" height="1540" data-path="assets/images/guides/api/guides/custom-roles-and-permissions/user-edit-sidebar-pages.png" />
</Frame>

## Using the new Custom Roles feature

This section describes how to use the new Custom Roles feature, in order to customize user permissions for your organization.

Custom Roles give you a very fine level of control over user permissions, and because of this, we recommend you to initially use the GUI in the Partoo app to set up your new Custom Roles and permissions.

The GUI offers you an easier way to visualize and manage the sometimes complex permission structures.

### Understanding Permissions

Permissions are the building blocks of Custom Roles, identified by unique names like `business_edit` for editing business data.

Permissions are what give a role its capabilities, and by combining different permissions, you can create roles that fit your organization's needs. Permissions can be anything from allowing you to edit the opening hours of businesses, to managing reviews or accessing analytics data.

<Frame caption="When creating a new Custom Role or editing an existing one, you can assign it various permissions from the categories seen in the screenshot above.">
  <img src="https://mintcdn.com/partoo/P_Jb4Af_6Al7QkYi/assets/images/guides/api/guides/custom-roles-and-permissions/permissions-overview.png?fit=max&auto=format&n=P_Jb4Af_6Al7QkYi&q=85&s=6b924f4d59a3c05819ea73f2a3ac3f9b" alt="Permissions Overview" width="2354" height="1858" data-path="assets/images/guides/api/guides/custom-roles-and-permissions/permissions-overview.png" />
</Frame>

<br />

<Frame caption="Once clicking on a section of permissions, you can see subsection as well as individual permissions, which can be toggled on or off for the Custom Role you are editing.">
  <img src="https://mintcdn.com/partoo/P_Jb4Af_6Al7QkYi/assets/images/guides/api/guides/custom-roles-and-permissions/permissions-detail.png?fit=max&auto=format&n=P_Jb4Af_6Al7QkYi&q=85&s=d42f5a40176ccedc4c244202ac769713" alt="Permissions Detail" width="1244" height="1630" data-path="assets/images/guides/api/guides/custom-roles-and-permissions/permissions-detail.png" />
</Frame>

**Permission Data Fields:**

* **`name`**: Unique identifier for the permission (e.g., `review_reply_positive_reviews`)
* **`disabled_for_roles`**: Array of user roles that cannot access this permission
* **`depends_on`**: Specifies if this permission requires another permission to function
* **Hierarchical Organization**: Permissions are grouped into logical `sections` and `subsections` for easier navigation

**Retrieving Available Permissions:**

Use the [GET `/permissions`](/api-reference/custom-roles/get-permissions) endpoint to discover all permissions available to your organization.

**Example Response:**

```json theme={null}
{
  "sections": [
    {
      "name": "presence",
      "order": 100,
      "subsections": [
        {
          "name": "presence_pages",
          "order": 100,
          "permissions": [
            {
              "name": "business_edit",
              "order": 100,
              "feature": "business_edition",
              "depends_on": null,
              "disabled_for_roles": []
            },
            {
              "name": "business_edit_name",
              "order": 101,
              "feature": "business_edition",
              "depends_on": "business_edit",
              "disabled_for_roles": []
            }
          ]
        }
      ]
    }
  ]
}
```

## Working with Custom Roles

### Custom Role Structure

Every Custom Role consists of three essential components:

* **`name`** — Human-readable display name for the role
* **`api_id`** — Unique identifier used in API operations
  * ⚠️ This ID is used for retrieving, updating, and deleting roles. Changes can break integrations.
* **`permissions`** — Array of permission identifiers granted by this role

**Optional Fields:**

* **`description`** — Detailed explanation of the role's purpose and scope

<Warning>
  The `api_id` field for custom roles is intended for use by integrations —
  changing it can break any existing integrations you have put in place. Use
  caution.
</Warning>

### Built-in Custom Roles

Every organization has access to two pre-configured Custom Roles with special characteristics:

**Restrictions on Built-in Roles:**

* ✅ **Permissions**: Can be updated
* ❌ **Name, API ID, Description**: Cannot be modified
* ❌ **Deletion**: Cannot be deleted (use "reset" to restore defaults)

**Identification:**
Built-in roles are easily identified by these properties:

* `is_builtin: true`
* `org_id: null`

**Updating a built-in role**
To update a built-in role, use the [POST `/org/{org_id}/custom_role/{api_id}`](/api-reference/custom-roles/update-custom-role) endpoint with the desired permission changes, and the built-in role will be updated for your organization. The built-in role can now be identified by having the `build_in` property set to `true`, and `org_id` set to the ID of your organization.

<Frame caption="Built-in Custom Roles can easily be identified in the app by their 'Built-in' labels">
  <img src="https://mintcdn.com/partoo/P_Jb4Af_6Al7QkYi/assets/images/guides/api/guides/custom-roles-and-permissions/built-in-roles.png?fit=max&auto=format&n=P_Jb4Af_6Al7QkYi&q=85&s=6dbedf73b38f43bcd0278cd43794f391" alt="Built-in Custom Roles in App" width="2350" height="1314" data-path="assets/images/guides/api/guides/custom-roles-and-permissions/built-in-roles.png" />
</Frame>

### Assigning Custom Roles to Users

To assign a Custom Role to a user, update the user's `custom_role` field with the desired role's `api_id`. Of course, you can also assign a Custom Role upon user creation.

Once a user is assigned a Custom Role, they inherit all permissions defined in that role.

**Endpoint:** [POST `/user/{user_id}`](/api-reference/users/update-user) and/or [POST `/user`](/api-reference/users/create-user)

### Role Lifecycle Management

Custom Roles support full CRUD operations through the REST API:

* **Create**: [POST `/org/{org_id}/custom_role`](/api-reference/custom-roles/create-custom-role)
* **Read**:
  * [GET `/org/{org_id}/custom_role`](/api-reference/custom-roles/list-custom-roles) (list)
  * [GET `/org/{org_id}/custom_role/{api_id}`](/api-reference/custom-roles/get-custom-role) (single)
* **Update**: [POST `/org/{org_id}/custom_role/{api_id}`](/api-reference/custom-roles/update-custom-role)
* **Delete**: [DELETE `/org/{org_id}/custom_role/{api_id}`](/api-reference/custom-roles/delete-custom-role)
* **Assigning Custom Roles to Users**: [POST `/user/{user_id}`](/api-reference/users/update-user) and/or [POST `/user`](/api-reference/users/create-user)

## Migration Guide

This section covers the migration from the legacy Business Fields and Sidebar Pages system to Custom Roles.

Organizations can check if they're eligible to migrate and manually trigger the switch when ready using the migration endpoints below. **Before making the switch, we strongly recommend reading this entire guide to understand the implications and changes that Custom Roles will bring to your organization.**

The migration is **non-destructive** - all legacy permission data is preserved, allowing you to switch back to the legacy system if needed. However, after the deprecation period ends (6 months), legacy data will be permanently deleted and organizations will be automatically migrated to Custom Roles.

### New Migration Endpoints

To support the migration from the legacy permission system to Custom Roles, two new endpoints have been added:

* **[GET `/org/{org_id}/switch_to_custom_roles`](/api-reference/custom-roles/get-custom-roles-switch-status)** - Get the current migration status for your organization. Returns information about whether your organization has switched to Custom Roles and whether you're allowed to make the switch.

* **[POST `/org/{org_id}/switch_to_custom_roles`](/api-reference/custom-roles/switch-to-custom-roles)** - Update your organization's Custom Roles migration status. This endpoint allows you to enable or disable the Custom Roles feature for your organization (provided you have permission to make this change).

These endpoints help you manage the transition from the legacy permission system to the new Custom Roles system at the organization level.

### Automatic Update of Built-in Roles

When an organization switches to the Custom Roles system, the built-in roles (*Business Manager* and *Group Manager*) are automatically updated to match your current [Business Field permissions](#business-fields). This ensures that users assigned to these roles retain their existing capabilities without any manual intervention.

<Warning>
  The automatic migration only applies to Business Field permissions. [Sidebar
  Pages](#sidebar-pages) configurations are **not** automatically migrated
  during this process. If you want to create Custom Roles that match your
  current Sidebar Pages configuration and assign them to users accordingly, we
  encourage you to do so manually through the Partoo app or contact
  [api@partoo.fr](mailto:api@partoo.fr) for assistance.
</Warning>

For example, if you have restricted the *Business Manager* role from editing certain business fields, those restrictions will be reflected in the updated built-in Custom Role.

## REST API Examples

Below are two concrete examples that demonstrate how to create custom roles with specific permission sets.

### Example A: Business Editor (restricted sensitive fields)

In this example, we'll create a **"Business Editor"** role with comprehensive business editing permissions, while restricting access to sensitive fields.

**Excluded Sensitive Fields:**

* `business_edit_status` — Controls business open/closed status
* `business_edit_siret` — French business tax identification number
* `business_edit_code` — Business identifier used in integrations

<Steps>
  <Step title="Discover Available Permissions">
    Call [GET `/permissions`](/api-reference/custom-roles/get-permissions) to
    retrieve all available permissions for your organization.
  </Step>

  <Step title="Create the Custom Role">
    Use [POST `/org/{org_id}/custom_role`](/api-reference/custom-roles/create-custom-role) with the selected permissions:

    ```json theme={null}
    {
      "name": "Business Editor",
      "api_id": "business_editor",
      "description": "Can edit most business data but cannot modify status, SIRET or store code.",
      "permissions": [
        "business_edit",
        "business_edit_name",
        "business_edit_categories",
        "business_edit_country",
        "business_edit_city",
        "business_edit_zipcode",
        "business_edit_address",
        "business_edit_address2",
        "business_edit_coordinates",
        "business_edit_open_hours",
        "business_edit_specific_hours",
        "business_edit_more_hours",
        "business_edit_description_short",
        "business_edit_description_long",
        "business_edit_attributes",
        "business_edit_website_url",
        "business_edit_facebook_url",
        "business_edit_twitter_url",
        "business_edit_attributes_url",
        "business_edit_email",
        "business_edit_phone_number",
        "business_edit_fax",
        "business_edit_full_name",
        "business_edit_photo_secondary",
        "business_edit_photo_cover",
        "business_edit_photo_logo",
        "business_edit_services",
        "business_edit_menus"
      ]
    }
    ```

    <Info>
      **Excluded Permissions**: `business_edit_status`, `business_edit_siret`, `business_edit_code` are intentionally omitted, preventing users from editing these sensitive fields.
    </Info>
  </Step>

  <Step title="Assign the Role to Users">
    Once created, assign the "Business Editor" role to users by updating their `custom_role` field.

    **Endpoint**: [POST `/user/{user_id}`](/api-reference/users/update-user)

    **Request Body:**

    ```json theme={null}
    {
      "custom_role": "business_editor"
    }
    ```

    ✅ **Result**: The user inherits all permissions defined in the "Business Editor" role.
  </Step>
</Steps>

### Example B: Review Manager (all review-related permissions)

In this example, we'll create a comprehensive **"Review Manager"** role with full access to review-related functionality.

**Role Capabilities:**

* View and filter reviews
* Download review data and analytics
* Manage review states and flags
* Create and assign tags
* Reply to reviews (with templates and AI suggestions)
* Access review booster features
* Configure automated settings

<Steps>
  <Step title="Retrieve Available Permissions">
    Use [GET `/permissions`](/api-reference/custom-roles/get-permissions) and
    select all `review_*` permissions for comprehensive coverage.
  </Step>

  <Step title="Create the Review Manager Role">
    Use [POST `/org/{org_id}/custom_role`](/api-reference/custom-roles/create-custom-role) to create the role:

    ```json theme={null}
    {
      "name": "Review Manager",
      "api_id": "review_manager",
      "description": "Full access to reviews, reply templates, tags, analytics and review booster features.",
      "permissions": [
        "review_management",
        "review_download",
        "review_manage_state",
        "review_flag",
        "review_tags_manage",
        "review_tags_assign",
        "review_tags_manage_auto_settings",
        "review_reply_positive_reviews",
        "review_reply_neutral_reviews",
        "review_reply_negative_reviews",
        "review_reply_template_use",
        "review_reply_template_manage",
        "review_reply_suggestion",
        "review_manage_auto_reply_without_comments",
        "review_manage_auto_reply_with_comments",
        "review_analytics",
        "review_analytics_download",
        "review_analysis",
        "review_analysis_manage_settings",
        "review_booster",
        "review_booster_edit_expeditor_name",
        "review_booster_share_link",
        "review_booster_show_qr_code",
        "review_booster_manage_sms_template"
      ]
    }
    ```

    <Warning>
      **Scope Limitation**: This role grants comprehensive review access but no other permissions. Ensure you include all review-related permissions your users need.
    </Warning>
  </Step>

  <Step title="Assign the Role to Users">
    Assign the "Review Manager" role by updating the user's `custom_role` field.

    **Endpoint**: [POST `/user/{user_id}`](/api-reference/users/update-user)

    **Request Body:**

    ```json theme={null}
    {
      "custom_role": "review_manager"
    }
    ```

    ✅ **Result**: The user gains comprehensive review management capabilities.
  </Step>
</Steps>

## Best Practices

### Role Design Principles

* **Principle of Least Privilege**: Grant only the minimum permissions necessary for users to perform their tasks
* **Role Naming**: Use clear, descriptive names that indicate the role's purpose and scope
* **API ID Stability**: Choose stable `api_id` values that won't need changes
* **Documentation**: Maintain clear descriptions for each custom role

## Troubleshooting

### Common Issues

* **Permission Dependencies**: Ensure all required dependent permissions are included
* **API ID Conflicts**: Choose unique `api_id` values within your organization
* **Invalid Permissions**: Verify permissions exist using the permissions endpoint before assignment
* **Built-in Role Modifications**: Remember that built-in roles have limited editability

### Getting Help

If you encounter any issues with Custom Roles that are not covered in this guide or in the [API Reference documentation](/api-reference/custom-roles/), please contact [api@partoo.fr](mailto:api@partoo.fr) for assistance.

We kindly ask you to describe your issue in as much detail as possible, in order for us to provide you with the best support.