# Onboarding (KYC/KYB)
## Getting started
This guide explains how to integrate the Footprint onboarding flow for KYC (Know Your Customer) and KYB (Know Your Business) into your JavaScript/TypeScript applications.
**Note:** Make sure you have `@onefootprint/footprint-js` version 5.0.0 or higher installed for the onboarding integration to work properly.
The default behavior launches the onboarding flow within a modal. For an inline integration option, see the [Inline Integration](#inline-integration) section below.
1. **Start the onboarding**:
* Start the onboarding and get an onboarding token, e.g., `obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH`, from [POST /onboardings](/articles/guide/definitive-integration-guide#the-end-to-end-integration-step-4-run-the-playbook).
2. **Initialize the Footprint Flow**:
* Trigger Footprint, for example, when a button is clicked. Then, pass the `onboardingSessionToken` and `onComplete` callback to the `initialize` method.
```javascript
import "@onefootprint/footprint-js/dist/footprint-js.css";
import { onboarding } from "@onefootprint/footprint-js";
const App = () => {
const launch = () => {
onboarding.initialize({
onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
onComplete: (validationToken) => {
console.log(validationToken);
},
});
};
return (
);
}
```
3. **Handle Completion:**
* Once the user completes the flow, you'll receive the validationToken through the `onComplete` callback. Post this token to your backend for further processing.
Click [here](https://github.com/onefootprint/examples/tree/master/idv/frontend-vite-vanilla) to check out a full example.
## Listening to events
Footprint provides several events based on actions performed by the user. To listen to events, pass them from either the `initialize` (modal) or `initializeInline` method.
```typescript
import { onboarding } from "@onefootprint/footprint-js";
onboarding.initialize({
onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
onComplete: (validationToken) => {
console.log(validationToken);
},
onError: (error) => {
console.log(error);
},
onAuth: (validationToken) => {
console.log(validationToken);
},
onCancel: () => {
console.log("User canceled the flow");
},
onClose: () => {
console.log("User closed the flow");
},
});
```
## Tracking flow progress
**Note:** The `onRequirementChange` callback is supported from version 5.6.0 onwards.
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
import { onboarding } from "@onefootprint/footprint-js";
onboarding.initializeInline({
onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
containerId: "footprint-container",
onComplete: (validationToken) => {
console.log(validationToken);
},
onRequirementChange: ({ kind, page }) => {
console.log(kind); // e.g. "collect_business_data"
console.log(page); // e.g. "business_owners", or undefined
},
});
```
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.
## Inline Integration
**Note:** The `initializeInline` method is supported from version 5.1.0 onwards.
For use cases where you prefer to embed the onboarding flow directly within your page instead of using a modal, you can use the `initializeInline` method.
**Note:** The inline integration requires a container element in your DOM where the flow will be rendered.
```javascript
import "@onefootprint/footprint-js/dist/footprint-js.css";
import { onboarding } from "@onefootprint/footprint-js";
const App = () => {
const launchInline = () => {
onboarding.initializeInline({
onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
containerId: "footprint-container",
onComplete: (validationToken) => {
console.log(validationToken);
},
});
};
return (
);
}
```
The inline integration supports the same event handlers and customization options as the modal version. Make sure to provide adequate height for the container element (recommended minimum: 600px).
## Setting a custom appearance
You can customize the appearance of the onboarding flow by passing an `appearance` object to either the `initialize` (modal) or `initializeInline` method.
```typescript
import { onboarding } from "@onefootprint/footprint-js";
onboarding.initialize({
onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
onComplete: (validationToken) => {
console.log(validationToken);
},
appearance: {
variables: {
borderRadius: "8px",
colorSuccess: "#10b981",
colorError: "#F87171",
buttonPrimaryBg: "#5550e9",
},
},
});
```
For more information, including a list of available variables, check out the [customization guide](/articles/integrate/customization).
## Available Props
| Variable | Description |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onboardingSessionToken` | The onboarding session token you created. |
| `onComplete` | Triggered after the user completes the onboarding flow. You'll receive a `validationToken` that your backend can exchange with Footprint to see the fp\_id, the login method used, and the KYC status. |
| `onAuth` | Optional. Triggered after the user finishes logging in, before the user has finished fully onboarding. You'll receive a `validationToken` in this callback that your backend can exchange with Footprint to see the fp\_id and the login method used. |
| `onError` | Optional. A function that is called when there was an unrecoverable error while initializing the onboarding flow. It takes in an error string argument with more details. |
| `onCancel` | Triggered when the user abandons the flow. This can be triggered when the user clicks on the close button inside our iframe |
| `onClose` | Triggered when the user closes the flow (either completed or canceled). |
| `onRequirementChange` | Optional. Triggered when the requirement being executed changes. Receives `{ kind, page? }`, so your page can track the flow's progress. |
| `appearance` | Optional. A `FootprintAppearance` object that customizes the look of your integration |
| `l10n` | Optional. Specifies the desired localization. More information [here](/articles/integrate/customization#localization-configuration). |
| `containerId` | Required for inline integration only. The ID of the DOM element where the onboarding flow will be rendered. |