Results and Callbacks

Receiving Results via Callback

When the analysis completes (typically 2-5 minutes), ReviewerZero sends a POST request to the callback_url you provided.

Callback Request Headers

Callback Request Body

The JSON body contains the analysis results. By default (payload_detail=issues_only) the item arrays inside project.reports[].reportData and integrity.files[] contain only the red ("needs review") findings — retracted references, decision-flipping statistical errors, high-confidence AI text, failed author verification, AI-provenance or web-matched figures, high-priority peer-review issues — while integrity.issueSummary always reports the complete issue counts for every dimension (high, medium, totalAnalyzed). With payload_detail=full, every analyzed item is included. See Callback Payload Reference for the structure.

Your Callback Endpoint

Your endpoint should:

1. Return 200 OK (or any 2xx status) to acknowledge receipt
2. Optionally verify the X-ReviewerZero-Signature-V2 and X-ReviewerZero-Timestamp headers (recommended)

If your endpoint returns a non-2xx status or is unreachable, ReviewerZero attempts delivery up to 3 times with exponential backoff (1s, 2s delays).

Callback Payload Reference

The example below shows the default payload_detail=issues_only shape. With payload_detail=full, the structure is identical but the item arrays (reports[].reportData.validation_results, integrity.files[].statchecks, authors, figures, and so on) contain every analyzed item instead of only the red ones.

{
  "event": "review.completed",
  "review_id": "proj_a1b2c3d4e5",
  "payload_detail": "issues_only",
  "project": {
    "id": "proj_a1b2c3d4e5",
    "name": "manuscript.pdf",
    "description": null,
    "status": "finished",
    "createdAt": "2026-03-15T10:30:00.000Z",
    "updatedAt": "2026-03-15T10:35:00.000Z",
    "targetJournalOrConference": null,
    "generatePeerReviewReport": true,
    "generateResearchIntegrityReport": true,
    "generateJournalRecommendation": false,
    "reports": [
      {
        "id": "rpt_xyz",
        "reportType": "review",
        "reportData": { "...": "AI peer review results (red items only in issues_only mode)" },
        "createdAt": "2026-03-15T10:34:00.000Z"
      },
      {
        "id": "rpt_abc",
        "reportType": "references",
        "reportData": { "...": "reference validation results (red items only in issues_only mode)" },
        "createdAt": "2026-03-15T10:34:30.000Z"
      }
    ],
    "user": { "id": "usr_...", "name": "...", "image": null },
    "organization": { "id": "org_publisher_acme", "name": "Acme Publishing", "slug": "acme", "logo": null }
  },
  "integrity": {
    "projectId": "proj_a1b2c3d4e5",
    "files": [
      {
        "id": "pf_...",
        "fileType": "application/pdf",
        "pages": [{ "pageNumber": 1, "publicUrl": "..." }]
      }
    ],
    "issueSummary": {
      "highTotal": 2,
      "mediumTotal": 5,
      "total": 7,
      "dimensions": [
        {
          "dimension": "statistics",
          "label": "Statistical Checks",
          "issueCount": 1,
          "high": 1,
          "medium": 0,
          "totalAnalyzed": 15,
          "totalAnalyzedDisplay": "15 statistics"
        },
        {
          "dimension": "figures",
          "label": "Figure Integrity",
          "issueCount": 1,
          "high": 1,
          "medium": 0,
          "totalAnalyzed": 8,
          "totalAnalyzedDisplay": "8 figures"
        }
      ]
    }
  },
  "report_url": "https://www.reviewerzero.ai/app/review/proj_a1b2c3d4e5",
  "dismissed_items": [
    { "itemType": "peer-review", "itemId": "review-issue-2" }
  ],
  "timestamp": "2026-03-15T10:35:01.000Z"
}

Key Fields

What counts as "red" (needs review)?

The issues_only payload keeps exactly the items the ReviewerZero report marks red:

In addition, integrity.files[].citationWorthiness (sentences flagged for problematic citation usage — a claim that needs a citation, or a citation where none is expected) is filtered to flagged items; these are counted in integrity.issueSummary.citations but are not part of the dimensions matrix.

Amber ("worth verifying") and green ("verified") items are excluded from the arrays; amber items are still counted in integrity.issueSummary (medium), and green items are reflected in totalAnalyzed.

Items an editor dismissed in the ReviewerZero app are excluded from the issues_only arrays and from every integrity.issueSummary count. In payload_detail=full they still appear in the report arrays (so "full" is a complete record), but each is listed in the top-level dismissed_items array so you can filter them out and reconcile against the counts.

Polling (Alternative)

If you prefer polling over callbacks (or need to re-fetch results), you can use:

Endpoint: GET https://www.reviewerzero.ai/api/v1/reviews/{review_id}

curl https://www.reviewerzero.ai/api/v1/reviews/proj_a1b2c3d4e5 \
  -H "Authorization: Bearer rz_abc123def456"

The response defaults to payload_detail=issues_only (red items only). To fetch every analyzed item:

curl "https://www.reviewerzero.ai/api/v1/reviews/proj_a1b2c3d4e5?payload_detail=full" \
  -H "Authorization: Bearer rz_abc123def456"

Check project.status:

• open -- not yet started
• processing -- analysis in progress
• finished -- results are ready