Skip to main content
Identity verification (KYC) for an 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. 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" without verificationUrl; call again shortly or wait for kyc.updated.
  • An approved, current verification is returned without a link. Nothing new is created, except after a payout returned reverify_identity for 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 409 and 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 returns nextAction: { "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:
  1. Call POST /v2/accounts/{accountId}/kyc/session. Because the payout recorded the request for this exact verification, a new session and verificationUrl are created even though the current approval is still valid. Tell the customer which document to use when acceptedDocumentTypes is present.
  2. 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.
The current approval keeps the account eligible while the new session is open. The new session’s decision then becomes the account’s latest decision: a decline revokes eligibility, as it would for any later verification. The new session counts toward the three-session limit. Fields the customer can supply, such as phone or address, never trigger re-verification; they use the hosted complete_compliance form.

Next actions

Errors

Webhooks

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.
  1. Read GET /v2/partners/kyc-reuse-policy using credentials with v2:kyc. An unconfigured policy returns enabled: 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 Stableyard app_... IDs.
  2. Verify the actual UPA owner’s email. Obtain and retain the user’s data-sharing consent and your consent receipt reference.
  3. 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.
  4. Submit POST /v2/accounts/{accountId}/kyc/imports with Idempotency-Key and 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.
  5. Read GET /v2/accounts/{accountId}/kyc/imports/{importId} or the existing account KYC endpoint. import.status: imported confirms the copy, not approval. Review-first copies remain requires_review until the provider decision and Stableyard compliance evidence review are complete. Preserving a source decision never waives screening, consent review, environment or freshness checks.
  6. Continue provider onboarding once verification.eligibility.status is eligible. 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.
Replay the same key with the exact same token and consent to retrieve the original operation; changed input conflicts. Preserve the key after an uncertain response. A 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.