{ "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:** 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" }, "tags": [ { "name": "dossiers", "description": "Operations about dossiers" }, { "name": "aml", "description": "Operations about amls" }, { "name": "api_keys", "description": "Operations about api_keys" }, { "name": "autodoc", "description": "Operations about autodocs" }, { "name": "sessions", "description": "Operations about sessions" }, { "name": "age_verification", "description": "Operations about age_verifications" }, { "name": "documents", "description": "Operations about documents" }, { "name": "nfc", "description": "Operations about nfcs" }, { "name": "moderation", "description": "Operations about moderations" }, { "name": "Face Collections", "description": "Operations about Face Collections" }, { "name": "Face Enrollment", "description": "Operations about Face Enrollments" }, { "name": "Face Search", "description": "Operations about Face Searches" } ], "paths": { "/dossiers": { "post": { "summary": "Create a dossier", "description": "Creates a new KYC or KYB dossier (a verification case) under one of your\nverification levels, provisions the applicant and a hosted verification\nsession, and returns the dossier token together with the verification URL\n(and, optionally, a QR code).\n\nChoose the product with the `type` parameter (`kyc` or `kyb`). The level you\nreference must belong to the same product family.\n\n### Sending the invite\nSet `send_sms` and/or `send_email` (with a `phone_number` / `email_address`) to\nhave Bynn deliver the verification link to the applicant for you. Otherwise the\nreturned `verification_url` (and optional `qr_base64_png`) is yours to deliver.\n\n\n### Retrieving results later\nAfter the applicant completes the session (see the `session.completed` webhook,\nwhich returns this `dossier_id`), call `GET /dossiers/:id` to fetch the full\nresult including the liveness selfie and ID-document images.\n\n### Errors\n- `401 authentication_error` — missing, malformed, or revoked private key.\n- `402 payment_required` — the request could not be completed for this account.\n- `404 validation_error` — no matching level for the requested `type`.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postDossiers" } } }, "required": true }, "security": [ { "PrivateKey": [] } ], "responses": { "201": { "description": "Create a dossier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_DossierCreatedEntity" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "No matching level for the requested type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "dossiers" ], "operationId": "postDossiers" }, "get": { "summary": "List and search dossiers", "description": "Returns a paginated list of the organization's dossiers (KYC, KYB and doc),\nmost recent first, with optional search and filtering. Each row is a\nlightweight summary — call `GET /dossiers/:id` for the full detail of a single\ndossier (media, applicants, identity documents, liveness images).\n\n### Query parameters\n- `search` — optional, case-insensitive match on the dossier name, humanized\n token, or your customer reference (`customer_identification`).\n- `status` — optional business status filter (`open`, `approved`, `rejected`, …).\n- `type` — optional dossier type filter (`kyc`, `kyb`, `doc`).\n- `date_from` / `date_to` — optional ISO 8601 created-at range.\n- `page` — optional, 1-based page number (default 1, max 1000).\n- `per_page` — optional, items per page (default 50, max 100).\n\n### Response\n```\n{\n \"dossiers\": [\n {\n \"id\": \"dossier_xxx\",\n \"token\": \"U45XZQE9N\",\n \"type\": \"kyc\",\n \"status\": \"approved\",\n \"name\": \"Jane Doe\",\n \"reference\": \"user-123\",\n \"risk_score\": 4,\n \"is_test\": false,\n \"download_status\": \"not_downloaded\",\n \"documents_count\": 2,\n \"created_at\": \"2025-01-20T10:30:00Z\",\n \"updated_at\": \"2025-01-20T10:35:00Z\",\n \"completed_at\": \"2025-01-20T10:34:00Z\"\n }\n ],\n \"page\": 1, \"per_page\": 50, \"total\": 128, \"total_pages\": 3\n}\n```\n\n### Errors\n- `401 authentication_error` — missing, malformed, or revoked private key.\n", "parameters": [ { "in": "query", "name": "search", "description": "Case-insensitive search over dossier name, humanized token and customer reference.", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "status", "description": "Filter by business status.", "required": false, "schema": { "type": "string", "enum": [ "draft", "open", "completed", "archived", "closed", "needs_attention", "approved", "rejected" ] } }, { "in": "query", "name": "type", "description": "Filter by dossier type.", "required": false, "schema": { "type": "string", "enum": [ "not_specified", "kyc", "kyb", "doc" ] } }, { "in": "query", "name": "date_from", "description": "Only dossiers created on/after this ISO 8601 timestamp.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "date_to", "description": "Only dossiers created on/before this ISO 8601 timestamp.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "page", "description": "Offset pagination: 1-based page number (max 1000). Ignored when `starting_after` is given.", "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 } }, { "in": "query", "name": "starting_after", "description": "Keyset pagination: a dossier id (`dossier_xxx`) from a previous page; returns the dossiers immediately after it. Cheaper than `page` for large result sets (no COUNT, no deep OFFSET). When given, `page`/`total` are not used — the response returns `has_more` + `next_cursor` instead.", "required": false, "schema": { "type": "string" } } ], "security": [ { "PrivateKey": [] } ], "responses": { "200": { "description": "List and search dossiers" } }, "tags": [ "dossiers" ], "operationId": "getDossiers" } }, "/dossiers/{id}": { "get": { "summary": "Retrieve a dossier", "description": "Retrieves a single dossier (a KYC/KYB case) with the full detail rendered in\nthe Bynn dashboard: dossier fields, **all dossier media**, and every applicant\n(entity) with their personal information, identity documents, captured media\nand **all liveness selfie frames** — each media asset tagged with its type and\na download URL.\n\n### Getting the dossier id\nThe `:id` accepts the prefixed dossier token (`dossier_xxx`) or the humanized\ntoken (e.g. `U45XZQE9N`). You receive `dossier_id` in the `session.completed`,\n`identity_document.*` and `decision.*` webhook events, and as `rel.url` on the\ndossier webhook payload. This endpoint is the supported way to fetch an\napplicant's liveness selfie and ID-document (front/back) images after a session\ncompletes.\n\n### ⚠️ Media URLs are short-lived — download immediately\nEvery `url` in the response (`media[].url`, `entities[].media[].url`,\n`entities[].identity_documents[].images[].url`, `entities[].liveness_images[].url`)\nis a **presigned, short-lived link** — it typically expires within **~5 minutes**.\nDownload and persist the files on your side **immediately** upon receiving the\nresponse. Do **not** store or cache the URLs themselves; request a fresh dossier\nto mint new URLs when needed.\n\n### Response\nSee `DossierEntity`. Notable fields:\n- `id` — prefixed `dossier_`\n- `type` — `kyc`, `kyb`, `doc`\n- `status` — business status (`open`, `approved`, `rejected`, …)\n- `media[]` — every dossier-level asset (`{ type, name, page, url, created_at }`)\n- `entities[]` — applicants, each with `identity_documents[]`, `media[]` and\n `liveness_images[]`\n\n### Errors\n- `401 authentication_error` — missing, malformed, or revoked private key.\n- `404 not_found` — no dossier with the given identifier exists in this organization.\n", "parameters": [ { "in": "path", "name": "id", "description": "Dossier identifier. Accepts the prefixed token (`dossier_xxx`) or the humanized token (e.g. `U45XZQE9N`).", "required": true, "schema": { "type": "string" } } ], "security": [ { "PrivateKey": [] } ], "responses": { "200": { "description": "Retrieve a dossier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_DossierEntity" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Dossier not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "dossiers" ], "operationId": "getDossiersId" } }, "/dossiers/entity/{id}": { "get": { "summary": "Retrieve an applicant (entity)", "description": "Returns the applicant payload delivered by `entity.*` webhooks (personal info + address).", "parameters": [ { "in": "path", "name": "id", "description": "Applicant identifier (`entity_xxx`).", "required": true, "schema": { "type": "string" } } ], "security": [ { "PrivateKey": [] } ], "responses": { "200": { "description": "Retrieve an applicant (entity)" }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "dossiers" ], "operationId": "getDossiersEntityId" } }, "/dossiers/identity_document/{id}": { "get": { "summary": "Retrieve an identity document", "description": "Returns the identity-document payload delivered by `identity_document.*` webhooks\n(document fields, MRZ flags) for the `id_doc_xxx` id, plus an `images` array with\nthe captured front/back (and cropped) images.\n\nThe image `url`s are short-lived presigned links (~5 minutes) — download\nimmediately, do not cache the URLs.\n", "parameters": [ { "in": "path", "name": "id", "description": "Identity document identifier (`id_doc_xxx`).", "required": true, "schema": { "type": "string" } } ], "security": [ { "PrivateKey": [] } ], "responses": { "200": { "description": "Retrieve an identity document" }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "dossiers" ], "operationId": "getDossiersIdentityDocumentId" } }, "/dossiers/decision/{id}": { "get": { "summary": "Retrieve a decision", "description": "Returns the decision payload delivered by `decision.*` webhooks (status, embedded dossier / entity / identity_document, risk tags).", "parameters": [ { "in": "path", "name": "id", "description": "Decision identifier (`decision_xxx`).", "required": true, "schema": { "type": "string" } } ], "security": [ { "PrivateKey": [] } ], "responses": { "200": { "description": "Retrieve a decision" }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "dossiers" ], "operationId": "getDossiersDecisionId" } }, "/dossiers/address_proof/{id}": { "get": { "summary": "Retrieve a proof of address", "description": "Returns the address-proof payload delivered by `address_proof.*` webhooks.", "parameters": [ { "in": "path", "name": "id", "description": "Address proof identifier (`poa_xxx`).", "required": true, "schema": { "type": "string" } } ], "security": [ { "PrivateKey": [] } ], "responses": { "200": { "description": "Retrieve a proof of address" }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "dossiers" ], "operationId": "getDossiersAddressProofId" } }, "/dossiers/funds_proof/{id}": { "get": { "summary": "Retrieve a proof of funds", "description": "Returns the funds-proof payload delivered by `funds_proof.*` webhooks.", "parameters": [ { "in": "path", "name": "id", "description": "Funds proof identifier (`pof_xxx`).", "required": true, "schema": { "type": "string" } } ], "security": [ { "PrivateKey": [] } ], "responses": { "200": { "description": "Retrieve a proof of funds" }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "dossiers" ], "operationId": "getDossiersFundsProofId" } }, "/aml/entity/{id}": { "get": { "summary": "Retrieve an AML entity", "description": "Returns the AML-entity payload delivered by `aml_entity.*` webhooks (screening status).", "parameters": [ { "in": "path", "name": "id", "description": "AML entity identifier (`aml_xxx`).", "required": true, "schema": { "type": "string" } } ], "security": [ { "PrivateKey": [] } ], "responses": { "200": { "description": "Retrieve an AML entity" }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "aml" ], "operationId": "getAmlEntityId" } }, "/aml/activity/{id}": { "get": { "summary": "Retrieve an AML activity / match", "description": "Returns the AML-activity payload delivered by `aml_activity.*` webhooks (the individual screening match).", "parameters": [ { "in": "path", "name": "id", "description": "AML activity identifier (`amla_xxx`).", "required": true, "schema": { "type": "string" } } ], "security": [ { "PrivateKey": [] } ], "responses": { "200": { "description": "Retrieve an AML activity / match" }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Not found in this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "aml" ], "operationId": "getAmlActivityId" } }, "/aml/search": { "post": { "summary": "Search AML data (sanctions, PEP & watchlists)", "description": "Screens a name against Bynn's AML data — global sanctions, PEP (politically\nexposed persons), and watchlists.\n\nSearch for a **person** or an **entity** (company / organization) with the\n`type` parameter. Returns the ranked matches; use the returned `id` with the\nAML detail endpoints to pull a full profile.\n\n### Response\n```\n{\n \"query\": \"John Doe\",\n \"type\": \"person\",\n \"total\": 2,\n \"results\": [\n { \"id\": \"NK-…\", \"name\": \"John Doe\", \"schema\": \"Person\", \"match\": true,\n \"score\": 0.92, \"topics\": [\"sanction\"], \"birth_date\": [\"1965-04-12\"],\n \"country\": [\"ru\"] }\n ]\n}\n```\n\n### Errors\n- `401 authentication_error` — missing, malformed, or revoked private key.\n- `402 payment_required` — the request could not be completed for this account.\n- `503 service_unavailable` — screening is temporarily unavailable; retry.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postAmlSearch" } } }, "required": true }, "security": [ { "PrivateKey": [] } ], "responses": { "201": { "description": "Search AML data (sanctions, PEP & watchlists)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_AmlSearchResultEntity" } } } }, "401": { "description": "Invalid or missing credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "503": { "description": "Screening temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "aml" ], "operationId": "postAmlSearch" } }, "/api_keys/public": { "get": { "summary": "Get the organization public API key", "description": "Returns the PUBLIC API key for the organization identified by the PRIVATE API\nkey used to authenticate this request.\n\nThis lets a server-side integration that holds only the private key obtain the\nmatching public key — which is required to create client-side verification\nsessions (e.g. `POST /v1/sessions`) — without logging in to the dashboard.\n\nThe returned public key matches the mode (test vs live) of the private key used\nto authenticate: a test private key returns the test public key, a live private\nkey returns the live public key.\n\n### Response\n- `public_key` — the organization's public API key string (e.g. `public_...`)\n- `is_test` — whether this is a test-mode key\n\n### Errors\n- `401 authentication_error` — missing, malformed, or revoked private key.\n- `404 not_found` — the organization has no public key of the matching mode.\n", "security": [ { "PrivateKey": [] } ], "responses": { "200": { "description": "Get the organization public API key" } }, "tags": [ "api_keys" ], "operationId": "getApiKeysPublic" } }, "/autodoc/invitations/locales": { "get": { "summary": "List supported invitation locales", "description": "Returns the list of IETF language tags supported as the `locale` parameter on POST /v1/autodoc/invitations.\n\nEach entry has a `code` (the value to send) and a `name` (a human-readable label rendered in the requesting user's locale where available, falling back to the uppercased code).\n\n", "security": [ { "PrivateKey": [] }, { "JwtAuth": [] } ], "responses": { "200": { "description": "List supported invitation locales" }, "401": { "description": "unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "autodoc" ], "operationId": "getAutodocInvitationsLocales" } }, "/autodoc/invitations": { "get": { "summary": "List AutoDoc invitations", "description": "Returns a paginated list of AutoDoc invitations belonging to the authenticated organization. Results are ordered by creation date, newest first.\n\n**Filtering.** All filter parameters are optional and combine with AND semantics. Use `reference` to look up invitations you previously created with a specific customer-defined identifier (e.g. your CRM customer ID). Use `search` for partial matches on the recipient email or phone (case-insensitive). Use `workflow_token`, `status`, or `channel` to narrow the result set. Use `date_from` / `date_to` to constrain creation time.\n\n**Pagination.** Default page size is 20, maximum 100. Use `page` (1-indexed) and `per_page` to navigate. Response includes a `pagination` object with `total`, `totalPages`, `page`, and `perPage`.\n\n", "parameters": [ { "in": "query", "name": "page", "description": "Page number (1-indexed). Defaults to 1.", "required": false, "example": 1, "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "in": "query", "name": "per_page", "description": "Items per page. Min 1, max 100. Defaults to 20.", "required": false, "example": 20, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 100, "default": 20 } }, { "in": "query", "name": "workflow_token", "description": "Filter by workflow token (e.g. wf_xxx). Returns only invitations created against this workflow.", "required": false, "example": "wf_ULA5NSu9pRsUctA9DBmkRQya", "schema": { "type": "string" } }, { "in": "query", "name": "status", "description": "Filter by lifecycle status.", "required": false, "example": "sent", "schema": { "type": "string", "enum": [ "pending", "sent", "delivered", "opened", "started", "failed", "completed", "rejected" ] } }, { "in": "query", "name": "channel", "description": "Filter by delivery channel.", "required": false, "example": "email", "schema": { "type": "string", "enum": [ "email", "sms" ] } }, { "in": "query", "name": "reference", "description": "Exact-match filter on the customer-defined reference. Use to look up invitations by your own customer ID, order number, or other external identifier.", "required": false, "example": "cust_42891", "schema": { "type": "string" } }, { "in": "query", "name": "date_from", "description": "Filter to invitations created on or after this timestamp (ISO 8601).", "required": false, "example": "2026-04-01T00:00:00Z", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "date_to", "description": "Filter to invitations created on or before this timestamp (ISO 8601).", "required": false, "example": "2026-04-30T23:59:59Z", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "search", "description": "Case-insensitive partial match against the recipient field (email or phone). Special LIKE characters are escaped. Minimum 3 characters required to avoid full-table scans.", "required": false, "example": "jane", "schema": { "type": "string" } } ], "security": [ { "PrivateKey": [] }, { "JwtAuth": [] } ], "responses": { "200": { "description": "List AutoDoc invitations" }, "400": { "description": "invalid_request_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "401": { "description": "unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "autodoc" ], "operationId": "getAutodocInvitations" }, "post": { "summary": "Send an AutoDoc invitation", "description": "Sends an invitation to a recipient (by email or SMS) to start a specific AutoDoc workflow. The recipient receives a link that opens the AutoDoc visitor app and begins the workflow with their identity already attached to the resulting dossier.\n\n**Lifecycle.** A new invitation is created with `status: pending`. A background delivery job is enqueued immediately; once the channel provider has accepted the message, status flips to `sent` and `sentAt` is populated. Subsequent provider-side events advance status through `delivered`, `opened`, and `started`. If delivery fails permanently the invitation is marked `failed` and `errorMessage` is populated.\n\n**Link expiration.** Invitation links are valid for 30 days from creation. After expiration the link returns an error to the recipient. There is no automatic resend — create a new invitation if needed.\n\n**Channel-specific behavior.**\n- `email`: a branded HTML email is sent to `recipient`. Use a valid email address. Emails are sent from `@auto-doc.ai` with your organization name as the display name (e.g. `Acme Corp `). \n- `sms`: a short message containing the start URL is sent to `recipient`. Use E.164 (`+15551234567`) or international format. Loose validation accepts most readable phone formats.\n\n**Idempotency.** This endpoint is **not** idempotent — repeated calls create new invitations. If you need de-duplication, send a unique `reference` and check `GET /v1/autodoc/invitations?reference=...` before retrying.\n\n**Recipient URL shape.** The link delivered to the recipient is:\n`https://start.auto-doc.ai/?invitation_token=`\nThe invitation token in the query string lets the visitor app correlate the resulting dossier with this invitation.\n\n**Localization.** Set `locale` to one of the supported language codes to send the email or SMS in that language. Supported codes are returned by `GET /v1/autodoc/invitations/locales`. Defaults to the organization's default locale or English.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postAutodocInvitations" } } }, "required": true }, "security": [ { "PrivateKey": [] }, { "JwtAuth": [] } ], "responses": { "201": { "description": "Send an AutoDoc invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_AutoDocInvitation" } } } }, "400": { "description": "invalid_request_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "401": { "description": "unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "402": { "description": "insufficient_balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "workflow_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "422": { "description": "validation_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "429": { "description": "rate_limit_exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "autodoc" ], "operationId": "postAutodocInvitations" } }, "/autodoc/invitations/{token}": { "get": { "summary": "Get an AutoDoc invitation", "description": "Returns a single invitation by its token. Use this endpoint to poll the lifecycle status of an invitation you previously created — `status` advances through `pending` → `sent` → `delivered` → `opened` → `started` as the recipient interacts with the link.\n\n**Lookup.** The `:token` segment accepts either the prefixed form (`adi_xxx`) or the raw token. The endpoint returns 404 if the invitation does not exist or belongs to a different organization (no existence leak across tenants).\n\n", "parameters": [ { "in": "path", "name": "token", "description": "Invitation token (adi_xxx).", "required": true, "example": "adi_abc123def456", "schema": { "type": "string" } } ], "security": [ { "PrivateKey": [] }, { "JwtAuth": [] } ], "responses": { "200": { "description": "Get an AutoDoc invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_AutoDocInvitation" } } } }, "401": { "description": "unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "autodoc" ], "operationId": "getAutodocInvitationsToken" } }, "/autodoc/invitations/{token}/resend": { "post": { "summary": "Resend an invitation", "description": "Re-dispatches the email or SMS for an invitation that was previously sent. Use this when the recipient never received the original (filtered, deleted, or wrong inbox) and asks for a copy.\n\n**What resend does.** Flips the invitation status from `sent` back to `pending`, clears `sentAt`, and enqueues a fresh delivery via the same job pipeline that handled the original send. Status will move `pending` → `sent` again as soon as the channel provider accepts the message. If the linked dossier already exists (recipient had partially started before), the link is preserved — only the delivery layer is re-fired.\n\n**Eligibility.** Only invitations in `sent` status can be resent. Other statuses are rejected:\n- `pending`: original delivery is still in flight; wait for it to settle.\n- `delivered`, `opened`, `started`, `completed`, `rejected`: the recipient has already engaged; resending would create confusion.\n- `failed`: handled by the delivery job's automatic retry — see invitation lifecycle.\n\n**Expiration.** Expired invitations cannot be resent. Create a new invitation instead.\n\n**Per-invitation limits.**\n- **Maximum 10 send attempts** per invitation (initial send + each successful resend). Once `deliveryAttempts` reaches 10, this endpoint returns 422 `max_attempts_reached`. Create a new invitation to continue contacting the recipient.\n- **3-minute cooldown** between sends. Resending within 3 minutes of `sentAt` returns 429 `cooldown_active` with a `remaining_seconds` hint in the error message.\n\n**Billing.** Resends are billed at the same rate as the original send (`send.email` for email, `send.sms` for SMS). Test private keys (the test counterpart of a live key) are not billed.\n\n**Authentication.** Both `JwtAuth` and `PrivateKey` are accepted. Per-IP throttle: 30 requests per minute. Per-organization throttle: 20 resends per minute (separate bucket from invitation creation).\n", "parameters": [ { "in": "path", "name": "token", "description": "Invitation token (adi_xxx).", "required": true, "example": "adi_abc123def456", "schema": { "type": "string" } } ], "security": [ { "PrivateKey": [] }, { "JwtAuth": [] } ], "responses": { "201": { "description": "Resend an invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_AutoDocInvitation" } } } }, "401": { "description": "unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "402": { "description": "insufficient_balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "422": { "description": "invalid_state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "429": { "description": "rate_limit_exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "autodoc" ], "operationId": "postAutodocInvitationsTokenResend" } }, "/sessions": { "post": { "summary": "Create a new identity verification session", "description": "Creates a new identity verification session using the provided applicant information. Returns the session token, URL, and optionally a QR code image as a base64 encoded PNG.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postSessions" } } }, "required": true }, "security": [ { "PublicKey": [] } ], "responses": { "201": { "description": "Create a new identity verification session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Session" } } } }, "404": { "description": "Invalid KYC Level", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "sessions" ], "operationId": "postSessions" } }, "/sessions/{session_id}": { "delete": { "summary": "Cancel / Abort a session", "description": "Cancels an active session identified by the session token. Returns a status message indicating if the cancellation was successful. Call this endpoint if applicant choose to abort or cancel the verification flow or if consent in rejected.", "parameters": [ { "in": "path", "name": "session_id", "description": "Unique session token to cancel", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancel / Abort a session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_SessionCancellation" } } } }, "404": { "description": "Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "sessions" ], "operationId": "deleteSessionsSessionId" }, "post": { "summary": "Update an existing session", "description": "Updates the session details using the provided parameters. Supports updating personal and contact information. Returns a status message if the update is successful.", "parameters": [ { "in": "path", "name": "session_id", "description": "Unique session token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postSessionsSessionId" } } }, "required": true }, "responses": { "201": { "description": "Update an existing session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_SessionUpdate" } } } }, "400": { "description": "Bad Request - Invalid phone or email format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "sessions" ], "operationId": "postSessionsSessionId" }, "get": { "summary": "Show session information", "description": "Shows session information.", "parameters": [ { "in": "path", "name": "session_id", "description": "Unique session token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Show session information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Session" } } } }, "404": { "description": "Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "410": { "description": "Session canceled or consent not given", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "sessions" ], "operationId": "getSessionsSessionId" } }, "/sessions/{session_id}/send_sms": { "post": { "summary": "Send SMS (device switch)", "description": "Sends an SMS to the specified phone number for the session identified by :session_id. The SMS includes a mobile code link so that the user can continue on their mobile phone.", "parameters": [ { "in": "path", "name": "session_id", "description": "Unique session token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postSessionsSessionIdSendSms" } } }, "required": true }, "responses": { "201": { "description": "Send SMS (device switch)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_SmsResponse" } } } }, "400": { "description": "Invalid phone number or unable to send SMS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "429": { "description": "Too many attempts to send SMS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "sessions" ], "operationId": "postSessionsSessionIdSendSms" } }, "/sessions/{session_id}/preflight": { "get": { "summary": "Get next verification step", "description": "Checks next step for session in verification flow, this shall be polled after each completed action to check next step.", "parameters": [ { "in": "path", "name": "session_id", "description": "Unique session token to do preflight request for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get next verification step", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Preflight" } } } }, "404": { "description": "Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "410": { "description": "Session canceled or consent not given", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "451": { "description": "No consent given, please ask user for consent to process and store PII data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "sessions" ], "operationId": "getSessionsSessionIdPreflight" } }, "/sessions/{session_id}/consent": { "patch": { "summary": "Consent", "description": "", "parameters": [ { "in": "path", "name": "session_id", "description": "Unique session token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/patchSessionsSessionIdConsent" } } }, "required": true }, "responses": { "200": { "description": "Consent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_StatusResponse" } } } }, "404": { "description": "Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "sessions" ], "operationId": "patchSessionsSessionIdConsent" } }, "/sessions/{session_id}/liveness/start": { "post": { "summary": "Start a liveness capture", "description": "Start a liveness capture for the session identified by :session_id. Run this to get the credentials for the liveness capture SDK.", "parameters": [ { "in": "path", "name": "session_id", "description": "Unique session token", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Start a liveness capture", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_LivenessStart" } } } }, "400": { "description": "Could not start liveness", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "sessions" ], "operationId": "postSessionsSessionIdLivenessStart" } }, "/sessions/{session_id}/liveness/complete": { "post": { "summary": "Complete a liveness capture", "description": "Complete a liveness capture for the session identified by :session_id. Run this after the liveness capture SDK is finnished to see if it was successful or need to be re-run.", "parameters": [ { "in": "path", "name": "session_id", "description": "Unique session token", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Complete a liveness capture", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_LivenessCompleted" } } } }, "400": { "description": "Could not complete liveness", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "sessions" ], "operationId": "postSessionsSessionIdLivenessComplete" } }, "/sessions/{session_id}/media": { "post": { "summary": "Upload media", "description": "Upload media (jpg, jpeg, png, mov, mp4, pdf, webm) (id document images, proof of address document, etc) to a current open session.", "parameters": [ { "in": "path", "name": "session_id", "description": "Unique session token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postSessionsSessionIdMedia" } } }, "required": true }, "responses": { "201": { "description": "Upload media", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_MediaResponse" } } } }, "400": { "description": "Bad Request ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "sessions" ], "operationId": "postSessionsSessionIdMedia" } }, "/sessions/{session_id}/address_verification": { "post": { "summary": "Upload address verification", "description": " Upload an address verification document to an active session. This endpoint accepts images (jpg, jpeg, png) \n or PDF documents that serve as proof of address.The combination of document scanning, GPS location, and cellular network data provides \n a multi-layered approach to address verification, helping ensure the authenticity of \n the submitted location.\n", "parameters": [ { "in": "path", "name": "session_id", "description": "Unique session token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postSessionsSessionIdAddressVerification" } } }, "required": true }, "responses": { "201": { "description": "Upload address verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_ProofOfAddress" } } } }, "400": { "description": "Bad Request ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "422": { "description": "Rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "sessions" ], "operationId": "postSessionsSessionIdAddressVerification" } }, "/sessions/{session_id}/funds_verification": { "post": { "summary": "Upload funds verification", "description": " Upload an funds verification document to an active session. This endpoint accepts images (jpg, jpeg, png) \n or PDF documents that serve as proof of funds.\n", "parameters": [ { "in": "path", "name": "session_id", "description": "Unique session token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postSessionsSessionIdFundsVerification" } } }, "required": true }, "responses": { "201": { "description": "Upload funds verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_ProofOfFunds" } } } }, "400": { "description": "Bad Request ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "422": { "description": "Rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "sessions" ], "operationId": "postSessionsSessionIdFundsVerification" } }, "/sessions/{session_id}/phone_verification": { "post": { "summary": "Phone verification (Initiate)", "description": " Start phone verification\n", "parameters": [ { "in": "path", "name": "session_id", "description": "Unique session token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postSessionsSessionIdPhoneVerification" } } }, "required": true }, "responses": { "201": { "description": "Phone verification (Initiate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_PhoneVerification" } } } }, "400": { "description": "Invalid phone number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "422": { "description": "Rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "sessions" ], "operationId": "postSessionsSessionIdPhoneVerification" }, "patch": { "summary": "Phone verification (Complete)", "description": " Complete phone verification\n", "parameters": [ { "in": "path", "name": "session_id", "description": "Unique session token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/patchSessionsSessionIdPhoneVerification" } } }, "required": true }, "responses": { "200": { "description": "Phone verification (Complete)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_PhoneVerification" } } } }, "400": { "description": "Invalid phone number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "422": { "description": "Rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "sessions" ], "operationId": "patchSessionsSessionIdPhoneVerification" } }, "/sessions/{session_id}/email_verification": { "post": { "summary": "Email verification (Initiate)", "description": " Start email verification\n", "parameters": [ { "in": "path", "name": "session_id", "description": "Unique session token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postSessionsSessionIdEmailVerification" } } }, "required": true }, "responses": { "201": { "description": "Email verification (Initiate)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_EmailVerification" } } } }, "400": { "description": "Invalid email address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "422": { "description": "Rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "sessions" ], "operationId": "postSessionsSessionIdEmailVerification" }, "patch": { "summary": "Email verification (Complete)", "description": " Complete email verification\n", "parameters": [ { "in": "path", "name": "session_id", "description": "Unique session token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/patchSessionsSessionIdEmailVerification" } } }, "required": true }, "responses": { "200": { "description": "Email verification (Complete)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_EmailVerification" } } } }, "400": { "description": "Invalid email address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "422": { "description": "Rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "sessions" ], "operationId": "patchSessionsSessionIdEmailVerification" } }, "/age_verification/liveness": { "post": { "summary": "Create - Age Verification with Liveness", "description": "Age Verification with Liveness ensures the user is physically present in front of the camera by requiring real-time facial movement detection. This method prevents spoofing, deepfakes, and injection attacks by verifying biometric liveness before estimating age. It provides a significantly higher level of security compared to static selfie-based verification, making it the preferred choice for fraud prevention and regulatory compliance.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postAgeVerificationLiveness" } } }, "required": true }, "security": [ { "PublicKey": [] } ], "responses": { "201": { "description": "Create - Age Verification with Liveness", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_LivenessCreate" } } } }, "400": { "description": "Could not start liveness", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "age_verification" ], "operationId": "postAgeVerificationLiveness" } }, "/age_verification/liveness/{age_verification_id}": { "get": { "summary": "Finnish - Get Age Verification Liveness Result", "description": "Get the result of an Age Verification Liveness session", "parameters": [ { "in": "path", "name": "age_verification_id", "description": "Age Verification ID from Livensess Age Verification call", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "age_verification_model", "description": "Select the AI-powered age verification model trained to estimate whether a person meets or exceeds the specified age threshold. Each model is optimized to detect individuals who are likely to be at least the given age, using facial analysis and machine learning.", "required": false, "schema": { "type": "string", "enum": [ "age_verification_21_years", "age_verification_20_years", "age_verification_19_years", "age_verification_18_years", "age_verification_17_years", "age_verification_16_years", "age_verification_15_years", "age_verification_14_years", "age_verification_13_years", "age_verification_12_years" ], "default": "age_verification_18_years" } }, { "in": "query", "name": "legal_age_21", "description": "Set the legal age threshold based on your jurisdiction. The default legal age is 18. If your jurisdiction requires a legal age of 21, set this to true. This is distinct from the age verification model, which determines the age threshold for verification and does not necessarily reflect the legal age requirement.", "required": false, "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "liveness_confidence_threshold", "description": "Set liveness treshold, normally 50 is ok, for high security applications consider around 80", "required": false, "schema": { "type": "number", "format": "float", "default": 50 } } ], "security": [ { "PrivateKey": [] } ], "responses": { "200": { "description": "Finnish - Get Age Verification Liveness Result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_AgeVerificationResult" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "age_verification" ], "operationId": "getAgeVerificationLivenessAgeVerificationId" } }, "/age_verification/liveness/{session_id}": { "patch": { "summary": "Start - Age Verification with Liveness", "description": "Age Verification with Liveness ensures the user is physically present in front of the camera by requiring real-time facial movement detection. This method prevents spoofing, deepfakes, and injection attacks by verifying biometric liveness before estimating age. It provides a significantly higher level of security compared to static selfie-based verification, making it the preferred choice for fraud prevention and regulatory compliance.", "parameters": [ { "in": "path", "name": "session_id", "description": "Session ID from Create Livensess Age Verification", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Start - Age Verification with Liveness", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_LivenessStart" } } } }, "400": { "description": "Could not start liveness", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "401": { "description": "Session already processed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "age_verification" ], "operationId": "patchAgeVerificationLivenessSessionId" } }, "/age_verification/liveness/{age_verification_id}/complete": { "get": { "summary": "Complete - Age Verification Liveness Result", "description": "Run this to complete liveness session", "parameters": [ { "in": "path", "name": "age_verification_id", "description": "Age Verification ID from Livensess Age Verification call", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Complete - Age Verification Liveness Result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_LivenessCompleted" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "age_verification" ], "operationId": "getAgeVerificationLivenessAgeVerificationIdComplete" } }, "/age_verification/selfie": { "post": { "summary": "No liveness - Age Verification with Selfie", "description": "Age Verification with Selfie is a less secure method where you submit a user’s selfie to estimate their age. It does not ensure the user is physically present and does not detect deepfakes or injection attacks. This method is suitable for images where consent has been obtained but lacks liveness detection, making it vulnerable to spoofing. For higher security, we recommend using Age Verification with Liveness, which confirms real-time presence and enhances fraud prevention.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postAgeVerificationSelfie" } } }, "required": true }, "security": [ { "PrivateKey": [] } ], "responses": { "201": { "description": "No liveness - Age Verification with Selfie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_AgeVerificationResult" } } } }, "400": { "description": "invalid_request_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "402": { "description": "insufficient_balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "481": { "description": "processing_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "482": { "description": "multiple_faces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "483": { "description": "no_face", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "484": { "description": "could_not_estimate_age", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "age_verification" ], "operationId": "postAgeVerificationSelfie" } }, "/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\nrecent first, with optional free-text search.\n\n### Query parameters\n- `search` — optional, case-insensitive match on the document name or the\n humanized document id (e.g. `5PGACUU2E`).\n- `page` — optional, 1-based page number (default 1).\n- `per_page` — optional, items per page (default 50, max 100).\n\n### Response\nA lightweight summary per document (use `GET /documents/:id` for the full\nforensic analysis):\n\n```\n{\n \"documents\": [\n {\n \"submission_id\": \"document_UBCG4a...\",\n \"document_id\": \"5PGACUU2E\",\n \"name\": \"passport.jpg\",\n \"reference_id\": \"your-ref-123\",\n \"status\": \"analyzed\",\n \"analysis_risk_status\": \"trusted\",\n \"analysis_risk_score\": 4,\n \"document_content_type\": \"passport\",\n \"created_at\": \"2025-01-20T10:30:00Z\"\n }\n ],\n \"page\": 1, \"per_page\": 50, \"total\": 128, \"total_pages\": 3\n}\n```\n\n### Errors\n- `401 authentication_error` — missing, malformed, or revoked private key.\n", "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.\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" }, "delete": { "summary": "Delete a document submission", "description": "Deletes a previously submitted document.\n\nThe supplied identifier can be any of:\n - the humanized `document_id` returned on creation (e.g. `5PGACUU2E`),\n - the prefixed `submission_id` (`document_xxx`),\n - the raw token.\n\nThis operation is idempotent — deleting an already-deleted document returns 200 with no error.\n", "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" } }, "/nfc": { "post": { "summary": "NFC data submission", "description": "Submit NFC-scanned identity document data from mobile device NFC reader to the session.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postNfc" } } }, "required": true }, "responses": { "201": { "description": "NFC data submission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_LivenessStart" } } } }, "400": { "description": "Invalid NFC data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "404": { "description": "Invalid session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } }, "422": { "description": "NFC data validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_Error" } } } } }, "tags": [ "nfc" ], "operationId": "postNfc" } }, "/moderation/models/all": { "get": { "summary": "List all public moderation models (no auth required)", "description": "Get all available moderation models across all types (image, video, audio, text) with public pricing", "responses": { "200": { "description": "List all public moderation models (no auth required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_ModerationCategoryEntity" } } } } }, "tags": [ "moderation" ], "operationId": "getModerationModelsAll" } }, "/moderation/models/{api_name}": { "get": { "summary": "Get a single moderation model with full documentation", "description": "Get detailed information about a specific moderation model including full documentation", "parameters": [ { "in": "path", "name": "api_name", "description": "Model API name (e.g., nudity-detection)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a single moderation model with full documentation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_ModerationModelEntity" } } } } }, "tags": [ "moderation" ], "operationId": "getModerationModelsApiName" } }, "/moderation/infer": { "post": { "summary": "Create a moderation inference", "description": "Submit content for moderation using the specified model", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postModerationInfer" } } }, "required": true }, "security": [ { "PrivateKey": [] } ], "responses": { "201": { "description": "Create a moderation inference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_InferenceEntity" } } } } }, "tags": [ "moderation" ], "operationId": "postModerationInfer" } }, "/moderation/infer_async": { "post": { "summary": "Create an asynchronous moderation inference", "description": "Submit content for moderation using the specified model. Returns 202 immediately; poll GET /moderation/inference/:token for the result. Billing happens at submit and is refunded automatically if processing fails.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postModerationInferAsync" } } }, "required": true }, "security": [ { "PrivateKey": [] } ], "responses": { "201": { "description": "Create an asynchronous moderation inference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_InferenceEntity" } } } } }, "tags": [ "moderation" ], "operationId": "postModerationInferAsync" } }, "/moderation/inference/{token}": { "get": { "summary": "Get inference result", "description": "Retrieve the result of a moderation inference by token", "parameters": [ { "in": "path", "name": "token", "description": "The inference token (e.g., inf_abc123)", "required": true, "schema": { "type": "string" } } ], "security": [ { "PrivateKey": [] } ], "responses": { "200": { "description": "Get inference result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_InferenceEntity" } } } } }, "tags": [ "moderation" ], "operationId": "getModerationInferenceToken" } }, "/face-collections": { "post": { "summary": "Create a face collection", "description": "Create a new face collection for your organization. Collections are used to group enrolled faces for search and identification.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postFaceCollections" } } }, "required": true }, "security": [ { "PrivateKey": [] } ], "responses": { "201": { "description": "Create a face collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_FaceCollectionEntity" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "422": { "description": "Validation error - Missing required parameters" }, "429": { "description": "Rate limit exceeded" } }, "tags": [ "Face Collections" ], "operationId": "postFaceCollections" }, "get": { "summary": "List face collections", "description": "List all face collections belonging to your organization, ordered by most recently created. Each collection includes the number of enrolled faces. Supports pagination via page and per_page parameters.", "parameters": [ { "in": "query", "name": "page", "description": "Page number (1-based)", "required": false, "example": 1, "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "in": "query", "name": "per_page", "description": "Number of collections per page (1-100)", "required": false, "example": 25, "schema": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 100, "default": 25 } } ], "security": [ { "PrivateKey": [] } ], "responses": { "200": { "description": "List face collections", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Bynn_V1_Entities_FaceCollectionEntity" } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "429": { "description": "Rate limit exceeded" } }, "tags": [ "Face Collections" ], "operationId": "getFaceCollections" } }, "/face-collections/{token}": { "delete": { "summary": "Delete a face collection", "description": "Delete a face collection and all its enrolled faces. This action is irreversible.", "parameters": [ { "in": "path", "name": "token", "description": "Collection token (e.g. fc_abc123)", "required": true, "example": "fc_abc123def456", "schema": { "type": "string" } } ], "security": [ { "PrivateKey": [] } ], "responses": { "204": { "description": "Delete a face collection" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Collection not found" }, "429": { "description": "Rate limit exceeded" } }, "tags": [ "Face Collections" ], "operationId": "deleteFaceCollectionsToken" } }, "/face-collections/{token}/enroll": { "post": { "summary": "Enroll a face into a collection", "description": "Enroll a single face into a collection by providing an image URL, base64-encoded image, or a file upload (multipart/form-data). The image must contain exactly one face. If no face or multiple faces are detected, an error is returned. You can optionally provide a name, external_id, and metadata for the enrolled face.", "parameters": [ { "in": "path", "name": "token", "description": "Collection token (e.g. fc_abc123)", "required": true, "example": "fc_abc123def456", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postFaceCollectionsTokenEnroll" } } }, "required": true }, "security": [ { "PrivateKey": [] } ], "responses": { "201": { "description": "Enroll a face into a collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bynn_V1_Entities_FaceEntity" } } } }, "400": { "description": "No face detected or multiple faces detected in image" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Collection not found" }, "422": { "description": "Validation error - Invalid input" }, "429": { "description": "Rate limit exceeded" } }, "tags": [ "Face Enrollment" ], "operationId": "postFaceCollectionsTokenEnroll" } }, "/face-collections/{collection_token}/faces/{face_token}": { "delete": { "summary": "Delete a face from a collection", "description": "Remove an enrolled face from a collection. This action is irreversible and the face embedding will be permanently deleted.", "parameters": [ { "in": "path", "name": "collection_token", "description": "Collection token (e.g. fc_abc123)", "required": true, "example": "fc_abc123def456", "schema": { "type": "string" } }, { "in": "path", "name": "face_token", "description": "Face token (e.g. face_abc123)", "required": true, "example": "face_abc123def456", "schema": { "type": "string" } } ], "security": [ { "PrivateKey": [] } ], "responses": { "204": { "description": "Delete a face from a collection" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Collection or face not found" }, "429": { "description": "Rate limit exceeded" } }, "tags": [ "Face Enrollment" ], "operationId": "deleteFaceCollectionsCollectionTokenFacesFaceToken" } }, "/face-collections/{token}/search": { "post": { "summary": "Search for faces in a collection", "description": "Search for similar faces in a collection by providing a probe image (URL, base64, or file upload). Returns matching faces ordered by similarity (lowest distance first). If the image contains multiple faces, the largest/first detected face is used for the search.", "parameters": [ { "in": "path", "name": "token", "description": "Collection token (e.g. fc_abc123)", "required": true, "example": "fc_abc123def456", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/postFaceCollectionsTokenSearch" } } }, "required": true }, "security": [ { "PrivateKey": [] } ], "responses": { "201": { "description": "Search for faces in a collection", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Bynn_V1_Entities_FaceSearchResultEntity" } } } } }, "400": { "description": "No face detected in probe image" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "Collection not found" }, "422": { "description": "Validation error - Invalid input" }, "429": { "description": "Rate limit exceeded" } }, "tags": [ "Face Search" ], "operationId": "postFaceCollectionsTokenSearch" } } }, "servers": [ { "url": "https://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`" }, "PublicKey": { "type": "apiKey", "name": "Authorization", "in": "header", "description": "Enter your PUBLIC KEY token prefixed with `Bearer `, e.g. `Bearer your_token_here`" } }, "schemas": { "postDossiers": { "type": "object", "properties": { "type": { "type": "string", "description": "Dossier product: `kyc` (individual) or `kyb` (company).", "enum": [ "kyc", "kyb" ], "default": "kyc" }, "level": { "type": "string", "description": "Verification level identifier (humanized token) of the matching type. Defaults to your first level of that type when omitted." }, "first_name": { "type": "string", "description": "Applicant first name (individual). Highly recommended." }, "last_name": { "type": "string", "description": "Applicant last name (individual). Highly recommended." }, "company_name": { "type": "string", "description": "Company name (used as the dossier/subject name for `kyb`)." }, "unique_id": { "type": "string", "description": "Your identifier for this applicant (stored as the dossier reference / customer_identification)." }, "phone_number": { "type": "string", "description": "Applicant phone number (E.164). Required to send an SMS invite." }, "email_address": { "type": "string", "description": "Applicant email address. Required to send an email invite." }, "i18n": { "type": "string", "description": "Locale for the applicant / invite (e.g. \"en\")." }, "generate_qr": { "type": "boolean", "description": "Return a base64 PNG QR code of the verification URL." }, "send_sms": { "type": "boolean", "description": "Send the verification link to the applicant by SMS (requires phone_number)." }, "send_email": { "type": "boolean", "description": "Send the verification link to the applicant by email (requires email_address)." } }, "description": "Create a dossier" }, "Bynn_V1_Entities_DossierCreatedEntity": { "type": "object", "properties": { "dossier_id": { "type": "string", "example": "dossier_xxx", "description": "Identifier of the created dossier (prefixed)." }, "session_id": { "type": "string", "example": "sess_xxx", "description": "Verification session token for the applicant." }, "verification_url": { "type": "string", "example": "https://verify.bynn.com/...", "description": "Hosted verification URL to send the applicant to." }, "qr_base64_png": { "type": "string", "description": "Base64-encoded PNG QR code of the verification URL (only when generate_qr=true)." } }, "required": [ "dossier_id", "session_id", "verification_url", "qr_base64_png" ], "description": "Bynn_V1_Entities_DossierCreatedEntity model" }, "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_DossierEntity": { "type": "object", "properties": { "id": { "type": "string", "example": "dossier_xxx", "description": "Dossier identifier (prefixed)." }, "token": { "type": "string", "example": "U45XZQE9N", "description": "Humanized dossier token." }, "type": { "type": "string", "enum": [ "not_specified", "kyc", "kyb", "doc" ], "example": "kyc", "description": "Dossier type." }, "status": { "type": "string", "enum": [ "draft", "open", "completed", "archived", "closed", "needs_attention", "approved", "rejected" ], "example": "approved", "description": "Business status of the dossier." }, "name": { "type": "string", "example": "Jane Doe", "description": "Dossier / applicant name." }, "name_latin": { "type": "string", "example": "Jane Doe", "description": "Latin-transliterated name, when applicable." }, "reference": { "type": "string", "example": "user-123", "description": "Your customer reference (customer_identification)." }, "description": { "type": "string", "description": "Free-text description, when set." }, "risk_score": { "type": "integer", "format": "int32", "example": 4, "description": "Dossier risk score (0-100)." }, "is_test": { "type": "boolean", "example": false, "description": "Whether this dossier was created with a test/sandbox key." }, "download_status": { "type": "string", "enum": [ "not_downloaded", "downloaded", "synced" ], "example": "not_downloaded", "description": "Download status." }, "workflow_status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "failed", "awaiting_approval" ], "example": "completed", "description": "Workflow status (autodoc dossiers)." }, "level": { "type": "object", "description": "The verification level the dossier runs under." }, "documents_count": { "type": "integer", "format": "int32", "example": 2, "description": "Number of documents collected." }, "documents_required": { "type": "integer", "format": "int32", "example": 2, "description": "Number of documents expected." }, "tags": { "type": "array", "items": { "type": "array", "items": {} }, "description": "User-editable organization tags on the dossier." }, "created_at": { "type": "string", "example": "2025-01-20T10:30:00Z", "description": "ISO 8601 creation timestamp." }, "updated_at": { "type": "string", "example": "2025-01-20T10:35:00Z", "description": "ISO 8601 last-update timestamp." }, "completed_at": { "type": "string", "example": "2025-01-20T10:34:00Z", "description": "ISO 8601 completion timestamp, when completed." }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/Bynn_V1_Entities_MediumEntity" }, "description": "All dossier-level media assets, each with type and a short-lived URL (~5 min — download immediately)." }, "entities": { "type": "array", "items": { "$ref": "#/components/schemas/Bynn_V1_Entities_DossierApplicantEntity" }, "description": "Applicants (subjects) on the dossier with their personal info, identity documents, media and liveness images." } }, "required": [ "id", "token", "type", "status", "name", "name_latin", "reference", "description", "risk_score", "is_test", "download_status", "workflow_status", "level", "documents_count", "documents_required", "tags", "created_at", "updated_at", "completed_at", "media", "entities" ], "description": "Bynn_V1_Entities_DossierEntity model" }, "Bynn_V1_Entities_MediumEntity": { "type": "object", "properties": { "type": { "type": "string", "example": "passport_front_image", "description": "The kind of media asset (e.g. passport_front_image, selfie_image, extracted_avatar, dossier_report)." }, "name": { "type": "string", "example": "passport.jpg", "description": "Original file name of the media asset." }, "page": { "type": "integer", "format": "int32", "example": 1, "description": "Page number for multi-page documents (starts at 1)." }, "url": { "type": "string", "example": "https://files.bynn.com/...", "description": "Signed, time-limited URL to download the file. Nil when no file is attached." }, "created_at": { "type": "string", "example": "2025-01-20T10:30:00Z", "description": "ISO 8601 creation timestamp." } }, "required": [ "type", "name", "page", "url", "created_at" ] }, "Bynn_V1_Entities_DossierApplicantEntity": { "type": "object", "properties": { "token": { "type": "string", "example": "entity_xxx", "description": "Applicant (entity) identifier." }, "name": { "type": "string", "example": "Jane Doe", "description": "Full name of the applicant." }, "name_latin": { "type": "string", "example": "Jane Doe", "description": "Latin-transliterated name, when the original is non-Latin." }, "first_name": { "type": "string", "example": "Jane", "description": "Given name." }, "last_name": { "type": "string", "example": "Doe", "description": "Surname." }, "date_of_birth": { "type": "string", "example": "1990-05-12", "description": "Date of birth (YYYY-MM-DD)." }, "gender": { "type": "string", "enum": [ "female", "male" ], "example": "female", "description": "Gender." }, "personal_number": { "type": "string", "example": "199005121234", "description": "National / personal identification number, when captured." }, "nationality": { "type": "string", "example": "Sweden", "description": "Nationality country." }, "residence_country": { "type": "string", "example": "Sweden", "description": "Country of residence." }, "birth_country": { "type": "string", "example": "Sweden", "description": "Country of birth." }, "email": { "type": "string", "example": "jane@example.com", "description": "Applicant email address." }, "phone_number": { "type": "string", "example": "+46700000000", "description": "Applicant phone number." }, "occupation": { "type": "string", "example": "Engineer", "description": "Occupation, when captured." }, "marital_status": { "type": "string", "example": "single", "description": "Marital status, when captured." }, "height_cm": { "type": "integer", "format": "int32", "example": 175, "description": "Height in centimetres, when read from a document." }, "risk_score": { "type": "integer", "format": "int32", "example": 4, "description": "Applicant risk score (0-100)." }, "address": { "type": "object", "description": "Applicant address, as captured." }, "liveness_status": { "type": "string", "enum": [ "not_verified", "pre_verification_successful", "successful", "failed", "skipped" ], "example": "successful", "description": "Liveness verification outcome." }, "liveness_confidence": { "type": "number", "example": 98.5, "description": "Liveness confidence score." }, "liveness_images": { "type": "array", "items": { "type": "array", "items": {} }, "description": "All captured liveness selfie frames as { url, bounding_box }. URLs are short-lived presigned links (~5 min) — download immediately." }, "identity_documents": { "type": "array", "items": { "$ref": "#/components/schemas/Bynn_V1_Entities_IdentityDocumentEntity" }, "description": "Identity documents captured for this applicant." }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/Bynn_V1_Entities_MediumEntity" }, "description": "All media assets for this applicant, each with type and a short-lived URL." } }, "required": [ "token", "name", "name_latin", "first_name", "last_name", "date_of_birth", "gender", "personal_number", "nationality", "residence_country", "birth_country", "email", "phone_number", "occupation", "marital_status", "height_cm", "risk_score", "address", "liveness_status", "liveness_confidence", "liveness_images", "identity_documents", "media" ] }, "Bynn_V1_Entities_IdentityDocumentEntity": { "type": "object", "properties": { "token": { "type": "string", "example": "iddoc_xxx", "description": "Identity document identifier." }, "document_type": { "type": "string", "enum": [ "passport", "identity_card", "drivers_license", "residence_permit", "social_security", "unknown" ], "example": "passport", "description": "Detected document category." }, "document_number": { "type": "string", "example": "X1234567", "description": "Document number as printed on the document." }, "first_name": { "type": "string", "example": "Jane", "description": "Given name as read from the document." }, "last_name": { "type": "string", "example": "Doe", "description": "Surname as read from the document." }, "full_name": { "type": "string", "example": "Jane Doe", "description": "Full name as read from the document." }, "name_latin": { "type": "string", "example": "Jane Doe", "description": "Latin-transliterated full name, when the original is non-Latin." }, "birth_date": { "type": "string", "example": "1990-05-12", "description": "Date of birth (YYYY-MM-DD)." }, "issue_date": { "type": "string", "example": "2018-01-01", "description": "Issue date (YYYY-MM-DD)." }, "expiry_date": { "type": "string", "example": "2028-01-01", "description": "Expiry date (YYYY-MM-DD)." }, "is_expired": { "type": "boolean", "example": false, "description": "Whether the document is past its expiry date." }, "gender": { "type": "string", "enum": [ "female", "male", "intersex", "not_specified" ], "example": "female", "description": "Gender as read from the document." }, "nationality_code": { "type": "string", "example": "SWE", "description": "Nationality as an ISO country code from the document." }, "issuing_country": { "type": "string", "example": "Sweden", "description": "Country that issued the document." }, "personal_number": { "type": "string", "example": "199005121234", "description": "National / personal identification number, when present." }, "place_of_birth": { "type": "string", "example": "Stockholm", "description": "Place of birth, when present." }, "document_status": { "type": "string", "example": "valid", "description": "Reported status of the document." }, "mrz_type": { "type": "string", "example": "TD3", "description": "Machine Readable Zone format (e.g. TD1, TD3)." }, "mrz_checksum_valid": { "type": "boolean", "example": true, "description": "Whether the MRZ checksums validated." }, "has_portrait_image": { "type": "boolean", "example": true, "description": "Whether a portrait photo was detected on the document." }, "has_signature": { "type": "boolean", "example": true, "description": "Whether a signature was detected on the document." }, "tampered": { "type": "boolean", "example": false, "description": "Whether tampering was detected." }, "e_id": { "type": "boolean", "example": false, "description": "Whether NFC / electronic-chip (eID) data was read from the document." }, "risk_score": { "type": "integer", "format": "int32", "example": 3, "description": "Document risk score (0-100)." }, "verification_status": { "type": "string", "enum": [ "pending", "analyzed", "verified", "rejected", "expired", "requires_resubmission" ], "example": "verified", "description": "Verification outcome for the document." }, "images": { "type": "array", "items": { "type": "array", "items": {} }, "description": "Captured document images (front / back / cropped) with type and URL." } }, "required": [ "token", "document_type", "document_number", "first_name", "last_name", "full_name", "name_latin", "birth_date", "issue_date", "expiry_date", "is_expired", "gender", "nationality_code", "issuing_country", "personal_number", "place_of_birth", "document_status", "mrz_type", "mrz_checksum_valid", "has_portrait_image", "has_signature", "tampered", "e_id", "risk_score", "verification_status", "images" ] }, "postAmlSearch": { "type": "object", "properties": { "name": { "type": "string", "description": "Name to screen against the AML data." }, "type": { "type": "string", "description": "What to search for: a `person` or an entity (`company` / `organization` / `legal_entity`).", "enum": [ "person", "company", "organization", "legal_entity" ], "default": "person" }, "limit": { "type": "integer", "format": "int32", "description": "Maximum number of matches to return (default 10, max 50).", "minimum": 1, "maximum": 50, "default": 10 } }, "required": [ "name" ], "description": "Search AML data (sanctions, PEP & watchlists)" }, "Bynn_V1_Entities_AmlSearchResultEntity": { "type": "object", "properties": { "id": { "type": "string", "example": "NK-abc123", "description": "Stable identifier of the matched profile (use it to fetch full detail)." }, "name": { "type": "string", "example": "John Doe", "description": "Primary name / caption of the match." }, "schema": { "type": "string", "enum": [ "Person", "Company", "Organization", "LegalEntity" ], "example": "Person", "description": "Kind of profile matched." }, "match": { "type": "boolean", "example": true, "description": "Whether the provider considers this a strong match (above the match threshold)." }, "score": { "type": "number", "example": 0.92, "description": "Match score (0.0–1.0)." }, "topics": { "type": "array", "items": { "type": "array", "items": {} }, "example": [ "sanction" ], "description": "Risk topics on the profile (e.g. sanction, role.pep, crime, debarment)." }, "birth_date": { "type": "array", "items": { "type": "array", "items": {} }, "example": [ "1965-04-12" ], "description": "Known dates of birth (YYYY-MM-DD)." }, "birth_place": { "type": "array", "items": { "type": "array", "items": {} }, "description": "Known places of birth." }, "death_date": { "type": "array", "items": { "type": "array", "items": {} }, "description": "Known dates of death, when applicable." }, "country": { "type": "array", "items": { "type": "array", "items": {} }, "example": [ "ru" ], "description": "Citizenship / nationality / country of the profile." } }, "required": [ "id", "name", "schema", "match", "score", "topics", "birth_date", "birth_place", "death_date", "country" ], "description": "Bynn_V1_Entities_AmlSearchResultEntity model" }, "postAutodocInvitations": { "type": "object", "properties": { "workflowToken": { "type": "string", "description": "Workflow token (e.g. wf_xxx) to start when the recipient opens the invitation link.", "example": "wf_ULA5NSu9pRsUctA9DBmkRQya" }, "channel": { "type": "string", "description": "Delivery channel — \"email\" or \"sms\".", "enum": [ "email", "sms" ], "example": "email" }, "recipient": { "type": "string", "description": "Email address (when channel=email) or phone number in E.164 or international format (when channel=sms). Max 255 characters.", "example": "jane.doe@example.com" }, "reference": { "type": "string", "description": "Customer-defined identifier (customer number, UUID, order number, etc.) for cross-referencing this invitation back to your own system. Returned verbatim on the invitation entity. Max 255 characters.", "example": "cust_42891" }, "locale": { "type": "string", "description": "IETF language tag for the recipient-facing email/SMS content. See GET /v1/autodoc/invitations/locales for supported values. Defaults to the organization default locale, or English if unset.", "example": "en" } }, "required": [ "workflowToken", "channel", "recipient" ], "description": "Send an AutoDoc invitation" }, "Bynn_V1_Entities_AutoDocInvitation": { "type": "object", "properties": { "token": { "type": "string", "example": "adi_abc123def456", "description": "Invitation token (adi_xxx). Use this to look up or cancel the invitation." }, "workflowToken": { "type": "string", "example": "wf_ULA5NSu9pRsUctA9DBmkRQya", "description": "Workflow token the invitation will start (wf_xxx)." }, "channel": { "type": "string", "enum": [ "email", "sms" ], "example": "email", "description": "Delivery channel." }, "recipient": { "type": "string", "example": "jane.doe@example.com", "description": "Email address or phone number the invitation is sent to." }, "reference": { "type": "string", "example": "cust_42891", "description": "Customer-defined identifier echoed back from the create request. Useful for cross-referencing this invitation against your own system." }, "locale": { "type": "string", "example": "en", "description": "Language tag the email/SMS was rendered in. Null when no locale was specified at create time." }, "status": { "type": "string", "enum": [ "pending", "sent", "delivered", "opened", "started", "failed", "completed", "rejected" ], "example": "pending", "description": "Lifecycle status of the invitation. Mirrors dossier terminal state once a submission is linked: started=visitor opened the link and a dossier was created; completed=dossier was approved/completed; rejected=dossier was rejected." }, "dossierToken": { "type": "string", "example": "dossier_4tDH5f7yKN3bRsFy5xTEFrxw", "description": "Token of the dossier this invitation produced, once the recipient has started the workflow. Null until then." }, "deliveryAttempts": { "type": "integer", "format": "int32", "example": 1, "description": "Number of times this invitation has been successfully sent (initial send + each resend). Capped at 10." }, "errorMessage": { "type": "string", "description": "Failure reason (only populated when status=failed)." }, "expiresAt": { "type": "string", "format": "date-time", "example": "2026-05-27T13:54:00Z", "description": "When the invitation link stops working." }, "sentAt": { "type": "string", "format": "date-time", "example": "2026-04-27T13:54:00Z", "description": "When the invitation was dispatched to the channel provider. Null until status flips to sent." }, "startedAt": { "type": "string", "format": "date-time", "example": "2026-04-27T14:10:00Z", "description": "When the recipient first started the workflow (a dossier was created). Null until status flips to started." }, "completedAt": { "type": "string", "format": "date-time", "example": "2026-04-27T14:20:00Z", "description": "When the linked dossier was approved/completed. Null until status flips to completed." }, "rejectedAt": { "type": "string", "format": "date-time", "example": "2026-04-27T14:20:00Z", "description": "When the linked dossier was rejected. Null until status flips to rejected." }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-04-27T13:54:00Z", "description": "When the invitation record was created." } }, "required": [ "token", "workflowToken", "channel", "recipient", "reference", "locale", "status", "dossierToken", "deliveryAttempts", "errorMessage", "expiresAt", "sentAt", "startedAt", "completedAt", "rejectedAt", "createdAt" ], "description": "Bynn_V1_Entities_AutoDocInvitation model" }, "postSessions": { "type": "object", "properties": { "first_name": { "type": "string", "description": "Applicant first name, (not required but highly recommended)" }, "last_name": { "type": "string", "description": "Applicant last name, (not required but highly recommended)" }, "unique_id": { "type": "string", "description": "Unique identifier for the applicant in your system so you can identify the applicant in a webhook callback. Can be email or uuid., (not required but highly recommended)" }, "phone_number": { "type": "string", "description": "Applicant phone number, (not required but highly recommended)" }, "email_address": { "type": "string", "description": "Applicant email address, (not required but highly recommended)" }, "kyc_level": { "type": "string", "description": "KYC level token Identifier (see: https://dashboard.bynn.com/setting/product/kyc)" }, "generate_qr": { "type": "boolean", "description": "Flag indicating if a QR code should be generated" }, "i18n": { "type": "string", "description": "Locale for the applicant (\"en\" for English)" } }, "required": [ "kyc_level" ], "description": "Create a new identity verification session" }, "Bynn_V1_Entities_Session": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Unique session token" }, "url": { "type": "string", "description": "URL to the session" }, "qr_base64_png": { "type": "string", "description": "QR code image as base64 encoded PNG" }, "branding": { "allOf": [ { "$ref": "#/components/schemas/Bynn_V1_Entities_SessionBranding" } ], "description": "Brand configuration parameters for the session." }, "websocket_url": { "type": "string", "example": "wss://url.com", "description": "URL to websocket for event status updates for this specific session" } }, "required": [ "session_id", "url", "qr_base64_png", "branding", "websocket_url" ], "description": "Bynn_V1_Entities_Session model" }, "Bynn_V1_Entities_SessionBranding": { "type": "object", "properties": { "whitelabel": { "type": "boolean", "example": false, "description": "Indicates if Bynn logos shall be hidden." }, "name": { "type": "string", "example": "Test Company", "description": "" }, "jurisdiction": { "type": "string", "example": "US", "description": "" }, "url": { "type": "string", "example": "https://example.com", "description": "" }, "url_data_processing_consent": { "type": "string", "example": "https://example.com/privacy_consent", "description": "" }, "url_terms": { "type": "string", "example": "https://example.com/terms", "description": "" }, "url_privacy": { "type": "string", "example": "https://example.com/privacy", "description": "" }, "text_data_processing_consent": { "type": "string", "example": "I consent to the collection, processing, and storage of my personal data, including biometric data, for the purpose of identity verification. I understand that my information will be handled securely and in compliance with applicable privacy laws and regulations. For more details, please refer to the Privacy Policy", "description": "" }, "url_icon": { "type": "string", "example": "https://example.com/icon.png", "description": "Can be url or base64 encoded (strict) image url" }, "url_logo": { "type": "string", "example": "https://example.com/icon.png", "description": "Can be url or base64 encoded (strict) image url" }, "brand_color": { "type": "string", "example": "#5156be", "description": "" }, "accent_color": { "type": "string", "example": "#5156be", "description": "" }, "web_sdk_return_url": { "type": "string", "example": "https://example.com/return_back_after_verification?identifier=[identifier]&sessionId=[sessionId]", "description": "" }, "is_test": { "type": "boolean", "example": false, "description": "Indicates if this is a test verification." } }, "required": [ "whitelabel", "name", "jurisdiction", "url", "url_data_processing_consent", "url_terms", "url_privacy", "text_data_processing_consent", "url_icon", "url_logo", "brand_color", "accent_color", "web_sdk_return_url", "is_test" ] }, "Bynn_V1_Entities_SessionCancellation": { "type": "object", "properties": { "status": { "type": "string", "description": "Indicates that the session has been cancelled. Example: \"cancelled\"" } }, "required": [ "status" ], "description": "Bynn_V1_Entities_SessionCancellation model" }, "postSessionsSessionId": { "type": "object", "properties": { "first_name": { "type": "string", "description": "Applicant first name" }, "last_name": { "type": "string", "description": "Applicant last name" }, "unique_id": { "type": "string", "description": "Unique identifier for the applicant" }, "phone_number": { "type": "string", "description": "Applicant phone number" }, "phone": { "type": "string", "description": "Alternative applicant phone number" }, "email_address": { "type": "string", "description": "Applicant email address" }, "email": { "type": "string", "description": "Alternative applicant email address" }, "country_code": { "type": "string", "description": "Country code for the phone number" }, "i18n": { "type": "string", "description": "Locale for the applicant" }, "identifier": { "type": "string", "description": "Alternative identifier for the applicant" } }, "description": "Update an existing session" }, "Bynn_V1_Entities_SessionUpdate": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "description": "Result status; \"success\" if the session update was successful" } }, "required": [ "status" ], "description": "Bynn_V1_Entities_SessionUpdate model" }, "postSessionsSessionIdSendSms": { "type": "object", "properties": { "phone_number": { "type": "string", "description": "The phone number to which the SMS should be sent, with or without country prefix: \"+12124567890\" or \"2124567890\"" }, "country_code": { "type": "string", "description": "Country code (ISO 3166-1 alpha-2) for the provided phone number, ie: \"US\" for USA" } }, "required": [ "phone_number", "country_code" ], "description": "Send SMS (device switch)" }, "Bynn_V1_Entities_SmsResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "description": "Status message indicating the outcome of the SMS send operation" } }, "required": [ "status" ], "description": "Bynn_V1_Entities_SmsResponse model" }, "Bynn_V1_Entities_Preflight": { "type": "object", "properties": { "entity_id_document_type": { "type": "string", "enum": [ "id_card", "passport", "drivers_license", "residence_permit" ], "description": "Identified ID document type (only for ID documents). " }, "entity_id_state": { "type": "string", "enum": [ "none_received", "front_received_but_needs_resubmission", "front_received_awaiting_back", "front_received_and_back_received_but_back_needs_resubmission", "id_received_awaiting_liveness", "awaiting_liveness", "awaiting_nfc", "awaiting_poa", "awaiting_pof", "awaiting_a4_document", "completed" ], "description": "ID state (only for ID documents)." }, "extra_data": { "allOf": [ { "$ref": "#/components/schemas/Bynn_V1_Entities_PreflightScreenExtraData" } ], "description": "Additional data derived from preflight analysis of the document/image." }, "session_id": { "type": "string", "description": "Unique session token" }, "screen": { "allOf": [ { "$ref": "#/components/schemas/Bynn_V1_Entities_PreflightScreen" } ], "description": "Preflight screen information, including the screen to display and its configuration parameters." }, "requirement": { "allOf": [ { "$ref": "#/components/schemas/Bynn_V1_Entities_PreflightRequirement" } ], "description": "Requirement" } }, "required": [ "entity_id_document_type", "entity_id_state", "extra_data", "session_id", "screen", "requirement" ], "description": "Bynn_V1_Entities_Preflight model" }, "Bynn_V1_Entities_PreflightScreenExtraData": { "type": "object", "properties": { "detect_blur_and_bright_spot": { "type": "object", "description": "Detection results for image quality issues such as blur and bright spots. Contains detailed metrics if available." }, "difficult_to_read": { "type": "boolean", "description": "Indicates whether the document or image is difficult to read due to poor quality or blurriness." }, "entire_document_not_in_frame": { "type": "boolean", "description": "Indicates if the entire document is not captured within the frame." }, "document_type": { "type": "string", "description": "The detected type of document, if applicable." }, "wrong_side": { "type": "boolean", "description": "Indicates if the wrong side of the document has been captured." }, "finger_cover": { "type": "boolean", "description": "Indicates whether a finger is covering part of the document." } }, "required": [ "detect_blur_and_bright_spot", "difficult_to_read", "entire_document_not_in_frame", "document_type", "wrong_side", "finger_cover" ] }, "Bynn_V1_Entities_PreflightScreen": { "type": "object", "properties": { "show": { "type": "string", "enum": [ "waiting_for_previous_call_to_complete", "consent_screen", "scan_id_document_front_screen", "scan_id_document_back_screen", "scan_a4_document_screen", "proof_of_address_screen", "proof_of_funds_screen", "nfc_capture_screen", "liveness_screen", "input_screen", "qr_scan_screen", "cancel_screen", "completed_screen", "successful_screen", "rejected_screen", "phone_verification_screen", "email_verification_screen" ], "description": "Screen to show." }, "parameters": { "allOf": [ { "$ref": "#/components/schemas/Bynn_V1_Entities_PreflightScreenParams" } ], "description": "Configuration parameters for the preflight screen." } }, "required": [ "show", "parameters" ] }, "Bynn_V1_Entities_PreflightScreenParams": { "type": "object", "properties": { "camera": { "type": "string", "enum": [ "back", "front" ], "description": "Indicating use of the back camera (main camera), of the front camera (selfie camera). If null, then no camera is allowed." }, "camera_quality": { "type": "string", "enum": [ "low", "medium", "high", "ultra" ], "description": "Camera image quality" }, "allow_manual_upload": { "type": "boolean", "description": "Allow the user to upload an image or document already on the device" }, "multipage": { "type": "boolean", "description": "If true, allow multiple pages to be scanned and upload when the user confirms the complete scan." }, "autocapture": { "type": "boolean", "description": "If true, automatically capture the document when it is well-framed and in focus." }, "title": { "type": "string", "description": "Title text to display at the top of the screen." }, "text": { "type": "string", "description": "Additional text to display at the bottom of the screen." } }, "required": [ "camera", "camera_quality", "allow_manual_upload", "multipage", "autocapture", "title", "text" ] }, "Bynn_V1_Entities_PreflightRequirement": { "type": "object", "properties": { "requirement_type": { "type": "string", "enum": [ "identity_document", "liveness", "proof_of_address", "proof_of_funds", "phone_verification", "email_verification" ], "description": "Requirement type" }, "status": { "type": "string", "enum": [ "preconditions_pending", "not_checked", "received", "analyzed", "passed", "rejected", "failed", "matched", "bypassed", "manual_approved", "manual_rejected", "manual_review", "manual_review_bynn", "awaiting_receipt", "could_not_check" ], "description": "Status" } }, "required": [ "requirement_type", "status" ] }, "patchSessionsSessionIdConsent": { "type": "object", "properties": { "gives_consent": { "type": "boolean", "description": "Is user consent given to process and store users data (PII including biometrics, video, audio, images, location)" } }, "required": [ "gives_consent" ], "description": "Consent" }, "Bynn_V1_Entities_StatusResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "description": "Status message indicating the outcome of the operation" } }, "required": [ "status" ], "description": "Bynn_V1_Entities_StatusResponse model" }, "Bynn_V1_Entities_LivenessStart": { "type": "object", "properties": { "age_verification_id": { "type": "string", "description": "Age Verification ID" }, "liveness_session": { "allOf": [ { "$ref": "#/components/schemas/Bynn_V1_Entities_LivenessSession" } ], "description": "Liveness session information" } }, "required": [ "age_verification_id", "liveness_session" ], "description": "Bynn_V1_Entities_LivenessStart model" }, "Bynn_V1_Entities_LivenessSession": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Liveness session identifier" }, "credentials": { "allOf": [ { "$ref": "#/components/schemas/Bynn_V1_Entities_LivenessCredentials" } ], "description": "Credentials" }, "server_time": { "type": "integer", "format": "int32", "description": "Server time in milliseconds" } }, "required": [ "session_id", "credentials", "server_time" ] }, "Bynn_V1_Entities_LivenessCredentials": { "type": "object", "properties": { "id": { "type": "string", "description": "Access ID" }, "access_key": { "type": "string", "description": "Access Key" }, "token": { "type": "string", "description": "Access Session Token" } }, "required": [ "id", "access_key", "token" ] }, "Bynn_V1_Entities_LivenessCompleted": { "type": "object", "properties": { "verification": { "type": "string", "description": "The verification status (always \"completed\" if successfully completed) " }, "status": { "type": "string", "description": "Liveness Status: \"created\",\"successful\", \"failed\", \"expired\"" } }, "required": [ "verification", "status" ], "description": "Bynn_V1_Entities_LivenessCompleted model" }, "postSessionsSessionIdMedia": { "type": "object", "properties": { "media_base64_strict": { "type": "string", "description": "Base64 Strict Encoded media (jpg, jpeg, png, mov, mp4, pdf, webm)" }, "visitor_id": { "type": "string", "description": "Unique visitor ID" }, "device_id": { "type": "string", "description": "Unique device ID" }, "app_screen": { "type": "string", "description": "What screen is the data uploaded from", "enum": [ "waiting_for_previous_call_to_complete", "consent_screen", "scan_id_document_front_screen", "scan_id_document_back_screen", "scan_a4_document_screen", "proof_of_address_screen", "proof_of_funds_screen", "nfc_capture_screen", "liveness_screen", "input_screen", "qr_scan_screen", "cancel_screen", "completed_screen", "successful_screen", "rejected_screen", "phone_verification_screen", "email_verification_screen" ] } }, "required": [ "media_base64_strict", "app_screen" ], "description": "Upload media" }, "Bynn_V1_Entities_MediaResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success", "description": "Status message indicating the outcome of the operation" } }, "required": [ "status" ], "description": "Bynn_V1_Entities_MediaResponse model" }, "postSessionsSessionIdAddressVerification": { "type": "object", "properties": { "document_base64_strict": { "type": "string", "description": "Base64 Strict Encoded media (jpg, jpeg, png, pdf)" }, "file": { "type": "string", "format": "binary", "description": "File media (jpg, jpeg, png, pdf)" }, "latitude": { "type": "number", "format": "float", "description": "GPS latitude coordinate" }, "longitude": { "type": "number", "format": "float", "description": "GPS longitude coordinate" }, "cell_info": { "type": "object", "description": "Cell tower information", "properties": { "cell_id": { "type": "string", "description": "Primary cell ID (CID/PCI) - Unique identifier for the cell tower" }, "lac": { "type": "string", "description": "Location Area Code (LAC)" }, "mnc": { "type": "string", "description": "Mobile Network Code (MNC)" }, "mcc": { "type": "string", "description": "Mobile Country Code (MCC)" } } } }, "description": "Upload address verification" }, "Bynn_V1_Entities_ProofOfAddress": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "received" ], "description": "Result" } }, "required": [ "status" ], "description": "Bynn_V1_Entities_ProofOfAddress model" }, "postSessionsSessionIdFundsVerification": { "type": "object", "properties": { "document_base64_strict": { "type": "string", "description": "Base64 Strict Encoded media (jpg, jpeg, png, pdf)" }, "file": { "type": "string", "format": "binary", "description": "File media (jpg, jpeg, png, pdf)" } }, "description": "Upload funds verification" }, "Bynn_V1_Entities_ProofOfFunds": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "received" ], "description": "Result" } }, "required": [ "status" ], "description": "Bynn_V1_Entities_ProofOfFunds model" }, "postSessionsSessionIdPhoneVerification": { "type": "object", "properties": { "phone_number": { "type": "string", "description": "The phone number to which the SMS should be sent, with or without country prefix: \"+12124567890\" or \"2124567890\"" }, "country_code": { "type": "string", "description": "Country code (ISO 3166-1 alpha-2) for the provided phone number, ie: \"US\" for USA" } }, "required": [ "phone_number" ], "description": "Phone verification (Initiate)" }, "Bynn_V1_Entities_PhoneVerification": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "sent" ], "description": "Result" } }, "required": [ "status" ], "description": "Bynn_V1_Entities_PhoneVerification model" }, "patchSessionsSessionIdPhoneVerification": { "type": "object", "properties": { "code": { "type": "string", "description": "The 6 digit code that was sent out to the applicants phone" } }, "required": [ "code" ], "description": "Phone verification (Complete)" }, "postSessionsSessionIdEmailVerification": { "type": "object", "properties": { "email_address": { "type": "string", "description": "The email address to verify. A verification code will be sent out to the email address." } }, "required": [ "email_address" ], "description": "Email verification (Initiate)" }, "Bynn_V1_Entities_EmailVerification": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "sent" ], "description": "Result" } }, "required": [ "status" ], "description": "Bynn_V1_Entities_EmailVerification model" }, "patchSessionsSessionIdEmailVerification": { "type": "object", "properties": { "code": { "type": "string", "description": "The 6 digit code that was sent out to the applicants email address" } }, "required": [ "code" ], "description": "Email verification (Complete)" }, "postAgeVerificationLiveness": { "type": "object", "properties": { "unique_id": { "type": "string", "description": "Unique identifier for the user in your system so you can identify the user in a webhook callback. Can be email or uuid" } }, "required": [ "unique_id" ], "description": "Create - Age Verification with Liveness" }, "Bynn_V1_Entities_LivenessCreate": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Liveness session identifier" } }, "required": [ "session_id" ], "description": "Bynn_V1_Entities_LivenessCreate model" }, "Bynn_V1_Entities_AgeVerificationResult": { "type": "object", "properties": { "unique_id": { "type": "string", "example": "my@user.com", "description": "Unique identifier for the user in your system so you can identify the user in a webhook callback. Can be email or uuid" }, "is_adult": { "type": "boolean", "example": true, "description": "Verification result indicating whether the detected face belongs to an adult based on the estimated age range. This is a prediction and may not match the person’s actual age." }, "verification_status": { "type": "string", "enum": [ "pass", "underage", "unknown", "pending", "error" ], "example": "pass", "description": "Verification result indicating whether the detected face passed the given model in age verification threshold." }, "age_verification_model": { "type": "string", "enum": [ "age_verification_21_years", "age_verification_20_years", "age_verification_19_years", "age_verification_18_years", "age_verification_17_years", "age_verification_16_years", "age_verification_15_years", "age_verification_14_years", "age_verification_13_years", "age_verification_12_years" ], "example": "age_verification_18_years", "description": "The AI-powered age verification model used, trained to estimate whether a person meets or exceeds the specified age threshold." }, "confidence": { "type": "string", "enum": [ "high", "moderate", "low" ], "example": "high", "description": "Confidence level indicating how certain the system is about the age verification result." }, "age_range": { "allOf": [ { "$ref": "#/components/schemas/Bynn_V1_Entities_AgeRange" } ], "description": "Estimated age range of the person in the image. This is a prediction and may not match the person’s actual age." }, "age_estimated": { "type": "integer", "format": "int32", "example": 25, "description": "Estimated age of person. This is a prediction and may not match the person’s actual age." }, "face": { "allOf": [ { "$ref": "#/components/schemas/Bynn_V1_Entities_Face" } ], "description": "Detected face information and attributes" }, "liveness": { "allOf": [ { "$ref": "#/components/schemas/Bynn_V1_Entities_Liveness" } ], "description": "Liveness attributes" }, "image_saved": { "type": "boolean", "example": false, "description": "Indicates whether the image was saved for further validation" }, "biometrics_saved": { "type": "boolean", "example": false, "description": "Indicates whether the biometrics was saved for further validation" }, "evaluated_at": { "type": "string", "example": "2025-02-23T00:31:56.076+00:00", "description": "Timestamp of when the entity was last evaluated." }, "data_destroyed_at": { "type": "string", "example": "2025-02-23T00:31:56.076+00:00", "description": "Timestamp of when the data is (or will be) destroyed." } }, "required": [ "unique_id", "is_adult", "verification_status", "age_verification_model", "confidence", "age_range", "age_estimated", "face", "liveness", "image_saved", "biometrics_saved", "evaluated_at", "data_destroyed_at" ], "description": "Bynn_V1_Entities_AgeVerificationResult model" }, "Bynn_V1_Entities_AgeRange": { "type": "object", "properties": { "high": { "type": "integer", "format": "int32", "example": 35, "description": "Upper bound of the estimated age range" }, "low": { "type": "integer", "format": "int32", "example": 25, "description": "Lower bound of the estimated age range" } }, "required": [ "high", "low" ] }, "Bynn_V1_Entities_Face": { "type": "object", "properties": { "bounding_box": { "allOf": [ { "$ref": "#/components/schemas/Bynn_V1_Entities_BoundingBox" } ], "description": "The bounding box of the face in the image" }, "glasses": { "type": "boolean", "example": true, "description": "Indicates whether the person is wearing sunglasses or eyeglasses" }, "predicted_gender": { "type": "string", "enum": [ "male", "female", "undetermined" ], "example": "female", "description": "Automated guess of a person’s gender based on facial analysis. This is a prediction and may not match the person’s actual gender." } }, "required": [ "bounding_box", "glasses", "predicted_gender" ] }, "Bynn_V1_Entities_BoundingBox": { "type": "object", "properties": { "height": { "type": "number", "format": "float", "example": 0.7512, "description": "Height of the bounding box as a ratio of the overall image height" }, "left": { "type": "number", "format": "float", "example": 0.2615, "description": "Left coordinate of the bounding box as a ratio of overall image width" }, "top": { "type": "number", "format": "float", "example": 0.1235, "description": "Top coordinate of the bounding box as a ratio of overall image height" }, "width": { "type": "number", "format": "float", "example": 0.4836, "description": "Width of the bounding box as a ratio of the overall image width" } }, "required": [ "height", "left", "top", "width" ] }, "Bynn_V1_Entities_Liveness": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "verified", "not_verified", "not_evaluated" ], "example": "not_evaluated", "description": "Indicates whether its a verified real human in front of the camera" }, "confidence": { "type": "number", "format": "float", "example": 95.4836, "description": "Indicates confidence in whether its a verified real human in front of the camera. Normally around 50 is good enough for most applications. To protect against highly sofisticated deepfake or injection attacks this should be over 80-90" } }, "required": [ "status", "confidence" ] }, "postAgeVerificationSelfie": { "type": "object", "properties": { "image_base64_strict": { "type": "string", "description": "Base64 Strict Encoded selfie image (jpg, jpeg, png)" }, "image_url": { "type": "string", "description": "URL of a selfie image (jpg, jpeg, png)" }, "age_verification_model": { "type": "string", "description": "Select the AI-powered age verification model trained to estimate whether a person meets or exceeds the specified age threshold. Each model is optimized to detect individuals who are likely to be at least the given age, using facial analysis and machine learning.", "enum": [ "age_verification_21_years", "age_verification_20_years", "age_verification_19_years", "age_verification_18_years", "age_verification_17_years", "age_verification_16_years", "age_verification_15_years", "age_verification_14_years", "age_verification_13_years", "age_verification_12_years" ], "default": "age_verification_18_years" }, "legal_age_21": { "type": "boolean", "description": "Set the legal age threshold based on your jurisdiction. The default legal age is 18. If your jurisdiction requires a legal age of 21, set this to true. This is distinct from the age verification model, which determines the age threshold for verification and does not necessarily reflect the legal age requirement.", "default": false } }, "description": "No liveness - Age Verification with Selfie" }, "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_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" }, "postNfc": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Unique session token" }, "can": { "type": "string", "description": "Card Access Number (CAN) for PACE authentications." }, "authenticationStatus": { "type": "object", "description": "Authentication status from NFC chip", "properties": { "chipAuth": { "type": "boolean", "description": "Chip authentication status" }, "paceAuth": { "type": "boolean", "description": "PACE authentication status" }, "passiveAuth": { "type": "boolean", "description": "Passive authentication status" } }, "required": [ "chipAuth", "paceAuth", "passiveAuth" ] }, "cameraImage": { "type": "string", "description": "Base64 strict encoded camera image of the document" }, "faceImageBase64": { "type": "string", "description": "Base64 strict encoded face image from NFC chip" }, "certificateInfo": { "type": "object", "description": "Document certificate information", "properties": { "documentSignerCertificate": { "type": "object", "description": "Document signer certificate details", "properties": { "algorithm": { "type": "string", "description": "Certificate algorithm" }, "issuer": { "type": "string", "description": "Certificate issuer" }, "serialNumber": { "type": "string", "description": "Certificate serial number" }, "subject": { "type": "string", "description": "Certificate subject" }, "validFrom": { "type": "string", "description": "Certificate valid from date" }, "validTo": { "type": "string", "description": "Certificate valid to date" } } } } }, "dateOfBirth": { "type": "string", "description": "Date of birth (YYMMDD format)" }, "dateOfExpiry": { "type": "string", "description": "Document expiry date (YYMMDD format)" }, "documentNumber": { "type": "string", "description": "Document number" }, "gender": { "type": "string", "description": "Gender", "enum": [ "MALE", "FEMALE", "OTHER" ] }, "givenNames": { "type": "string", "description": "Given names from document" }, "surname": { "type": "string", "description": "Surname from document" }, "nationality": { "type": "string", "description": "Nationality code (3-letter)" }, "issuer": { "type": "string", "description": "Document issuing country code (3-letter)" }, "personalNumber": { "type": "string", "description": "Personal identification number" }, "hashVerification": { "type": "object", "description": "Hash verification data", "properties": { "algorithmUsed": { "type": "string", "description": "Hash algorithm used" }, "dg1Hash": { "type": "string", "description": "Base64 strict Data Group 1 hash" }, "dg2Hash": { "type": "string", "description": "Base64 strict Data Group 2 hash" }, "dg3Hash": { "type": "string", "description": "Base64 strict Data Group 3 hash" }, "dg4Hash": { "type": "string", "description": "Base64 strict Data Group 4 hash" }, "dg5Hash": { "type": "string", "description": "Base64 strict Data Group 5 hash" }, "dg6Hash": { "type": "string", "description": "Base64 strict Data Group 6 hash" }, "dg7Hash": { "type": "string", "description": "Base64 strict Data Group 7 hash" }, "dg8Hash": { "type": "string", "description": "Base64 strict Data Group 8 hash" }, "dg9Hash": { "type": "string", "description": "Base64 strict Data Group 9 hash" }, "dg10Hash": { "type": "string", "description": "Base64 strict Data Group 10 hash" }, "dg11Hash": { "type": "string", "description": "Base64 strict Data Group 11 hash" }, "dg12Hash": { "type": "string", "description": "Base64 strict Data Group 12 hash" }, "dg13Hash": { "type": "string", "description": "Base64 strict Data Group 13 hash" }, "dg14Hash": { "type": "string", "description": "Base64 strict Data Group 14 hash" }, "dg15Hash": { "type": "string", "description": "Base64 strict Data Group 15 hash" }, "dg16Hash": { "type": "string", "description": "Base64 strict Data Group 16 hash" }, "faceImageHash": { "type": "string", "description": "Base64 strict Face image hash" }, "sodHash": { "type": "string", "description": "Base64 strict Security Object Data hash" } }, "required": [ "algorithmUsed", "dg1Hash", "dg2Hash", "dg14Hash", "faceImageHash", "sodHash" ] }, "locationData": { "type": "object", "description": "Location data", "properties": { "accuracy": { "type": "number", "format": "float", "description": "Location accuracy in meters" }, "altitude": { "type": "number", "format": "float", "description": "Altitude in meters" }, "latitude": { "type": "number", "format": "float", "description": "Latitude coordinate" }, "longitude": { "type": "number", "format": "float", "description": "Longitude coordinate" }, "provider": { "type": "string", "description": "Location provider", "enum": [ "gps", "network", "passive" ] }, "timestamp": { "type": "integer", "format": "int32", "description": "Location timestamp in milliseconds" } } }, "mrzData": { "type": "string", "description": "Complete MRZ data as multi-line string" }, "rawDG1": { "type": "string", "description": "Data Group 1 - MRZ information" }, "rawDG2": { "type": "string", "description": "Data Group 2 - Encoded face image (Biometrics)" }, "rawDG3": { "type": "string", "description": "Data Group 3 - Fingerprint data (Biometrics)" }, "rawDG4": { "type": "string", "description": "Data Group 4 - Iris data (Biometrics)" }, "rawDG5": { "type": "string", "description": "Data Group 5 - Displayed portrait" }, "rawDG6": { "type": "string", "description": "Data Group 6 - Reserved for future use" }, "rawDG7": { "type": "string", "description": "Data Group 7 - Displayed signature" }, "rawDG8": { "type": "string", "description": "Data Group 8 - Data features" }, "rawDG9": { "type": "string", "description": "Data Group 9 - Structure features" }, "rawDG10": { "type": "string", "description": "Data Group 10 - Substance features" }, "rawDG11": { "type": "string", "description": "Data Group 11 - Additional personal details" }, "rawDG12": { "type": "string", "description": "Data Group 12 - Additional document details" }, "rawDG13": { "type": "string", "description": "Data Group 13 - Optional details" }, "rawDG14": { "type": "string", "description": "Data Group 14 - Security infos" }, "rawDG15": { "type": "string", "description": "Data Group 15 - Active authentication public key" }, "rawDG16": { "type": "string", "description": "Data Group 16 - Persons to notify" }, "rawSOD": { "type": "string", "description": "SOD - Security Object Data" } }, "required": [ "authenticationStatus", "faceImageBase64", "dateOfBirth", "dateOfExpiry", "documentNumber", "gender", "givenNames", "surname", "nationality", "issuer", "hashVerification", "rawDG1", "rawDG2", "rawDG14", "rawDG15", "rawSOD" ], "description": "NFC data submission" }, "Bynn_V1_Entities_ModerationCategoryEntity": { "type": "object", "properties": { "name": { "type": "string", "example": "Standard Moderation", "description": "Category name" }, "description": { "type": "string", "example": "Essential moderation models for detecting harmful content", "description": "Category description" }, "icon": { "type": "string", "example": "shield", "description": "Lucide icon name for the category" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/Bynn_V1_Entities_ModerationModelEntity" }, "description": "Models in this category" } }, "required": [ "name", "description", "icon", "models" ], "description": "Bynn_V1_Entities_ModerationCategoryEntity model" }, "Bynn_V1_Entities_ModerationModelEntity": { "type": "object", "properties": { "id": { "type": "string", "example": "nudity_detection", "description": "Unique model identifier" }, "api_name": { "type": "string", "example": "nudity-detection", "description": "API name for model (hyphenated, used in API calls)" }, "name": { "type": "string", "example": "Nudity & Adult Content Detection", "description": "Model display name" }, "description": { "type": "string", "example": "Detect nudity across 29 classes from very explicit to mildly suggestive", "description": "Model description" }, "category": { "type": "string", "example": "Standard Moderation", "description": "Model category" }, "moderation_type": { "type": "string", "enum": [ "image", "video", "audio", "text" ], "example": "image", "description": "Type of moderation (image, video, audio, text)" }, "icon": { "type": "string", "example": "shield-alert", "description": "Lucide icon name for the model" }, "is_active": { "type": "boolean", "example": true, "description": "Whether the model is currently active" }, "accuracy": { "type": "number", "example": 96.5, "description": "Model accuracy percentage" }, "avg_response_time_ms": { "type": "integer", "format": "int32", "example": 150, "description": "Average response time in milliseconds (calculated from last 10 completed inferences)" }, "pricing": { "type": "object", "description": "Pricing information" }, "all_plans_pricing": { "type": "object", "description": "Pricing information for all plan tiers (Trial, Core, Compliance, Forensic, Enterprise, Custom, Crypto)" }, "supported_formats": { "type": "array", "items": { "type": "array", "items": {} }, "example": [ "jpg", "png", "gif", "webp" ], "description": "Supported file formats" }, "max_file_size_mb": { "type": "integer", "format": "int32", "example": 10, "description": "Maximum file size in MB" }, "tags": { "type": "array", "items": { "type": "array", "items": {} }, "example": [ "nsfw", "adult-content", "safety" ], "description": "Model tags for filtering" }, "input_schema": { "type": "object", "description": "Input parameter schema from Triton model class" }, "output_schema": { "type": "object", "description": "Output field schema from Triton model class" }, "example_request": { "type": "object", "description": "Example API request parameters" }, "example_response": { "type": "object", "description": "Example API response" }, "require_plan": { "type": "string", "enum": [ "trial", "core", "compliance", "forensic", "enterprise", "custom", "crypto" ], "example": "core", "description": "Minimum plan required to access this model" }, "sample_content": { "type": "array", "example": [ { "url": "https://example.com/sample.jpg", "label": "Sample image" } ], "description": "Sample content for testing (URLs for media, text for text models)", "items": {} }, "version": { "type": "integer", "format": "int32", "example": 2601, "description": "Model version number" }, "version_date": { "type": "string", "example": "2026-01-03", "description": "Model version release date" }, "documentation_image_url": { "type": "string", "example": "https://cdn.example.com/model-docs/nudity-detection.webp", "description": "Main documentation image URL" }, "has_documentation": { "type": "boolean", "example": true, "description": "Whether the model has documentation content" }, "documentation": { "type": "string", "description": "Rich text HTML documentation for the model" } }, "required": [ "id", "api_name", "name", "description", "category", "moderation_type", "icon", "is_active", "accuracy", "avg_response_time_ms", "pricing", "supported_formats", "max_file_size_mb", "tags", "input_schema", "output_schema", "example_request", "example_response", "require_plan", "sample_content", "version", "version_date", "documentation_image_url", "has_documentation" ], "description": "Bynn_V1_Entities_ModerationModelEntity model" }, "postModerationInfer": { "type": "object", "properties": { "model": { "type": "string", "description": "The model API name to use for moderation (e.g., nudity-detection, violence-detection)" }, "content": { "type": "string", "description": "Text content to moderate (for text models)" }, "image_url": { "type": "string", "description": "URL of the image to moderate (for image models)" }, "base64_image": { "type": "string", "description": "Base64-encoded image data (alternative to image_url)" }, "base64_pdf": { "type": "string", "description": "Base64-encoded PDF data (for OCR model, billed per page)" }, "video_url": { "type": "string", "description": "URL of the video to moderate (for video models)" }, "base64_video": { "type": "string", "description": "Base64-encoded video data (alternative to video_url)" }, "audio_url": { "type": "string", "description": "URL of the audio to moderate (for audio models)" }, "base64_audio": { "type": "string", "description": "Base64-encoded audio data (alternative to audio_url)" }, "metadata": { "type": "object", "description": "Additional metadata for the inference" }, "idempotency_key": { "type": "string", "description": "Idempotency key for request deduplication" }, "image_urls": { "type": "array", "description": "Array of image URLs (for batch image processing)", "items": { "type": "string" } }, "base64_images": { "type": "array", "description": "Array of base64-encoded images (for batch image processing)", "items": { "type": "string" } }, "fps": { "type": "integer", "format": "int32", "description": "Frames per second to extract from video (1-10)", "minimum": 1, "maximum": 10, "default": 4 }, "distance_threshold": { "type": "number", "format": "float", "description": "Face matching distance threshold (0.3-0.7, lower = stricter)", "default": 0.5 }, "extract_faces": { "type": "boolean", "description": "Extract cropped face PNG for best match", "default": false } }, "required": [ "model" ], "description": "Create a moderation inference" }, "Bynn_V1_Entities_InferenceEntity": { "type": "object", "properties": { "inference_id": { "type": "string", "example": "inf_abc123def456", "description": "Unique inference identifier" }, "model_id": { "type": "string", "example": "nudity_detection", "description": "The model used for this inference" }, "model_name": { "type": "string", "example": "Nudity & Adult Content", "description": "The model display name" }, "moderation_type": { "type": "string", "example": "image", "description": "Type of moderation (image, video, audio, text)" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "example": "completed", "description": "Current status of the inference" }, "processing_mode": { "type": "string", "enum": [ "sync", "async" ], "example": "sync", "description": "How the inference is processed: sync (in-request) or async (queued, poll for result)" }, "result": { "type": "object", "description": "The moderation result data. Inline result images (segmentation masks, face crops, redacted images) from async inferences are returned as presigned *_url fields, downloadable for up to 24 hours after completion." }, "input_url": { "type": "string", "example": "https://example.com/image.jpg", "description": "URL of the input file/content that was moderated, or indicator of base64 upload" }, "ip_address": { "type": "string", "example": "192.168.1.1", "description": "IP address from which the inference request originated" }, "response_time_ms": { "type": "integer", "format": "int32", "example": 150, "description": "Response time in milliseconds" }, "error_message": { "type": "string", "description": "Error message if the inference failed" }, "created_at": { "type": "string", "example": "2024-01-15T10:30:00Z", "description": "When the inference was created" }, "completed_at": { "type": "string", "description": "When the inference was completed" }, "duration_seconds": { "type": "number", "example": 135.5, "description": "Duration of the media file in seconds (for video/audio models)" }, "billable_quantity": { "type": "integer", "format": "int32", "example": 3, "description": "Number of billable units (minutes for video/audio, images for batch)" }, "cost": { "type": "string", "example": "$0.00010", "description": "Total cost of this inference (formatted with 5 decimals). Returns null for failed inferences." } }, "required": [ "inference_id", "model_id", "model_name", "moderation_type", "status", "processing_mode", "result", "input_url", "ip_address", "response_time_ms", "created_at", "completed_at", "duration_seconds", "billable_quantity", "cost" ], "description": "Bynn_V1_Entities_InferenceEntity model" }, "postModerationInferAsync": { "type": "object", "properties": { "model": { "type": "string", "description": "The model API name to use for moderation (e.g., nudity-detection, violence-detection)" }, "content": { "type": "string", "description": "Text content to moderate (for text models)" }, "image_url": { "type": "string", "description": "URL of the image to moderate (for image models)" }, "base64_image": { "type": "string", "description": "Base64-encoded image data (alternative to image_url)" }, "base64_pdf": { "type": "string", "description": "Base64-encoded PDF data (for OCR model, billed per page)" }, "video_url": { "type": "string", "description": "URL of the video to moderate (for video models)" }, "base64_video": { "type": "string", "description": "Base64-encoded video data (alternative to video_url)" }, "audio_url": { "type": "string", "description": "URL of the audio to moderate (for audio models)" }, "base64_audio": { "type": "string", "description": "Base64-encoded audio data (alternative to audio_url)" }, "metadata": { "type": "object", "description": "Additional metadata for the inference" }, "idempotency_key": { "type": "string", "description": "Idempotency key for request deduplication" }, "image_urls": { "type": "array", "description": "Array of image URLs (for batch image processing)", "items": { "type": "string" } }, "base64_images": { "type": "array", "description": "Array of base64-encoded images (for batch image processing)", "items": { "type": "string" } }, "fps": { "type": "integer", "format": "int32", "description": "Frames per second to extract from video (1-10)", "minimum": 1, "maximum": 10, "default": 4 }, "distance_threshold": { "type": "number", "format": "float", "description": "Face matching distance threshold (0.3-0.7, lower = stricter)", "default": 0.5 }, "extract_faces": { "type": "boolean", "description": "Extract cropped face PNG for best match", "default": false } }, "required": [ "model" ], "description": "Create an asynchronous moderation inference" }, "postFaceCollections": { "type": "object", "properties": { "name": { "type": "string", "description": "Name for the face collection (max 255 characters)", "example": "Employee Faces" }, "description": { "type": "string", "description": "Optional description of the collection (max 1000 characters)", "example": "Headshots for building access control" } }, "required": [ "name" ], "description": "Create a face collection" }, "Bynn_V1_Entities_FaceCollectionEntity": { "type": "object", "properties": { "collection_id": { "type": "string", "example": "fc_abc123def456", "description": "Unique collection identifier with fc_ prefix" }, "name": { "type": "string", "example": "Employee Faces", "description": "Name of the face collection" }, "description": { "type": "string", "example": "Collection of employee headshots for access control", "description": "Optional description of the collection" }, "face_count": { "type": "integer", "format": "int32", "example": 42, "description": "Number of enrolled faces in the collection" }, "created_at": { "type": "string", "example": "2024-01-15T10:30:00Z", "description": "When the collection was created (ISO 8601)" } }, "required": [ "collection_id", "name", "description", "face_count", "created_at" ], "description": "Bynn_V1_Entities_FaceCollectionEntity model" }, "postFaceCollectionsTokenEnroll": { "type": "object", "properties": { "image_url": { "type": "string", "description": "URL of the image containing a face", "example": "https://example.com/photo.jpg" }, "base64_image": { "type": "string", "description": "Base64 strict encoded image data (max 20MB decoded)" }, "file": { "type": "string", "format": "binary", "description": "Image file upload (multipart/form-data, max 20MB)" }, "name": { "type": "string", "description": "Name or label for the enrolled face (max 255 characters)", "example": "John Doe" }, "external_id": { "type": "string", "description": "External reference ID for your system (max 255 characters)", "example": "emp_12345" }, "metadata": { "type": "object", "description": "Additional metadata to store with the face (max 16KB)", "example": { "department": "Engineering" } } }, "description": "Enroll a face into a collection" }, "Bynn_V1_Entities_FaceEntity": { "type": "object", "properties": { "face_id": { "type": "string", "example": "face_abc123def456", "description": "Unique face identifier with face_ prefix" }, "name": { "type": "string", "example": "John Doe", "description": "Name or label for the enrolled face" }, "external_id": { "type": "string", "example": "emp_12345", "description": "External reference ID for integration with your system" }, "category": { "type": "string", "example": "celeb_sport", "description": "Face category (celeb_sport, celeb_movie, celeb_other, unknown)" }, "metadata": { "type": "object", "example": { "department": "Engineering" }, "description": "Additional metadata associated with the face" }, "created_at": { "type": "string", "example": "2024-01-15T10:30:00Z", "description": "When the face was enrolled (ISO 8601)" } }, "required": [ "face_id", "name", "external_id", "category", "metadata", "created_at" ], "description": "Bynn_V1_Entities_FaceEntity model" }, "postFaceCollectionsTokenSearch": { "type": "object", "properties": { "image_url": { "type": "string", "description": "URL of the image containing a face to search for", "example": "https://example.com/photo.jpg" }, "base64_image": { "type": "string", "description": "Base64 strict encoded image data (max 20MB decoded)" }, "file": { "type": "string", "format": "binary", "description": "Image file upload (multipart/form-data, max 20MB)" }, "limit": { "type": "integer", "format": "int32", "description": "Maximum number of results to return (1-100)", "minimum": 1, "maximum": 100, "default": 10, "example": 10 }, "distance_threshold": { "type": "number", "format": "float", "description": "Max cosine distance for matches (0.1-1.0, lower is stricter); omit for the gallery-calibrated default.", "example": 0.5 } }, "description": "Search for faces in a collection" }, "Bynn_V1_Entities_FaceSearchResultEntity": { "type": "object", "properties": { "face_id": { "type": "string", "example": "face_abc123def456", "description": "Unique face identifier with face_ prefix" }, "name": { "type": "string", "example": "John Doe", "description": "Name or label of the matched face" }, "external_id": { "type": "string", "example": "emp_12345", "description": "External reference ID of the matched face" }, "distance": { "type": "number", "example": 0.23, "description": "Cosine distance between the query face and this match (lower is more similar)" }, "similarity": { "type": "number", "example": 0.77, "description": "Similarity score (1 - distance, higher is more similar)" }, "metadata": { "type": "object", "description": "Additional metadata associated with the face" } }, "required": [ "face_id", "name", "external_id", "distance", "similarity", "metadata" ], "description": "Bynn_V1_Entities_FaceSearchResultEntity model" } } } }