> ## Documentation Index > Fetch the complete documentation index at: https://docs.beltic.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Document > Retrieve a document by its unique identifier. Returns the complete document record including processing status, extracted data, and fraud detection results. **Document Status Values:** - `pending`: Document created but file not yet uploaded - `submitted`: File uploaded, queued for processing - `processing`: Currently being processed - `processed`: Processing completed successfully - `failed`: Processing failed (check error details) **Use Cases:** - Check document processing status - Retrieve extracted data after processing completes - Access fraud detection analysis results **Sparse Fieldsets (JSON:API):** - Use `fields[document]` with a comma-separated list to return only specific fields (attributes and relationships) - `id` and `type` are always returned; an empty value returns only `id`/`type` - Omit the parameter to return all fields - Unknown field names return `400 Bad Request` ## OpenAPI ````yaml GET /v1/documents/{id} openapi: 3.1.0 info: title: Beltic Document API version: 1.0.0 description: >- # The Beltic Document API provides a comprehensive solution for document processing with AI-powered data extraction and fraud detection capabilities. ## Key Features - **Template-Based Processing**: Create reusable document templates with predefined schemas and processing configurations - **Ad-Hoc Processing**: Process documents without templates using custom configurations - **AI Data Extraction**: Intelligent document data extraction powered by AI - **Fraud Detection**: Document authenticity verification and fraud analysis - **Secure File Handling**: Pre-signed URLs for secure file uploads ## Workflow 1. **Create a Document Template**: Define a template with extraction schema and fraud detection settings 2. **Create a Document**: Initialize a document with either a template reference or ad-hoc configuration 3. **Upload File**: Use the pre-signed URL to upload your document file 4. **Automatic Processing**: Once uploaded, the document is automatically processed with extraction and fraud detection 5. **Retrieve Results**: Fetch the document to access extracted data and fraud analysis results ## Authentication All endpoints require authentication. Include your API key in the `X-Api-Key` header: ``` X-Api-Key: YOUR_API_KEY ``` ## Response Format All responses follow the JSON:API specification for consistent data structures. contact: name: Beltic API Support email: engineering@beltic.com servers: - url: https://api.beltic.com description: Production security: - ApiKeyAuth: [] tags: - name: Document Templates description: >- Manage document templates for repeatable processing workflows. Templates define the structure and processing configuration for documents including JSON schemas for data extraction and fraud detection settings. - name: Documents description: >- Create and manage documents for processing. Documents can be associated with a template for standardized processing, or configured ad-hoc with custom settings. The workflow involves creating a document record, uploading the file via pre-signed URL, and automatically processing the document with AI-powered extraction and fraud detection. Documents track their processing status and store extracted data and fraud analysis results. - name: Webhooks description: >- Configure webhook endpoints to receive real-time notifications when document status changes. Webhooks support automatic retries with exponential backoff and provide options for manual resend and DLQ reprocessing. externalDocs: description: Beltic Platform Documentation url: https://docs.beltic.com paths: /v1/documents/{id}: get: tags: - Documents summary: Get document description: >- Retrieve a document by its unique identifier. Returns the complete document record including processing status, extracted data, and fraud detection results. **Document Status Values:** - `pending`: Document created but file not yet uploaded - `submitted`: File uploaded, queued for processing - `processing`: Currently being processed - `processed`: Processing completed successfully - `failed`: Processing failed (check error details) **Use Cases:** - Check document processing status - Retrieve extracted data after processing completes - Access fraud detection analysis results **Sparse Fieldsets (JSON:API):** - Use `fields[document]` with a comma-separated list to return only specific fields (attributes and relationships) - `id` and `type` are always returned; an empty value returns only `id`/`type` - Omit the parameter to return all fields - Unknown field names return `400 Bad Request` parameters: - schema: type: string format: uuid description: Document ID required: true description: Document ID name: id in: path - schema: type: string description: >- Sparse fieldset: comma-separated list of `document` fields (attributes and relationships) to return. An empty value returns only `id`/`type`. Omit the parameter to return all fields. example: status,file required: false description: >- Sparse fieldset: comma-separated list of `document` fields (attributes and relationships) to return. An empty value returns only `id`/`type`. Omit the parameter to return all fields. name: fields[document] in: query responses: '200': description: Document found successfully content: application/json: schema: $ref: '#/components/schemas/DocumentResponse' '400': description: Bad Request (invalid fieldset values) content: application/json: schema: type: object properties: errors: type: array items: type: object properties: status: type: string title: type: string detail: type: string required: - status - title - detail required: - errors '404': description: Document not found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: status: type: string title: type: string detail: type: string required: - status - title - detail required: - errors '500': description: Internal Server Error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: status: type: string title: type: string detail: type: string required: - status - title - detail required: - errors security: - ApiKeyAuth: [] components: schemas: DocumentResponse: type: object properties: data: $ref: '#/components/schemas/DocumentResource' required: - data DocumentResource: type: object properties: id: type: string format: uuid description: Unique identifier for the document example: 123e4567-e89b-12d3-a456-426614174000 type: type: string enum: - document description: Resource type attributes: type: object properties: status: type: string enum: - pending - submitted - processing - processed - failed - redacted file: $ref: '#/components/schemas/FileInfoResponse' processing_errors: type: - array - 'null' items: type: object properties: status: type: string code: type: string title: type: string detail: type: - string - 'null' meta: type: object properties: occurred_at: type: string required: - occurred_at required: - status - code - title created_at: type: string submitted_at: type: - string - 'null' processed_at: type: - string - 'null' redacted_at: type: - string - 'null' extracted_data: type: - object - 'null' additionalProperties: {} fraud_result: type: - object - 'null' properties: score: type: string enum: - NORMAL - TRUSTED - WARNING - HIGH_RISK description: Fraud detection risk score example: NORMAL file_metadata: type: object properties: producer: type: - string - 'null' description: File producer metadata example: null creator: type: - string - 'null' description: File creator metadata example: null creation_date: type: - string - 'null' description: File creation date example: null mod_date: type: - string - 'null' description: File modification date example: null author: type: - string - 'null' description: File author metadata example: null title: type: - string - 'null' description: File title metadata example: null keywords: type: - string - 'null' description: File keywords metadata example: null subject: type: - string - 'null' description: File subject metadata example: null required: - producer - creator - creation_date - mod_date - author - title - keywords - subject description: File metadata extracted from the document indicators: type: array items: type: object properties: id: type: string description: Indicator identifier type: type: string enum: - RISK - TRUST - INFO description: >- Indicator type: RISK (negative), TRUST (positive), or INFO (neutral) category: type: string description: Indicator category title: type: string description: Indicator title description: type: string description: Indicator description origin: type: string enum: - FRAUD - QUALITY description: 'Indicator origin: FRAUD or QUALITY' required: - id - type - category - title - description - origin description: Array of fraud detection indicators document_classification: type: - object - 'null' properties: id: type: string description: Document classification ID type: type: string description: Document type document_class_type: type: string description: Document class type detailed_type: type: - string - 'null' description: Detailed document type required: - id - type - document_class_type - detailed_type description: Document classification information required: - score - file_metadata - indicators - document_classification description: Simplified fraud detection result structure extracted_data_coordinates: type: - object - 'null' properties: version: type: number enum: - 1 description: >- Schema version for forward compatibility. Currently always 1. fields: type: object additionalProperties: type: array items: type: object properties: surface: type: object properties: type: type: string enum: - page description: >- Surface type. Currently only "page" is supported. number: type: integer exclusiveMinimum: 0 description: >- 1-indexed page number where the region is located example: 2 processed_number: type: - integer - 'null' exclusiveMinimum: 0 description: >- Page number after provider processing (e.g., after page reordering). Null when no reordering occurred. required: - type - number description: >- Identifies the document surface (page) where the coordinate region is located coordinate_space: type: string enum: - normalized_page description: >- Coordinate space identifier. Always "normalized_page", meaning all values are normalized to [0,1] relative to page dimensions. bbox: type: - object - 'null' properties: left: type: number minimum: 0 maximum: 1 description: >- Left edge X position, normalized to page width (0 = left edge, 1 = right edge) example: 0.177 top: type: number minimum: 0 maximum: 1 description: >- Top edge Y position, normalized to page height (0 = top edge, 1 = bottom edge) example: 0.783 width: type: number minimum: 0 maximum: 1 description: >- Width of the bounding box, normalized to page width example: 0.672 height: type: number minimum: 0 maximum: 1 description: >- Height of the bounding box, normalized to page height example: 0.016 required: - left - top - width - height description: >- Axis-aligned bounding box enclosing the region. Derived from polygon bounds when a polygon is present. Null when no spatial information is available. polygon: type: - array - 'null' items: type: object properties: x: type: number minimum: 0 maximum: 1 description: >- X coordinate normalized to page width (0 = left edge, 1 = right edge) example: 0.177 'y': type: number minimum: 0 maximum: 1 description: >- Y coordinate normalized to page height (0 = top edge, 1 = bottom edge) example: 0.783 required: - x - 'y' description: >- A single point in page-relative [0,1] coordinate space. Used as a vertex in polygon outlines. description: >- Ordered list of vertices forming a closed polygon that outlines the region. Provides finer spatial precision than the bounding box. Typically 4 points for rectangular regions. Null when only a bounding box is available (common for fraud indicators). detail: type: object additionalProperties: {} description: >- Optional metadata providing context about what was found at this location. For extraction coordinates, this is typically absent. For fraud indicators, may contain `original_text` and `new_text` showing tampered content. required: - surface - coordinate_space - bbox description: >- A coordinate reference pinpointing a region on a document page. Used to highlight where extracted data was found or where fraud indicators were detected. Coordinates are always in normalized [0,1] page-relative space. description: >- Map of extraction field paths to arrays of coordinate references. Keys use dot-notation with bracket indices for arrays (e.g., "invoice_number", "partners[0]", "line_items[2].amount"). Each field maps to one or more coordinate references indicating where on the document the value was extracted from. Multiple references mean the field value spans several regions (e.g., a multi-line address). example: partners[0]: - surface: type: page number: 2 coordinate_space: normalized_page bbox: left: 0.177 top: 0.783 width: 0.672 height: 0.016 polygon: - x: 0.177 'y': 0.783 - x: 0.848 'y': 0.783 - x: 0.848 'y': 0.799 - x: 0.177 'y': 0.799 required: - version - fields description: >- Maps each extracted data field to the coordinates of its source location(s) on the document. Allows clients to highlight or annotate the exact regions where data was read from. Each field path corresponds to a key in the `extracted_data` attribute. fraud_result_coordinates: type: - object - 'null' properties: version: type: number enum: - 1 description: >- Schema version for forward compatibility. Currently always 1. indicators: type: object additionalProperties: type: array items: type: object properties: surface: type: object properties: type: type: string enum: - page description: >- Surface type. Currently only "page" is supported. number: type: integer exclusiveMinimum: 0 description: >- 1-indexed page number where the region is located example: 2 processed_number: type: - integer - 'null' exclusiveMinimum: 0 description: >- Page number after provider processing (e.g., after page reordering). Null when no reordering occurred. required: - type - number description: >- Identifies the document surface (page) where the coordinate region is located coordinate_space: type: string enum: - normalized_page description: >- Coordinate space identifier. Always "normalized_page", meaning all values are normalized to [0,1] relative to page dimensions. bbox: type: - object - 'null' properties: left: type: number minimum: 0 maximum: 1 description: >- Left edge X position, normalized to page width (0 = left edge, 1 = right edge) example: 0.177 top: type: number minimum: 0 maximum: 1 description: >- Top edge Y position, normalized to page height (0 = top edge, 1 = bottom edge) example: 0.783 width: type: number minimum: 0 maximum: 1 description: >- Width of the bounding box, normalized to page width example: 0.672 height: type: number minimum: 0 maximum: 1 description: >- Height of the bounding box, normalized to page height example: 0.016 required: - left - top - width - height description: >- Axis-aligned bounding box enclosing the region. Derived from polygon bounds when a polygon is present. Null when no spatial information is available. polygon: type: - array - 'null' items: type: object properties: x: type: number minimum: 0 maximum: 1 description: >- X coordinate normalized to page width (0 = left edge, 1 = right edge) example: 0.177 'y': type: number minimum: 0 maximum: 1 description: >- Y coordinate normalized to page height (0 = top edge, 1 = bottom edge) example: 0.783 required: - x - 'y' description: >- A single point in page-relative [0,1] coordinate space. Used as a vertex in polygon outlines. description: >- Ordered list of vertices forming a closed polygon that outlines the region. Provides finer spatial precision than the bounding box. Typically 4 points for rectangular regions. Null when only a bounding box is available (common for fraud indicators). detail: type: object additionalProperties: {} description: >- Optional metadata providing context about what was found at this location. For extraction coordinates, this is typically absent. For fraud indicators, may contain `original_text` and `new_text` showing tampered content. required: - surface - coordinate_space - bbox description: >- A coordinate reference pinpointing a region on a document page. Used to highlight where extracted data was found or where fraud indicators were detected. Coordinates are always in normalized [0,1] page-relative space. description: >- Map of fraud indicator IDs to arrays of coordinate references. Keys match the `id` field from `fraud_result.indicators[]` (e.g., "grp_overlaps", "grp_fonts_suspicious"). Each indicator maps to one or more coordinate references showing where on the document the anomaly was detected. The `detail` field on each reference may contain contextual metadata such as `original_text` and `new_text` for tampering indicators. example: grp_overlaps: - surface: type: page number: 1 coordinate_space: normalized_page bbox: left: 0.471 top: 0.601 width: 0.397 height: 0.27 polygon: null detail: original_text: ParsedImage new_text: '' required: - version - indicators description: >- Maps each fraud indicator to the coordinates of the anomalous region(s) detected on the document. Allows clients to highlight or annotate regions where tampering, suspicious fonts, overlapping content, or other fraud signals were found. Keys correspond to indicator IDs from the `fraud_result.indicators` array. required: - status description: >- Document attributes (a subset is returned when a sparse fieldset is requested) relationships: type: object properties: document_template: type: object properties: data: type: - object - 'null' properties: type: type: string enum: - document-template description: Resource type example: document-template id: type: string format: uuid description: Resource identifier example: 123e4567-e89b-12d3-a456-426614174000 required: - type - id description: Resource identifier (null if relationship is empty) required: - data description: Document template relationship session: type: object properties: data: type: - object - 'null' properties: type: type: string enum: - session description: Resource type example: session id: type: string format: uuid description: Session identifier example: 123e4567-e89b-12d3-a456-426614174000 required: - type - id description: >- Session relationship (document 1:1 session, session 1:many documents) required: - data description: Session relationship description: Document relationships meta: type: object properties: extraction_config: type: object properties: enabled: type: boolean schema: type: object properties: type: type: string enum: - object properties: type: object additionalProperties: {} required: type: array items: type: string additionalProperties: type: boolean required: - type - properties - required additionalProperties: {} extraction_rules: type: string default: '' fraud_config: type: object properties: enabled: type: boolean requires_digital_signature: type: boolean required: - enabled file_url: type: string ocr_external_id: type: string fraud_check_external_id: type: string description: Document metadata required: - id - type - attributes FileInfoResponse: type: - object - 'null' properties: id: type: string filename: type: string content_type: type: string description: MIME type of the file example: image/jpeg byte_size: type: number description: File size in bytes example: 3340938 checksum: type: string description: SHA-256 checksum of the file example: cdff95d353d86a9fa1f06532a8ca212430d5b512efa669250c0777c9525d55fb status: type: string enum: - pending_upload - uploaded - failed - deleted url: type: string format: uri description: Presigned download URL (valid for 15 minutes) example: >- https://files.beltic.com/9941d601-0dd4-4a33-8043-4f158b480f0e/file?X-Amz-Signature=... required: - id - filename - content_type - byte_size - checksum - status - url securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key description: |- API key for authentication. Access https://console.beltic.com/ to obtain your API key. ````