API Reference

Verify academic references programmatically using the SourceVerify API.

Need an API key? Get one from your account

Two-Step Process

Reference verification uses async processing:

Submit references → receive job IDs
Poll for results using those job IDs (typically ready in 10-45 seconds)

Authentication

Include your API key in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_KEY

1. Submit References

POST/api/verify-reference

Submit 1-20 academic references for verification. Returns job IDs immediately. Up to 15 verified concurrently.

Request Body

Parameter	Type	Description
`references`	`string[]`	Array of 1-20 reference strings (max 1200 chars each)

Response

Field	Type	Description
`jobIds`	`string[]`	Job IDs for tracking verification (one per reference)
`documentId`	`string`	Document ID grouping these references
`message`	`string`	Confirmation message
`tokensAvailable`	`number`	Remaining token balance after this submission

2. Get Results

POST/api/verify-reference/results

Poll for the status and results of your verification jobs. Pass up to 50 job IDs per request.

Request Body

Parameter	Type	Description
`jobIds`	`string[]`	Job IDs from the submit endpoint (max 50)

Response

Field	Type	Description
`jobs`	`array`	Array of job objects
`jobs[].id`	`string`	The job ID
`jobs[].state`	`string`	"completed", "active", "waiting", "failed", or "not-found"
`jobs[].error`	`string \| null`	Error message if the job failed
`jobs[].progress`	`object \| null`	Live progress while job is active (step + message)

Result Object `jobs[].result`

Present when state is "completed". Contains the full verification result.

Field	Type	Description
`status`	`string`	"verified", "verified-with-error", "unverified", or "needs-human"
`message`	`string`	Human-readable explanation with a Reference Match line, Summary, and Details sections (Markdown)
`reference`	`string`	Corrected APA7 reference (if verified) or a status message (if unverified)
`field_results`	`object`	Per-field verification labels (see Field Labels below)
`match_set_size`	`number`	Number of fields that matched evidence
`contained_set_size`	`number`	Number of fields with partial matches
`verificationGraph`	`object \| null`	Verification reasoning graph (see Verification Graph below)

Verification Graph `verificationGraph`

A structured reasoning trace that shows exactly how the verification decision was made. Contains four types of nodes connected by edges, allowing you to inspect every step of the process.

Field	Type	Description
`version`	`string`	"1.0"
`createdAt`	`string`	ISO 8601 timestamp
`citationId`	`string`	ID of the citation node (e.g., "cit_1")
`nodes`	`array`	All nodes in the graph (see Node Types below)
`edges`	`array`	Connections between nodes. Each has `source`, `target` (node IDs), and `type` ("FOUND" or "COMPARED")
`metadata`	`object`	`totalCandidates`, `sourcesQueried` (e.g., "OPENALEX", "GOOGLE", "SCHOLAR", "URL"), `processingTimeMs`

Node Types

Type	ID Pattern	Description	Key Fields
`CITATION`	`cit_1`	The original reference being verified	`rawText`, `parsedFields` (title, authors, year, venue, doi, url)
`CANDIDATE`	`cand_1`	A potential match found in evidence	`sourceType`, `candidateFields`, `comparisonSummary` (matches, contradictions, etc.)
`COMPARISON`	`cmp_1`	A single field comparison between citation and candidate	`fieldName`, `result` (field label), `citationValue`, `candidateValue`, `reasoning`
`RESULT`	`result_1`	The final verification decision	`status`, `bestCandidateId`, `reasoning`, `matchSetSize`

Graph Flow

CITATION —FOUND→ CANDIDATE —COMPARED→ COMPARISON (per field)

Each candidate has 5 comparison nodes (title, authors, year, venue, identifier). The result node references the best candidate by ID.

Example (condensed)

{
  "version": "1.0",
  "createdAt": "2026-02-12T10:30:00.000Z",
  "citationId": "cit_1",
  "nodes": [
    {
      "id": "cit_1",
      "type": "CITATION",
      "rawText": "Kuhn, T. S. (1962). The Structure of ...",
      "parsedFields": {
        "title": "The Structure of Scientific Revolutions",
        "authors": ["Kuhn"],
        "year": 1962,
        "venue": "University of Chicago Press",
        "doi": null,
        "url": null
      }
    },
    {
      "id": "cand_1",
      "type": "CANDIDATE",
      "sourceType": "OPENALEX",
      "sourceSuccess": true,
      "candidateFields": {
        "title": "The Structure of Scientific Revolutions",
        "authors": ["Kuhn, Thomas S."],
        "year": 1962,
        "venue": "University of Chicago Press"
      },
      "comparisonSummary": {
        "matches": 4, "contains": 0,
        "absent": 1, "unconfirmed": 0,
        "contradictions": 0
      }
    },
    {
      "id": "cmp_1",
      "type": "COMPARISON",
      "candidateId": "cand_1",
      "fieldName": "title",
      "result": "MATCH",
      "citationValue": "The Structure of Scientific Revolutions",
      "candidateValue": "The Structure of Scientific Revolutions",
      "reasoning": "Titles are identical after normalization"
    },
    ...
    {
      "id": "result_1",
      "type": "RESULT",
      "status": "verified",
      "bestCandidateId": "cand_1",
      "reasoning": "4 of 5 fields match (identifier absent)",
      "matchSetSize": 4,
      "containedSetSize": 0
    }
  ],
  "edges": [
    { "source": "cit_1", "target": "cand_1", "type": "FOUND" },
    { "source": "cand_1", "target": "cmp_1", "type": "COMPARED" },
    ...
  ],
  "metadata": {
    "totalCandidates": 1,
    "sourcesQueried": ["OpenAlex", "GOOGLE"],
    "processingTimeMs": 12450
  }
}

Field Results `field_results`

Each field in the citation is compared against evidence and assigned a label.

Field	Description
`title`	Article/book title
`authors`	Author surnames
`year`	Publication year
`venue`	Journal, publisher, or conference
`identifier`	DOI or URL

Field Labels

Each field is assigned one of these labels based on how it compares to the evidence found.

	Label	Meaning
	`MATCH`	Evidence confirms this field
	`MATCH_WITH_TYPO`	Match found but with minor typos in the citation
	`CONTAINS`	Partial overlap (e.g., abbreviated journal name)
	`ABSENT`	Citation does not provide this field
	`UNCONFIRMED`	Could not verify (no evidence found for this field)
	`CONTRADICTION`	Evidence shows a different value than the citation claims

3. Check Balance

GET/api/verify-reference/balance

Check your current token balance and plan information.

Response

Field	Type	Description
`totalAvailable`	`number`	Total tokens available to spend
`subscriptionTokens`	`number`	Tokens from subscription plan
`purchasedTokens`	`number`	Tokens from one-time purchases
`pendingTokens`	`number`	Tokens reserved for jobs currently in progress
`plan`	`string \| null`	Current subscription plan name
`context`	`string`	"user" or "team"
`name`	`string \| null`	Account display name
`email`	`string \| null`	Account email (optional)

4. Verification History

GET/api/verify-reference/history

Retrieve past verification documents and their references.

Query Parameters

Parameter	Type	Description
`limit`	`number`	Max documents to return (default 20, max 50)
`offset`	`number`	Number of documents to skip (default 0)

Response

Field	Type	Description
`documents`	`array`	Array of verification documents
`documents[].id`	`string`	Document ID
`documents[].title`	`string`	Document title
`documents[].status`	`string`	"PENDING", "PROCESSING", "COMPLETED", or "FAILED"
`documents[].referenceCount`	`number`	Number of references in the document
`documents[].createdAt`	`string`	ISO 8601 timestamp
`documents[].references`	`array`	Each reference with `id`, `rawText`, `status`, `parsedData`, `verifiedAt`
`pagination`	`object`	`total`, `limit`, `offset`, `hasMore`

5. Cancel Verification

POST/api/verify-reference/cancel

Cancel verification jobs. You can cancel all remaining jobs in a document, or cancel specific jobs by ID. Tokens for cancelled jobs are automatically refunded.

Request Body

Provide documentId, jobIds, or both. At least one is required.

Parameter	Type	Description
`documentId`	`string`	Cancel all remaining jobs in this document
`jobIds`	`string[]`	Cancel specific jobs by ID (max 50)

Response

Field	Type	Description
`success`	`boolean`	Whether the cancellation succeeded
`cancelledJobs`	`number`	Number of jobs that were cancelled
`refundedTokens`	`number`	Tokens refunded for cancelled jobs
`documentId`	`string \| null`	The affected document ID
`documentStatus`	`string \| null`	New document status if changed ("COMPLETED" or "FAILED")

Complete Example

# Step 1: Submit references for verification
curl -X POST https://sourceverify.ai/api/verify-reference \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_..." \
  -d '{
    "references": [
      "Kuhn, T. S. (1962). The Structure of Scientific Revolutions. University of Chicago Press.",
      "Einstein, A. (1905). On the Electrodynamics of Moving Bodies. Annalen der Physik."
    ]
  }'

# Step 2: Check results using job IDs
curl -X POST https://sourceverify.ai/api/verify-reference/results \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_..." \
  -d '{"jobIds":["7","8"]}'

Verification Statuses

Status	Meaning
`verified`	Reference confirmed by evidence across all fields
`verified-with-error`	Reference exists but has errors (e.g., wrong year, misspelled author)
`needs-human`	Ambiguous evidence; requires human judgment
`unverified`	No matching reference found in evidence

Rate Limiting

Unauthenticated requests are rate limited to 10 requests per minute per IP. Authenticated requests (with a valid API key) are not rate limited. Each request can contain up to 20 references. Exceeding the rate limit returns a 429 status code.

HTTP Status Codes

`200`	Success
`400`	Invalid request body or parameters
`401`	Invalid or missing API key
`402`	Insufficient tokens
`403`	Invalid or expired API key
`429`	Rate limit exceeded

API Reference

Verify academic references programmatically using the SourceVerify API.

Need an API key? Get one from your account

Two-Step Process

Reference verification uses async processing:

Submit references → receive job IDs
Poll for results using those job IDs (typically ready in 10-45 seconds)

Authentication

Include your API key in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_KEY

1. Submit References

POST/api/verify-reference

Submit 1-20 academic references for verification. Returns job IDs immediately. Up to 15 verified concurrently.

Request Body

Parameter	Type	Description
`references`	`string[]`	Array of 1-20 reference strings (max 1200 chars each)

Response

Field	Type	Description
`jobIds`	`string[]`	Job IDs for tracking verification (one per reference)
`documentId`	`string`	Document ID grouping these references
`message`	`string`	Confirmation message
`tokensAvailable`	`number`	Remaining token balance after this submission

2. Get Results

POST/api/verify-reference/results

Poll for the status and results of your verification jobs. Pass up to 50 job IDs per request.

Request Body

Parameter	Type	Description
`jobIds`	`string[]`	Job IDs from the submit endpoint (max 50)

Response

Field	Type	Description
`jobs`	`array`	Array of job objects
`jobs[].id`	`string`	The job ID
`jobs[].state`	`string`	"completed", "active", "waiting", "failed", or "not-found"
`jobs[].error`	`string \| null`	Error message if the job failed
`jobs[].progress`	`object \| null`	Live progress while job is active (step + message)

Result Object `jobs[].result`

Present when state is "completed". Contains the full verification result.

Field	Type	Description
`status`	`string`	"verified", "verified-with-error", "unverified", or "needs-human"
`message`	`string`	Human-readable explanation with a Reference Match line, Summary, and Details sections (Markdown)
`reference`	`string`	Corrected APA7 reference (if verified) or a status message (if unverified)
`field_results`	`object`	Per-field verification labels (see Field Labels below)
`match_set_size`	`number`	Number of fields that matched evidence
`contained_set_size`	`number`	Number of fields with partial matches
`verificationGraph`	`object \| null`	Verification reasoning graph (see Verification Graph below)

Verification Graph `verificationGraph`

A structured reasoning trace that shows exactly how the verification decision was made. Contains four types of nodes connected by edges, allowing you to inspect every step of the process.

Field	Type	Description
`version`	`string`	"1.0"
`createdAt`	`string`	ISO 8601 timestamp
`citationId`	`string`	ID of the citation node (e.g., "cit_1")
`nodes`	`array`	All nodes in the graph (see Node Types below)
`edges`	`array`	Connections between nodes. Each has `source`, `target` (node IDs), and `type` ("FOUND" or "COMPARED")
`metadata`	`object`	`totalCandidates`, `sourcesQueried` (e.g., "OPENALEX", "GOOGLE", "SCHOLAR", "URL"), `processingTimeMs`

Node Types

Type	ID Pattern	Description	Key Fields
`CITATION`	`cit_1`	The original reference being verified	`rawText`, `parsedFields` (title, authors, year, venue, doi, url)
`CANDIDATE`	`cand_1`	A potential match found in evidence	`sourceType`, `candidateFields`, `comparisonSummary` (matches, contradictions, etc.)
`COMPARISON`	`cmp_1`	A single field comparison between citation and candidate	`fieldName`, `result` (field label), `citationValue`, `candidateValue`, `reasoning`
`RESULT`	`result_1`	The final verification decision	`status`, `bestCandidateId`, `reasoning`, `matchSetSize`

Graph Flow

CITATION —FOUND→ CANDIDATE —COMPARED→ COMPARISON (per field)

Each candidate has 5 comparison nodes (title, authors, year, venue, identifier). The result node references the best candidate by ID.

Example (condensed)

{
  "version": "1.0",
  "createdAt": "2026-02-12T10:30:00.000Z",
  "citationId": "cit_1",
  "nodes": [
    {
      "id": "cit_1",
      "type": "CITATION",
      "rawText": "Kuhn, T. S. (1962). The Structure of ...",
      "parsedFields": {
        "title": "The Structure of Scientific Revolutions",
        "authors": ["Kuhn"],
        "year": 1962,
        "venue": "University of Chicago Press",
        "doi": null,
        "url": null
      }
    },
    {
      "id": "cand_1",
      "type": "CANDIDATE",
      "sourceType": "OPENALEX",
      "sourceSuccess": true,
      "candidateFields": {
        "title": "The Structure of Scientific Revolutions",
        "authors": ["Kuhn, Thomas S."],
        "year": 1962,
        "venue": "University of Chicago Press"
      },
      "comparisonSummary": {
        "matches": 4, "contains": 0,
        "absent": 1, "unconfirmed": 0,
        "contradictions": 0
      }
    },
    {
      "id": "cmp_1",
      "type": "COMPARISON",
      "candidateId": "cand_1",
      "fieldName": "title",
      "result": "MATCH",
      "citationValue": "The Structure of Scientific Revolutions",
      "candidateValue": "The Structure of Scientific Revolutions",
      "reasoning": "Titles are identical after normalization"
    },
    ...
    {
      "id": "result_1",
      "type": "RESULT",
      "status": "verified",
      "bestCandidateId": "cand_1",
      "reasoning": "4 of 5 fields match (identifier absent)",
      "matchSetSize": 4,
      "containedSetSize": 0
    }
  ],
  "edges": [
    { "source": "cit_1", "target": "cand_1", "type": "FOUND" },
    { "source": "cand_1", "target": "cmp_1", "type": "COMPARED" },
    ...
  ],
  "metadata": {
    "totalCandidates": 1,
    "sourcesQueried": ["OpenAlex", "GOOGLE"],
    "processingTimeMs": 12450
  }
}

Field Results `field_results`

Each field in the citation is compared against evidence and assigned a label.

Field	Description
`title`	Article/book title
`authors`	Author surnames
`year`	Publication year
`venue`	Journal, publisher, or conference
`identifier`	DOI or URL

Field Labels

Each field is assigned one of these labels based on how it compares to the evidence found.

	Label	Meaning
	`MATCH`	Evidence confirms this field
	`MATCH_WITH_TYPO`	Match found but with minor typos in the citation
	`CONTAINS`	Partial overlap (e.g., abbreviated journal name)
	`ABSENT`	Citation does not provide this field
	`UNCONFIRMED`	Could not verify (no evidence found for this field)
	`CONTRADICTION`	Evidence shows a different value than the citation claims

3. Check Balance

GET/api/verify-reference/balance

Check your current token balance and plan information.

Response

Field	Type	Description
`totalAvailable`	`number`	Total tokens available to spend
`subscriptionTokens`	`number`	Tokens from subscription plan
`purchasedTokens`	`number`	Tokens from one-time purchases
`pendingTokens`	`number`	Tokens reserved for jobs currently in progress
`plan`	`string \| null`	Current subscription plan name
`context`	`string`	"user" or "team"
`name`	`string \| null`	Account display name
`email`	`string \| null`	Account email (optional)

4. Verification History

GET/api/verify-reference/history

Retrieve past verification documents and their references.

Query Parameters

Parameter	Type	Description
`limit`	`number`	Max documents to return (default 20, max 50)
`offset`	`number`	Number of documents to skip (default 0)

Response

Field	Type	Description
`documents`	`array`	Array of verification documents
`documents[].id`	`string`	Document ID
`documents[].title`	`string`	Document title
`documents[].status`	`string`	"PENDING", "PROCESSING", "COMPLETED", or "FAILED"
`documents[].referenceCount`	`number`	Number of references in the document
`documents[].createdAt`	`string`	ISO 8601 timestamp
`documents[].references`	`array`	Each reference with `id`, `rawText`, `status`, `parsedData`, `verifiedAt`
`pagination`	`object`	`total`, `limit`, `offset`, `hasMore`

5. Cancel Verification

POST/api/verify-reference/cancel

Cancel verification jobs. You can cancel all remaining jobs in a document, or cancel specific jobs by ID. Tokens for cancelled jobs are automatically refunded.

Request Body

Provide documentId, jobIds, or both. At least one is required.

Parameter	Type	Description
`documentId`	`string`	Cancel all remaining jobs in this document
`jobIds`	`string[]`	Cancel specific jobs by ID (max 50)

Response

Field	Type	Description
`success`	`boolean`	Whether the cancellation succeeded
`cancelledJobs`	`number`	Number of jobs that were cancelled
`refundedTokens`	`number`	Tokens refunded for cancelled jobs
`documentId`	`string \| null`	The affected document ID
`documentStatus`	`string \| null`	New document status if changed ("COMPLETED" or "FAILED")

Complete Example

# Step 1: Submit references for verification
curl -X POST https://sourceverify.ai/api/verify-reference \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_..." \
  -d '{
    "references": [
      "Kuhn, T. S. (1962). The Structure of Scientific Revolutions. University of Chicago Press.",
      "Einstein, A. (1905). On the Electrodynamics of Moving Bodies. Annalen der Physik."
    ]
  }'

# Step 2: Check results using job IDs
curl -X POST https://sourceverify.ai/api/verify-reference/results \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_..." \
  -d '{"jobIds":["7","8"]}'

Verification Statuses

Status	Meaning
`verified`	Reference confirmed by evidence across all fields
`verified-with-error`	Reference exists but has errors (e.g., wrong year, misspelled author)
`needs-human`	Ambiguous evidence; requires human judgment
`unverified`	No matching reference found in evidence

Rate Limiting

HTTP Status Codes

`200`	Success
`400`	Invalid request body or parameters
`401`	Invalid or missing API key
`402`	Insufficient tokens
`403`	Invalid or expired API key
`429`	Rate limit exceeded

Reference Verification API | SourceVerify

API Reference

Two-Step Process

Authentication

1. Submit References

Request Body

Response

2. Get Results

Request Body

Response

Result Object jobs[].result

Verification Graph verificationGraph

Node Types

Field Results field_results

Field Labels

3. Check Balance

Response

4. Verification History

Query Parameters

Response

5. Cancel Verification

Request Body

Response

Complete Example

Verification Statuses

Rate Limiting

HTTP Status Codes

API Reference

Two-Step Process

Authentication

1. Submit References

Request Body

Response

2. Get Results

Request Body

Response

Result Object jobs[].result

Verification Graph verificationGraph

Node Types

Field Results field_results

Field Labels

3. Check Balance

Response

4. Verification History

Query Parameters

Response

5. Cancel Verification

Request Body

Response

Complete Example

Verification Statuses

Rate Limiting

HTTP Status Codes

Result Object `jobs[].result`

Verification Graph `verificationGraph`

Field Results `field_results`

Result Object `jobs[].result`

Verification Graph `verificationGraph`

Field Results `field_results`