> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt > Use this file to discover all available pages before exploring further. # Upload the front of the ID > Uploads the front of the user's identity document as a base64-encoded image. This step acknowledges receipt; the next step (`back`) tells you what comes next. Any upload response may include a `warnings` array with actionable feedback (for example, that the other side of the document is still needed). The response's `extracted` object carries what the document reader pulled off the image — use it to prefill your details form so the user confirms instead of typing. ## OpenAPI ````yaml openapi.json POST /api/v2/kyc/documents/front openapi: 3.1.0 info: title: Agentcard API version: 2.0.0 description: >- The Agentcard v2 API — connect your users and verify their identity from your own backend. Every call is authenticated with a platform access token minted from your `client_id` + `client_secret`. servers: - url: https://api.agentcard.sh description: >- There is one base URL. Sandbox vs production is decided by the client credential you use, never by the host. security: - platformToken: [] tags: - name: Authentication description: >- Exchange your client credentials for a platform access token, and introspect what a token acts as. - name: Connect description: >- Connect a user to your platform: send a one-time code, verify it, record consent, and keep the connection alive. - name: Identity verification description: >- Verify a connected user's identity: upload their ID, submit any extra fields we ask for, then show a short face scan. - name: Wallet funding description: >- Fund a connected user's wallet from your own UI — request a payment link, relay the phone verification code, and poll until the funds land. - name: Withdrawals description: >- Move money out of a connected user's wallet — to a saved bank account or a crypto address on Base. Transfers are processed manually by the Agentcard team, usually within 1-3 business days. paths: /api/v2/kyc/documents/front: post: tags: - Identity verification summary: Upload the front of the ID description: >- Uploads the front of the user's identity document as a base64-encoded image. This step acknowledges receipt; the next step (`back`) tells you what comes next. Any upload response may include a `warnings` array with actionable feedback (for example, that the other side of the document is still needed). The response's `extracted` object carries what the document reader pulled off the image — use it to prefill your details form so the user confirms instead of typing. operationId: kycUploadFront requestBody: $ref: '#/components/requestBodies/KycDocument' responses: '200': description: >- Receipt acknowledged — upload the back next. May include a `warnings` array. content: application/json: schema: $ref: '#/components/schemas/KycState' example: object: kyc status: awaiting_documents extracted: document_type: drivers_license issuing_country: US first_name: Jane last_name: Doe date_of_birth: '1990-05-14' '400': $ref: '#/components/responses/KycDocumentBadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/ConnectionNotFound' '409': $ref: '#/components/responses/UserConflict' '422': $ref: '#/components/responses/DocumentUnprocessable' '502': $ref: '#/components/responses/VerificationError' components: requestBodies: KycDocument: required: true content: application/json: schema: type: object required: - user_id - image properties: user_id: type: string description: The connected user's id. image: type: string description: The image bytes, base64-encoded. mime_type: type: string default: image/jpeg description: The image's MIME type. document_type: type: string enum: - drivers_license - state_id - passport description: >- Optional document-type hint. Without it the document is auto-detected and defaults to a US driver's license. If a response `warnings` entry asks you to resubmit with a `document_type`, send the same image again with this field set — no need to go back to the user. issuing_country: type: string description: >- Optional ISO 3166-1 country code (alpha-2 or alpha-3) of the country that issued the document. Defaults to US when the document doesn't reveal it — always send it for non-US documents (e.g. `DE` for a German national ID). example: user_id: user_7g8h9i image: mime_type: image/jpeg schemas: KycState: type: object description: The single status contract every KYC response carries. properties: object: type: string enum: - kyc status: type: string enum: - awaiting_documents - needs_information - requires_verification - pending - approved - rejected description: >- `awaiting_documents` — upload the front and back. `needs_information` — collect the `required_fields` and submit them. `requires_verification` — show the user the `iframe_url`. `pending` — under review, no action needed. `approved` — verified, done. `rejected` — the user did not pass. Statuses are not one-way: a review can send a user back — `pending` may return to `needs_information` (a detail didn't match the document; re-collect the listed fields and resubmit, the check re-runs automatically) or to `awaiting_documents` (the images were unusable; upload both sides again). Always branch on the current status. required_fields: type: array items: type: string description: >- Only on `needs_information` — exactly the fields to collect and post to `/kyc/information`. iframe_url: type: string description: >- Only on `requires_verification` — the URL to show the user for the face scan. Embed it in an iframe with `allow="camera; microphone"`. Short-lived: always use the most recent one from a poll or webhook, never a stored copy. warnings: type: array items: type: string description: >- Optional, on document uploads — actionable feedback safe to show the user (for example, that the other side of the document is still needed). extracted: type: object description: >- Optional, on document uploads — what the document reader pulled off the uploaded image(s), so you can prefill your details form instead of asking the user to re-type what the ID already says. Keys match the `/kyc/information` request fields (`first_name`, `last_name`, `date_of_birth`, `address_line1`, `address_city`, `address_region`, `address_postal_code`, `address_country`) plus `document_type`, `issuing_country`, and `document_number` (the number printed on the document — for US documents this is NOT the SSN, so never prefill it into `national_id_number` when `issuing_country` is `US`). Fields appear as they become readable: the front usually carries the name and date of birth; a US back adds the barcode address. Always let the user confirm or correct prefilled values. additionalProperties: type: string reason: type: string description: >- Optional, on `needs_information`, `awaiting_documents`, `requires_verification`, and `rejected` — a short, end-user-safe explanation of what the review asked for (for example, “Enter your full name exactly as it appears on your identity document.”). Safe to show the user verbatim. Error: type: object description: Every v2 error uses the same envelope. properties: error: type: object properties: code: type: string description: A stable, machine-readable string (snake_case). Branch on this. message: type: string description: A human-readable explanation, safe to log. docs: type: string description: A link back to the reference. field_errors: type: object additionalProperties: type: string description: Only on `invalid_fields` — names each field to fix. warnings: type: array items: type: string description: >- Only on document upload errors — actionable feedback safe to show the user. responses: KycDocumentBadRequest: description: >- `invalid_request` — missing `user_id` or `image`, or an unrecognized `document_type` / `issuing_country`. `invalid_image` — `image` isn't valid base64. `client_credentials_required` — the token wasn't minted from client credentials. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: >- `unauthorized` — the platform access token is missing or expired. Exchange your client credentials for a fresh one. content: application/json: schema: $ref: '#/components/schemas/Error' ConnectionNotFound: description: >- `connection_not_found` — no connection exists for that user under your client. content: application/json: schema: $ref: '#/components/schemas/Error' UserConflict: description: >- `user_conflict` — the email on file in your organization belongs to a different account. Contact support. content: application/json: schema: $ref: '#/components/schemas/Error' DocumentUnprocessable: description: >- `document_rejected` — the image couldn't be processed; ask the user to retake the photo. `document_expired` — the document itself is expired; ask for a valid one. Either may include a `warnings` array with actionable feedback. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: document_rejected message: >- The document image could not be processed — ask the user for a new, clear photo. warnings: - >- The verification provider still needs the back of the document — ask the user for the other side. VerificationError: description: '`verification_error` — the step failed downstream. Try again.' content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: platformToken: type: http scheme: bearer description: >- A platform access token. Get one on the **Create an access token** endpoint by exchanging your `client_id` + `client_secret`, then send it as `Authorization: Bearer `. Tokens live one hour. ````