KYC & Accreditation

Users must complete KYC (Know Your Customer) verification before subscribing to offerings. Accredited investor verification is required for certain offering types. Both flows are session-based: create a session, direct the user to a hosted verification page, and receive the result via webhook or polling.

All endpoints below require a Rialto access_token (obtained via token exchange).

KYC Flow

How It Works

Your backend creates a KYC session
Redirect or embed the returned session_url for the user
User completes identity verification through the hosted flow
Session progresses through states automatically
You are notified via webhook or poll for the result

Creating a KYC Session

curl -X POST https://api.rialto.com/identity/kyc-sessions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <rialto_access_token>" \
  -d '{
    "redirectUrl": "https://yourapp.com/kyc-callback"
  }'

redirectUrl is optional -- if provided, the user is redirected there after completing verification.

Response (201):

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-...",
    "user_id": "70000000-...",
    "org_id": "550e8400-...",
    "session_url": "https://verify.rialto.com/kyc/a1b2c3d4-...",
    "redirect_url": "https://yourapp.com/kyc-callback",
    "status": "awaiting_input",
    "identity_check": "not_attempted",
    "document_check": "not_attempted",
    "flags": [],
    "created_at": "2026-03-15T10:30:00.000Z",
    "updated_at": "2026-03-15T10:30:00.000Z"
  }
}

Only one active (non-terminal) KYC session is allowed per user at a time.

KYC Session Statuses

Status	Description	Terminal?
`awaiting_input`	Waiting for user to submit identity info	No
`pii_submitted`	Identity info submitted, awaiting verification	No
`processing`	Document scan / identity check in progress	No
`approved`	Identity verified successfully	Yes
`denied`	Identity verification failed	Yes
`requires_review`	Needs manual review by Rialto staff	No
`expired`	Session timed out	Yes
`error`	Unrecoverable processing error	Yes

Check Statuses

Each session has identity_check and document_check fields:

Check Status	Meaning
`clear`	Check passed
`failed`	Check failed
`unverified`	Could not verify
`not_attempted`	Check not yet run
`pending`	Check in progress

Checking KYC Status

# Get a specific session
curl https://api.rialto.com/identity/kyc-sessions/<session_id> \
  -H "Authorization: Bearer <rialto_access_token>"

# List all sessions for the authenticated user
curl https://api.rialto.com/identity/kyc-sessions/user \
  -H "Authorization: Bearer <rialto_access_token>"

KYC Webhook Events

Subscribe to these events via the webhooks API:

Event	When it fires
`kyc.session.created`	Session created
`kyc.session.pii_submitted`	User submitted identity info
`kyc.session.processing`	Verification in progress
`kyc.session.approved`	Verification passed
`kyc.session.denied`	Verification failed
`kyc.session.requires_review`	Flagged for manual review

Accreditation Flow

How It Works

Your backend creates an accreditation session
Direct the user to the returned session_url
User selects a verification method and submits documentation
For self-certification as non-accredited: completes immediately
For documentation review: requires admin review
You are notified via webhook or poll for the result

Creating an Accreditation Session

curl -X POST https://api.rialto.com/identity/accreditation-sessions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <rialto_access_token>" \
  -d '{
    "verificationMethod": "documentation_review",
    "redirectUrl": "https://yourapp.com/accreditation-callback"
  }'

Both fields are optional:

verificationMethod: "self_certification" (default) or "documentation_review"
redirectUrl: Where to redirect the user after completion

Response (201):

{
  "success": true,
  "data": {
    "id": "b2c3d4e5-...",
    "status": "pending",
    "session_url": "https://verify.rialto.com/accreditation/b2c3d4e5-...",
    "redirect_url": "https://yourapp.com/accreditation-callback",
    "accreditation_verification_method": "documentation_review",
    "created_at": "2026-03-15T10:30:00.000Z",
    "updated_at": "2026-03-15T10:30:00.000Z"
  }
}

Only one active (non-terminal) accreditation session is allowed per user at a time.

Verification Methods

Method	How it works
`self_certification`	User declares their status. Non-accredited completes immediately (approved). Accredited goes to `submitted` for review.
`documentation_review`	User uploads proof documents. Always goes through admin review for accredited status.

Accreditation Session Statuses

Status	Description	Terminal?
`pending`	Initial state, user has not submitted	No
`submitted`	User submitted, awaiting admin review	No
`under_review`	Admin is reviewing	No
`more_info_needed`	Admin requested additional information	No
`approved`	Accreditation verified	Yes
`denied`	Accreditation denied	Yes
`expired`	Session timed out	Yes

Accreditation Statuses

When approved, users receive one of these accreditation statuses:

Status	Description
`accredited`	Accredited investor
`non_accredited`	Not accredited
`qualified_purchaser`	Qualified purchaser (QP)
`qualified_client`	Qualified client (QC)
`expired`	Accreditation expired

Accreditation Bases

The basis for accreditation:

Basis	Description
`income`	Income-based accreditation
`net_worth`	Net worth-based
`license_7_65_82`	Series 7, 65, or 82 license holder
`entity`	Entity-based accreditation
`not_accredited`	Not accredited

Uploading Documents

For documentation_review sessions, upload proof documents:

curl -X POST https://api.rialto.com/identity/accreditation-sessions/<session_id>/documents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <rialto_access_token>" \
  -d '{
    "type": "income_proof",
    "fileName": "tax-return-2025.pdf",
    "content": "<base64-encoded-file>",
    "contentType": "application/pdf"
  }'

Field	Required	Description
`type`	Yes	`income_proof`, `net_worth_proof`, `license_proof`, or `entity_proof`
`fileName`	Yes	Original file name
`content`	Yes	Base64-encoded file content
`contentType`	No	MIME type (defaults to `application/pdf`)

Max file size: 10 MB

Checking Accreditation Status

# Get a specific session
curl https://api.rialto.com/identity/accreditation-sessions/<session_id> \
  -H "Authorization: Bearer <rialto_access_token>"

# List all sessions for the authenticated user
curl https://api.rialto.com/identity/accreditation-sessions/user \
  -H "Authorization: Bearer <rialto_access_token>"

Accreditation Webhook Events

Event	When it fires
`accreditation.session.created`	Session created
`accreditation.document.uploaded`	User uploaded a document
`accreditation.session.submitted`	User submitted for review
`accreditation.session.more_info_needed`	Admin requested more info
`accreditation.session.approved`	Accreditation approved
`accreditation.session.denied`	Accreditation denied

Token Claims After Verification

After KYC and accreditation are completed, subsequent Rialto tokens include updated claims:

Event	Claim updated
KYC approved	`kyc_completed = true`
Accreditation approved	`accredited = true`, `accreditation_verified = true`

Use these claims to gate features in your application -- for example, only allow users with kyc_completed = true and accredited = true to subscribe to regulated offerings.

Typical User Journey

1. Token Exchange     → User gets Rialto access token
2. Create KYC Session → User verifies identity
3. KYC Approved       → kyc_completed = true in token
4. Create Accreditation Session → User proves accreditation
5. Accreditation Approved → accredited = true in token
6. User can now subscribe to offerings

KYC & Accreditation

On this page