Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: BYNN Documents 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:** Use your **Private API Key**, which looks like `private_xxxxxxxxxxxxxxxxxxxxxxxx` (or `private_sandbox_xxxxxxxxxxxxxxxxxxxxxxxx` for a sandbox key), as the username in HTTP Basic auth with an empty password, or send it as `Authorization: Bearer `. Your keys are at https://dashboard.bynn.com/integration.'
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'
servers:
- url: https://api.bynn.com/v1
tags:
- name: Documents
description: Operations about documents
paths:
/documents:
post:
summary: Create a submission
description: Create a new submission for a document to be analyzed
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/postDocuments'
required: true
security:
- PrivateKey: []
responses:
'201':
description: Create a submission
content:
application/json:
schema:
$ref: '#/components/schemas/Bynn_V1_Entities_Documents'
'404':
description: Invalid Document Type
content:
application/json:
schema:
$ref: '#/components/schemas/Bynn_V1_Entities_Error'
tags:
- Documents
operationId: postDocuments
get:
summary: List and search document submissions
description: 'Returns a paginated list of the organization''s document submissions, most
recent first, with optional free-text search.
### Query parameters
- `search` — optional, case-insensitive match on the document name or the
humanized document id (e.g. `5PGACUU2E`).
- `page` — optional, 1-based page number (default 1).
- `per_page` — optional, items per page (default 50, max 100).
### Response
A lightweight summary per document (use `GET /documents/:id` for the full
forensic analysis):
```
{
"documents": [
{
"submission_id": "document_UBCG4a...",
"document_id": "5PGACUU2E",
"name": "passport.jpg",
"reference_id": "your-ref-123",
"status": "analyzed",
"analysis_risk_status": "trusted",
"analysis_risk_score": 4,
"document_content_type": "passport",
"created_at": "2025-01-20T10:30:00Z"
}
],
"page": 1, "per_page": 50, "total": 128, "total_pages": 3
}
```
### Errors
- `401 authentication_error` — missing, malformed, or revoked private key.'
parameters:
- in: query
name: search
description: Case-insensitive search over document name and humanized id.
required: false
schema:
type: string
- in: query
name: page
description: 1-based page number (max 1000).
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 1000
default: 1
- in: query
name: per_page
description: Items per page (default 50, max 100).
required: false
schema:
type: integer
format: int32
minimum: 1
maximum: 100
default: 50
security:
- PrivateKey: []
responses:
'200':
description: List and search document submissions
tags:
- Documents
operationId: getDocuments
/documents/{id}:
get:
summary: Retrieve a document submission
description: '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`.'
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
delete:
summary: Delete a document submission
description: 'Deletes a previously submitted document.
The supplied identifier can be any of:
- the humanized `document_id` returned on creation (e.g. `5PGACUU2E`),
- the prefixed `submission_id` (`document_xxx`),
- the raw token.
This operation is idempotent — deleting an already-deleted document returns 200 with no error.'
parameters:
- in: path
name: id
description: Document identifier — accepts the humanized `document_id` returned on creation, the prefixed `document_xxx` token, or the raw token.
required: true
schema:
type: string
security:
- PrivateKey: []
responses:
'204':
description: Delete 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: deleteDocumentsId
components:
schemas:
postDocuments:
type: object
properties:
reference_id:
type: string
description: User-defined ID for the analyzed file, typically corresponding to the internal document ID used in your CMS or system. Please make sure the reference_id does not contain any personally identifiable information (PII) before submission. This identifier is used to reference and index the output from the document forensic analysis.
configuration:
type: string
description: ''
document_base64_strict:
type: string
description: Base64 Strict Encoded media (jpg, jpeg, png, pdf) - Use [file] or [document_base64_strict] to send the document.
file:
type: string
format: binary
description: File media sent as form-data (jpg, jpeg, png, pdf) - Use [file] or [document_base64_strict] to send the document.
characteristics:
type: object
description: Optional customer information and metadata
properties:
document:
type: object
description: Document characteristics
properties:
submission_time:
type: string
description: Document submission time
customer_tenant_id:
type: string
description: Customer-assigned identifier of tenant
customer_case_id:
type: string
description: Customer-assigned identifier of the case
document_type_string:
type: string
description: Unconstrained value for type of document
issuing_country_code:
type: string
description: ISO 3166-1 alpha-3 code of the country
document_id:
type: string
description: Document ID assigned by customer
document_filename:
type: string
description: Document filename
document_score:
type: string
description: Internal document score or classification
status:
type: string
description: Document submission status
document_position_on_image:
type: object
description: Position of document on image
source_channel:
type: string
description: Channel that the document originated from
enum:
- api
- web
- mobile
document_side:
type: string
description: Side of the document
enum:
- front
- back
device:
type: object
description: Device characteristics
properties:
device_ip_address:
type: string
description: Public IP address of device
server_ip_address:
type: string
description: IP address of the server
country_code:
type: string
description: ISO 3166-1 alpha-3 code
country_name:
type: string
description: Country name
city:
type: string
description: City
postal_code:
type: string
description: Postal code
gcs_latitude:
type: string
description: Latitude in decimal degrees
gcs_longitude:
type: string
description: Longitude in decimal degrees
isp:
type: string
description: Internet service provider
referer:
type: string
description: Browser referer url
user_agent:
type: string
description: User agent of the browser
browser_description:
type: string
description: Browser description
device_platform:
type: string
description: Device platform
device_language:
type: string
description: Device language (ISO 639-1)
screen_height:
type: integer
format: int32
description: Screen height in pixels
screen_width:
type: integer
format: int32
description: Screen width in pixels
device_fingerprint:
type: string
description: Unique identifier of the device
identity:
type: object
description: User identity characteristics
properties:
first_name:
type: string
description: First name
last_name:
type: string
description: Last name
email:
type: string
description: Email address
user_id:
type: string
description: User ID assigned by customer
user_group_id:
type: string
description: User grouping ID
phone_number:
type: string
description: Phone number
date_of_birth:
type: string
description: Date of birth (YYYY-MM-DD)
transaction:
type: object
description: Transaction characteristics
properties:
amount_usd:
type: number
format: float
description: Amount converted to USD
maturity_days:
type: integer
format: int32
description: Number of days until maturity
email:
type: object
description: Email interaction characteristics
properties:
originator_address_hashes:
type: array
description: SHA256 hashes of originator email addresses
items:
type: string
originator_domain_hashes:
type: array
description: SHA256 hashes of originator domains
items:
type: string
subject_hash:
type: string
description: SHA256 hash of email subject
number_of_recipients:
type: integer
format: int32
description: Number of email recipients
recipient_hashes:
type: array
description: Hashes of email recipients
items:
type: string
body_embedding:
type: string
description: Embedding of email body
subject_embedding:
type: string
description: Embedding of email subject
claims:
type: object
description: Insurance claims characteristics
properties:
claim_number:
type: string
description: Claim number
policy_number:
type: string
description: Policy number
insurance_type:
type: string
description: Insurance type
incident_date:
type: string
description: Incident date (YYYY-MM-DD)
reported_date:
type: string
description: Reported date (YYYY-MM-DD)
incident_description:
type: string
description: Incident description
incident_location:
type: string
description: Incident location
claim_value:
type: number
format: float
description: Claim value
description: Create a submission
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
reason:
type: string
example: issuer_key_unavailable
description: Machine-readable cause, where one is set
retry_after:
type: integer
format: int32
example: 60
description: Seconds to wait before retrying
limit:
type: integer
format: int32
example: 30
description: The limit that was exceeded
detail:
type: string
description: Operator-facing detail, outside production
required:
- type
- message
required:
- error
description: Bynn_V1_Entities_Error model
Bynn_V1_Entities_Documents:
type: object
properties:
submission_id:
type: string
example: UBCG4aCU2dUMLGRPJU5PHyJL
description: Document submission ID
document_id:
type: string
example: 5PGACUU2E
description: Document ID
status:
type: string
enum:
- received
description: Result
jwt:
type: string
description: JSON WebToken (only for non pre-authenticated requests)
required:
- submission_id
- document_id
- status
- jwt
description: Bynn_V1_Entities_Documents model
securitySchemes:
PrivateKey:
type: apiKey
name: Authorization
in: header
description: Enter your PRIVATE KEY token prefixed with `Bearer `, e.g. `Bearer your_token_here`
PublicKey:
type: apiKey
name: Authorization
in: header
description: Enter your PUBLIC KEY token prefixed with `Bearer `, e.g. `Bearer your_token_here`