Identity verification (KYC) sessions

Identity verification (KYC) is how a user's identity is checked. Create a KYC session starts it, or resumes it, and gives you a link to send your user to.

curl -X POST "https://sdk.tilt-pay.com/v1/users/4821/kyc-sessions" \
  -H "Authorization: Bearer $TILT_PAY_API_KEY"

{
  "object": "kyc_session",
  "id": "ks_5b1f0c2e7a4d9e3f8a6b1c0d",
  "user_id": "4821",
  "status": "pending",
  "url": "https://verify.example.com/session/abc123",
  "expires_at": "2026-10-09T09:30:00.000Z",
  "livemode": false
}

The call has no body and is idempotent by nature: while the verification is in progress it returns the same session (same id). A user whose KYC was rejected can start again. You can read the status at any time with Retrieve the KYC status of a user, and you are told of the outcome by the kyc.approved and kyc.rejected events.

Sandbox#

The session is simulated: status is pending, url is null and expires_at is 24 hours ahead. Play the outcome with the simulator: {"scenario": "kyc_approved"} or {"scenario": "kyc_rejected"}.

Live#

• url is the link to open for the end user. When a session already exists and no new link is available, url is null and status stays pending.
• expires_at is null in live: the lifetime of the link is not communicated.
• The final result arrives through kyc.approved or kyc.rejected (and in status).
• Return links to your own site or app are not supported yet.

Errors#