The Crossref Curriculum

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-supplied username Not applicable Yes Not applicable
login_passwd Crossref-supplied 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 a system username and password
  • 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)

for example (note: in these examples, we have used the fictional username/password combination of: mrcrossref/abc134):

java -jar crossref-upload-tool.jar --user mrcrossref abc134 --metadata crdeposit234.xml
java -jar crossref-upload-tool.jar --user mrcrossref 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 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 username 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: Laura J. Wilkinson   |   Last updated 2020-April-08