Get started with KYC
4 min read
By the end, users verify their identity with a KYC (Know Your Customer) playbook from your app, and your backend exchanges the result for an fp_id.
Create a playbook
Go to the Playbooks tab in the dashboard and create a playbook, selecting Onboard users.
- Add or remove the nodes that collect the data you need, 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:
bash1# With NPM
2npm install @onefootprint/footprint-js
3
4# With yarn
5yarn add @onefootprint/footprint-js
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.
javascript1import "@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_xxx",
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_xxxxx. 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:
bash1curl -X POST https://api.onefootprint.com/onboarding/session/validate \
2 -u sk_test_xxxxx: \
3 -d '{"validation_token": "vtok_udLaWUxPBo3fss603v8kY8k9ssjboxfwI"}'
Footprint returns information about this onboarding session, including a user-specific fp_id that identifies this user across Footprint's APIs.
json1{
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 ...
10}
fp_id in your database tied to the individual user. It is the
identifier you send to request any user-specific information.
Check the onboarding status
Your playbook defines the rules that evaluate the user's status and decide whether to flag the user for manual review. Use the status and requires_manual_review fields to decide whether to onboard this user 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 a user has onboarded onto Footprint, you interact with the user via API using their fp_id. The most common action is to decrypt the user's information. For example:
bash1curl -X POST https://api.onefootprint.com/users/fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX/vault/decrypt \
2 -u sk_test_xxxxx: \
3 -d '{"fields": ["id.dob", "id.last_name", "id.ssn4"], "reason": "getting started"}'
json1{
2 "id.dob": "1988-12-25",
3 "id.last_name": "Doe",
4 "id.ssn4": "1212"
5}
Vault fields lists the fields available for decryption.