For what the Citation Checker does and when to use it, see the Citation Checker concept page. This guide will walk you through submitting a scan with the citation checker turned on, reading the summary from the completed webhook, and fetching the full per-reference results.

How it works

Each detected reference is sorted into one of two categories, and each category is validated differently: A reference is counted as validated only when the top suggestion matches the title and no checked field contradicts it. Fields that could not be checked are simply ignored - they do not count against the reference.

Get started

1

Before you begin

Before you start, ensure you have the following:
2

Installation

Choose your preferred method for making API calls.
HTTP needs no installation - call the API with any standard HTTP client, or import our Postman collection for a quicker start.
3

Login

To perform a scan, we first need to generate an access token. For that, we will use the login endpoint. The API key can be found on the Copyleaks API Dashboard.Upon successful authentication, you will receive a token that must be attached to subsequent API calls via the Authorization: Bearer <TOKEN> header. This token remains valid for 48 hours.
Response
Save this token. It is valid for 48 hours and can be reused for subsequent API calls.
4

Submit a scan with the citation checker

Submit a document for scanning and turn the citation checker on. Use the top-level properties.references.validate field and set it to true.If you omit the section entirely, validation defaults to false.This example also disables internet plagiarism scanning (scanning.internet: false) so the scan runs references-only.
Keep track of the scanId (in this case my-scan-id). You will need it to fetch the full per-reference results once the scan completes.
5

Read the summary from the completed webhook

When the scan finishes, Copyleaks sends the completed webhook to the status URL you provided. The payload reports that validation ran via scannedDocument.enabled.referencesValidation, and adds a top-level referencesValidation.summary with the counts.
Completed webhook (excerpt)
The summary fields are:
  • total - total references detected in the document.
  • academic - how many of those were academic.
  • academicValidated - academic references that were fully corroborated.
  • nonAcademicValidated - non-academic references that were fully corroborated.
The completed webhook carries the summary only. To see each individual reference, what was parsed, and which sources corroborated it, fetch the crawled version in the next step.
6

Fetch the per-reference results

The completed webhook gives you the summary only. The full per-reference results live in the crawled version of the scan.Retrieve it with the Export method, using the scanId from your submission. The exported crawled version contains a top-level referencesValidation block: the same summary plus a results array with one entry per reference.For the full field-by-field response schema, including how a reference counts as validated and the strict year matching rule, see the Citation Checker results data type.
7

Summary

You have just:
  • Submitted a scan with the citation checker turned on via references.validate
  • Read the validation counts from the completed webhook summary
  • Fetched the crawled version to inspect each parsed reference and its corroborating sources

Cross-check citations against the reference list

Citations Cross-Check adds a second check on top of validation: it compares the in-text citations with the reference list and flags citations that have no entry and entries that are never cited.
1

Turn on cross-check

Add crossCheck to the same references section. Cross-check needs the parsed reference list, so it turns on validate automatically. You can send crossCheck on its own.
Request body (excerpt)
2

Read the summary from the completed webhook

The completed webhook reports scannedDocument.enabled.citationsCrossCheck and adds a citationsCrossCheck.summary next to the validation summary.
Completed webhook (excerpt)
In this example, two citations point to an entry, one has no entry in the reference list, and one needs review because the year does not match. On the reference side, two entries are cited, one is never cited, and one needs review.
3

Fetch the per-citation results

The full results are in the same crawled version you fetch for validation, under referencesValidation.citationsCrossCheck. Each citation comes with its position in the text, what was parsed from it, its outcome, and the reference entry it points to. Each checked reference entry lists the citations that cite it.

Important notes

  • A reference list is required. If the document has no reference list, citationsCrossCheck is null.
  • Large reference lists are skipped. A reference list with more than 200 entries is not validated, and citationsCrossCheck is null.
  • Fewer than 3 citations, no reference flags. Many documents with a reference list barely cite in the text. When a document has fewer than 3 in-text citations, its citations are still checked, but the reference entries are not judged: references is empty and summary.references.total is 0.
  • Not every entry is checked. Entries without a recognizable author, such as some web pages, are left out of references. A missing entry means “not checked”, not “cited”.
  • Needs review is not a verdict. It marks a close but inexact match, most often the right author with the wrong year. Show it to a person rather than treating it as an error.
  • Links use indexes. matchedReferenceId and referenceId point into referencesValidation.results, and citedBy lists citation id values.
  • Empty fields are omitted. A citation with no entry in the reference list has no matchedReferenceId, and parsed.year or parsed.numeric are left out when they do not apply. Treat a missing field as null.

Next steps

How the Citation Checker Works

Understand the concepts behind reference detection, parsing, and corroboration before you build.

Citation Checker Results

The full field reference for the summary and per-reference results, including signals and suggestions.

Detect AI-Generated Content

Run AI detection on uploaded documents as part of a full authenticity scan.

Check for Plagiarism

Submit text or files and get a plagiarism report with matched sources.