API

Getting started

3 min read

Add Footprint.js to your app

  1. Go to the Footprint developer dashboard and create a new Onboarding configuration

    • Select the “standard” list of IDV fields to collect or customize the fields.
    • Select the “standard” list of IDV fields you require access to decrypt.

  2. Grab the Onboarding Publishable Key, for example ob_test_VMooXd04EUlnu3AvMYKjMW.

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

html
<head>
  <link
    rel="stylesheet"
    href="https://unpkg.com/@onefootprint/footprint-js@latest/dist/style.css"
  />
</head>
<body>
  ...
  <script
    crossorigin
    src="https://unpkg.com/@onefootprint/footprint-js/latest"
  ></script>
</body>

or

bash
# With NPM
npm install @onefootprint/footprint-js

# With yarn
yarn add @onefootprint/footprint-js
  1. Embed the Footprint button.
html
<div id="footprint-button" data-public-key="pk_test_yflLnFW219f9bC0pdyGd"></div>
  1. Add your Footprint completion handler
javascript
window.onFootprintCompleted = function (token) {
  // TODO: Post the token to your server
};
  1. To customize the button placement, the easiest way is to wrap the button in a div and apply the styles to this div:
html
<style>
  .container {
    display: flex;
    align-items: center;
    justify-content: center;
    height: 100vh;
  }
</style>

<div class="container">
  <div
    id="footprint-button"
    data-public-key="ob_test_VMooXd04EUlnu3AvMYKjMW"
  ></div>
</div>

Click here to check out a full example.

Verify the Footprint token server-side

Setup and authentication

Go to the Footprint developer dashboard and generate a new Secret API Key. This 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

Validate the onboarding token (from Step 5 above)

You should create an endpoint on your backend to handle signups. It should receive the validation token given in step 5 above from your frontend and pass it to Footprint’s backend in order to authenticate and verify the user:

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

Footprint will give you some information from this onboarding session. We’ll also give you a footprint_user_id, which looks like fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX

json
{
  "data": {
    "footprint_user_id": "fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX",
    "status": "pass",
    "requires_manual_review": false,
    "timestamp": "2022-07-30T05:39:33.723Z",
    "onboarding_configuration_id": "ob_config_id_k5y4WLMfhtlXlGeFpl5tD9KGtjZilNf"
  }
}

Check the onboarding decision status

Using the status and required_manual_review fields to decide whether or not to onboard this user to your product.

StatusReviewWhat does this mean?
passFalseVerification checks succeeded and this user can be onboarded.
passTrueVerification checks succeeded, but Footprint suggests manually reviewing identified risks.
failFalseVerification failed. Do not onboard this user.
failTrueVerification failed, but Footprint suggests manually checking possible acceptance criteria.

Optionally, decrypt identity fields from the user’s vault:

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