Know Your Business (KYB)

1. Go to the Footprint Playbooks tab and create a new Playbook, selecting 'Onboard businesses and their beneficial owners'.

   • On the "Your Playbook" screen, click the edit button to change the fields you plan to collect from beneficial owners and businesses.
   • On the "Authorized scopes" screen, select the fields you require access to decrypt.

2. Grab the Playbook key, for example pb_test_VMooXd04EUlnu3AvMYKjMW. You may pass the Playbook key directly into the SDK. For more advanced use cases, you may use onboarding sessions to create a session for a specific user of your product, control when users are allowed to reonboard onto a playbook, and more.

3. Add the footprint.js script to your app:

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

4. Render Footprint

On your app, initialize Footprint when needed, passing the publicKey and onComplete callback. The onComplete callback will be called with a validation token that you can 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};

Get or create a Secret API Key on your developer dashboard. The key will look something like sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv. Add this to the credential manager of your server-side app. To learn more about server-side API authentication, read the short guide on API Authentication.

You should create an endpoint on your backend to handle signups. It should receive the validation token given in step 4 above from your frontend and pass it to Footprint's backend in order to authenticate and verify the user using the POST /onboarding/session/validate API:

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

Footprint will give you some information from 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}

Your playbook will define a set of rules used to evaluate the user and business's status and to decide whether the user or business should be flagged for manual review. Use the status and requires_manual_review fields to decide whether or not to onboard this user and business to your product.

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}

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}

You can learn more about the fields available for decryption here.