Skip to main content
POST
Create or resume KYC session
Returns the one active identity verification session for the UPA, creating it if needed. A verified UPA email is required first, through the email verification endpoints or the initial managed-Vault policy OTP. Repeated calls reuse the same active verificationUrl; once verification is approved, the approved record is returned without a reusable link. Rejected or expired sessions can be retried, but Stableyard creates at most three provider sessions per UPA. Further attempts return 409 conflict and need manual review. The request has no body: the account path fixes the subject, and provider configuration is server-controlled.

Authorizations

Authorization
string
header
required

HTTP Basic auth. Username is the Stableyard app ID. Password is the app secret. The optional Stableyard-Version request header must match the environment pin.

Headers

Stableyard-Version
enum<string>

Optional contract-version assertion. Omit it to use the app environment's pinned version. A different supported version is accepted only after that environment is explicitly migrated.

Available options:
2026-09-09

Path Parameters

accountId
string
required

Canonical account id returned by the Accounts API.

Example:

"acct_123"

Response

KYC verification session

id
string
required
Pattern: ^kyc_[A-Za-z0-9_-]+$
Example:

"kyc_123"

accountId
string
required
Pattern: ^acct_[A-Za-z0-9_-]+$
Example:

"acct_123"

status
enum<string>
required
Available options:
not_started,
pending,
in_progress,
approved,
rejected,
expired,
requires_review
eligibility
object
required
nextAction
object
required
createdAt
string<date-time>
required
updatedAt
string<date-time>
required
verificationUrl
string<uri>

Provider-hosted verification URL while payer action is required.

Maximum string length: 2048
completedAt
string<date-time>