# Validate References

> A guide on how to validate the references and citations in a document using the Copyleaks API.

For what References Validation does and when to use it, see the [References Validation](/concepts/features/references-validation) concept page.

This guide will walk you through submitting a scan with reference validation 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:

| Reference type | How Copyleaks validates it | What you get back |
| :--- | :--- | :--- |
| **Academic** _(papers, journal articles)_ | Looked up in the Copyleaks academic citation index by title, then corroborated on year and authors. | Parsed fields plus matching source suggestions with per-field signals. |
| **Non-academic** _(web pages, docs, blogs, encyclopedias)_ | The cited URL is fetched live and its title, year, and authors are compared to what was cited. | Parsed fields plus the fetched source as a suggestion with per-field signals. |

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

<Steps>
  <Step title="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](https://api.copyleaks.com/signup)**.
    - You can find your API key on the **[API Dashboard](https://api.copyleaks.com/dashboard)**.
  </Step>

  <Step title="Installation">
    <InstallSDKs />
  </Step>

  <Step title="Login">
    <GuideLogin />
  </Step>

  <Step title="Submit a scan with reference validation">

    Submit a document for scanning and turn reference validation 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.

    <CodeGroup>
        ```http title="HTTP" icon="globe"
        PUT https://api.copyleaks.com/v3/scans/submit/file/my-scan-id
        Content-Type: application/json
        Authorization: Bearer <YOUR_AUTH_TOKEN>

        {
          "base64": "VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQu",
          "filename": "paper_with_references.txt",
          "properties": {
            "webhooks": {
              "status": "https://your-server.com/webhook/{STATUS}"
            },
            "scanning": {
              "internet": false
            },
            "references": {
              "validate": true
            }
          }
        }
        ```
        ```bash title="cURL" icon="terminal"
        curl -X PUT "https://api.copyleaks.com/v3/scans/submit/file/my-scan-id" \
             -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
             -H "Content-Type: application/json" \
             -d '{
                   "base64": "VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQu",
                   "filename": "paper_with_references.txt",
                   "properties": {
                     "webhooks": {
                       "status": "https://your-server.com/webhook/{STATUS}"
                     },
                     "scanning": {
                       "internet": false
                     },
                     "references": {
                       "validate": true
                     }
                   }
                 }'
        ```
        ```python title="Python" icon="python"
        import requests
        import base64

        # Document content (your text with references)
        document_content = "This is a test document with references."
        base64_content = base64.b64encode(document_content.encode()).decode('utf-8')

        url = "https://api.copyleaks.com/v3/scans/submit/file/my-scan-id"
        payload = {
            "base64": base64_content,
            "filename": "paper_with_references.txt",
            "properties": {
                "webhooks": {
                    "status": "https://your-server.com/webhook/{STATUS}"
                },
                "scanning": {
                    "internet": False
                },
                "references": {
                    "validate": True
                }
            }
        }
        headers = {
            "Authorization": "Bearer <YOUR_AUTH_TOKEN>",
            "Content-Type": "application/json"
        }

        response = requests.put(url, json=payload, headers=headers)
        print(response.json())
        ```
        ```javascript title="JavaScript" icon="square-js"
        const axios = require('axios');

        const url = 'https://api.copyleaks.com/v3/scans/submit/file/my-scan-id';
        const headers = {
            'Authorization': 'Bearer <YOUR_AUTH_TOKEN>',
            'Content-Type': 'application/json'
        };

        const data = {
            base64: "VGhpcyBpcyBhIHRlc3QgZG9jdW1lbnQu",
            filename: "paper_with_references.txt",
            properties: {
                webhooks: {
                    status: "https://your-server.com/webhook/{STATUS}"
                },
                scanning: {
                    internet: false
                },
                references: {
                    validate: true
                }
            }
        };

        axios.put(url, data, { headers })
            .then(response => console.log(response.data))
            .catch(error => console.error(error));
        ```
        ```java title="Java" icon="java"
        import classes.Copyleaks;
        import models.submissions.CopyleaksFileSubmissionModel;
        import models.submissions.properties.*;
        import java.util.Base64;
        import java.nio.charset.StandardCharsets;

        String scanId = "my-scan-id";
        String base64Content = Base64.getEncoder().encodeToString("This is a test document with references.".getBytes(StandardCharsets.UTF_8));

        // Create submission properties
        SubmissionProperties properties = new SubmissionProperties(new SubmissionWebhooks("https://your-server.com/webhook/{STATUS}"));

        // Disable plagiarism so the scan runs references-only
        SubmissionScanning scanning = new SubmissionScanning();
        scanning.setInternet(false);
        properties.setScanning(scanning);

        // Turn reference validation on
        SubmissionReferences references = new SubmissionReferences();
        references.setValidate(true);
        properties.setReferences(references);

        // Create and submit the file
        CopyleaksFileSubmissionModel submission = new CopyleaksFileSubmissionModel(base64Content, "paper_with_references.txt", properties);

        Copyleaks.submitFile(authToken, scanId, submission);
        System.out.println("Scan submitted with reference validation.");
        ```
    </CodeGroup>

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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.

    ```json title="Completed webhook (excerpt)"
    {
      "scannedDocument": {
        "enabled": {
          "referencesValidation": true
        }
      },
      "referencesValidation": {
        "summary": {
          "total": 2,
          "academic": 1,
          "academicValidated": 1,
          "nonAcademicValidated": 0
        }
      }
    }
    ```

    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.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Fetch the per-reference results">

    The completed webhook gives you the summary only. The full per-reference results live in the [crawled version](/reference/data-types/authenticity/results/crawled-version) of the scan.

    Retrieve it with the [Export method](/reference/actions/downloads/export), 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 [References Validation results](/reference/data-types/authenticity/results/crawled-version#references-validation) data type.
  </Step>

  <Step title="Summary">
    You have just:

    - Submitted a scan with reference validation 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
  </Step>
</Steps>

## Next steps
<CardGroup cols={2}>
  <Card title="How References Validation Works" icon="book-open-cover" href="/concepts/features/references-validation">
    Understand the concepts behind reference detection, parsing, and corroboration before you build.
  </Card>
  <Card title="References Validation Results" icon="list-check" href="/reference/data-types/authenticity/results/crawled-version#references-validation">
    The full field reference for the summary and per-reference results, including signals and suggestions.
  </Card>
  <Card title="Detect AI-Generated Content" icon="robot" href="/guides/authenticity/detect-ai-generated-content">
    Run AI detection on uploaded documents as part of a full authenticity scan.
  </Card>
  <Card title="Check for Plagiarism" icon="magnifying-glass" href="/guides/authenticity/detect-plagiarism-text">
    Submit text or files and get a plagiarism report with matched sources.
  </Card>
</CardGroup>