Overview

The addExternalId API is a POST endpoint used to assign an external identifier (externalId) to a document within the system. This assignment may also trigger document locking depending on the document’s state and system configuration.

The API ensures that each document is uniquely identified by its externalId, and it enforces several validation rules to maintain data integrity. Upon successful execution, the API returns a standard success response. In cases of failure, appropriate error messages and codes are returned.

Method: POST

Resource

api/s1m/v2/integration/full/addExternalId

Request Parameters

Element	Type	Description	Required	Example or Default Value
addExternalID	Root		Yes
username	String	Profile User Name. This is the user name used by the API, not a ScholarOne Manuscripts user. This is from the Caller’s profile.	Yes	sample_user
password	String	The API Key. Encrypted value uniquely identifying and authenticating Caller	Yes	SRU4DQ5WOJ2PX8CA
site_name	String	Site short name. The short name is the abbreviated or truncated name of the journal, society, publisher, or family.	Yes	salesdemoplus
url	String	The Web Service URL, which identifies the specific service to handle the request.	Yes	v2/integration/full/addExternalId
external_id	String	An id value that can be set by the client for call tracking. Caller supplied Text string to be stored with Audit History information.	No	123456
_type	String	The data type requested from the Service <xml> or <json>. This defaults to <xml>.	No	xml (default if omitted), or json

Request Body Elements

The request body must be in JSON format.

Request Body Elements example

{
"input":  {
    "clientKey":"434559b0-58c9-4120-89ee-95cf1c9a783b",
    "documentId": 1234567,
    "externalId": "12345_test"
        }               
}

Request Body Elements Description

Request Body Elements	Type	Description	Req	Example or Default Value
input	Object	This is the root object containing all the data required for adding an external ID on the manuscripts.	Yes
clientKey	String	A key defined for the existing ingestion profile used by the publisher or society to ingest papers into ScholarOne Manuscripts.	Yes	`"434559b0-58c9-4120-89ee-95cf1c9a783b"`
documentId	Integer	The internal identifier of the document to which the externalId will be assigned.	Yes	`52891506`
externalId	String	The unique identifier to assign to the document. Must be non-empty and not previously assigned.	Yes	`"12345_test"`

Validation Rules & Constraints

externalId and clientKey must not exceed 256 characters.
externalId must not be already in use or assigned to another document.
documentId must reference a valid, existing document.
If document locking is configured, the document will be locked upon successful assignment.
The clientKey must be valid and associated with the existing ingestion profile used by the publisher or society.

Audit Logging

Upon successful execution, an audit log entry is created with the message: “External Id successfully assigned”