individual account runs on a page hosted by a verification provider. You start a session, send the customer to the verificationUrl it returns, and read the result.
KYC via hosted link
The hosted link is the only way to verify an individual. There is no partner-collected KYC: no API accepts identity data or documents from you, and the provider’s decision and documents are never returned to you.1
Verify the email
KYC needs a verified email first. See Email verification.
2
Start a session
POST /v2/accounts/{accountId}/kyc/session. It returns the hosted verificationUrl.3
Send the customer to the link
Open
verificationUrl for the customer. The page takes no return URL and does not redirect back to you.4
Wait for the result
Act on the
kyc.updated webhook, or poll GET /v2/accounts/{accountId}/kyc.5
Read eligibility
Offer a bank rail only when
eligibility.status is eligible. Then activate a capability.Start a session
- No body, no return URL. The account path identifies the customer.
- Repeated calls reuse the active session and return the same link. A session still being prepared returns
status: "pending"withoutverificationUrl; call again shortly or wait forkyc.updated. - An approved, current verification is returned without a link. Nothing new is created, except after a payout returned
reverify_identityfor that verification (see below). - At most three verification sessions per account. A rejected or expired session can be retried with a new session; the fourth attempt is refused with
409and needs manual review.
verificationUrl is returned only while a session is open. It is absent once the verification is approved, rejected or expired. What the customer sees on the page is on Branding and your frontend.
Read the result
current is the newest verification, and verifications holds the ten most recent, newest first. Before the first session, current is absent and verifications is empty.
KYC states
rejected and expired are final for that verification. Another attempt is a new session.
Eligibility
eligibility.status is what regulated operations check, and they recheck it every time they run. Read it, not status, before you offer a bank rail.
Re-verify for a payout provider
A payout provider can need identity data that the approved verification lacks, such as a document number or ID image, or it can refuse the verified document type. The customer cannot type these into a form, so a fiat payout returnsnextAction: { "type": "reverify_identity" }. This can happen after a reused partner verification as well as after a Stableyard-hosted one. The payout readiness response explains why:
identity_data_missing lists the fields in missingFields. Then:
- Call
POST /v2/accounts/{accountId}/kyc/session. Because the payout recorded the request for this exact verification, a new session andverificationUrlare created even though the current approval is still valid. Tell the customer which document to use whenacceptedDocumentTypesis present. - Once the new session is approved, retry the payout. Details already entered on a hosted payout form belong to the previous verification and are asked for again if still needed.
complete_compliance form.
Next actions
Errors
Webhooks
Related
Email verification
The gate before KYC.
Capability activation
The gate after KYC: approval for a bank service.
Onboarding overview
Every gate between an account and a fiat rail.
Event catalog
Every KYC and compliance event.
Reuse a partner’s existing Didit verification
Approved partner integrations can share an existing identity instead of asking the user to upload documents again. This is a backend-to-backend flow for Individual UPAs. It does not import business KYB or activate a banking service automatically.- Read
GET /v2/partners/kyc-reuse-policyusing credentials withv2:kyc. An unconfigured policy returnsenabled: false. Ask Stableyard operations to configure your Didit source application UUID, our receiving application UUID and workflow, consent version and review mode, agreement reference, whitelist expiry and explicit identity/screening age limits. These UUIDs differ from Stableyardapp_...IDs. - Verify the actual UPA owner’s email. Obtain and retain the user’s data-sharing consent and your consent receipt reference.
- Your backend must bind the source session to the same actual user as the destination UPA; importing another person’s record is not authorized. Your backend uses your own Didit API key to mint a share token for the existing session, addressed to our receiving Didit application. Never send your Didit API key to Stableyard.
- Submit
POST /v2/accounts/{accountId}/kyc/importswithIdempotency-Keyand body{ "shareToken": "<short-lived-token>", "consent": { "accepted": true, "version": "<configured-version>", "reference": "<your-receipt-id>" } }. Never place the token in a URL, browser storage or logs. Stableyard never stores the raw token. - Read
GET /v2/accounts/{accountId}/kyc/imports/{importId}or the existing account KYC endpoint.import.status: importedconfirms the copy, not approval. Review-first copies remainrequires_reviewuntil the provider decision and Stableyard compliance evidence review are complete. Preserving a source decision never waives screening, consent review, environment or freshness checks. - Continue provider onboarding once
verification.eligibility.statusiseligible. Imported approvals require one unambiguous approved ID, liveness and face-match result, an unexpired dated document and approved AML screening of the same person. Unreviewed, inconclusive and confirmed AML hits block this reuse path. Stableyard compliance must verify original evidence dates and consent receipts. Eligibility expires at the earliest document, original-verification, screening, whitelist or policy deadline; copying a record is not a fresh identity capture. Missing provider information and provider approval can still be required.
requires_reconciliation result must be resolved by Stableyard operations using the provider-owned session record: do not create fresh sessions or blindly redeem another token. A confirmed rejected import can be retried with a new token and a new key. An original session can bind to only one receiving UPA; contact support rather than attaching it to another person or tenant.
The hosted KYC session endpoint remains available for users without a reusable verification. User-controlled Didit reauthentication is separate from this partner sharing API.
Partner authorization is rechecked when applying approvals, activating or using regulated capabilities, and handing identity evidence to another provider. Suspending a policy blocks pending approvals and new regulated use even when earlier provider approval is cached. Historical records and already submitted money movements are retained for reconciliation.
AML refresh requires a new audited evidence review. It can renew eligibility within the unchanged original identity deadline; it cannot reset the original verification date. Missing address, phone, additional provider checks or proof of address must still be collected when the provider requires them. This integration does not treat AML as proof of address or a verified email contact.