Reference-processing modes

The create_job and create_job_from_file endpoints both accept an optional service_modes parameter. It sets how much PubMed and Crossref may change a reference once they have matched it.

For the request schema itself, see openapi.yaml.

The modes

Mode	What the job returns
link	The service ID and its link are inserted. The reference text is returned exactly as written, and comments describe anything that disagrees with the service record. Article titles are not compared.
add	An element the reference does not contain is filled in from the service record. An element already present is kept, and a comment records any difference. When a check fails, the whole reference is returned unchanged.
merge	The reference is rebuilt from the service record, field by field.

Only journal references are corrected. Every other reference type is processed as link, whatever the mode says.

No mode is better than another; they trade correction against fidelity to what the author wrote. link keeps an ahead-of-print citation as the author read it, where merge replaces it with the published version. add fills in an issue number the author left out, which link does not.

Defaults

Service	Key	Default
PubMed	pubmed	merge
Crossref	crossref	add

A request that omits service_modes runs both services in their default mode, exactly as before the parameter existed. A request that names one service leaves the other at its default.

A mode has no effect when its service is switched off: pubmed_flag or crossref_flag set to false means the service does not run at all.

A job whose editorial style has no reference template runs both services in link, whatever the request asked for.

Sending the parameter

service_modes is a map from service to mode.

In a JSON body (create_job):

{
  "edit_style": "AMA11",
  "input_refs": "...",
  "pubmed_flag": true,
  "crossref_flag": true,
  "service_modes": { "pubmed": "link", "crossref": "add" }
}

In a multipart form (create_job_from_file), one field per service:

service_modes[pubmed]=link
service_modes[crossref]=add

Service names and modes are lowercase.

Errors

Code	Cause
0055	service_modes is not a map, for example "service_modes": "link".
0056	A service other than pubmed or crossref. The message names it.
0057	A mode other than link, add, or merge. The message names the service.

An empty map, null, or an empty form field is treated as if the parameter had not been sent.

In the job response

Every job record (create_job, create_job_from_file, check_job, list_jobs, and the job_data of get_job and export_job) carries the mode each service ran in, defaults included:

"service_modes": { "pubmed": "link", "crossref": "add" }

The row reports the mode even when the service was switched off, and it does not reflect the link override for an editorial style that has no reference template.