data-src=../../../includes/saas-only.md

companyRoles API

The GET /V1/customers/:customerId/companyRoles REST endpoint returns every role a single customer holds, across all companies the customer is assigned to. Each returned role includes the permissions for that role. This allows you to retrieve all of a customer's permissions with one request, instead of querying each company assignment separately.

For more information on company permissions, see Manage company roles.

Authentication

All requests require an admin or integration bearer token. The token must belong to a role that includes the View Customer Company Roles (Magento_CustomerCompany::company_roles_view) permission under the existing company resources.

Requests are tenant-scoped. The endpoint resolves companies and roles from the active tenant only.

REST API reference

GET /V1/customers/:customerId/companyRoles retrieves the company roles assigned to a customer.

Retrieve company roles for a customer

GET /V1/customers/:customerId/companyRoles returns one entry for each company assignment the customer has a role in.

data-variant=info

data-slots=text

If the customer holds a role in some companies but not others, the companies where the customer does not have a role are not included.

Company Administrator roles return an empty permissions array.

To retrieve every role without paging, use searchCriteria[pageSize]=0.

Path parameters

Query parameters

Pass search criteria as query parameters to manage the results. For general search criteria syntax, see Search using REST endpoints.

Sorting applies to the returned roles after filtering and before paging. The permissions array has no sortable field.

Filter fields

The endpoint supports two categories of filter fields. Company fields restrict which companies are considered. Permission fields narrow the permissions array of each matching role.

data-variant=warning

data-slots=text

Response fields

The endpoint returns an empty items array in the following cases:

• The customer is not a member of any company.
• The customer is a member of a company but does not have a role.
• No company or role matches the search criteria.

The response is a search results object with the following fields.

Each object in the items array contains the following fields.

Each object in the permissions array contains the following fields.

Error responses

Examples

The following examples demonstrate how to retrieve company roles for a customer.

Retrieve all roles for a customer

GET /V1/customers/5/companyRoles?searchCriteria[pageSize]=0

Response (200):

{
  "items": [
    {
      "id": 2,
      "company_id": 1,
      "role_name": "Purchasing Agent",
      "permissions": [
        {
          "resource_id": "Magento_Company::view",
          "permission": "allow"
        }
      ]
    },
    {
      "id": 5,
      "company_id": 3,
      "role_name": "Approver",
      "permissions": []
    }
  ],
  "search_criteria": {
    "filter_groups": []
  },
  "total_count": 2
}

The Approver role grants no permissions, so its permissions array is empty.

Filter by company

The following request returns the roles the customer holds in companies 1 and 3, sorted by company ID:

GET /V1/customers/5/companyRoles
    ?searchCriteria[filterGroups][0][filters][0][field]=company_id
    &searchCriteria[filterGroups][0][filters][0][value]=1,3
    &searchCriteria[filterGroups][0][filters][0][conditionType]=in
    &searchCriteria[sortOrders][0][field]=company_id
    &searchCriteria[sortOrders][0][direction]=ASC

Filter by company name

The following request returns the roles the customer holds in companies whose name starts with Adobe:

GET /V1/customers/5/companyRoles
    ?searchCriteria[filterGroups][0][filters][0][field]=company_name
    &searchCriteria[filterGroups][0][filters][0][value]=Adobe%25
    &searchCriteria[filterGroups][0][filters][0][conditionType]=like

Filter by permission

Company fields and permission fields must occupy separate filter groups. The following request returns only the roles that grant the Magento_Company::view permission, and each returned role lists only that permission:

GET /V1/customers/5/companyRoles
    ?searchCriteria[filterGroups][0][filters][0][field]=resource_id
    &searchCriteria[filterGroups][0][filters][0][value]=Magento_Company::view
    &searchCriteria[filterGroups][0][filters][0][conditionType]=eq
    &searchCriteria[filterGroups][1][filters][0][field]=permission
    &searchCriteria[filterGroups][1][filters][0][value]=allow
    &searchCriteria[filterGroups][1][filters][0][conditionType]=eq

Response (200):

{
  "items": [
    {
      "id": 2,
      "company_id": 1,
      "role_name": "Purchasing Agent",
      "permissions": [
        {
          "resource_id": "Magento_Company::view",
          "permission": "allow"
        }
      ]
    }
  ],
  "search_criteria": {
    "filter_groups": [
      {
        "filters": [
          {
            "field": "resource_id",
            "value": "Magento_Company::view",
            "condition_type": "eq"
          }
        ]
      },
      {
        "filters": [
          {
            "field": "permission",
            "value": "allow",
            "condition_type": "eq"
          }
        ]
      }
    ]
  },
  "total_count": 1
}