submit_kyc_document
Submit the user's ID photo for identity verification. Ways in: (a) image data you hold programmatically (e.g. the user sent the photo in this chat and your platform exposes its bytes) — pass front_base64 (and back_base64 for a license back; its barcode reads most accurately); (b) local (stdio) mode — pass file_path/back_file_path and the file is read from disk; (c) neither — you get a secure upload link to hand the user. Do NOT ask the user what kind of document it is or where it was issued — the type and country are detected automatically from the photo; only relay a question if the result says the type could not be determined. Returns the fields read off the document — SHOW THEM TO THE USER for confirmation before continuing — plus whatever is still missing. If the result says NO identity details could be read, the image did not read as an ID at all: never insist to the user that it was their ID. Supported: JPEG/PNG/WebP up to 12MB (convert HEIC or HEIF photos first).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | No | Local path to the ID photo (front of license, or passport photo page). Local/stdio connections only — remote connections without image data receive an upload link instead. | |
| back_base64 | No | Base64 image bytes of the license back (optional, recommended — the barcode reads most accurately). Same rule: programmatically sourced only. | |
| front_base64 | No | Base64 image bytes of the ID front (or passport photo page). ONLY pass base64 you received programmatically from your platform (e.g. an injected chat attachment) — never type or reconstruct image bytes yourself. | |
| document_type | No | ONLY pass this when the user themselves said what the document is ("here's my license") — otherwise omit it; the type is detected from the photo. Never ask up front. | |
| back_file_path | No | Local path to the back of the license (optional, recommended). Local/stdio connections only. | |
| back_mime_type | No | MIME type of back_base64. Defaults to image/jpeg. | |
| front_mime_type | No | MIME type of front_base64 (image/jpeg, image/png, image/webp). Defaults to image/jpeg. | |
| issuing_country | No | 2-letter ISO country that issued the document (e.g. US, AR). ONLY when the user volunteered it — otherwise omit; it is detected from the photo. Never ask up front. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | processed | document_expired | upload_failed | upload_link_provided | |
| message | Yes | ||
| nextStep | No | ||
| extracted | No | Fields read from the document (confirm with the user). | |
| uploadUrl | No | ||
| unreadable | No | True when the image was received but NO identity fields could be read from it — it did not read as an ID; never assert to the user that it was one. | |
| missingFields | No | ||
| verificationUrl | No |