Backend API: Manage company roles

This document describes how to manage company roles using the Backend API. A company role groups the permissions a company grants its company users—who may approve a quote, add a company user, or manage a shopping list. Every company user holds at least one role of their own company. You can use these endpoints to build Back Office extensions, CRM and ERP integrations, and onboarding automation.

Installation

These endpoints are implemented using API Platform. To install and enable it, see Enable API Platform.

For the modules that provide the company role endpoints and their installation instructions, see Install the Company Roles Backend API.

Conventions

Request headers, pagination, and the filter and sort syntax are the same for every Backend API resource—see Backend API conventions. This page lists only what is specific to company roles.

Retrieve company roles

To retrieve a paginated collection of company roles, send the request:

GET /company-roles

Request

name, companyName, companyUuid, and isDefault are the filterable properties; a filter addressing any other property returns 400 with the error code 1215, as does a filter whose value is not a scalar.

Filters combine with each other and with q. The collection then contains only the roles that match every criterion.

Response

{
    "links": {
        "self": "https://glue-backend.mysprykershop.com/company-roles",
        "first": "https://glue-backend.mysprykershop.com/company-roles?page[limit]=10&page[offset]=0",
        "last": "https://glue-backend.mysprykershop.com/company-roles?page[limit]=10&page[offset]=10",
        "next": "https://glue-backend.mysprykershop.com/company-roles?page[limit]=10&page[offset]=10"
    },
    "meta": {
        "pagination": {
            "numFound": 12,
            "currentPage": 1,
            "maxPage": 2,
            "currentItemsPerPage": 10
        }
    },
    "data": [
        {
            "type": "company-roles",
            "id": "50c647a4-d27f-5d82-a587-1d0b7cc6b58d",
            "attributes": {
                "uuid": "50c647a4-d27f-5d82-a587-1d0b7cc6b58d",
                "name": "Approver",
                "isDefault": false,
                "companyUuid": "a0e4d1c8-6b47-5f19-9c2d-3f8b1e7a5d40",
                "companyName": "Acme Corporation",
                "permissionKeys": [
                    "AddCompanyUserPermissionPlugin",
                    "ApproveQuotePermissionPlugin"
                ]
            },
            "links": {
                "self": "https://glue-backend.mysprykershop.com/company-roles/50c647a4-d27f-5d82-a587-1d0b7cc6b58d"
            }
        }
    ]
}

Retrieve a company role

To retrieve a single company role, send the request:

GET /company-roles/{{company_role_uuid}}

Response

The response contains one company role, with the same attributes as Retrieve company roles.

Create a company role

To create a company role, send the request:

POST /company-roles

Request

Request sample: POST https://glue-backend.mysprykershop.com/company-roles

{
    "data": {
        "type": "company-roles",
        "attributes": {
            "name": "Approver",
            "companyUuid": "a0e4d1c8-6b47-5f19-9c2d-3f8b1e7a5d40",
            "permissionKeys": ["ApproveQuotePermissionPlugin"]
        }
    }
}

Response

{
    "data": {
        "type": "company-roles",
        "id": "50c647a4-d27f-5d82-a587-1d0b7cc6b58d",
        "attributes": {
            "uuid": "50c647a4-d27f-5d82-a587-1d0b7cc6b58d",
            "name": "Approver",
            "isDefault": false,
            "companyUuid": "a0e4d1c8-6b47-5f19-9c2d-3f8b1e7a5d40",
            "companyName": "Acme Corporation",
            "permissionKeys": ["ApproveQuotePermissionPlugin"]
        },
        "links": {
            "self": "https://glue-backend.mysprykershop.com/company-roles/50c647a4-d27f-5d82-a587-1d0b7cc6b58d"
        }
    }
}

A successful request returns the 201 Created status code. The response contains the uuid that you can use to address the company role in subsequent requests, and the permissions assigned to it.

Edit a company role

To update a company role, send the request:

PATCH /company-roles/{{company_role_uuid}}

Request

Request sample: PATCH https://glue-backend.mysprykershop.com/company-roles/50c647a4-d27f-5d82-a587-1d0b7cc6b58d

{
    "data": {
        "type": "company-roles",
        "attributes": {
            "name": "Quote Approver"
        }
    }
}

The request accepts name, isDefault, and permissionKeys, and all of them are optional. The endpoint applies only the attributes present in the payload; every attribute you omit keeps its stored value.

To make a role the company’s default, send isDefault as true:

{
    "data": {
        "type": "company-roles",
        "attributes": {
            "isDefault": true
        }
    }
}

This promotes the role and demotes the company’s previous default, so a company never holds more than one default role.

Response

The response contains the updated company role, with the same attributes as Retrieve a company role.

Delete a company role

To delete a company role, send the request:

DELETE /company-roles/{{company_role_uuid}}

Response

A successful request returns the 204 No Content status code with an empty body.

Possible errors

To view generic errors, see API errors and troubleshooting.