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

Identities Request Service

Identities Request ServiceπŸ”—

The integrating system needs to implement this service to support the following features: * Project Sharing: users can select other users and roles to share a project with. * Email Alerts: selection of users or roles to email (instead of manual entry of email addresses). This requires the Email Address Service as well. * Sharing results by email: selection of users or roles to email (instead of manual entry of email addresses). This requires the Email Address Service as well. * User Activity Reporting: for mapping user/role IDs to their labels.

The Identities Request Service. needs to output he user and role IDs accompanied by labels to display them in the user interface. The service is accessed from within the user’s browser, in the same manner that the Token Request Service is called. Therefore the service should identify the user by the cookie that is sent along with the HTTP request.

Identities Request Service SpecificationπŸ”—


The Identities 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/JSONP as output.

The service must return lists of other users and/or roles that the current user may share projects with, as well as the current user him/herself. Note that the current user can be identified by use of a web session (i.e. HTTP cookie) in order to return a user-specific list. If the service cannot fulfill its request, for example when the user cannot be identified, then it must return an error message with error code EXTERNAL_ERROR.


If the following URL parameters were provided when opening Search, they will be included in the Identities Service Request call.

Parameter Name Type Description
environment string Search! environment.
externalToken string The identification token from external service


Result format Type Description
JSON identities object JSON JSON encoded object with three object fields: users, roles and currentUser. All three object fields should contain IDs as keys and labels as values. The currentUser object should have just one key.
callback(JSON identities object) JSONP Same as for JSON but enclosed by a javascript function callback, if request parameter callback is given (cross-domain only)


The user is logged in to the integration application and has a cookie for identification and authentication.


  • On success, the list of users and access roles will be available for selection when sharing projects; or when for email-alert of email-export recipient selection when Email Address Service is configured.
  • On error, the user will not be able to share projects.

Error HandlingπŸ”—

Error Code Description
EXTERNAL_ERROR Any error occurred during processing of the request (details in message).


JSON result for successful request:

    "users": {
        "A12" : "Kevin Bacon",
        "CX3" : "Alice Bush"
    "roles": {
        "staff" : "Office staff",
        "admin" : "Administrators"
    "currentUser": {
        "B00" : "Bob Davidson"

Example JSON result for EXTERNAL_ERROR:

    {"errorCode": "EXTERNAL_ERROR", "message": "No user logged in."}