Skip to content
Search! & Match! API
Email Address Service

Email Address Service

Email Address Service🔗

When project sharing and/or sharing of search results by email is enabled and the Identities Request Service is implemented to retrieve users and roles to share with, it is possible to set up an additional Email Address Service to look up email addresses belonging to those users and roles. The recipients of email alerts and email exports can then be chosen from the list of known users and roles instead of requiring manual entry of email addresses.

The service is called from the back-end in a similar fashion as the Roles Request Service: all processing is done in the back-end, no user sessions or access tokens are used in the making of these service calls.

Email Address Service Specification🔗


The Email Address 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.

The service must return an object containing all email addresses associated per user in one map and all email addresses associated with the roles in another map.

If the service cannot fulfill its request, for example when the user ID is invalid or unknown, then it must return an error message with error code EXTERNAL_ERROR.


Parameter Name Type Description
users comma-separated string list of user IDs to request email addresses for
roles comma-separated string list of role IDs to request email addresses for


Result format Type Description
JSON email addresses object JSON object JSON encoded object with two object fields: users_emails and roles_emails. Both containing IDs as keys and a list of associated email addresses as values.


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


  • On success, the user is able to send emails to all of the requested users and roles.
  • On error, the user will not be able to send an email.

Error Handling🔗

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


JSON result for successful request:

    "users_emails": {
        "A12" : [ "" ],
        "42" : [ "", "" ]
    "roles_emails": {
        "staff" : [ "" ],
        "42" : [ "", "" ]

Example JSON result for EXTERNAL_ERROR:

    {"errorCode": "EXTERNAL_ERROR", "message": "User unknown: A12"}