---
title: "Submit information"
method: POST
path: "/api/v2/kyc/information"
tags: ["Identity verification"]
---

# Submit information

`POST /api/v2/kyc/information`

Submits the extra fields requested by a `needs_information` response. Send only the fields listed in `required_fields`. On success, the response returns the `iframe_url` for the face scan.

## Request body

- object
  - `user_id` string, required — The connected user's id.
  - `first_name` string
  - `last_name` string
  - `date_of_birth` string — ISO 8601 date, `YYYY-MM-DD`.
  - `national_id_number` string — The user's national identification number.
  - `phone_number` string — E.164 format with country code (e.g. `+15551234567`).
  - `address_line1` string
  - `address_line2` string
  - `address_city` string
  - `address_region` string — State, province, or region.
  - `address_postal_code` string
  - `address_country` string — ISO 3166-1 alpha-2 country code (e.g. `US`).

## Response `200`

The next step — usually `requires_verification` with the `iframe_url`.

- KycState — The single status contract every KYC response carries.
  - `object` 'kyc'
  - `status` 'awaiting_documents' | 'needs_information' | 'requires_verification' | 'pending' | 'approved' | 'rejected' — `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` string[] — Only on `needs_information` — exactly the fields to collect and post to `/kyc/information`.
  - `iframe_url` string — 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` string[] — Optional, on document uploads — actionable feedback safe to show the user (for example, that the other side of the document is still needed).
  - `extracted` object — 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.
  - `reason` string — 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.

## Other responses

- `400` — `invalid_request` — missing `user_id`. `invalid_fields` — a value didn't check out; the error adds a `field_errors` object naming each field to fix.
- `401` — `unauthorized` — the platform access token is missing or expired. Exchange your client credentials for a fresh one.
- `404` — `connection_not_found` — no connection exists for that user under your client.
- `409` — `user_conflict` — the email on file in your organization belongs to a different account. Contact support.
- `502` — `verification_error` — the step failed downstream. Try again.

---

[API](https://skmtc.net/agentcard/apis/agentcard-api.md) · [All operations](https://skmtc.net/agentcard/apis/agentcard-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agentcard/agentcard-api/versions/638d12c8303f/schema)