Get started with KYB

4 min read

By the end, businesses and their beneficial owners onboard through a KYB (Know Your Business) playbook from your app, and your backend exchanges the result for an fp_id and an fp_bid.

Create a playbook

Go to the Playbooks tab in the dashboard and create a playbook, selecting Onboard Businesses.
- Add or remove the nodes that collect the data you need from the business and its beneficial owners, then publish the playbook. Building playbooks walks through the builder.
Copy the playbook key, for example pb_test_VMooXd04EUlnu3AvMYKjMW. You can pass the playbook key directly into the SDK. For more advanced cases, use onboarding sessions to create a session for a specific user of your product, control when users may reonboard onto a playbook, and more.

Add the JavaScript SDK to your app

Install the footprint.js package:

bash
1# With NPM
2npm install @onefootprint/footprint-js
3
4# With yarn
5yarn add @onefootprint/footprint-js

Configure your application's permissions and content security policy to allow the Footprint integration. See Content security policy.

Render Footprint

In your app, initialize Footprint when needed, passing the publicKey and an onComplete callback. Footprint calls onComplete with a validation token that you use to verify the user server-side.

javascript
1import "@onefootprint/footprint-js/dist/footprint-js.css";
2import footprint from "@onefootprint/footprint-js";
3
4const App = () => {
5  const handleClick = () => {
6    const component = footprint.init({
7      kind: "verify",
8      // If using the Playbook key directly:
9      publicKey: "pb_test_VMooXd04EUlnu3AvMYKjMW",
10      // If using onboarding sessions:
11      // authToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
12      bootstrapData: {},
13      onComplete: (validationToken) => {
14        // TODO: Post the token to Footprint server to exchange with Footprint user ID
15      },
16    });
17    component.render();
18  };
19
20  return <button onClick={handleClick}>Verify with Footprint</button>;
21};

Validate the token server-side

Get or create a secret API key on the API keys page of the dashboard. The key looks like sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv. Add it to the credential manager of your server-side app. API authentication covers server-side authentication.

Create an endpoint on your backend to handle signups. It receives the validation token from your frontend's onComplete callback and passes it to Footprint with POST /onboarding/session/validate, which authenticates and verifies the user:

bash
1curl -X POST https://api.onefootprint.com/onboarding/session/validate \
2   -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: \
3   -d '{"validation_token": "vtok_udLaWUxPBo3fss603v8kY8k9ssjboxfwI"}'

Footprint returns information about this onboarding session: an fp_id for the primary beneficial owner of the business (the user who submitted the information), and an fp_bid for the business itself.

json
1{
2  "user": {
3    "fp_id": "fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX",
4    "onboarding_id": "ob_SRFT2a1mN7DAWJ0VPXkiqK",
5    "playbook_key": "pb_test_VMooXd04EUlnu3AvMYKjMW",
6    "requires_manual_review": false,
7    "status": "pass"
8  },
9  "business": {
10    "fp_id": "fp_bid_YuZKhCJb7LAqDYFjfyRulpNfaTnCOCzZ",
11    "onboarding_id": "ob_Y2FsI9culBihE5wBr5Yab7",
12    "playbook_key": "pb_test_VMooXd04EUlnu3AvMYKjMW",
13    "requires_manual_review": false,
14    "status": "pass"
15  },
16  ...
17}

Save both identifiers in your database tied to the user and business. They are the identifiers you send to request any user- or business-specific information.

Check the onboarding status

Your playbook defines the rules that evaluate the user's and business's status and decide whether to flag the user or business for manual review. Use the status and requires_manual_review fields to decide whether to onboard this user and business to your product.

Status	What does this mean?
`pass`	The rules defined on your playbook to verify the user evaluated to an outcome of `pass`.
`fail`	The rules defined on your playbook evaluated to an outcome of `fail`.
`none`	Your playbook has no rules defined.
`pending`	Verifying this user's identity is taking longer than expected. This happens in rare cases where asynchronous actions are required to make a decision. A final decision will be delivered via webhooks to your application.

Review	What does this mean?
False	Your playbook's rules have made a decision automatically.
True	Your playbook's rules have requested that this user is reviewed manually before onboarding.

After onboarding

Once the business has onboarded, you can decrypt fields from the user vault with the fp_id and from the business vault with the fp_bid. Both calls are optional.

Decrypt identity fields from the user vault

bash
1curl -X POST https://api.onefootprint.com/users/fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX/vault/decrypt \
2   -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: \
3   -d '{"fields": ["id.dob", "id.last_name", "id.ssn4"], "reason": "getting started test"}'

json
1{
2  "id.dob": "1988-12-25",
3  "id.last_name": "Doe",
4  "id.ssn4": "1212"
5}

Decrypt business fields from the business vault

bash
1curl -X POST https://api.onefootprint.com/businesses/fp_bid_YuZKhCJb7LAqDYFjfyRulpNfaTnCOCzZ/vault/decrypt \
2   -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: \
3   -d '{"fields": ["business.name", "business.tin"], "reason": "getting started test"}'

json
1{
2  "business.tin": "43-12322342",
3  "business.name": "Acme Inc"
4}

Vault fields lists the fields available for decryption.