How to use the Post user identifier Associations API operation to bulk import user identifiers

Pre-requisite: You will need Elements V5.11 or higher.

This example shows an HTTP request that can be used to bulk import user identifier associations. The request body should contain a set of up to 25 user identifier associations elements, each specifying:

• User: a string in general object identifier format (see here) that uniquely identifies an existing Elements User.

• Identifier scheme: a string specifying an identifier scheme (e.g 'ORCID', email-address, etc.)

• Identifier value: the identifier itself.

Multiple identifiers may be specified for a single user, and the same identifier may be specified for multiple users. 

The operation is idempotent, and therefore will update existing user identifier associations rather than duplicate them.

User identifier associations imported via this operation will be used to auto-claim publications (rather than suggest) for the users they are associated with. Read more here for an explanation of what this means.

The URL and Authorisation header shown here are for illustration only - you should replace them with appropriate values for your system and the task you wish to perform.

HTTP verb:  POST

Example URL:  https://server-name:8091/secure-api/v5.5/user/identifiers

Headers:    Content-Type:text/xml

Authorization:Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Request body:  

<?xml version="1.0" encoding="utf-8"?>
<import-users-identifier-associations xmlns="http://www.symplectic.co.uk/publications/api" >
    <import-user-identifier-association user="5" scheme="email-address">mcgrath@email.university.edu</import-user-identifier-association>
    <import-user-identifier-association user="pid-asvilaverde" scheme="researcherid">A-4091-2016</import-user-identifier-association>
    <import-user-identifier-association user="authority-Internal,username-dwh" scheme="scopus-author-id">57195255250</import-user-identifier-association>
    <import-user-identifier-association user="username-dwh" scheme="orcid" >0000-0001-9746-1193</import-user-identifier-association>
</import-users-identifier-associations>

Responses:

Successful - HTTP 200 (OK)

Returned if the request resulted in creation of any new user identifier associations or if any existing associations were updated.

Unsuccessful - HTTP 400 (Bad request)

This will be returned in the following cases:

• XML request body not in the correct format.

• More than 25 <import-user-identifier-association> elements in the request body

• If no <import-user-identifier-association> elements in the request body resulted in successful imports (reasons for failure set out below).

For each user affected by the creates/updates, a full list of the user's identifier associations will be return in the response content.

Warnings (detailing the relevant failed user identifier association imports) will be added to the response if the import failed for a proper subset of the import set.

Import of a single user identifier association can fail for the following reasons:

• missing or invalid 'scheme' attribute.

• missing or invalid 'user' attribute.

• unable to match value in 'user' attribute with a unique existing Elements user.

• identifier value invalid for scheme. (e.g importing an email address as an orcid identifier)