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:
- An active Copyleaks account. If you don’t have one, sign up for free.
- You can find your API key on the API Dashboard.
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 The summary fields are:
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)
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 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.
scannedDocument.enabled.citationsCrossCheck and adds a citationsCrossCheck.summary next to the validation summary.Completed webhook (excerpt)
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,
citationsCrossCheckisnull. - Large reference lists are skipped. A reference list with more than 200 entries is not validated, and
citationsCrossCheckisnull. - 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:
referencesis empty andsummary.references.totalis0. - 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.
matchedReferenceIdandreferenceIdpoint intoreferencesValidation.results, andcitedBylists citationidvalues. - Empty fields are omitted. A citation with no entry in the reference list has no
matchedReferenceId, andparsed.yearorparsed.numericare left out when they do not apply. Treat a missing field asnull.
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.

