> ## 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. # Import a verification > Import a verification you already ran on your **own Sumsub account** (Reusable KYC). Generate a single-use share token for the Agentcard client id, send it here, and the user skips document capture and the face scan. A successful import drops into the exact same status contract as a fresh verification: poll `GET /api/v2/kyc` or listen for `identity.verification.updated`. Requires one-time partner pairing between your Sumsub account and Agentcard's (per environment) — ask your Agentcard contact to enable it. Share tokens are single-use with a short TTL, so generate one fresh per import attempt. ## Where the token comes from The `share_token` is a Sumsub artifact you mint on your own account, so this endpoint only applies if you run KYC on Sumsub yourself. Generate it with Sumsub's `POST /resources/accessTokens/shareToken`, with `forClientId` set to the Agentcard client id from your pairing setup. Tokens are single-use and expire after their `ttlInSecs`: generate one right before each import call, never from storage. ## After the import The import creates the verification on Agentcard's side, and from that moment nothing distinguishes it from one your user ran here. Poll [GET /api/v2/kyc](/companies/api/reference/kyc-status) or consume the `identity.verification.updated` [webhook](/ship/webhooks); a `needs_information` status carries the exact `required_fields` to submit via [POST /api/v2/kyc/information](/companies/api/reference/kyc-submit-information). ## OpenAPI ````yaml openapi.json POST /api/v2/kyc/import 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/import: post: tags: - Identity verification summary: Import a verification (Sumsub share token) description: >- Import a verification you already ran on your **own Sumsub account** (Reusable KYC). Generate a single-use share token for the Agentcard client id, send it here, and the user skips document capture and the face scan. A successful import drops into the exact same status contract as a fresh verification: poll `GET /api/v2/kyc` or listen for `identity.verification.updated`. Requires one-time partner pairing between your Sumsub account and Agentcard's (per environment) — ask your Agentcard contact to enable it. Share tokens are single-use with a short TTL, so generate one fresh per import attempt. operationId: kycImport requestBody: required: true content: application/json: schema: type: object required: - user_id - share_token properties: user_id: type: string description: The connected user's id. share_token: type: string description: >- A Sumsub share token generated by your account for the Agentcard client id (`POST /resources/accessTokens/shareToken` with `forClientId`). Single-use; expires after its `ttlInSecs`. example: user_id: user_7g8h9i share_token: _act-jwt-eyJhbGciOiJub25lIn0... responses: '200': description: >- The verification's state after the import, exactly as `GET /api/v2/kyc` now reports it. A complete applicant lands on `pending` while checks run (then `approved`); an applicant missing program fields lands on `needs_information` with the exact `required_fields`. content: application/json: schema: $ref: '#/components/schemas/KycState' example: object: kyc status: pending '400': description: >- `invalid_request` — missing `user_id` or `share_token`. `invalid_share_token` — the token is invalid, expired, or already used; generate a fresh one and retry. `sharing_not_configured` — test mode has no sharing tenant configured; use `POST /api/v2/kyc/simulate` instead. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- `sharing_not_enabled` — your Sumsub account and Agentcard's are not paired in this environment. Complete partner pairing first. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- `connection_not_found` — the user has no active connection under this client. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- `verification_in_progress` — a verification is already in flight for this user. Drive it to completion with the status flow instead of importing. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- `verification_not_compatible` — the shared verification does not include everything the card program requires (an identity document and a selfie check). Share applicants from a level that includes both, or let the user run the standard flow. content: application/json: schema: $ref: '#/components/schemas/Error' components: 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: 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' 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. ````