Skip to content
Search! & Match! API
Roles Request Service

Roles Request Service

Roles Request Service🔗

If the Search! email alerting or sharing by email functionality is enabled, then the integrating application must also implement a roles request service. It enables Search! to check the current access rights of a user before sending scheduled email alerts.

Roles Request Service Specification🔗


The roles request service is part of the integrating application and follows this specification.

  • An HTTP GET service that accepts URL parameters as input and produces JSON as output.

Upon receiving a request with the user identifier and search environment name as URL parameters it must return the user's access roles for the environment. The roles are returned as a list of strings in JSON format. If the user is not authorized, it must return a USER_NOT_AUTHORIZED exception which disables email alerting for that user. Other errors must result in an EXTERNAL_ERROR exception message. See examples below.


Parameter Name Type Description
environment string Search! environment to request access roles for.
user string The user id to request access roles for.


Result format Type Description
roles JSON list of String the access roles, one or more strings.


No requirements. The service must return results without the user being logged in.


  • On success, the list of access roles will be used for executing the user's saved search and sending email alerts in the given environment.
  • On USER_NOT_AUTHORIZED error, the user's saved searches will be disabled for sending email alerts in the given environment.
  • On EXTERNAL_ERROR error, no email alerts will be sent but the email alerting remains enabled.

Error Handling🔗

Error Code Description
USER_NOT_AUTHORIZED The user is unknown or has no valid access roles for the environment.
EXTERNAL_ERROR Another error occurred during processing of the authorization request (details in message).


JSON result for successful request returning two roles:



    {"errorCode": "USER_NOT_AUTHORIZED", "message": "User 'user500' is not known"}


    {"errorCode": "EXTERNAL_ERROR", "message": "Error reading users database."}