Overview

The Relay API supports submission and management of third-party reviewer suggestions for manuscripts in ScholarOne Manuscripts. It allows integrated reviewer-matching providers to push their recommendations directly into the editor's reviewer selection workflow, so editors can evaluate, compare, and invite suggested reviewers without leaving ScholarOne.

Using a single endpoint, a provider can:

• Submit a batch of suggested reviewers (candidates) for a specific manuscript - for example, when the provider's matching engine first produces recommendations.
• Add further candidates to an existing batch over time - for example, when a user hand-picks an additional reviewer in the provider's interface.
• Update details of previously sent candidates - for example, refreshed relevance scores or match explanations.
• Delete candidates that should no longer be shown to editors.

Method: POST

Resource

/api/s1m/v2/system/addJSONData

Terminology

A manuscript can accumulate multiple suggestion batches, from different providers, or several from the same provider over time.

Request Parameters

Request Body Elements

• The request body must be in JSON format.
• The reviewer suggestion payload is wrapped in a data root element, with the processor type as a string ("4") and the payload nested under payload:

JSON

{
  "data": {
    "type": "4",
    "payload": {
      ...reviewer suggestion payload...
    }
  }
}	

• Every payload requires an operation field: "submit", "add", "update", or "delete". Unknown values are rejected.
• The reviewers field is always an array. A single entry is fine, and a bare object is also accepted anywhere an array is expected.

Operation: submit - Creates a Batch

Request Body Elements for submit example

JSON

{
  "data": {
    "type": "4",
    "payload": {
      "operation": "submit",
      "provider": "GlobalCampus" or "Prophy" ,
      "providerVersion": "2.1",
      "submissionId": "WRK-2026-001",
      "documentId": 12345,
      "timestamp": "2026-02-25T10:30:00Z",
      "reviewers": [
        {
          "providerCandidateId": "gc-001",
          "firstName": "Jane",
          "lastName": "Doe",
          "email": "[email protected]",
          "orcid": "0000-0001-2345-6789",
          "relevanceScore": 95,
          "matchReason": "Expert in quantum computing, 7 related publications",
          "matchDetails": "<ul><li><a href=\"https://doi.org/10.1136/example\">Paper title</a></li></ul>"
        }
      ]
    }
  }
}

Request Body Elements Description - submit

For candidate-level fields inside reviewers (names, email, ORCID, relevance score, match explanations, metrics), see the Candidate Field Reference section below. On submit, the required candidate fields are providerCandidateId, firstName, lastName, and email.

Operation: add - Appends Candidates to an Existing Batch

Request Body Elements for add example

JSON

{
  "data": {
    "type": "4",
    "payload": {
      "operation": "add",
      "provider": "GlobalCampus" or "Prophy",
      "submissionId": "WRK-2026-001",
      "timestamp": "2026-02-26T09:15:00Z",
      "reviewers": [
        {
          "providerCandidateId": "gc-003",
          "firstName": "Maria",
          "lastName": "Garcia",
          "email": "[email protected]",
          "relevanceScore": 91,
          "matchReason": "Hand-picked by the requesting user"
        }
      ]
    }
  }
}

Request Body Elements Description - add

Candidate-level requirements on add are identical to submit: providerCandidateId, firstName, lastName, and email are required; all other fields in the Candidate Field Reference are optional. If a providerCandidateId already exists as a live record in the batch, that entry is skipped and audited (the existing record is not modified - use update for that).

Operation: update - Modifies Existing Candidates

Request Body Elements for update example

JSON

{
  "data": {
    "type": "4",
    "payload": {
      "operation": "update",
      "provider": "GlobalCampus" or "Prophy",
      "submissionId": "WRK-2026-001",
      "timestamp": "2026-02-27T14:00:00Z",
      "reviewers": [
        {
          "providerCandidateId": "gc-003",
          "relevanceScore": 90,
          "matchReason": "Updated after full-text analysis"
        }
      ]
    }
  }
}

Request Body Elements Description - update

Any field from the Candidate Field Reference may be sent alongside providerCandidateId to change it. Note: sending personId on update re-validates and re-links the person record, but changing email or orcid alone does not re-trigger automated person matching.

Operation: delete - Removes Candidates from a Batch

Request Body Elements for delete example

JSON

{
  "data": {
    "type": "4",
    "payload": {
      "operation": "delete",
      "provider": "GlobalCampus" or "Prophy",
      "submissionId": "WRK-2026-001",
      "timestamp": "2026-02-28T08:45:00Z",
      "reviewers": [
        {
          "providerCandidateId": "gc-002"
        }
      ]
    }
  }
}

Request Body Elements Description - delete

Candidate Field Reference

The fields below apply to each object inside the reviewers array.

* "Required" applies to submit and add. For update and delete, only providerCandidateId is required.

** Limit applies to the serialized JSON of each field independently, measured in both characters and UTF-8 bytes (the stricter applies).

"Candidate rejected" means that one candidate is skipped and the reason is written to the manuscript's audit trail; the rest of the batch still processes (see Per-Candidate Failures).

Person Matching

When personId is not provided, ScholarOne automatically matches each candidate to its user records: first by email address, then by ORCID, scoped to the journal's configuration family.

When personId is provided:

• If the person exists, belongs to the target site's configuration family, and does not conflict with the email/ORCID match, it is used directly (bypassing automated matching).
• If the email/ORCID resolves to a different person, the automated match wins, and the conflict is written to the manuscript's audit trail.
• If the person is not found, or does not belong to the site's configuration family, ScholarOne falls back to automated matching and logs the issue.

On update: sending personId re-validates and re-links the record. Changing email or orcid alone does not re-trigger automated matching.

ORCID Format

Both forms are accepted on input and normalized to the bare form for storage:

• Bare: 0000-0001-2345-6789

• 🔄 [TEMP - finalize before release] URL form: http://orcid.org/0000-0001-2345-6789 or https://orcid.org/0000-0001-2345-6789 - both prefixes are accepted and stripped during normalization.

After normalization the value must match 0000-0000-0000-000X (the final character may be X); otherwise the candidate is rejected.

Metrics and Flags

The metrics and flagsfields accept an array of JSON objects with free-form keys. There are no reserved or recognized keys; content is stored and displayed as-is. All of the following are accepted and equivalent:

JSON

"metrics": [{"hIndex": 24, "citationCount": 3456}]

"metrics": [{"hIndex": 24}, {"citationCount": 3456}]

"metrics": {"hIndex": 24}

Provider Data: Recognized Keys (relevantWorks / relatedWorks)

Within providerData, two keys are recognized specially by the reviewer suggestion interface: relevantWorks and relatedWorks. When either key is present, its contents render in the candidate's detail view as a titled list of links, labeled "Most Relevant Works" instead of being shown as generic, unformatted detail.

Each entry in a relevantWorks / relatedWorks array is an object describing one linked item:

If an item is missing both a recognized title field and a recognized URL field, it does not render as a link.

JSON

"providerData": [
  {
    "relevantWorks": [
      { "title": "Machine Learning Approaches in Peer Review", "detailUrl": "https://provider.example.com/works/12345" },
      { "title": "Bias Detection in Reviewer Matching Systems", "detailUrl": "https://provider.example.com/works/12346" }
    ]
  },
  {
    "expertiseArea": "Natural Language Processing"
  }
]

In this example, relevantWorks renders as a two-item "Most Relevant Works" list with working links, while expertiseArea not a recognized key, displays as plain, unformatted detail alongside it.

relatedWorks is accepted as an alias for relevantWorks and behaves identically; use whichever name best matches your own data model.

Allowed HTML (matchReason, matchDetails)

Accepted tags:

a, abbr, b, blockquote, br, cite, code, dd, div, dl, dt, em, h1, h2, h3, h4, h5, h6, hr, i, img, li, ol, p, pre, q, small, span, strike, strong, sub, sup, table, tbody, td, th, thead, tr, u, ul

Attribute rules:

• a: href only, and it must use the http:// or https:// scheme.
• img: src (must use https://) and alt (always allowed, for accessibility).
• All other tags, including div and span: no attributes. CSS classes and inline styles are not accepted; visual presentation is controlled by ScholarOne.

Character limits count the full content including markup, attribute values, and entity references. As sizing guidance: ten DOI links in list format consume roughly 3,500 of 'matchDetails' 4,000 characters.

Responses

All responses use the standard ScholarOne API envelope. Results are reported at the request level; there is no per-candidate detail in the response.

Success - HTTP 200

{
  "Response": {
    "status": "SUCCESS",
    "callId": "...",
    "result": {
      "returnCode": "OK",
      "type": 4
    }
  }
}

The request was accepted and processed. Individual candidates may still have been skipped or rejected (see Per-Candidate Failures).

Request-Level Failure - HTTP 400

{
  "Response": {
    "status": "FAILURE",
    "callId": "...",
    "errorDetails": {
      "errorCode": 100,
      "moreInfo": {
        "errors": {
          "errorCode": 100,
          "errorMessage": "Duplicate submission already processed: GC-2026-001"
        }
      },
      "userMessage": "An unexpected error has occurred"
    }
  }
}

The entire request was rejected and nothing was stored. The underlying reason is in errorDetails.moreInfo.errors.errorMessage. Request-level failures include:

• Missing/unknown operation, missing required batch-level fields, malformed timestamp
• documentId not found or not belonging to the caller's site (submit)

• 🔄 [TEMP - finalize before release] The target manuscript is not in an active peer-review state. Suggestions are accepted only for a manuscript whose current version is submitted, revised, or resubmitted and is not in the author's draft. Manuscripts in draft (including a revised/resubmitted version still in the author's hands), in appeal, or in any terminal state (decisioned, accepted, withdrawn, …) are rejected. Applies to all four operations. The rejection message is: "Document is not accepting reviewer suggestions: the manuscript must be a submitted, revised, or resubmitted version that is not in draft."

• Batch not found for provider + submissionId (add/update/delete)
• Duplicate fully-processed batch on submit retry (see Idempotency)
• Provider not active, or the Relay feature disabled for the site
• Empty reviewers array

• 🔄 [TEMP - finalize before release] reviewers array exceeding twice the configured per-document maximum (more than 200 candidates at the default maximum of 100) - see Candidate Limits

• 🔄 [TEMP - finalize before release] ScholarOne is unable to determine the provider's current live candidate count for the manuscript (a data-tier error); the request is rejected rather than risk exceeding the limit

Per-Candidate Failures - Audited, Not Returned

Within an otherwise valid request, individual candidates can be skipped (duplicate ID, over the per-request cap) or rejected (validation failure: disallowed HTML, bad ORCID, bad country, missing required fields, oversized JSON fields). The remaining candidates are still committed. Each skip/rejection is written to the manuscript's audit trail in ScholarOne with the provider, submissionId, providerCandidateId, and reason.

The response does not enumerate these. Providers who need to verify ingestion can coordinate with the journal team, who can read the audit trail and the suggestion list in the editor interface. A batch that loses candidates this way is marked partial, and a partial batch can be wholly replaced by re-submitting the same submissionId (see Idempotency, case c).

Batch Lifecycle

Statuses

Idempotency (Submit Retries)

A submit retry is identified by the same provider + submissionId on the same site.

• (a) Happy path. First submit of GC-2026-001 → batch stored, status 2 (processed). Response: SUCCESS.
• (b) Retry after full processing. Second submit of GC-2026-001 → rejected, HTTP 400, "Duplicate submission already processed: GC-2026-001". The original batch is untouched. A fully-processed batch is immutable via submit; use add/update/delete to change it.
• (c) Retry after incomplete processing. If the existing GC-2026-001 batch is in any state other than fully processed (received, partial, failed), the old batch is marked superseded (soft-deleted) and the retry creates a fresh batch from the new payload. This is the intended recovery path after a partial failure: fix the offending records and re-submit the entire batch under the same submissionId.

Duplicate Candidates

• Within a single submit: if the same providerCandidateId appears twice, the first occurrence wins; later duplicates are skipped and audited.
• On add: if the providerCandidateId already exists as a live record in the batch, the add is skipped and audited (the existing record is not modified - use update for that).
• On update/delete: if no live record matches the providerCandidateId, that entry is skipped and audited; the request still returns SUCCESS.

Delete Behavior and Modeling User Actions

Delete is a soft delete: the record disappears from all editor-facing views but is retained internally. A deleted providerCandidateId can be re-added later via add;🔄 [TEMP - finalize before release] this creates a new record with a new activity time (so it surfaces at the top of the editor's list - see Display Order).

If an editor has already actioned a candidate (e.g. sent a review invitation), that workflow is independent of this API; deleting the suggestion does not retract the invitation.

Automated vs. user-selected candidates: the API does not record why a candidate was sent (there is no addedBy field). Both kinds coexist freely in one batch and are distinguished only by providerCandidateId. If your system needs the distinction to be visible to editors or to itself later, either:

• Use separate batches (submissionIds) for the automated run vs. user selections, or
• Carry an origin marker in providerData (e.g. [{"origin": "user-selected"}]), which editors can see in the candidate's detail view.

Ordering and Concurrency

Display Order

Operation Ordering

Operations are applied in the order ScholarOne receives them. The timestamp field is informational and is not used to order or reconcile operations. There is no server-side conflict resolution for out-of-order delivery: for example, if a delete that was issued before a re-add arrives after it, the candidate ends up deleted.

Providers should therefore serialize operations per candidate - wait for the response to one operation before issuing the next operation that touches the same providerCandidateId. Independent candidates may be sent concurrently.

Quick Reference - What Fails Where