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
Theshare_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 or consume theidentity.verification.updated webhook; a needs_information status carries the exact required_fields to submit via POST /api/v2/kyc/information.
If the shared verification did not carry a residential address, the import returns needs_information right away: submit the address (and any other listed field) as soon as the import call returns, in that order. Submitting information before the import would start a separate verification on Agentcard’s side, and the import then returns 409 verification_in_progress. That information call returns pending, and the card issuer application is filed right after it, so the verification moves to review without waiting for a scheduled retry. If the issuer cannot take the application at that moment, the user’s timeline in your Agentcard dashboard records the failure and the retry runs automatically.Authorizations
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 <token>. Tokens live one hour.
Body
The connected user's id.
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.
The end user's IP address as your frontend saw it (public IPv4 or IPv6; private or reserved addresses are rejected). Strongly recommended: identity screening checks the applicant's IP, and an IP belonging to a datacenter (such as your backend's) can fail an otherwise valid verification. Pass the address your user connected to you from; without it, your server's own address may be recorded as a last resort and can fail that screening.
Response
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 whose shared verification carried no residential address lands on needs_information with the exact required_fields: submit them via POST /api/v2/kyc/information right away (import first, then information), and the card issuer application is filed as soon as the address lands.
The single status contract every KYC response carries.
kyc 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.
awaiting_documents, needs_information, requires_verification, pending, approved, rejected Only on needs_information — exactly the fields to collect and post to /kyc/information.
On every actionable status (awaiting_documents, needs_information, requires_verification): the hosted page that collects whatever the verification still needs, and the face scan at requires_verification. 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.
Optional, on document uploads — actionable feedback safe to show the user (for example, that the other side of the document is still needed).
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.
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.