XML deposit using HTTPS POST

When files are POSTed to our system they are added to a submission queue to await processing.

Submission limits

We have a limit of 10,000 pending submissions per user. If there are 10,000 submissions in our queue for a given user, subsequent uploads will fail with a 429 error. You may resume POSTing when pending submissions are below 10,000.

Submitting files

Uploading files (for deposit or for bulk queries) are submitted using HTTPS POST with the encType: multipart/form-data. The URL for all submissions is You may also POST submissions to our test system using Learn more about our test system.

The following parameters are supported:

Form field Description Possible values Mandatory? Default
operation Depends on submission type doMDUpload: For metadata (XSD) submissions doDOICitUpload: For DOI citations or resources submissions doQueryUpload: For query submissions doDOIQueryUpload: For DOI-to-metadata query submissions No doMDUpload
subType subtype for metadata submissions cm: for conflict management submissions No Not applicable
login_id Crossref account credentials username If using shared role credentials, add the role. If using personal user credentials, add your email address and the role in this format Yes Not applicable
login_passwd Crossref account credentials password Not applicable Yes Not applicable
Content parts
fname Submission contents Not applicable Yes Not applicable

Upload tool

We provide a simple Java program that performs file uploads (via HTTPS POST) to Crossref. This program allows you to upload a single file, a list of files, or a whole directory of files.

To use, download crossref-upload-tool.jar and place it in /usr/local/lib.

How to use

In the following examples:

  • user is the username and password from your Crossref account credentials. If you are using organization-wide shared role credentials, the username is the role. If you’re using personal user credentials, the username is your email address plus the role in the following format email/role.
  • file is the name of the file you are uploading or
  • directory is the name of the directory containing files to upload

To upload a metadata file

java -jar crossref-upload-tool.jar --user myusername mypassword --metadata (filename | directory)

Using role credentials (note: in these examples, we have used the fictional role and password combination of mrcrossref and abc134):

java -jar crossref-upload-tool.jar --user mrcrossref abc134 --metadata crdeposit234.xml
java -jar crossref-upload-tool.jar --user mrcrossref abc134 --metadata crdeposits

Using user credentials (note: in these examples, we have used the fictional user credential, role, and password combination of, mrcrossref, and abc134)

java -jar crossref-upload-tool.jar --user abc134 --metadata crdeposit234.xml
java -jar crossref-upload-tool.jar --user abc134 --metadata crdeposits

To upload a resource-only deposit file

java -jar crossref-upload-tool.jar --user mrcrossref abc134 --resources (file | directory)

for example:

java -jar crossref-upload-tool.jar --user mrcrossref abc134 --metadata cr_refs.xml
java -jar crossref-upload-tool.jar --user mrcrossref abc134 --metadata refdata

To upload conflict files

Single file:

java -jar crossref-upload-tool.jar --user mrcrossref abc134 --conflicts ticket1234.txt

Directory of files:

java -jar crossref-upload-tool.jar --user mrcrossref abc134 --transfers ALIAS_123

To direct upload(s) to the test system

java -jar crossref-upload-tool.jar --user mrcrossref abc134 --host --metadata crdeposit234.xml

Dry run (test)

Note that if the –metadata option is given a directory name instead of a filename then all files within the directory are uploaded. To ensure that you are uploading what you want use the –dry-run option and review the listing of files, eg:

java -jar crossref-upload-tool.jar --user mrcrossref abc134 --metadata mydeposits/ --dry-run

Additional info

If your upload is successful, you will see this message:

[…] INFO uploading to
[…] INFO uploading submission: file=myfile.xml
[…] INFO uploaded submission: file=myfile.xml
[…] INFO done

If the username is wrong, you will see the message:

[…] INFO uploading to
[…] INFO uploading submission: file=myfile.xml
[…] INFO unauthorized: file=myfile.xml; user=mrcrossref
[…] INFO done

Upload options

--user name password
--metadata ( file | directory )
--query ( file | directory )
--transfers ( file | directory )
--handles ( file | directory )
--resources ( file | directory )
--conflicts ( file | directory )
--address host port
--protocol ( http | https )


  • user: your Crossref system username (either role, for role credentials, or email/role, for user credentials) and password
  • metadata: use for metadata deposits
  • query: use for query deposits
  • transfers: admin use only
  • handles: admin use only
  • resources: resource-only deposits
  • conflicts: conflict resolution files
  • address: direct to a different address (such as
  • protocol: http or https
  • dry-run: test uploader without uploading
  • help: displays the above list of upload options

Further examples

Entry into terminal

java -jar /usr/local/crossref-upload-tool.jar --user mrcrossref abc134 --metadata /Users/mistercrossref/Uploader/September/19/134/

Key for entry into terminal:

  • usr/local/crossref-upload-tool.jar = location of the upload program on your machine
  • mrcrossref abc134 = Crossref role and password you are using for upload
  • metadata = type of content being uploaded
  • Users/mistercrossref/Uploader/September/19/134/ = location of XML files on my machine being uploaded

Page owner: Rachael Lammey   |   Last updated 2021-April-23