Anatomy of a Submission

In order to register a DOI for your award, certain minimum information needs to be submitted. Additionally, there are other fields that can optionally be supplied.

All interactions with the API service are encoded in JSON and are completed over HTTP.

The following is a sample submission:

{
   "award_funding_type": "award",
   "doi_infix": "ab.123",
   "award_title": "Title of the Award",
   "award_num": "TEST-AWARD",
   "ident_nums": [
      "OTHER-1234"
   ],
   "award_urls": [
      "https://example.com/TEST-AWARD"
   ],
   "award_description": "optional description",
   "award_date_range_start": "2020-07-01",
   "award_date_range_end": "2020-07-31",
   "investigator": [
      {
         "first_name": "Josiah",
         "last_name": "Cranberry",
         "investigator_orcid": "0000000218250097",
         "role": "investigator",
         "investigator_start_date": "2020-07-16",
         "investigator_end_date": "2020-07-18",
         "affiliations": [
            {
               "organization_name": "Smithsonian Institution",
               "organization_country": "US",
               "ror_id": "01pp8nd67"
            },
            {
               "organization_name": "Arup",
               "organization_country": "US",
               "ror_id": "03awtex73"
            }
         ]
      }
   ],
   "additional_fund_org": [
      {
         "funder": "EMSL",
         "funding_type": "award"
      }
   ],
   "related_idents": [
      {
         "relation": "hasReview",
         "identifier": "http://example.com/url",
         "type": "uri"
      }
   ],
   "permissions": [
      {
         "user_email": "EMAIL ADDRESS 1"
      },
      {
         "user_email": "EMAIL ADDRESS 2"
      }
   ]
   }
                                            

JSON Object Key Descriptions

The following describes the top-level keys found in the submission object. Nested objects are described in more detail later in this document.

Object Key	Description
*award_num	An internally unique award number assigned by the awarding organization. The award organization assigned award or grant number.
*award_funding_type	The type of funding for this award, e.g. “award”, “contract”, “grant”, etc.
*award_title	The title of the award.
doi_infix	A site-selected alpha-numeric string inserted in the DOI value itself for new DOIs. (e.g. infix = FICUS, DOI = https://doi.org/10.46936/FICUS/12345).
ident_nums	JSON array of strings. Contains other identifying numbers, identifiers, codes, or IDs.
award_description	A description or abstract of the award.
award_date_range_start	The start date of the award.
award_date_range_end	The end date of the award.
award_urls	JSON array of strings. A URL link to the site, facility, or page with information about the specific award. URLs must be a valid http:// or https:// link in order to be accepted.
*investigator	JSON array of objects. Investigator objects are described below.
additional_fund_org	JSON array of objects. Funding objects are described below.
related_idents	JSON array of objects. Related Identifier objects are described below.
permissions	JSON array of objects. User Permission objects are described below.

Note

Required fields are marked with an asterisk.

Investigator Objects

A submission must have at least one valid investigator entry in order to be registered with Crossref.

Each investigator entry must have at least the first and last name, as well as the role, which is one of investigator, co-lead_investigator or lead_investigator.

Optionally, an ORCID can be provided, a start and end date for the investigator and any affiliations.

Affiliations, if provided, require at minimum the ROR ID for the organization.

{
   "first_name": "Josiah",
   "last_name": "Cranberry",
   "investigator_orcid": "0000000218250097",
   "role": "investigator",
   "investigator_start_date": "2020-07-16",
   "investigator_end_date": "2020-07-18",
   "affiliations": [
      {
         "organization_name": "Smithsonian Institution",
         "organization_country": "US",
         "ror_id": "01pp8nd67"
      },
      {
         "organization_name": "Arup",
         "organization_country": "US",
         "ror_id": "03awtex73"
      }
   ]
}
                                                

Funding Objects

Note

The submitting organization will be automatically added as a funder. The key for additional_fund_org is for any funding organizations in addition to the submitting organization.

Additional funders are represented as funding objects. Funding objects must have a name for the organization and must have a funding_type such as award, grant or facilities.

User Permission Objects

Users who are not a part of your site, but that you would like to allow to add related identifiers to a record can be added using this object.

The objects simply contain a single key, user_email. The only items they will be allowed to add are related identifiers, and they can also remove any related identifiers that they themselves have added through the web interface.

{
   "permissions": [
      {
         "user_email": "user@email.com"
      }
   ]
}
                                                