Skip to main content
GET
Get file analysis details
Retrieve comprehensive analysis results for a specific file, including signed download URLs for the original file, thumbnail, PDF analysis report, and detailed logs.

​
Permission

You can get the analysis of a file you uploaded, or of any file in your organisation if you have organisation_files:read; otherwise the API returns 404. See Permissions and API Keys.

​
Analysis Engines

The Veridox platform runs multiple analysis engines to provide a complete forensic view:
  • Context Analysis: Extracts metadata and classifies the document type.
  • Image Metadata: Analyses EXIF/JFIF data for indicators of tampering or source verification.
  • Tampering Detection: Uses advanced computer vision to identify pixel-level anomalies and digital edits.
  • AI Summary: Provides a high-level, human-readable summary of the combined findings.

​
Highlights

The highlights field contains a plain list of key findings summarising the most significant indicators from the analysis. It is omitted from the response when the analysis did not produce any highlights.

​
Previously Seen

previously_seen is true when the file is identical to one already uploaded in your organisation and Veridox reused that earlier analysis instead of analysing the file again. previously_seen_at is when the earlier file was uploaded, and is null when previously_seen is false. Files reused before these fields were introduced are dated from the earlier upload where it can still be found, and report previously_seen: false where it cannot.

​
Module Evidence

Each entry in analysis_results.modules reports its findings together with the evidence supporting them:
  • findings — structured findings, each with an alert_type, a severity (Informational, Low, Medium, or High), a description, a severity_justification, an evidence list, and evidence_refs. Some findings also carry confidence, confidence_reason and uncertainty_cause (see Finding confidence).
  • search_evidence (object or null) — the search and grounding queries run for the module, with their results and any failures.
  • verification_evidence (object or null) — checks run against an authoritative registry or API for the module.
A finding’s evidence_refs are IDs that resolve back into that module’s own evidence: q1.1 matches a result_id in search_evidence.results, and v1 matches a check_id in verification_evidence.checks. full_analysis.search_evidence_summary and full_analysis.verification_evidence_summary roll the same evidence up across modules, keyed by module_id.

​
Verification Evidence

Verification checks run only when your organisation’s verification setting is on for that analysis. An analysis run with the setting off has no checks: each module’s verification_evidence is null or has an empty checks list, full_analysis.verification_evidence_summary is null, and no finding carries a v reference. Search evidence is unaffected. A result keeps the evidence it was produced with after the setting changes, so read each result’s evidence fields rather than inferring them from the current setting. Findings under results carry no evidence_refs of their own. See Tracing a finding back to its evidence for how to get from one to its sources, and for the cases where that lookup does not resolve.
On an analysis from the current engine these keys are always present, though search_evidence_summary, verification_evidence_summary and a query’s answer may each be null. analysis_results.modules can be an empty array when no module produced results, and is absent on the oldest analyses, so check that it is a non-empty array before reading it. An analysis produced by an earlier version of the engine has both summaries set to null and an empty modules_run.

​
Finding confidence

Only some modules report finding confidence. When a module reports it, a finding can carry any of:
  • confidence — a number from 0 to 1: the module’s own estimate that the finding is correct as stated.
  • confidence_reason — a short explanation of that estimate, which may quote details from the document.
  • uncertainty_cause — epistemic (the evidence may have been misread or misjudged), aleatoric (the document itself is ambiguous) or coverage (something needed was missing or unreadable).
Summary findings in analysis_results.full_analysis.findings carry the same three fields, copied from the module finding they were derived from. Treat each of these fields as optional on every finding, independently of the others: a finding can carry a confidence_reason or uncertainty_cause without a confidence. Confidence is self-reported and not calibrated: it is not a probability of fraud, and it has no effect on a finding’s severity or on the overall risk score.

​
Summary finding sources

A summary finding in analysis_results.full_analysis.findings can carry source_findings: an array of { module_id, finding_index } that names the module finding it was derived from. Each summary finding currently has exactly one entry. An empty array means no source was recorded for that finding. To resolve an entry, find the item in analysis_results.modules whose module_id matches, then read its findings[finding_index]. finding_index starts at 0 and counts every finding in that module, including findings with found: false. Do not filter a module’s findings before indexing. The index is a position within the response that contains it. Always resolve it against the modules returned in the same response. Do not store it or hard-code it, because the order of modules and findings can differ between analyses.
In this example the summary finding resolves to analysis_results.modules[0].findings[1], the second finding, because the first has found: false and still counts. source_findings carries no location data. It is returned whether or not the finding locations setting is on. The key is absent on analyses made before the field was introduced. For those, match on source_analysis and alert_type (and custom_alert_type when alert_type is "OTHER"), as described in Tracing a finding back to its evidence. That match is not guaranteed to be unique.

​
Page Locations

An evidence item in findings[].evidence can carry locations: a list of { block_id, page, box }. page starts at 1. box gives the area of that page as numbers from 0 to 1, as fractions of the page. Do not rely on the names of the keys inside box. analysis_results.key_terms lists the people (persons), organisations, locations, dates and reference_numbers found in the document. Each term has its text in value (date_value for a date) and, where found, its locations. Both appear only when your organisation’s finding locations setting is on and page locations are available to your organisation. The setting applies to every analysis when it is read, including older ones. Not every analysis or item has locations. An item without a location has no locations key, never an empty list, and key_terms is absent unless at least one term has a location. Treat both as optional.

​
Best Practices

  1. URL Expiration: Download URLs for assets (original file, PDF report, logs) are time-limited for security. Ensure you download or display them promptly after retrieval.
  2. Wait for Completion: This endpoint provides the most value after a file’s analysis_status has reached settled.
  3. Security: Never expose the signed download URLs in client-side code or public environments.

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
fileId
string
required

File ID

Response

File analysis retrieved successfully

​
file_id
string<uuid>
required

Unique identifier for the file

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
Example:

"0191234568-89ab-7cdef-0123-456789abcdef"

​
case_id
string<uuid>
required

Unique identifier of the case containing this file

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
Example:

"0191234567-89ab-7cdef-0123-456789abcdef"

​
label
string | null
required

Human-readable label for the file

Example:

"Contract_Page1.pdf"

​
mime_type
string | null
required

MIME type of the file

Example:

"application/pdf"

​
file_download_url
string<uri> | null
required

Signed URL for downloading the original file (valid for 60 minutes)

Example:

"https://storage.net/documents/0191234567/0191234568?sig=..."

​
file_download_url_expires_at
string<date-time> | null
required

ISO 8601 timestamp when the file download URL expires

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Example:

"2025-11-19T12:30:00.000Z"

​
thumbnail_url
string<uri> | null
required

Signed URL for accessing the file's thumbnail image (valid for 30 minutes)

Example:

"https://storage.net/thumbnails/0191234568?sig=..."

​
pdf_report_url
string<uri> | null
required

Signed URL for downloading the detailed PDF analysis report

Example:

"https://storage.net/reports/0191234568.pdf?sig=..."

​
log_output_url
string<uri> | null
required

Signed URL for accessing the raw analysis log output

Example:

"https://storage.net/logs/0191234568.log?sig=..."

​
ela_overlay_url
string<uri> | null
required

Signed URL for accessing the Error Level Analysis (ELA) overlay image (valid for 30 minutes)

Example:

"https://storage.net/ela/019c4c64-03c2-7c21-ba43-8573c1d775c8/019c4c64-03cc-77a0-adec-666380071047.ela.jpg?sig=..."

​
reverse_search
object | null
required

Reverse image/document search results from external services

​
file_info
object | null
required

File information including hash and extracted metadata

Example:
​
analysis_status
enum<string>
required

Current status of the file analysis process

Available options:
waiting_for_upload,
processing,
settled
Example:

"settled"

​
analysis_outcome
enum<string> | null
required

Outcome of the analysis process

Available options:
success,
failed
Example:

"success"

​
current_analysis_phase
string | null
required

Current phase of the analysis process

Example:

"completed"

​
current_risk_score
string | null
required

Current effective risk score for this file

Example:

"high"

​
analysis_results
object | null
required

Detailed, structured results from the various analysis engines

​
case_context_at_analysis
string | null
required
​
user_risk_confirmations
object[]
required

History of manual risk score confirmations and overrides by users

​
created_at
string<date-time>
required

ISO 8601 timestamp when this file record was created

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Example:

"2025-11-19T11:30:00.000Z"

​
uploaded_at
string<date-time> | null
required

ISO 8601 timestamp when the file was uploaded to storage

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Example:

"2025-11-19T11:30:00.000Z"

​
analysis_completed_at
string<date-time> | null
required

ISO 8601 timestamp when analysis finished for this file

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Example:

"2025-11-19T11:45:00.000Z"

​
previously_seen
boolean
required

True when this file's analysis was reused from an identical file uploaded earlier in the same organisation.

Example:

true

​
previously_seen_at
string<date-time> | null
required

ISO 8601 timestamp when the identical file was first uploaded in the organisation. Null when the file was not previously seen.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Example:

"2025-11-19T11:30:00.000Z"

​
highlights
string[]

Key findings from the analysis as a plain list of strings. Omitted when no highlights were produced for the file.

Example:
​
caveats
object[]

Analysis quality caveats — additive uncertainty annotations (failed modules, could-not-verify checks, searches limited to the public web, low OCR confidence). Present when caveats exist; omitted when the analysis has none.

Example:
​
team_id
string<uuid>

ID of the team that uploaded this file, omitted if unassigned

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Example:

"0191234568-89ab-7cdef-0123-456789abcdef"

​
team_name
string

Name of the team that uploaded this file, omitted if unassigned

Example:

"Fraud Team"