Retrieve a previously completed PDF analysis by its unique check ID.
GET https://api.htpbe.tech/v1/result/{id}
This endpoint requires API key authentication via the Authorization header.
Authorization: Bearer YOUR_API_KEYImportant: You can only retrieve analysis results that belong to your API client. Attempting to access another client's results will return a 404 error, even if the check ID exists. This ensures complete data privacy and isolation between API clients.
A test API key (htpbe_test_...) can only resolve the predefined synthetic check ids (see below) — it never returns a real check, even one created by the same account with a live key.
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Check ID returned from POST /api/v1/analyze. UUID v4 for all requests — live and test keys both return UUID v4 IDs. |
Live key format: UUID v4 — xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx
Test key format: Deterministic UUID v4 — fixed all-zeros pattern, e.g. 00000000-0000-4000-8000-000000000001. A test key can only resolve one of these synthetic ids — passing any other id, including a real check id owned by the same account, returns 404 not_found.
Valid Examples:
506a6b1b-1360-48a2-b389-abb346f85d04(live key request)00000000-0000-4000-8000-000000000001(test key request —clean.pdf)
Invalid Examples:
abc123(too short, not a UUID)- `` (empty string)
Where to Get: The id field returned by POST /api/v1/analyze.
| Header | Type | Required | Description |
|---|---|---|---|
Authorization |
string | Yes | Bearer token with your API key (Bearer htpbe_live_... or Bearer htpbe_test_...). The Bearer prefix is recommended but optional — sending the raw key directly is also accepted, but only if the key starts with htpbe_ (e.g., Authorization: htpbe_live_sk_...). |
curl https://api.htpbe.tech/v1/result/506a6b1b-1360-48a2-b389-abb346f85d04 \
-H "Authorization: Bearer htpbe_live_sk_1234567890abcdef"// Node.js / TypeScript
const checkId = '506a6b1b-1360-48a2-b389-abb346f85d04';
const response = await fetch(`https://api.htpbe.tech/v1/result/${checkId}`, {
headers: {
Authorization: `Bearer ${process.env.HTPBE_API_KEY}`,
},
});
const result = await response.json();# Python
import requests
import os
check_id = '506a6b1b-1360-48a2-b389-abb346f85d04'
response = requests.get(
f'https://api.htpbe.tech/v1/result/{check_id}',
headers={
'Authorization': f"Bearer {os.getenv('HTPBE_API_KEY')}"
}
)
result = response.json()Returns a ResultResponse object containing all stored analysis data for the check.
Note: /api/v1/analyze returns only { "id": "..." }. This endpoint is where all analysis data lives: metadata, structure, signatures, findings, and verdict details.
{
// Core Identification
id: string;
filename: string;
check_date: number | null;
file_size: number;
// Algorithm version tracking
algorithm_version: string;
current_algorithm_version: string;
outdated_warning?: string;
// Primary Verdict
status: "intact" | "modified" | "inconclusive";
status_reason?: "consumer_software_origin" | "online_editor_origin" | "scanned_document" | "unverifiable_metadata" | "filled_form_origin" | "fill_sign_origin" | "visible_signature_origin" | "analysis_incomplete";
// PDF Metadata (Unix timestamps)
creation_date: number | null;
modification_date: number | null;
creator: string | null;
producer: string | null;
creator_truncated: boolean;
producer_truncated: boolean;
// Critical Modification Detection
modification_confidence: string | null;
// Metadata Analysis
date_sequence_valid: boolean;
metadata_completeness_score: number;
// PDF Structure
xref_count: number | null;
has_incremental_updates: boolean | null;
update_chain_length: number;
pdf_version: string | null;
// Digital Signatures
has_digital_signature: boolean;
signature_count: number;
signature_removed: boolean;
modifications_after_signature: boolean;
// Content Analysis
page_count: number;
object_count: number;
has_javascript: boolean;
has_embedded_files: boolean;
// Modification Evidence
modification_markers: string[];
// Responsible-use guardrail (always present)
usage_caution: {
safe_for_automated_adverse_decision: false;
recommended_action: "route_to_human_review" | "request_from_issuer" | "no_action";
message: string;
};
}- Type:
string(UUID v4) - Always Present: Yes
- Description: Unique identifier for this check
- Format:
xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx - Example:
"506a6b1b-1360-48a2-b389-abb346f85d04"
- Type:
string - Always Present: Yes
- Description: The stored filename for this check. If
original_filenamewas provided in thePOST /analyzerequest body, that value is used. Otherwise the last segment of theurlpath is used if it is a.pdffilename (percent-decoded); any other last segment — a share-link token, an ID, an empty path — is not stored, and"document.pdf"is used instead. - Examples:
"contract.pdf"(provided asoriginal_filenamein the analyze request, or extracted fromhttps://example.com/docs/contract.pdf)"invoice-2024-01.pdf""document.pdf"(default set at analysis time when nooriginal_filenamewas sent and the URL path does not end in a.pdffilename)""(empty string for legacy records created before filename tracking)
- Type:
number | null(Unix timestamp in seconds) - Can Be Null: Yes —
nullfor test key results (synthetic responses have no real analysis timestamp) and for legacy records created before timestamp tracking was introduced - Description: Timestamp when the analysis was performed
- Format: Seconds since Unix epoch (January 1, 1970 00:00:00 UTC)
- Example:
1736542583= January 10, 2025, 18:23:03 UTC - Convert to Date:
- JavaScript:
check_date ? new Date(check_date * 1000) : null - Python:
datetime.fromtimestamp(check_date) if check_date else None
- JavaScript:
- Type:
number(integer, bytes) - Always Present: Yes
- Range:
1to10485760(10 MB) - Description: File size in bytes
- Example:
245632= ~240 KB - Convert to MB:
file_size / 1024 / 1024
Note: Examples on this page use
X.Y.Zin place of a real version number. The current algorithm version is listed in the changelog.
- Type:
string - Always Present: Yes
- Description: Version of the detection algorithm used when this check was performed. Defaults to
"1.0.0"for records created before algorithm versioning was introduced. - Format: Semantic versioning (e.g.,
"X.Y.Z") - Usage: Compare against the current version to determine if re-analysis is recommended
- Example:
"X.Y.Z"
- Type:
string - Always Present: Yes
- Description: The current algorithm version running on the server
- Format: Semantic versioning (e.g.,
"X.Y.Z") - Usage: Compare
algorithm_versionagainstcurrent_algorithm_versionto determine if the check is outdated. Ifalgorithm_version !== current_algorithm_version, the check was performed with an older algorithm and re-analysis is recommended. - Example:
"X.Y.Z"
- Type:
string(optional) - Present When:
algorithm_versionis older thancurrent_algorithm_version(semver comparison — a future version would not trigger this warning even if the values differ) - Absent When:
algorithm_versionis current - Description: Human-readable explanation of what changed in the newer algorithm version and why re-analysis is recommended
- Example:
"Our detection software has been updated since this file was analyzed. The results shown below may no longer be accurate. We recommend re-analyzing this file for more accurate results. Running the check again starts a new analysis and may use another credit or quota unit."
- Type:
"intact" | "modified" | "inconclusive" - Always Present: Yes
- Description: PRIMARY VERDICT. Priority:
modified > inconclusive > intact"modified"— forensic evidence of post-creation modification detected; takes priority over origin type — a modified Word or Excel document is stillmodified"inconclusive"— no modification was established, and the check cannot confirm the document is unchanged. The cause is one of four kinds: the document belongs to a class anyone can create, reprocess, fill in, or scan from scratch, so an integrity check does not apply to it (consumer_software_origin,online_editor_origin,scanned_document,filled_form_origin,fill_sign_origin); the document's history after creation could not be established (unverifiable_metadata); the document carries a visible signature that the check cannot confirm as unchanged (visible_signature_origin); or the check could not be completed in full (analysis_incomplete). The specific cause is instatus_reason"intact"— no structural evidence of modification, and no inconclusive cause applies (seestatus_reason)
- Note:
status_reasononly appears whenstatus === "inconclusive"
- Type:
"consumer_software_origin" | "online_editor_origin" | "scanned_document" | "unverifiable_metadata" | "filled_form_origin" | "fill_sign_origin" | "visible_signature_origin" | "analysis_incomplete"| absent - Always Present: No — only present when
status === "inconclusive" - Description: Explains why the result is inconclusive.
- Values:
"consumer_software_origin"— the PDF was created by consumer software (Microsoft Word, LibreOffice, Google Docs, etc.) or a freely available HTML-to-PDF renderer. These tools let anyone create a document from scratch, so there is no meaningful "original" to compare against. For a file that claims institutional origin (a payslip, an invoice, a bank statement), this origin is itself a strong signal to route for review — a real payroll or banking system does not distribute documents this way. If the document will support a financial or compliance decision, verify its content directly with the issuing organisation."online_editor_origin"— the PDF was processed through an online editing service (iLovePDF, Smallpdf, PDF24, etc.). These services strip original metadata, making provenance verification impossible."scanned_document"— the PDF is a scanned document. Anyone can print and scan a document, so its content cannot be confirmed through a structural check. If the document will support a financial or compliance decision, request the original digital file from the issuing organisation."unverifiable_metadata"— the document's history after creation could not be established, so the check cannot confirm that it is unchanged. That is not a finding that the document was edited, and not a statement that it is clean. If the document will support a financial or compliance decision, confirm its content directly with the issuing organisation."filled_form_origin"— the PDF is a form with filled-in fields, so a structural check cannot certify what it currently shows. If the document will support a financial or compliance decision, request the issuer's own copy."fill_sign_origin"— the PDF carries a fill-and-sign overlay, so a structural check cannot certify what it currently shows. If the document will support a financial or compliance decision, request the issuer's own copy."visible_signature_origin"— the document carries a visible signature that the check cannot confirm as unchanged, so the result is inconclusive rather than intact. Nothing here is a statement about the signature's validity — this check never tests the certificate, the certificate chain, the signer's identity, or whether the signed digest matches. A structural check is not an authenticity check."analysis_incomplete"— the check could not be completed in full, so the document was not fully examined, and no modification was established in the part that was examined.modification_markers[]is empty, and that emptiness is not evidence the document is clean. (If a modification was established despite the incomplete analysis, the result ismodifiedwith its markers instead, and carries nostatus_reason.) This describes the check, not the document. It uses a credit or quota like any other delivered result. (An analysis stopped by a fault on our side returns no result at all — see Analysis Interrupted.) Reading this result again, or replaying the original request with the sameIdempotency-Key, costs nothing and returns this same result. Submitting the file again (with no key or a new one) is a new analysis that may use another credit or quota — see Quota & Credits. Treat the document as unverified rather than clean.
- Usage: Always check
status_reasonwhenstatus === "inconclusive"— it tells you why the result is inconclusive, not just that it is.
Handle every branch — an inconclusive verdict is not a failure and not a pass. It means no modification was established and the check cannot confirm the document is unchanged, so route the document by why rather than treating it as clean:
function handleResult(result) {
switch (result.status) {
case 'modified':
// Forensic evidence of post-creation modification — route to human review.
return 'review';
case 'intact':
// No structural evidence of modification.
return 'accept';
case 'inconclusive':
// Not a pass — branch on status_reason to decide handling.
switch (result.status_reason) {
case 'scanned_document':
// Scanned document — content cannot be confirmed through a structural check.
case 'online_editor_origin':
// Processed through an online editor — original metadata stripped.
case 'unverifiable_metadata':
// Post-creation history could not be established — cannot certify unchanged.
case 'filled_form_origin':
// Form with filled-in fields — current content cannot be certified.
case 'fill_sign_origin':
// Fill-and-sign overlay — current content cannot be certified.
case 'consumer_software_origin':
// Created in consumer software or a free HTML-to-PDF renderer.
// On a document that CLAIMS institutional origin (payslip, invoice, bank
// statement), this is itself a red flag — verify the content directly with
// the issuing organisation before relying on it.
return 'verify-with-issuer';
case 'visible_signature_origin':
// Signed, with a drawn signature appearance. A structural check is not an
// authenticity check — the signature itself was not validated.
return 'verify-with-issuer';
case 'analysis_incomplete':
// The check could not be completed in full — this says nothing about
// the document. Treat it as unverified, not as clean.
return 'unverified';
default:
return 'verify-with-issuer';
}
}
}All timestamps are Unix integers (seconds since epoch). Convert with: new Date(timestamp * 1000) in JavaScript, datetime.fromtimestamp(ts) in Python.
- Type:
number | null(Unix timestamp in seconds) - Can Be Null: Yes
- Description: PDF creation timestamp from embedded metadata
- Null When: PDF does not contain creation date
- Example:
1704110400= January 2, 2024 00:00:00 UTC - Convert: JavaScript:
new Date(creation_date * 1000).toISOString()
- Type:
number | null(Unix timestamp in seconds) - Can Be Null: Yes
- Description: Last modification timestamp from embedded metadata
- Null When: PDF does not contain modification date
- Note: Read from embedded metadata, which any software can write. Do not derive a verdict by comparing it with
creation_date– date findings are reported instatusandmodification_markers. - Example:
1707840000= February 13, 2024 12:00:00 UTC
- Type:
string | null - Can Be Null: Yes
- Description: Application that created the original document
- Example:
"Microsoft Word for Microsoft 365" - Common Values:
"Microsoft Word for Microsoft 365","Adobe InDesign CC","LibreOffice Writer","Google Docs" - May be a prefix: see
creator_truncated.
- Type:
string | null - Can Be Null: Yes
- Description: Software that generated the final PDF
- Example:
"Adobe PDF Library 15.0" - Common Values:
"Adobe PDF Library 15.0","PDFKit","Microsoft: Print To PDF","iText 7.0.0" - May be a prefix: see
producer_truncated.
- Type:
boolean - Can Be Null: No (always present)
- Description:
truewhencreatoris only the beginning of a longer value, returned as a bare prefix with no ellipsis.falsemeans the value was not shortened; results stored before this field existed were never shortened and can be longer than current ones. - Note: Only the stored and returned copy is shortened, and detection never uses it. Never display or compare a truncated value as if it were the complete field.
- Type:
boolean - Can Be Null: No (always present)
- Description:
truewhenproduceris only the beginning of a longer value, returned as a bare prefix with no ellipsis.falsemeans the value was not shortened; results stored before this field existed were never shortened and can be longer than current ones. - Note: Only the stored and returned copy is shortened, and detection never uses it. Never display or compare a truncated value as if it were the complete field.
- Type:
string | null(enum) - Can Be Null: Yes
- Description: How certain the algorithm is about the modification verdict. Use it to decide how to route the case for review — never as a trigger for an automatic adverse decision against a person (see
usage_caution). - Possible Values:
"certain"– the strongest level of evidence the analysis reports. Treat the document as modified and route it to human review or request a fresh copy directly from the issuer – do not auto-reject the person on this alone."high"– strong forensic evidence; flag for manual review – reliable, but unusual legitimate workflows can occasionally produce it."none"– no modification marker fired; route according tostatus(intactorinconclusive) andusage_caution.recommended_action.
- Relationship to
status:certainandhighalways correspond tostatus: "modified".nonecorresponds tostatus: "intact"or"inconclusive"depending on origin. - Null When: Legacy records before this field was added
- Type:
boolean - Always Present: Yes
- Description: Whether a contradiction was found among the document’s embedded dates
- Possible Values:
true– no date contradiction found. This is not evidence that the document is unmodified.false– the embedded dates contain a contradiction.
- Verdict: Whether this contributed to the verdict is reported in
statusandmodification_markers
- Type:
number(integer) - Always Present: Yes
- Range:
0to100 - Description: How complete the document’s descriptive metadata is. Descriptive only – neither a low nor a high score is by itself evidence for or against modification. Use
statusandmodification_markersfor the verdict.
When the check could not be completed in full, or for legacy records, the counters and flags it would have filled are returned as 0, false or an empty string – placeholders, not measurements. The exceptions are xref_count and has_incremental_updates, which are null when the number of revisions could not be established, or was not recorded for this check (older records).
- Type:
number | null(integer) - Always Present: Yes
- Description: Number of cross-reference sections in the file
- Null: The number of revisions in the file could not be established, or was not recorded for this check (older records).
nullis not a count of zero or one. - Note: A structural count reported for transparency. Its value alone does not determine the verdict – see
statusandmodification_markers.
- Type:
boolean | null - Always Present: Yes
- Description: Whether the file contains incremental update sections
- Null: The number of revisions in the file could not be established, or was not recorded for this check (older records).
nullis notfalse. - Note: Many legitimate workflows produce these, and their absence is not evidence that the document is unmodified. See
statusandmodification_markersfor the verdict.
- Type:
number(integer) - Always Present: Yes
- Description: Length of the file’s update chain
- Note: Reported for transparency; the value alone does not determine the verdict – see
statusandmodification_markers.
- Type:
string | null - Can Be Null: Yes
- Description: PDF version declared in the file header
- Examples:
"1.7","1.4","2.0" - Special Values:
"unknown"when the header declares no version;""when the file structure could not be read;nullfor legacy records
- Type:
boolean - Always Present: Yes
- Description: A signature dictionary is present; validity is not checked. This field is an observation about the file's structure and nothing more — it does not mean the signature is valid, that the certificate is trusted, that the signer is who the document says, or that the content is unchanged. No verdict is softened on the strength of it. Do not present it to an end user as "signed and verified".
- Values:
true= a signature dictionary is present,false= no signature dictionary was found - Note: Signature validity is NOT checked (only presence)
- Type:
number(integer) - Always Present: Yes
- Description: Number of digital signature fields in the PDF
- Range:
0and higher
- Type:
boolean - Always Present: Yes
- Description: Whether a digital signature was removed from the document
- Note: Signature findings that contribute to the verdict are reported in
modification_markers(e.g.HTPBE_SIGNATURE_REMOVED).
- Type:
boolean - Always Present: Yes
- Description: Whether PDF was modified after being digitally signed
- Note: Signature findings that contribute to the verdict are reported in
modification_markers(e.g.HTPBE_POST_SIGNATURE_EDIT). Signature validity itself is not checked.
- Type:
number(integer) - Always Present: Yes
- Range:
0and higher (0when the value could not be measured – a legacy record or an incomplete analysis) - Description: Total number of pages in the PDF document
- Example:
12= 12-page document - Usage: Useful for estimating document size and complexity
- Type:
number(integer) - Always Present: Yes
- Range:
0and higher - Description: Number of PDF objects in the internal structure
- What It Means:
- PDF objects include: pages, fonts, images, annotations, forms, etc.
- A measure of document complexity; not a verdict input you should branch on
- Type:
boolean - Always Present: Yes
- Description: Whether PDF contains embedded JavaScript code
- Values:
true= JavaScript present (potential security risk),false= no JavaScript detected - Security Note: JavaScript in PDFs can be used for malicious purposes
- Type:
boolean - Always Present: Yes
- Description: Whether PDF has embedded file attachments
- Values:
true= has attachments (potential security risk),false= no attachments - Security Note: Attachments can hide malware
- Type:
string[](array of strings) - Always Present: Yes
- Description: All modification signals detected, ordered strongest-first. The first element (
modification_markers[0]) is the strongest marker — the single most important forensic indicator that drove the verdict. Usually contains one entry; may have two or three when multiple independent signals fired simultaneously (e.g. dates disagree AND an editing tool detected). Empty whenstatusis"intact"or"inconclusive". - Format: Each entry is a stable machine-readable id (e.g.
HTPBE_SIGNATURE_REMOVED,HTPBE_DATES_DISAGREE). The full id → outcome-label dictionary is published on htpbe.tech/how — branch on the id in your integration, render the user-facing label from the dictionary. - Empty When: No modification detected (
status: "intact"orstatus: "inconclusive") - Example Values:
"HTPBE_DATES_DISAGREE""HTPBE_MULTIPLE_REVISION_LAYERS""HTPBE_SIGNATURE_REMOVED""HTPBE_POST_SIGNATURE_EDIT""HTPBE_EDITING_TOOL_FINGERPRINT""HTPBE_IDENTITY_BLANKED""HTPBE_FONT_VS_TOOL_MISMATCH""HTPBE_DESIGN_TEMPLATE_ASSEMBLY""HTPBE_TEXT_OVERLAY_ON_SCAN""HTPBE_PAGES_FROM_MULTIPLE_SOURCES"
- Type:
object - Always Present: Yes
- Description: In-contract responsible-use guardrail. A structural verdict describes the file, not the person who sent it, so it must never be the sole basis for an automatic adverse decision (rejecting or denying an applicant, claimant, or customer). This field ships the guardrail in the payload itself, not only in the docs — branch on
recommended_actionto route the case instead of auto-rejecting. - Fields:
safe_for_automated_adverse_decision—boolean, alwaysfalse. A machine-checkable assertion that this verdict alone must not drive an automatic adverse decision against a person.recommended_action—"route_to_human_review"(forstatus: "modified"),"request_from_issuer"(forstatus: "inconclusive"— the check could not confirm integrity, which is not proof of fraud), or"no_action"(forstatus: "intact").message— human-readable guidance matchingrecommended_action.
- Example:
{
"safe_for_automated_adverse_decision": false,
"recommended_action": "route_to_human_review",
"message": "Structural evidence of post-creation modification was found. Route this document to a human reviewer before any decision — do not use this verdict as the sole basis for an automatic adverse decision against a person."
}{
"id": "506a6b1b-1360-48a2-b389-abb346f85d04",
"filename": "contract.pdf",
"check_date": 1736542583,
"file_size": 245632,
"algorithm_version": "X.Y.Z",
"current_algorithm_version": "X.Y.Z",
"status": "modified",
"creation_date": 1704110400,
"modification_date": 1707840000,
"creator": "Adobe Acrobat Pro DC",
"producer": "Adobe PDF Library 15.0",
"creator_truncated": false,
"producer_truncated": false,
"modification_confidence": "certain",
"date_sequence_valid": true,
"metadata_completeness_score": 90,
"xref_count": 2,
"has_incremental_updates": true,
"update_chain_length": 3,
"pdf_version": "1.7",
"has_digital_signature": false,
"signature_count": 0,
"signature_removed": true,
"modifications_after_signature": false,
"page_count": 12,
"object_count": 487,
"has_javascript": false,
"has_embedded_files": false,
"modification_markers": ["HTPBE_SIGNATURE_REMOVED", "HTPBE_DATES_DISAGREE"],
"usage_caution": {
"safe_for_automated_adverse_decision": false,
"recommended_action": "route_to_human_review",
"message": "Structural evidence of post-creation modification was found. Route this document to a human reviewer before any decision — do not use this verdict as the sole basis for an automatic adverse decision against a person."
}
}{
"id": "00000000-0000-4000-8000-000000000011",
"filename": "inconclusive.pdf",
"check_date": null,
"file_size": 204800,
"algorithm_version": "X.Y.Z",
"current_algorithm_version": "X.Y.Z",
"status": "inconclusive",
"status_reason": "consumer_software_origin",
"creation_date": 1709283600,
"modification_date": 1709283600,
"creator": "Microsoft Excel 2019",
"producer": "Microsoft: Print To PDF",
"creator_truncated": false,
"producer_truncated": false,
"modification_confidence": "none",
"date_sequence_valid": true,
"metadata_completeness_score": 65,
"xref_count": 1,
"has_incremental_updates": false,
"update_chain_length": 1,
"pdf_version": "1.7",
"has_digital_signature": false,
"signature_count": 0,
"signature_removed": false,
"modifications_after_signature": false,
"page_count": 1,
"object_count": 82,
"has_javascript": false,
"has_embedded_files": false,
"modification_markers": [],
"usage_caution": {
"safe_for_automated_adverse_decision": false,
"recommended_action": "request_from_issuer",
"message": "The check could not confirm this document’s integrity, which is not proof of fraud. Confirm the content directly with the issuing organisation or route it to human review — do not treat inconclusive as an automatic rejection."
}
}{
"id": "00000000-0000-4000-8000-000000000014",
"filename": "inconclusive-online-editor.pdf",
"check_date": null,
"file_size": 312000,
"algorithm_version": "X.Y.Z",
"current_algorithm_version": "X.Y.Z",
"status": "inconclusive",
"status_reason": "online_editor_origin",
"creation_date": null,
"modification_date": null,
"creator": null,
"producer": "iLovePDF",
"creator_truncated": false,
"producer_truncated": false,
"modification_confidence": "none",
"date_sequence_valid": true,
"metadata_completeness_score": 15,
"xref_count": 1,
"has_incremental_updates": false,
"update_chain_length": 1,
"pdf_version": "1.7",
"has_digital_signature": false,
"signature_count": 0,
"signature_removed": false,
"modifications_after_signature": false,
"page_count": 2,
"object_count": 110,
"has_javascript": false,
"has_embedded_files": false,
"modification_markers": [],
"usage_caution": {
"safe_for_automated_adverse_decision": false,
"recommended_action": "request_from_issuer",
"message": "The check could not confirm this document’s integrity, which is not proof of fraud. Confirm the content directly with the issuing organisation or route it to human review — do not treat inconclusive as an automatic rejection."
}
}{
"id": "00000000-0000-4000-8000-000000000015",
"filename": "scanned-document.pdf",
"check_date": null,
"file_size": 890000,
"algorithm_version": "X.Y.Z",
"current_algorithm_version": "X.Y.Z",
"status": "inconclusive",
"status_reason": "scanned_document",
"creation_date": null,
"modification_date": null,
"creator": null,
"producer": null,
"creator_truncated": false,
"producer_truncated": false,
"modification_confidence": "none",
"date_sequence_valid": true,
"metadata_completeness_score": 0,
"xref_count": 1,
"has_incremental_updates": false,
"update_chain_length": 1,
"pdf_version": "1.4",
"has_digital_signature": false,
"signature_count": 0,
"signature_removed": false,
"modifications_after_signature": false,
"page_count": 3,
"object_count": 45,
"has_javascript": false,
"has_embedded_files": false,
"modification_markers": [],
"usage_caution": {
"safe_for_automated_adverse_decision": false,
"recommended_action": "request_from_issuer",
"message": "The check could not confirm this document’s integrity, which is not proof of fraud. Confirm the content directly with the issuing organisation or route it to human review — do not treat inconclusive as an automatic rejection."
}
}All errors follow this format:
{
"error": "Human-readable error message",
"code": "machine_readable_error_code",
"details": "Optional additional context (present for some errors)"
}Returned when the check ID format is invalid.
{
"error": "Invalid check ID format",
"code": "invalid_request"
}Causes:
idis empty stringidis not a valid UUID v4 (e.g.abc123,12345678-1234-1234-1234-12345678)idcontains invalid characters
Solution: Ensure you're using the full UUID v4 returned by POST /api/v1/analyze or from the id field in GET /api/v1/checks. Format: xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx (32 hex digits with 4 hyphens).
Authentication errors (same as analyze endpoint).
See: analyze.md for details.
Returned when the API key exists but has been deactivated.
{
"error": "This API key has been deactivated. Please contact support.",
"code": "inactive_client"
}Note: inactive_client is the only 403 a read endpoint returns. The test_url_required and account_restricted cases are raised only by POST /analyze.
Check not found or access denied.
{
"error": "Check not found or access denied",
"code": "not_found"
}Causes:
- Check ID doesn't exist in the database
- Check ID belongs to another API client (data isolation)
- Check ID is malformed but passed basic validation
- A test API key was used with a check id that isn't one of the predefined synthetic ids — test keys never resolve real checks, even ones created by the same account with a live key
Security Note: For privacy, we intentionally don't distinguish between "doesn't exist" and "belongs to another client". This prevents enumeration attacks.
Solution:
- Verify the check ID is correct
- Ensure you're using the API key that created the check
- If you need to share results between API clients, contact support for guidance
Server error during retrieval.
{
"error": "Failed to fetch result",
"code": "internal_error",
"request_id": "3f2a9c1e-5b7d-4e8a-9c0f-1d2e3b4a5c6d"
}request_id is the id of this request, also returned in the x-request-id header.
Cause: Unexpected database or server error.
Solution:
- Retry the request
- If persists, contact support with the check ID and the
request_id
Store check IDs and retrieve full results later for compliance:
// Store check ID after analysis
await db.documents.create({
id: uploadId,
htpbe_check_id: analysisResponse.id,
verified_at: new Date(),
});
// Later, retrieve full details for audit
const auditData = await fetch(`https://api.htpbe.tech/v1/result/${doc.htpbe_check_id}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});Use the additional fields for comprehensive reports:
const result = await getResult(checkId);
const report = {
summary:
result.status === 'modified'
? 'Modified'
: result.status === 'inconclusive'
? 'Unverifiable'
: 'Original',
// Use fields not available in analyze endpoint
details: {
pages: result.page_count,
objects: result.object_count,
metadataQuality: result.metadata_completeness_score,
analysisDate: new Date(result.check_date * 1000),
},
criticalMarkers: result.modification_markers,
};Related Endpoints:
- POST /api/v1/analyze - Analyze a PDF
- GET /api/v1/checks - List all checks with filtering for custom analytics