Inbound Manuscript API Documentation

Please find below the technical documentation of the Inbound Manuscript native JAMS API. Head over to the public documentation space in Postman for more comprehensive details and the ability to run API requests directly in Postman.

Inbound Manuscript/Metadata API endpoint

Overview

This API allows the upload of manuscript metadata and creation of a new manuscript submission in JAMS. The API is secured using Bearer tokens and expects data in JSON format.

Authentication

Bearer Token: Each request must include a valid Bearer token in the Authorization header.

Example:

CODE

-H 'Authorization: Bearer <your-token>'

Endpoint

POST `https://{yourDomainName}.jams.pub/api/inbound_manuscript`

Request Headers

Header	Description
Authorization	Bearer token for authentication
Content-Type	`multipart/form-data`

Request Body

The request body must include a single parameter data, which contains a JSON string. Below is the schema and description of the required and optional fields:

JSON Parameters

Parameter	Type	Required	Description
title	`string`	Yes	Cannot be entirely numbers or special characters.
submit_user	`string`	Yes	Must be an email registered under the tenant.
authors	`array`	Yes	List of authors. See details below.
included_reviewers	`array`	No	List of included reviewers. See details below.
excluded_reviewers	`array`	No	List of excluded reviewers. See details below.
journal_name	`string`	Yes	Must be a journal name registered under the tenant.
doi	`string`	No	Optional DOI.
article_type	`string`	Yes	Must be an article type registered under the tenant.
number_of_pages	`integer`	Yes	Number of pages in the manuscript.
abstract	`string`	Yes	Abstract of the manuscript.
keywords	`string`	Yes	Keywords separated by semicolons.
special_issue	`string`	No	Name of the special issue.

Nested Objects

authors

Parameter	Type	Required	Description
first_name	`string`	Yes	Cannot be entirely numbers or special characters.
last_name	`string`	Yes	Cannot be entirely numbers or special characters.
corresponding	`boolean`	No	If not provided, the default is `false`.
email	`string`	Yes	Must be a valid email address.

included_reviewers and excluded_reviewers

Parameter	Type	Required	Description
email	`string`	Yes	Must be a valid email address.
first_name	`string`	Yes	Cannot be entirely numbers or special characters.
last_name	`string`	Yes	Cannot be entirely numbers or special characters.
affiliation	`string`	Yes	Optional affiliation.

Example Parameters

CODE

{
  "data": "{
    "title": "This is a test title", 
    "submit_user": "test@tenant.com", 
    "authors": [{
      "first_name": "user1 first name",
      "last_name": "user1 last name",
      "corresponding": true,
      "email": "testauthor1@email.com"
    }], 
    "journal_name": "Example Journal", 
    "article_type": "Research Article", 
    "number_of_pages": 10, 
    "abstract": "This is the abstract.", 
    "keywords": "science;research;innovation" 
  }"
}

Example Request

CODE

curl -X 'POST'
  'https://{yourDomainName}.jams.pub/api/inbound_manuscript'
  -H 'accept: application/json'
  -H 'Authorization: Bearer 1c17d390dcbf73bb4628a68e32eae5a8'
  -H 'Content-Type: multipart/form-data'
  -F 'data={
    "title":"This is a test title",
    "submit_user":"test@tenant.com",
    "authors": [{
      "first_name": "user1 first name",
      "last_name": "user1 last name",
      "corresponding": true,
      "email": "testauthor1@email.com"
    }], 
    "journal_name":"Test Journal",
    "article_type":"Article",
    "number_of_pages":10,
    "abstract":"This is a test abstract.",
    "keywords":"science;research;innovation"
  }'

Responses

Success Response

HTTP Code	Description
200	Metadata successfully uploaded. Includes a unique `hash_key`.

Example:

CODE

{
  "status": "200",
  "message": "The metadata was uploaded successfully. Please copy the hash_key and use the Inbound Manuscript/Files API endpoint to upload the manuscript files.",
  "hash_key": "89d53617da30aec93fbc986bec23bf04"
}

Error Responses

General Errors

HTTP Code	Message
400	The format of JSON data is incorrect.

Field-Specific Errors

HTTP Code	Field	Message
400	submit_user	The submit_user is not registered or verification failed.
400	title	The title is required.
400	title	The title is invalid.
400	number_of_pages	The type of number_of_pages must be an integer.
400	authors	The authors is required and must be an array.
400	authors-1.email	A valid email is required.
400	authors-1.first_name	The first name is required or invalid.
400	authors-1.last_name	The last name is required or invalid.
400	authors	No Corresponding Author.
400	journal_name	The journal_name is invalid.
400	article_type	The article_type does not belong to the current journal.
400	special_issue	The special_issue is invalid.
400	special_issue	The special_issue does not belong to the current journal.

Notes

Token: Ensure the provided Bearer token is valid.
Validation Rules: The API enforces strict validation rules. Ensure all fields meet the described criteria.
Debugging: If issues persist, check the server logs or contact support for further assistance.

Inbound Manuscript/Files API endpoint

Overview

This API allows users to upload manuscript-related files using a hash key generated from the inbound_manuscript/metadata API. The API is secured using Bearer tokens.

Authentication

Bearer Token: Each request must include a valid Bearer token in the Authorization header.

Example:

CODE

-H 'Authorization: Bearer <your-token>'

Endpoint

POST `https://{yourDomainName}.jams.pub/api/inbound_manuscript/file`

Request Headers

Header	Description
Authorization	Bearer token for authentication
Content-Type	`multipart/form-data`

Request Body

The request body must include the following parameters:

Parameter	Type	Required	Description
hash_key	`string`	Yes	The hash key returned from the `inbound_manuscript/metadata` API.
manuscript_file	`file`	Yes	Must be of type `word` or `zip`. Manuscript file.
presentation_file	`file`	Yes	Must be of type `pdf`. Anonymized manuscript file.
graphical_file	`file`	No	Optional graphical abstract. File type is unrestricted.
supplementary_file	`file`	No	Optional supplementary files. File type is unrestricted.
figures_file	`file`	No	Preferred formats: `TIFF`, `PNG`, `EPS`, or `PDF`. Figures, graphics, or images uploaded as a `.zip`.
non_published_material	`file`	No	Material not intended for publication. Must be `word`, `zip`, or `pdf`.

Example Request

CODE

curl -X 'POST' \
  'https://ucl.jams-staging.pub/api/inbound_manuscript/file' \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'hash_key=89d53617da30aec93fbc986bec23bf04' \
  -F 'manuscript_file=@/path/to/manuscript.zip' \
  -F 'presentation_file=@/path/to/presentation.pdf' \
  -F 'graphical_file=@/path/to/graphical.png'

Responses

Success Response

HTTP Code	Description
200	Manuscript file successfully uploaded.

Example:

CODE

{
  "status": "200",
  "message": "The manuscript file was uploaded successfully."
}

Error Responses

General Errors

HTTP Code	Message
500	The hash_key not exist.
429	You have uploaded more than 5 times and are restricted.

Field-Specific Errors

HTTP Code	Field	Message
400	manuscript_file	The manuscript_file cannot be empty.
400	presentation_file	The presentation_file cannot be empty.
415	presentation_file	Presentation_file has an invalid file type. Allowed types: PDF.
413	manuscript_file	The manuscript_file exceeds the maximum size of 5MB.
413	manuscript_file	The file manuscript_file is empty.

Notes

Token: Ensure the provided Bearer token is valid.
Validation Rules: The API enforces strict validation rules. Ensure all fields meet the described criteria.
File Size Limit: Files must not exceed the server’s allowed size.
Debugging: If issues persist, check the server logs or contact support for further assistance.

Inbound Manuscript/Metadata API endpoint

Overview

Authentication

Endpoint

POST https://{yourDomainName}.jams.pub/api/inbound_manuscript

Request Headers

Request Body

JSON Parameters

Nested Objects

Example Parameters

Example Request

Responses

Success Response

Error Responses

General Errors

Field-Specific Errors

Notes

Inbound Manuscript/Files API endpoint

Overview

Authentication

Endpoint

POST https://{yourDomainName}.jams.pub/api/inbound_manuscript/file

Request Headers

Request Body

Example Request

Responses

Success Response

Error Responses

General Errors

Field-Specific Errors

Notes

POST `https://{yourDomainName}.jams.pub/api/inbound_manuscript`

POST `https://{yourDomainName}.jams.pub/api/inbound_manuscript/file`