API guide

Send a document from your journal system, LMS or repository and get the similarity score, the sources and a report link back. Base URL: https://vordict.com/api/v1

Getting started

  1. Your Vordict admin creates a test key under API keys (vd_test_...). Test keys return a realistic sample report and are never charged.
  2. Build and test your integration with it.
  3. Create a live key (vd_live_...) and switch. Live checks use page credits.

Institutions and publishers get keys after onboarding. Request access.

Authentication

Send the key in a header on every request. Keys are secret: keep them on your server, never in a browser or app.

Authorization: Bearer vd_live_xxxxxxxxxxxxxxxx
# or
X-API-Key: vd_live_xxxxxxxxxxxxxxxx

A key can be limited to your server's IP addresses and to a number of pages per day.

Create a check

POST /api/v1/checks with a file (multipart) or JSON text. The answer comes back at once with status queued; the result follows by webhook or polling.

curl -X POST https://vordict.com/api/v1/checks \
  -H "Authorization: Bearer $VORDICT_KEY" \
  -H "Idempotency-Key: manuscript-1234-v2" \
  -F "file=@manuscript.pdf" \
  -F "title=Effect of split nitrogen on rice" \
  -F "external_ref=manuscript-1234" \
  -F "callback_url=https://journal.example/vordict-hook" \
  -F "exclude_dois=10.1234/own.paper.5678"
FieldMeaning
file or textPDF, DOCX, DOC, ODT, RTF, PPTX, LaTeX (.tex) or TXT up to 40 MB, or plain text (JSON). Scanned PDFs without a text layer are refused (scanned_pdf) and not charged.
titleShown on the report
external_refYour own id (manuscript, submission). Returned in every response and webhook.
callback_urlhttps URL for the webhook. Defaults to the key's webhook URL.
exclude_referencestrue leaves out the reference list
exclude_quotestrue leaves out text in quotation marks
min_match_wordsLeave out matched passages shorter than this many words (0 = keep all)
exclude_owntrue leaves out matches with your account's own earlier submissions
exclude_webtrue leaves out internet pages (when internet matching is on for your account)
exclude_doisComma separated DOIs to ignore, e.g. the article's own earlier version
add_to_repositorytrue/false: store the document's fingerprint so later submissions are matched against it. Defaults to your account setting.

Filters you leave out take your account's defaults (set by the account owner). They can all be changed later, free.

Response 202:

{
  "id": "chk_6f3c2a91b0d4e8f7a1c25d90",
  "status": "queued",
  "test": false,
  "external_ref": "manuscript-1234",
  "pages": 12,
  "pages_charged": 12,
  "free_recheck": false,
  "report_url": null
}

Get a result

GET /api/v1/checks/{id} (add ?detail=1 for the matched passages as character offsets). GET /api/v1/checks?external_ref=... lists your checks.

{
  "id": "chk_6f3c2a91b0d4e8f7a1c25d90",
  "status": "completed",
  "similarity": 18.4,
  "plagiarism": 6.2,
  "ai": {"status": "done", "score": 4.8, "level": "few", "provider": "openai", "words_checked": 4980, "words_flagged": 240,
         "flagged_passages": [{"i": 7, "score": 86, "words": 128, "reason": "generic, buzzword-heavy summary"}]},
  "total_words": 5210,
  "source_count": 6,
  "similarity_original": 18.4,
  "ugc": {"level": 1, "label": "Level 1", "range": "above 10% to 40%", "meaning": "Revise the manuscript"},
  "filters": {"exclude_references": true, "exclude_quotes": false, "min_match_words": 0, "exclude_own": false,
              "exclude_sources": [], "exclude_dois": []},
  "report_url": "https://vordict.com/report/...",
  "pdf_url": "https://vordict.com/report/.../pdf",
  "receipt_url": "https://vordict.com/report/.../receipt",
  "verify_url": "https://vordict.com/verify/7KQ2M9XHTA",
  "sources": [
    {"rank": 1, "id": 812345, "title": "...", "doi": "10.3390/...", "publication": "Agronomy", "year": 2021,
     "url": "https://doi.org/10.3390/...", "words": 412, "pct": 7.91, "all_words": 430, "all_pct": 8.25,
     "own": false, "repository": false}
  ]
}

With ?detail=1 you also get all_sources (every overlapping source, before each word is given to one source), excluded_sources and segments / excluded_ranges as character offsets.

Status is one of queued, processing, completed, failed. Most checks finish within a few minutes.

plagiarism is the share of checked words in matches that need attention (no citation nearby, or cited but copied word for word at length). ai holds the AI-writing signals: score is the share of checked words in passages that read as machine-generated. It is a signal for a reviewer, not proof. ai.status can also be skipped (document too short), failed (provider unavailable; the similarity result is still complete) or missing when the step is switched off for your account. Test keys return a fixed sample.

Filters, PDF report, receipt and verification

Change the filters of a finished check at any time. The report is re-scored in a moment from the saved match data; nothing is searched again and nothing is charged. Fields you leave out keep their current value.

curl -X POST https://vordict.com/api/v1/checks/chk_.../filters \
  -H "Authorization: Bearer $VORDICT_KEY" -H "Content-Type: application/json" \
  -d '{"exclude_quotes": true, "min_match_words": 14, "exclude_sources": [812345]}'
  • GET /api/v1/checks/{id}/report.pdf: the full PDF report (summary, highlighted document, all sources).
  • GET /api/v1/checks/{id}/receipt.pdf: a one-page receipt with a QR code.
  • The QR code opens https://vordict.com/verify/<code>, where anyone can confirm the title, date, similarity, UGC 2018 level and file fingerprint (SHA-256). The document text is never shown there.
  • UGC 2018 levels: Level 0 up to 10%, Level 1 above 10% to 40%, Level 2 above 40% to 60%, Level 3 above 60%.

Webhooks

When a check finishes we POST {"event": "check.completed" | "check.failed", "check": {...}} to your callback URL. Answer with any 2xx. Failed deliveries are retried up to 5 times with growing gaps.

Every call is signed with your account's signing secret (shown to the account owner under API keys). Check it before trusting the body:

X-Vordict-Signature: sha256=HEX( HMAC_SHA256(signing_secret, raw_request_body) )
X-Vordict-Event: check.completed

Pages and charges

  • A PDF is charged by its page count; every other file type and text by every 300 words.
  • Every check costs at least 5 pages.
  • The same file again within 7 days is free ("free_recheck": true).
  • If a check fails, its pages are returned automatically.
  • Test keys never charge.
  • GET /api/v1/pricing?pages=20 tells you what a document costs on your account.

Safe retries

Send an Idempotency-Key header (any id up to 80 characters, unique per document version). If your request times out and you send it again with the same key, you get the first check back (200, header Idempotent-Replayed: true) and are not charged twice.

Account and usage

GET /api/v1/me returns your balance, limits and price. GET /api/v1/usage?from=2026-10-01&to=2026-10-31 returns checks and pages per day and per key. Every authenticated response carries X-Vordict-Pages-Remaining.

Errors

Errors are JSON: {"error": "code", "message": "text"}.

HTTPerrorWhat to do
400no_document, bad_file_type, unreadable_file, scanned_pdf, too_little_text, too_longSend a readable document with a text layer (nothing is charged for these)
409rematch_pendingAn older report is being upgraded for filters; retry in a few minutes
401invalid_api_keyCheck the key; it may be revoked
402insufficient_creditsBuy pages, or ask your Vordict admin
402billing_suspendedAn invoice is overdue; pay it to resume
403ip_not_allowedCall from an allowed server IP
413file_too_largeFiles up to 40 MB
429daily_page_limit, daily_limit_reachedTry tomorrow, or raise the key's limit

Code samples

Python

import hmac, hashlib, requests
KEY = "vd_test_..."
r = requests.post("https://vordict.com/api/v1/checks",
                  headers={"Authorization": f"Bearer {KEY}", "Idempotency-Key": "ms-1234-v1"},
                  files={"file": open("manuscript.pdf", "rb")},
                  data={"external_ref": "ms-1234", "callback_url": "https://journal.example/hook"})
check = r.json()

# in your webhook handler
def valid(secret, raw_body, header):
    want = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, header or "")

PHP

$ch = curl_init("https://vordict.com/api/v1/checks");
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer $key", "Idempotency-Key: ms-1234-v1"],
  CURLOPT_POSTFIELDS => ["file" => new CURLFile("manuscript.pdf"), "external_ref" => "ms-1234"],
]);
$check = json_decode(curl_exec($ch), true);

// webhook
$raw = file_get_contents("php://input");
$ok = hash_equals("sha256=" . hash_hmac("sha256", $raw, $secret), $_SERVER["HTTP_X_VORDICT_SIGNATURE"] ?? "");

Node.js

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("manuscript.pdf")]), "manuscript.pdf");
form.append("external_ref", "ms-1234");
const res = await fetch("https://vordict.com/api/v1/checks", {
  method: "POST", body: form,
  headers: { Authorization: `Bearer ${key}`, "Idempotency-Key": "ms-1234-v1" } });
const check = await res.json();

// webhook (express.raw body)
const want = "sha256=" + crypto.createHmac("sha256", secret).update(req.body).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(want), Buffer.from(req.get("X-Vordict-Signature") || ""));

Questions about integration: support@vordict.com