/orcid/researchers/search

POST /api/orcid/researchers/search

Price: 5 credits

Search ORCID researchers by name, keyword, affiliation or identifier

How to use it

Search the ORCID registry for researchers. Filter by given and family name (separately or combined), credit or other names, biography text, email, research keyword, free text, affiliated organization name (current, past or any), organization identifier (ROR, Ringgold or GRID), the title of one of their works, a work DOI (any or self-authored), a work PubMed id (PMID or PMCID), or an exact ORCID iD. Provided filters are combined with AND; an advanced raw query expression is also supported. Returns each matching researcher's ORCID iD, name and alternative names, emails and the names of the institutions they are affiliated with.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
• query string nullable — Advanced raw search expression with field-scoped terms combined with AND/OR, e.g. 'family-name:Smith AND keyword:genomics'. Use the dedicated filter fields below for simple searches; this field is combined with them using AND. (examples: "family-name:Smith AND given-names:John")
• given_names string nullable — Researcher given (first) name
• family_name string nullable — Researcher family (last) name
• given_and_family_names string nullable — Match against the researcher's combined given and family name
• credit_name string nullable — Published / credit name of the researcher
• other_names string nullable — An alternative name the researcher is also known by
• biography string nullable — Text appearing in the researcher's biography
• email string nullable — Public email address of the researcher
• keyword string nullable — A research keyword listed on the researcher profile
• text string nullable — Free-text match across all profile fields
• affiliation_org_name string nullable — Name of any (current or past) affiliated organization
• current_institution_name string nullable — Name of a current employment affiliation organization
• past_institution_name string nullable — Name of a past employment affiliation organization
• affiliation_org_id string nullable — ROR id of an affiliated organization. Accepts the bare ROR id or the full ror.org URL.
• ringgold_org_id string nullable — Ringgold id of an affiliated organization
• grid_org_id string nullable — GRID id of an affiliated organization
• work_titles string nullable — Title of one of the researcher's works
• doi string nullable — A DOI of one of the researcher's works
• doi_self string nullable — A DOI of a work where the researcher is the primary author (self relationship)
• pmid string nullable — A PubMed id (PMID) of one of the researcher's works
• pmc string nullable — A PubMed Central id (PMCID) of one of the researcher's works
• orcid string nullable — Exact ORCID iD. Accepts the bare id, a dashed id, or the full orcid.org URL.
• count integer required — Number of researchers to return (min: 1)

Response

• @type string (default: "OrcidResearcherSearchResult")
• orcid string required
• given_name string nullable
• family_name string nullable
• credit_name string nullable
• other_names array (default: [])
• emails array (default: [])
• institution_names array (default: [])

Errors

• 422 — The request body did not validate Check the fields against this schema. A URN with the wrong prefix is the most common cause.
• 408 — The request ran past its time limit Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.
• 412 — The entity was not found, or a precondition failed Retrying will not help: either the entity does not exist, or the input points at a different one.
• 429 — Too many requests: a rate limit or a usage window is exhausted When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.
• 500 — Something broke on our side Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.
• 529 — Rate limit reached, or the endpoint is overloaded Wait at least 30 seconds, then retry.

Response headers

• X-Error — Error message text (present only on error)
• X-Request-ID — Unique request identifier
• X-Execution-Time — Execution time in seconds
• X-Result-Count — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
• X-Total-Available-Results — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
• X-Warning — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
• X-Retry-After — Seconds to wait before retrying. Present only on 429.