Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clear-box.io/llms.txt

Use this file to discover all available pages before exploring further.

ClearCheck is ClearBox’s identity layer. It verifies who a user is — KYC, AML, and KYB — before they can hold a wallet or transact. ClearCheck runs on Persona, surfaced to users through Crossmint Auth, and produces a verified identity that the rest of ClearBox depends on.
Persona’s core object is the inquiry: a single instance of a verification flow. You configure what to check in an inquiry template, create an inquiry for the user, and read the result once the inquiry reaches a terminal status.

​
Flow at a glance

1

Bank linked, profile cross-referenced

The user has completed the Quiltt bank link and ClearBox has matched the profile to the bank metadata.
2

Create an inquiry

ClearBox creates a Persona inquiry from your KYC inquiry template, tagged with the user’s reference ID.
3

User completes verification

The user completes the inquiry UI — typically capturing a government ID and a selfie.
4

Receive the result

Persona transitions the inquiry to a terminal status and fires a webhook. ClearBox reads the result.
5

Issue the verified identity

On approval, ClearBox marks the identity verified and proceeds to wallet provisioning.

​
1. Create an inquiry

On the ClearBox backend, create a Persona inquiry from your published KYC template. Pass a stable reference ID so repeat inquiries from the same user link to the same Persona account — ClearBox uses the identity_id for this. 
POST https://api.withpersona.com/api/v1/inquiries
Authorization: Bearer <PERSONA_API_KEY>
Content-Type: application/json

{
  "data": {
    "attributes": {
      "inquiry-template-id": "itmpl_ClearCheckKYC",
      "reference-id": "idn_8f2a..."
    }
  }
}
Persona returns an inquiry object with an id (for example inq_9d4f...) in status created.

​
2. Present the verification flow

Use the inquiry to launch verification for the user. ClearBox surfaces this through Crossmint Auth, which embeds the Persona flow. You can integrate the flow three ways:
MethodWhat it isBest for
HostedRedirect to a Persona-hosted pageFastest setup
EmbeddedPersona UI in an iframe/modal on your pageSeamless web UX
Mobile SDKNative iOS/Android/React NativeMobile apps, best device signals
The user captures their government ID and a selfie, and Persona runs the verification checks defined in the template.

​
3. Read the inquiry result

An inquiry moves through a lifecycle and emits an event at each transition. The terminal statuses that carry a usable result are:
StatusMeaning
approvedThe user passed all required checks.
declinedThe user failed one or more required checks.
needs_reviewThe inquiry requires manual review before a decision.
Get the result either by listening for webhooks or by fetching the inquiry directly. Webhook (recommended): Persona sends an event such as inquiry.approved or inquiry.declined to your endpoint. Verify the signature, then act on it. 
{
  "data": {
    "attributes": {
      "name": "inquiry.approved",
      "payload": {
        "data": {
          "id": "inq_9d4f...",
          "attributes": { "reference-id": "idn_8f2a...", "status": "approved" }
        }
      }
    }
  }
}
API: Fetch the inquiry on demand from the Retrieve an Inquiry endpoint. 
GET https://api.withpersona.com/api/v1/inquiries/inq_9d4f...
Authorization: Bearer <PERSONA_API_KEY>

​
4. Issue the verified identity

When the inquiry is approved, mark the ClearBox identity verified. This is the gate that unlocks wallet provisioning. 
PATCH /v1/identities/idn_8f2a...

{
  "kyc_status": "approved",
  "kyc_inquiry_id": "inq_9d4f...",
  "onboarding_state": "verified"
}
For needs_review, hold the user in a pending state and resolve through your review process. For declined, follow your program’s decline handling.

Next: Create a wallet

Provision a non-custodial wallet for the verified identity.

​
Compliance notes

ClearCheck enforces the AML and KYC requirements your program is licensed for, including Genius Act transaction limits. Verification is required before a wallet can transact, and the verified identity is bound to every wallet and card the user holds. See ClearCheck KYC/AML for the compliance model.

​
Reference

itmpl_ClearCheckKYC is a placeholder template ID. Replace it with your program’s actual Persona inquiry template ID, and replace the /v1/identities base URL with your ClearBox program’s value.