Finding Reviewers

Suggest peer reviewers for a manuscript: researchers who recently published close to it, each with a contact email, with the authors' co-authors and colleagues left out. The search runs in the background. Start it, then poll it until it ends.

Start a search: POST https://www.reviewerzero.ai/api/v1/reviewer-searches

curl -X POST https://www.reviewerzero.ai/api/v1/reviewer-searches \
  -H "Authorization: Bearer rz_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Predicting scientific success",
    "abstract": "We research scientists often worry about the future of our careers...",
    "keywords": ["science of science", "citation dynamics"],
    "authors": [
      { "name": "Daniel Acuna", "affiliation": "University of Colorado Boulder", "orcid": "0000-0002-7765-1595" }
    ],
    "reviewers": 10
  }'

Request fields:

Field	Type	Default	Description
`title`	string	required	The manuscript's title
`abstract`	string	required	The manuscript's abstract, 50 to 6,000 characters
`keywords`	string[]	`[]`	Up to 12 keywords; they widen the search beyond the wording of the abstract
`authors`	object[]	`[]`	Up to 40 authors, each with `name` and optionally `affiliation` and `orcid`. Without authors, conflicts of interest are not checked. An ORCID iD makes that check much more reliable.
`reviewers`	integer	`20`	How many reviewers to return, 5 to 20
`papers_since`	integer	ten years ago	Earliest publication year used for matching
`conflict_window_years`	integer	`5`	Co-authorship with an author this recent counts as a conflict of interest
`active_within_years`	integer	`3`	People with no paper in this window are left out
`recognized_journals_only`	boolean	`false`	Leave out people who mostly publish in journals that no recognized journal register lists

The response is 202 with the new search (status is queued). Keep its search_id.

Follow the search: GET https://www.reviewerzero.ai/api/v1/reviewer-searches/{search_id}

Poll every 10 to 30 seconds until status is completed, failed or canceled. While the search runs, progress says which step it is on, with a label you can show:

{
  "search_id": "52dac83b-d83a-4a35-a353-c5db640030c7",
  "status": "running",
  "progress": {
    "step": "contacts",
    "label": "Confirming identities and contact emails",
    "reviewers_found": 4,
    "reviewers_wanted": 10
  },
  "result": null
}

Once status is completed, result.reviewers lists the suggested reviewers, best match first:

{
  "name": "Jane Doe",
  "orcid": "0000-0001-2345-6789",
  "institution": { "name": "Example University", "country": "Canada", "ror": "https://ror.org/00example" },
  "match": "strong",
  "match_label": "Strong match",
  "acceptance": "likely",
  "acceptance_label": "Likely to accept",
  "career_stage": "mid",
  "career_label": "Mid-career",
  "h_index": 18,
  "last_publication_year": 2026,
  "papers": [{ "title": "...", "year": 2025, "venue": "Scientometrics", "url": "https://doi.org/..." }],
  "links": [{ "label": "ORCID record", "url": "https://orcid.org/0000-0001-2345-6789" }],
  "email": { "address": "jane.doe@example.edu", "kind": "institutional", "confidence": "high", "label": "Institutional address" },
  "other_emails": [],
  "works_with": [],
  "group_lead": true,
  "areas": []
}

result also carries excluded (people left out, each with reasons and kinds), areas (for an interdisciplinary manuscript, the areas of expertise its review panel needs; each reviewer's areas lists the ones they cover), authors (the manuscript's authors as found, with coauthors_checked) and notes. A failed search has error set instead. The interactive documentation lists every field.

Errors: 400 names the field that is missing or out of range. 402 means no reviewer search credits remain. 429 means 20 of your searches are already waiting or running; start more once some finish. A search uses one credit when it starts; if it fails or you stop it, the credit is given back. Your searches run one at a time for each organization (or your personal account); the others stay queued until it is their turn.

List your searches: GET https://www.reviewerzero.ai/api/v1/reviewer-searches

Your searches, newest first, including the ones started from the reviewer finder page in the app. With x-organization-id, the list holds the searches you started in that organization; without it, the ones in your personal account. offset (default 0) and limit (1 to 100, default 20) page through them.

curl "https://www.reviewerzero.ai/api/v1/reviewer-searches?limit=20" \
  -H "Authorization: Bearer rz_abc123def456"

{
  "searches": [
    {
      "search_id": "52dac83b-d83a-4a35-a353-c5db640030c7",
      "title": "Predicting scientific success",
      "status": "completed",
      "created_at": "2026-10-08T17:49:31.190Z",
      "completed_at": "2026-10-08T17:50:24.086Z",
      "reviewers_found": 10
    }
  ],
  "pagination": { "total": 1, "count": 1, "offset": 0, "limit": 20, "has_more": false, "next_offset": null }
}

reviewers_found is null until a search has completed. Fetch a search's reviewers with GET /reviewer-searches/{search_id}; pass next_offset as offset for the next page.

Delete a search: DELETE https://www.reviewerzero.ai/api/v1/reviewer-searches/{search_id}

curl -X DELETE https://www.reviewerzero.ai/api/v1/reviewer-searches/52dac83b-d83a-4a35-a353-c5db640030c7 \
  -H "Authorization: Bearer rz_abc123def456"

The search is removed with its manuscript details and suggested reviewers, and the response is { "success": true, "message": "The search was deleted." }. A search still running is stopped first and its credit is given back. Deleting can't be undone: afterwards the search returns 404, as does any search that isn't yours.