Access Roles API v2
Access Roles may be granted to users to offer access to password protected pages, preferential pricing (e.g. trade pricing).
The Access Roles API resource allows you to list built-in and manage custom Access Roles.
Scopes
Access to the Access Role API requires that the client have the following scopes granted:
roles- Permits write access to add, update or remove roles.roles.readonly- Read only access to search or get role data.
The Access Role object
An Access Role represents a permission/grant, which may be required to access protected web pages, or offer users preferential Product Prices.
Example JSON
{
"data": {
"id": 53245,
"reference": "trade-account",
"title": "Trade Account",
"deniedUrl": null,
"approvalMethod": "admin",
"emailValidationUrl": null,
"adminPendingUrl": null,
"adminApprovedUrl": null,
"adminRejectedUrl": null,
"adminApprovalEmail": "administrator@example.com",
"createdOn": "2022-05-21T15:54:05+00:00",
"modifiedOn": "2022-05-21T15:54:05+00:00"
}
}
List/search Access Roles
GET
/api/v2/roles.json
Get or search for one or more Access Roles.
Requires either the roles or roles.readonly OAuth scope.
Query parameters
id:in
Return Access Roles by a comma-separated list of IDs. |
reference
Used to find a single Access Role by its |
reference:in
A comma-separated list of references to find one or more Access Roles. The titles must match the correct spelling (case-insensitive) - does not permit partial matches. |
title
Used to find a single Access Role by its |
title:in
A comma-separated list of titles to find one or more Access Roles. The titles must match the correct spelling (case-insensitive) - does not permit partial matches. |
JSON response
Evance will return a JSON object containing the following properties:
success
A successful search request containing zero or more results will always return a true value.
|
status
An integer matching the HTTP response code. A successful request will have a status of 200.
|
data
An array containing zero or more Access Role data objects. |
pagination
Search results include a pagination object contain information about the current page, total pages, the limit per page and the total number of results available.
|
links
An object containing links to traverse available search results.
|
Example JSON response
{
"success": true,
"status": 200,
"data": [
{
"id": 53245,
"reference": "trade-account",
"title": "Trade Account",
"deniedUrl": null,
"approvalMethod": "admin",
"emailValidationUrl": null,
"adminPendingUrl": null,
"adminApprovedUrl": null,
"adminRejectedUrl": null,
"adminApprovalEmail": "administrator@example.com",
"createdOn": "2022-05-21T15:54:05+00:00",
"modifiedOn": "2022-05-21T15:54:05+00:00"
}
],
"pagination": {
"page": 1,
"limit": 100,
"total": 1,
"totalPages": 1
},
"links": {
"self": "https://examples.evance.me/api/v2/geozones.json",
"previous": null,
"next": null
}
}
Get an Access Role
GET
/api/v2/roles/{id}.json
Retrieve a single Access Role using its ID.
Requires either the roles or roles.readonly OAuth scope.
URL parameters
id
required
The ID of the Access Role is supplied as a path parameter. |
Response
Returns an object with the following properties:
success
A boolean where a value of true represents a successful request.
|
status
The HTTP status code e.g. 200 for a successful request.
|
data
Contains the Access Role object. |
Example JSON response
{
"success": true,
"status": 200,
"data": {
"id": 53245,
"reference": "trade-account",
"title": "Trade Account",
"deniedUrl": null,
"approvalMethod": "admin",
"emailValidationUrl": null,
"adminPendingUrl": null,
"adminApprovedUrl": null,
"adminRejectedUrl": null,
"adminApprovalEmail": "administrator@example.com",
"createdOn": "2022-05-21T15:54:05+00:00",
"modifiedOn": "2022-05-21T15:54:05+00:00"
}
}
Add an Access Role
POST
/api/v2/roles.json
Add an Access Role.
Requires the roles OAuth scope.
Request body
Your request body must contain an object including:
data
required
Containing a Access Role object. |
Example JSON request
The minimum requirement for an Access Role is a title value.
{
"data": {
"title": "Partner"
}
}
In the example above, reference is omitted and will be auto-generated. However,
we recommend defining the reference yourself.
{
"data": {
"title": "Partner",
"reference": "partner"
}
}
Success response
If the Access Role was created successfully you should receive a response with a 201 status
code:
success
A boolean where a value of true means the object was created successfully.
|
status
The HTTP status code e.g. 201 means the object was created successfully. |
data
Contains the Access Role object you created including its new id.
|
Error responses
If the Access Role could not be created you will encounter a response with a 422 status code:
success
A boolean where a value of false means the object could not be created.
|
status
A response code of 422 means the object could not be created and you should
check the errors property for further information. |
context
The context property indicates where the error occurred. For a 422 error this
will typically contain a value of data, indicating that there was an error
with the data object supplied. |
errors
Contains an array of error objects, each will have the following properties:
|
Update an Access Role
PUT
/api/v2/roles/{id}.json
Update an existing Access Role by its ID.
Requires the roles OAuth scope.
URL parameters
id
required
The ID of your Access Role object |
Request body
Your request body must contain an object including:
data
required
Containing updates to your Access Role object. |
Example JSON request
To update an Access Role you must PUT JSON to this resource within a data object.
You do not need to supply all properties and may choose to only supply properties that require modifying.
Note, changing the title of your Access Role, this will NOT auto-generate a new
reference.
{
"data": {
"title": "Trade Partner"
}
}
Success response
If the Access Role was updated successfully you should receive a response with a 200 status
code:
success
A boolean where a value of true means the object was saved successfully.
|
status
The HTTP status code e.g. 200 means the object was updated successfully. |
data
Contains the Access Role object you updated. |
Error responses
If the Access Role could not be updated you will encounter a response with either a
400,
403,
404 or
422status code:
success
A boolean where a value of false means the object could not be updated.
|
status
|
context
|
errors
Contains an array of error objects, each will have the following properties:
|
Delete an Access Role
DELETE
/api/v2/roles/{id}.json
Delete an Access Role by its ID.
Requires the roles OAuth scope.
URL Parameters
id
required
The ID of your Access Role object |
Request body
Does not require a payload
Success response
If the Access Role was deleted successfully you should receive a response with a 204 status
code and no body.
Error responses
If the Access Role could not be deleted you may encounter a response with a
400,
403, or
404 status code:
success
A boolean where a value of false means the object could not be deleted.
|
status
|