Onboarding (KYC/KYB)

The JavaScript SDK launches the Footprint onboarding flow for KYC (Know Your Customer) and KYB (Know Your Business) from your JavaScript or TypeScript app. By the end, your app opens the flow and receives a validation token when the user completes it.

By default the flow opens in a modal. To embed it in your page instead, see Inline integration.

1. Get an onboarding token. Start the onboarding with POST /onboardings and take the token it returns, such as obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH.

2. Initialize the flow. Trigger Footprint, for example when a button is clicked, and pass the onboardingSessionToken and an onComplete callback to initialize.

javascript
1import "@onefootprint/footprint-js/dist/footprint-js.css";
2import { onboarding } from "@onefootprint/footprint-js";
3
4const App = () => {
5  const launch = () => {
6    onboarding.initialize({
7      onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
8      onComplete: (validationToken) => {
9        console.log(validationToken);
10      },
11    });
12  };
13
14  return (
15    <button type="button" onClick={launch}>Launch Footprint</button>
16  );
17}

3. Handle completion. When the user completes the flow, onComplete receives the validationToken. Post it to your backend for further processing.

A complete example lives in onefootprint/examples.

The SDK fires events as the user acts in the flow. Pass the handlers to initialize (modal) or initializeInline:

typescript
1import { onboarding } from "@onefootprint/footprint-js";
2
3onboarding.initialize({
4  onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
5  onComplete: (validationToken) => {
6    console.log(validationToken);
7  },
8  onError: (error) => {
9    console.log(error);
10  },
11  onAuth: (validationToken) => {
12    console.log(validationToken);
13  },
14  onCancel: () => {
15    console.log("User canceled the flow");
16  },
17  onClose: () => {
18    console.log("User closed the flow");
19  },
20});

Pass onRequirementChange to track the flow's progress from your page, for example to drive your own stepper while the flow runs inline. It fires whenever the requirement being executed changes, and again when the flow moves to a different screen within the same requirement:

typescript
1import { onboarding } from "@onefootprint/footprint-js";
2
3onboarding.initializeInline({
4  onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
5  containerId: "footprint-container",
6  onComplete: (validationToken) => {
7    console.log(validationToken);
8  },
9  onRequirementChange: ({ kind, page }) => {
10    console.log(kind); // e.g. "collect_business_data"
11    console.log(page); // e.g. "business_owners", or undefined
12  },
13});

Possible kind values are collect_business_data, collect_data (personal information), collect_document, liveness (passkey registration), link_bank_account, collect_investor_profile, collect_card_data, collect_custom_data, collect_document_data, confirm_verified_prefill, register_auth_method and process. New kinds may be added over time, so handle unknown values gracefully.

When a requirement spans more than one distinct screen, the payload also carries a page field. Today it is set to business_owners while the beneficial owners screen of collect_business_data is shown, so a stepper can distinguish it from the business details screen of the same requirement. It is omitted everywhere else, and new page values may be added over time.

To embed the flow in your page instead of opening a modal, call initializeInline. It needs a container element in your DOM, where the flow renders:

javascript
1import "@onefootprint/footprint-js/dist/footprint-js.css";
2import { onboarding } from "@onefootprint/footprint-js";
3
4const App = () => {
5  const launchInline = () => {
6    onboarding.initializeInline({
7      onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
8      containerId: "footprint-container",
9      onComplete: (validationToken) => {
10        console.log(validationToken);
11      },
12    });
13  };
14
15  return (
16    <div>
17      <button type="button" onClick={launchInline}>Launch Footprint Inline</button>
18      <div id="footprint-container" style={{ height: '600px', width: '100%' }}></div>
19    </div>
20  );
21}

The inline integration takes the same event handlers and customization options as the modal. Give the container enough height; the recommended minimum is 600px.

Pass an appearance object to initialize (modal) or initializeInline to restyle the flow:

typescript
1import { onboarding } from "@onefootprint/footprint-js";
2
3onboarding.initialize({
4  onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
5  onComplete: (validationToken) => {
6    console.log(validationToken);
7  },
8  appearance: {
9    variables: {
10      borderRadius: "8px",
11      colorSuccess: "#10b981",
12      colorError: "#F87171",
13      buttonPrimaryBg: "#5550e9",
14    },
15  },
16});

The customization guide lists every variable.