Skip to main content

​
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

For a list of breaking changes, please refer to the Partoo API Changelog.

​
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
Business Fields Configuration

Business Fields Configuration - Here, Business Managers have been restricted from editing any fields in the category 'Main Description' of a business

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
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.
Inspection Endpoint: GET /user/{user_id}
User Edit Page - Sidebar Pages Selection

In the screenshot above, the user John Smith will not have access to any analytics features, since 'Analytics' has been toggled off.

​
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.
Permissions Overview

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.


Permissions Detail

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.

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 endpoint to discover all permissions available to your organization. Example Response: 
{
  "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
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.

​
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} 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.
Built-in Custom Roles in App

Built-in Custom Roles can easily be identified in the app by their 'Built-in' labels

​
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} and/or POST /user

​
Role Lifecycle Management

Custom Roles support full CRUD operations through the REST API:

​
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 - 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 - 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. This ensures that users assigned to these roles retain their existing capabilities without any manual intervention.
The automatic migration only applies to Business Field permissions. 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 [email protected] for assistance.
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
1

Discover Available Permissions

Call GET /permissions to retrieve all available permissions for your organization.
2

Create the Custom Role

Use POST /org/{org_id}/custom_role with the selected permissions:
{
  "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"
  ]
}
Excluded Permissions: business_edit_status, business_edit_siret, business_edit_code are intentionally omitted, preventing users from editing these sensitive fields.
3

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}Request Body:
{
  "custom_role": "business_editor"
}
✅ Result: The user inherits all permissions defined in the “Business Editor” role.
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
1

Retrieve Available Permissions

Use GET /permissions and select all review_* permissions for comprehensive coverage.
2

Create the Review Manager Role

Use POST /org/{org_id}/custom_role to create the role:
{
  "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"
  ]
}
Scope Limitation: This role grants comprehensive review access but no other permissions. Ensure you include all review-related permissions your users need.
3

Assign the Role to Users

Assign the “Review Manager” role by updating the user’s custom_role field.Endpoint: POST /user/{user_id}Request Body:
{
  "custom_role": "review_manager"
}
✅ Result: The user gains comprehensive review management capabilities.

​
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, please contact [email protected] 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.