Retrieving Company Role Information

In corporate environments, where users act as company representatives rather than private buyers, companies can leverage Company Roles in order to distribute scopes and permissions among Company Users. To identify which roles company users are assigned to, you can use the endpoints provided by the Company Role API.

Authentication
The endpoints provided by this API cannot be accessed anonymously. To access them, you need to impersonate users as Company Accounts and pass the authentication tokens received. For details on how to authenticate and retrieve such a token, see Logging In as Company User.

In your development, the endpoint can help you to identify the roles existing in the company of the currently logged in user.

Installation

For detailed information on the modules that provide the API functionality and related installation instructions, see Company Account Feature Integration.

Retrieving Company Role Information

Roles Performed by the Current User

To retrieve information on the Company Roles assigned to the currently logged in Company User, send a GET request to the following endpoint:

/company-roles/mine

Sample request: GET http://glue.mysprykershop.com/company-roles/mine

You can use the Accept-Language header to specify the locale.
Sample header: [{"key":"Accept-Language","value":"de, en;q=0.9"}]
where de, en are the locales; q=0.9 is the user's preference for a specific locale. For details, see 14.4 Accept-Language.

Response

The endpoint responds with a collection of RestCompanyRoleResponse, each containing information on a specific role.

Response Attributes:

Attribute* Type Description
name String Specifies the name of the Company Role.
isDefault Boolean Indicates whether the Company Role is the default role for the company.

*The attributes mentioned are all attributes in the response. Type and ID are not mentioned.

Specific Role

To retrieve information on a specific Company Role, send a GET request to the following endpoint:

/company-roles/{{role_id}}

Sample request: GET http://glue.mysprykershop.com/company-roles/2f0a9d3e-9e69-53eb-8518-284a0db04376

where 2f0a9d3e-9e69-53eb-8518-284a0db04376 is the ID of the Company Role you need.

The endpoint provides information only on the roles a user has access to. If a request is made against a role a user is not allowed to view, the endpoint responds with a 404 Not Found error code.

You can use the Accept-Language header to specify the locale.
Sample header: [{"key":"Accept-Language","value":"de, en;q=0.9"}]
where de, en are the locales; q=0.9 is the user's preference for a specific locale. For details, see 14.4 Accept-Language.

Response

The endpoint responds with a RestCompanyRoleResponse that contains information on the requested role.

Response Attributes:

Attribute* Type Description
name String Specifies the name of the Company Role.
isDefault Boolean Indicates whether the Company Role is the default role for the company.

*The attributes mentioned are all attributes in the response. Type and ID are not mentioned.

Fetching Additional Information

You can extend the response with the companies resource relationship in order to obtain information on the company where the role was created.

Sample request: GET http://glue.mysprykershop.com/company-roles/2f0a9d3e-9e69-53eb-8518-284a0db04376?include=companies

The response will include the following additional attributes:

Resource Attribute* Type Description
companies name String Specifies the Company name.

isActive

Boolean Indicates whether the Company is active.
status String Specifies the status of the Company. Possible values: Pending, Approved or Denied.

*The attributes mentioned are all attributes in the response. Type and ID are not mentioned.

Possible Errors

Code Reason
401 The access token is invalid.
403

The access token is missing.
- OR -
The current Company Account is not set.

This can occur if you didn't properly impersonate the user as a Company User Account. For details on how to do so, see Logging In as Company User.

404 The specified role was not found or the user does not have access to it.

See also:

 

Last review date: July 17, 2019