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.

This guide implements the open-banking step of onboarding. The user submits a profile, links their bank through the embedded Quiltt connector, and ClearBox receives the linked account asynchronously and cross-references it against the submitted profile. It corresponds to the onboarding sequence your team works from.
This flow uses the Quiltt Connector on the client and the Quiltt API on the server. Quiltt authenticates client sessions with short-lived session tokens that your backend mints — your Quiltt API key never reaches the browser.

​
Flow at a glance

1

Submit signup form

The user submits name, email, date of birth, and address. ClearBox saves the profile with status pending and initializes a session.
2

Launch the Quiltt connector

The frontend launches the embedded Quiltt Link widget using a session token minted by the ClearBox backend.
3

User authorizes bank access

The user logs into their bank and authorizes access inside the widget.
4

Receive the connection webhook

Quiltt fires an asynchronous webhook to the ClearBox backend indicating the bank is linked, and the backend retrieves the connection.
5

Cross-reference profile data

ClearBox matches the submitted profile against the bank’s account-owner metadata before proceeding to identity verification.

​
1. Save the profile

When the user submits the signup form, persist the profile server-side with a pending status. This record is the anchor every later object (bank connection, identity, wallet) maps back to. 
POST /v1/identities

{
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.com",
  "date_of_birth": "1990-12-10",
  "address": {
    "line1": "5 Analytical Ave",
    "city": "London",
    "postal_code": "EC1A 1BB",
    "country": "GB"
  }
}
The response returns an identity_id with kyc_status: "pending".

​
2. Mint a Quiltt session token

On the ClearBox backend, mint a Quiltt session token for the user. Quiltt scopes the token to a single profile, so pass a stable identifier (the ClearBox identity_id works well as the external profile reference). 
POST https://auth.quiltt.io/v1/users/sessions
Authorization: Bearer <QUILTT_API_SECRET>
Content-Type: application/json

{
  "userId": "idn_8f2a..."
}
Quiltt returns a session token your frontend uses to initialize the connector. Tokens are short-lived; see Managing Session Tokens.

​
3. Launch the embedded connector

On the client, initialize the Quiltt connector with the session token and your connector ID. The example below uses the React SDK. 
import { useQuilttConnector } from "@quiltt/react";

function LinkBankButton({ sessionToken }) {
  const { open } = useQuilttConnector("<CONNECTOR_ID>", {
    onExitSuccess: (metadata) => {
      // metadata.connectionId identifies the new bank connection
      notifyBackendBankLinked(metadata.connectionId);
    },
  });

  return <button onClick={open}>Link your bank</button>;
}
The user logs into their bank and authorizes access entirely within the widget. No bank credentials touch ClearBox.
Do not rely solely on the client onExitSuccess callback to mark a bank as linked — clients can close early or lose connectivity. Treat the webhook in the next step as the authoritative signal.

​
4. Handle the connection webhook

Quiltt notifies your backend asynchronously when a connection is established. Configure a webhook endpoint (see Setting up Webhooks) and handle the connection.synced event. 
{
  "eventTypes": ["connection.synced"],
  "events": [
    {
      "type": "connection.synced",
      "profile": { "id": "idn_8f2a..." },
      "connection": { "id": "conn_3b9c..." }
    }
  ]
}
On receipt, verify the signature, then fetch the connection’s accounts and owners from the Quiltt GraphQL API to obtain the metadata you’ll cross-reference. 
query AccountOwners($connectionId: ID!) {
  connection(id: $connectionId) {
    accounts {
      id
      name
      owners {
        names { full }
        addresses { line1 city postalCode countryCode }
      }
    }
  }
}

​
5. Cross-reference and advance

Compare the bank’s account-owner name and address against the profile the user submitted in step 1. When they match within your tolerance, advance the identity to verification. 
PATCH /v1/identities/idn_8f2a...

{
  "bank_connection_id": "conn_3b9c...",
  "onboarding_state": "bank_linked"
}
The user is now ready for identity verification.

Next: Verify identity (ClearCheck)

Run the KYC inquiry and issue a verified identity.

​
Reference

Endpoints under /v1/identities are ClearBox program endpoints (base URL https://api.clearbox.example.com). Replace the base URL and field names with your program’s actual values.