--- updatedAt: 2026-04-29T12:10:54.000Z agentTools: projectIndex: https://docs.bynn.com/llms.txt --- # Retrieve a document submission Retrieves a previously submitted document together with the full forensic analysis result. ### Identifier formats The `:id` path parameter accepts any of the three identifiers Bynn returns when a document is submitted: | Format | Example | Source | | --- | --- | --- | | Humanized document ID | `5PGACUU2E` | `document_id` field of the create response | | Prefixed submission ID | `document_UBCG4aCU2dUMLGRPJU5PHyJL` | `submission_id` field of the create response | ### Polling / webhook for analysis completion Forensic analysis is asynchronous, we recommend using webhook and get the result from there. Immediately after creation `status` is `pending`; once analysis finishes it becomes `analyzed` (or `error` if it could not be processed). Poll this endpoint, or subscribe to the document webhook, to receive the final result. Recommended polling interval is 30 seconds. The endpoint is rate-limited to 500 requests per minute per organization. ### Response Returns the same payload that is delivered to the configured `document.analyzed` webhook. Notable fields include: - `submission_id` — prefixed `document_`, matches `submission_id` from the create response - `request_id` — humanized document ID (e.g. `5PGACUU2E`) - `status` — `pending`, `analyzed`, or `error` - `analysis_risk_status` — `pending`, `trusted`, `low`, `medium`, `high`, `fraud`, or `rejected` - `analysis_risk_score` — integer 0–100 - `document_content_type` — detected document type (e.g. `passport`, `bank_statements`, `invoice`) - `ai_generated_score`, `ai_deepfake_score`, `ai_generated_or_modified` — AI-generation signals - `ai_analysis`, `image_manipulation`, `tampering_results`, `address_validation`, `signature_details`, `barcode_details`, `qr_tax_system`, `goverlink`, `exif`, `xray` — detailed forensic findings - `risk_tags`, `risk_tags_detailed` — human-readable risk indicators - `original_file_url`, `media` — signed URLs to the uploaded file and rendered previews - `reference_id` — the customer-supplied `reference_id` from creation - `created_at`, `updated_at` — ISO 8601 timestamps ### Errors - `401 authentication_error` — no key, malformed key, or the key has been revoked. - `404 not_found` — no document with the given identifier exists in this organization. Deleted documents (see `DELETE /documents/:id`) also return `404`. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "BYNN API", "description": "The BYNN API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects. To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no “switch” for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test-mode credentials never hit live networks and incur no cost. **AUTHENTICATION:** Please use your **Private API Key** that looks like this `private_Nv7UpwQbSmWtUTiSWfw1bdHm` as the username and password in HTTP basic auth.", "termsOfService": "https://bynn.com/terms", "contact": { "name": "BYNN Development Team", "email": "hello@bynn.com", "url": "https://docs.bynn.com" }, "license": { "name": "BYNN Documentation", "url": "https://docs.bynn.com" }, "version": "1.0" }, "tags": [ { "name": "documents", "description": "Operations about documents" } ], "paths": { "/documents/{id}": { "get": { "summary": "Retrieve a document submission", "description": "Retrieves a previously submitted document together with the full forensic analysis result.\n\n\n### Identifier formats\nThe `:id` path parameter accepts any of the three identifiers Bynn returns when a document is submitted:\n\n| Format | Example | Source |\n| --- | --- | --- |\n| Humanized document ID | `5PGACUU2E` | `document_id` field of the create response |\n| Prefixed submission ID | `document_UBCG4aCU2dUMLGRPJU5PHyJL` | `submission_id` field of the create response |\n\n\n### Polling / webhook for analysis completion\nForensic analysis is asynchronous, we recommend using webhook and get the result from there. Immediately after creation `status` is `pending`; once analysis finishes it becomes `analyzed` (or `error` if it could not be processed). Poll this endpoint, or subscribe to the document webhook, to receive the final result.\nRecommended polling interval is 30 seconds. The endpoint is rate-limited to 500 requests per minute per organization.\n\n### Response\nReturns the same payload that is delivered to the configured `document.analyzed` webhook. Notable fields include:\n\n- `submission_id` — prefixed `document_`, matches `submission_id` from the create response\n- `request_id` — humanized document ID (e.g. `5PGACUU2E`)\n- `status` — `pending`, `analyzed`, or `error`\n- `analysis_risk_status` — `pending`, `trusted`, `low`, `medium`, `high`, `fraud`, or `rejected`\n- `analysis_risk_score` — integer 0–100\n- `document_content_type` — detected document type (e.g. `passport`, `bank_statements`, `invoice`)\n- `ai_generated_score`, `ai_deepfake_score`, `ai_generated_or_modified` — AI-generation signals\n- `ai_analysis`, `image_manipulation`, `tampering_results`, `address_validation`, `signature_details`, `barcode_details`, `qr_tax_system`, `goverlink`, `exif`, `xray` — detailed forensic findings\n- `risk_tags`, `risk_tags_detailed` — human-readable risk indicators\n- `original_file_url`, `media` — signed URLs to the uploaded file and rendered previews\n- `reference_id` — the customer-supplied `reference_id` from creation\n- `created_at`, `updated_at` — ISO 8601 timestamps\n\n### Errors\n- `401 authentication_error` — no key, malformed key, or the key has been revoked.\n- `404 not_found` — no document with the given identifier exists in this organization. Deleted documents (see `DELETE /documents/:id`) also return `404`.\n\n\n", "parameters": [ { "in": "path", "name": "id", "description": "Document identifier. Accepts the humanized `document_id` (`5PGACUU2E`), the prefixed `submission_id` (`document_xxx`), or the raw token returned when the document was created.", "required": true, "schema": { "type": "string" } } ], "security": [ { "PrivateKey": [] } ], "responses": { "200": { "description": "Retrieve a document submission" }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Document not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "documents" ], "operationId": "getDocumentsId" } } }, "servers": [ { "url": "//api.bynn.com/v1" } ], "components": { "securitySchemes": { "PrivateKey": { "type": "apiKey", "name": "Authorization", "in": "header", "description": "Enter your PRIVATE KEY token prefixed with `Bearer `, e.g. `Bearer your_token_here`" } }, "schemas": { "Bynn_V1_Entities_Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "example": "validation_error", "description": "Type of error" }, "message": { "type": "string", "example": "Invalid parameters", "description": "Error message" } }, "required": [ "type", "message" ] } }, "required": [ "error" ], "description": "Bynn_V1_Entities_Error model" } } } } ```