AiPrise integration guide — Business (KYB) onboarding

Overview

When an applicant leaves a business (KYB) onboarding flow partway through and comes back later, there are two ways to restore their saved progress:

1. Email OTP: the applicant re-enters their email, receives a one-time code, and their saved data is restored after they verify it.

2. Onboarding SDK token: your backend mints a short-lived token for the session and passes it to the SDK. The applicant's saved data is restored automatically — no OTP step.

The token path is a seamless upgrade on top of the OTP path, not a replacement. If the token is missing, expired, or invalid, the applicant simply falls back to the OTP flow — it is never treated as an error.

Prerequisites

• The Save Progress feature must be enabled for your account. Contact AiPrise to turn it on (this also controls whether the "Save progress" button appears in the onboarding UI).

• You need your AiPrise API key (the same x-api-key you use for other server-to-server calls).

• The verification session must belong to your account.

Step 1 — Mint the token (server-side only)

Call this from your backend, never from the browser — it requires your API key.

GET /v1/verify/get_onboarding_sdk_token/<verification_session_id>
Header: x-api-key: <your API key>

Success (200):

{
  "onboarding_sdk_token": "<JWT>",
  "success": true
}

Errors:

Rate limits: 60/minute, 600/hour, 3,000/day per key.

Step 2 — Pass the token to the AiPrise Web SDK

Requires aiprise-web-sdk v2.1.5 or later.

Both <aiprise-frame> and <aiprise-button> accept the token through the onboarding-session-token attribute. The token is only used when resuming an existing session, so always set it together with session-id (the verification session you minted the token for in Step 1).

HTML / embedded frame:

<aiprise-frame
  mode="PRODUCTION"
  template-id="YOUR_TEMPLATE_ID"
  session-id="VERIFICATION_SESSION_ID"
  onboarding-session-token="TOKEN_FROM_STEP_1"
></aiprise-frame>

Button + modal:

<aiprise-button
  mode="PRODUCTION"
  template-id="YOUR_TEMPLATE_ID"
  session-id="VERIFICATION_SESSION_ID"
  onboarding-session-token="TOKEN_FROM_STEP_1"
></aiprise-button>

Plain JavaScript (dynamic):

// 1. Fetch a fresh token from YOUR backend (which calls
//    /v1/verify/get_onboarding_sdk_token with your API key)
const { onboarding_sdk_token } = await fetch("/your-backend/onboarding-token/" + sessionId)
  .then((res) => res.json());

// 2. Render the frame with both session-id and the token
const frame = document.createElement("aiprise-frame");
frame.setAttribute("mode", "PRODUCTION");
frame.setAttribute("template-id", "YOUR_TEMPLATE_ID");
frame.setAttribute("session-id", sessionId);
frame.setAttribute("onboarding-session-token", onboarding_sdk_token);
document.getElementById("container").appendChild(frame);

In React/Vue, set the same attributes on the custom element (see the framework examples at docs.aiprise.com for general SDK setup).

Good to know:

• Because the token expires after 5 minutes, fetch it from your backend right before rendering the component — not at app startup.

• The SDK passes the token to the hosted verification form in the URL fragment (#session_token=...), so it never appears in query strings, server logs, or referrer headers. The form then presents it to AiPrise as a bearer token.

• If the token is omitted, expired, or invalid, the component still works — the applicant just goes through the email OTP resume flow instead.

• The aiprise:resumed event fires on the component when an existing session is reopened.

Step 3 — What the applicant sees

Nothing else is required from your side. When the form opens with a valid token, AiPrise restores the applicant's saved progress automatically — they land back where they left off, with no OTP step.

Auto-resume happens when all of these hold:

1. The Save Progress feature is enabled for your account.

2. The session actually has saved progress (it isn't the first open).

3. The token is valid, unexpired, and was minted for this session — a token minted for one session can never unlock another.

If any of these fail, the applicant simply sees the email/OTP resume screen instead. Their saved data is never lost — only the shortcut is skipped.

Token properties and rules

• Format: JWT (HS256) with claims company_id, verification_session_id, type, iat, exp.

• Lifetime: 5 minutes. The token only needs to survive the handoff from your backend → frontend → SDK boot, not the whole onboarding flow. Mint a fresh token on every page load; do not cache or store it.

• Scope: read access to exactly one session's saved progress. It is intentionally not interchangeable with any other AiPrise token type.

• Never expose your API key to the browser. Only the minted token goes to the frontend.

Troubleshooting: applicant still sees the OTP screen

In every one of these cases the applicant can still resume via the email OTP flow. If the OTP screen keeps appearing even with a fresh, correctly scoped token, contact AiPrise support with the verification session ID and we can tell you which check failed.