Bootstrapping data

6 min read

Introduction

If you already have certain data about your user, you can share it with Footprint to expedite the onboarding process. This data will be pre-filled in the onboarding flow, allowing users to skip completed sections while still being able to edit and correct the information as needed.

Bootstrap data will be validated using the same validations applied to user-entered data. Any bootstrap data that fails validation will be ignored and the user will be asked to re-provide the value.

Note that only data fields that are collected by the provided playbook may be provided as bootstrap data.

How to pass bootstrap data

Bootstrap data is passed when you create an onboarding session token via the API. This ensures that the data is securely transmitted and validated before the user begins the onboarding flow.

Example API call

Here's how to create an onboarding session with bootstrap data:

bash
1curl -X POST https://api.onefootprint.com/onboarding/session \
2  -H 'X-Footprint-Secret-Key: <SECRET_API_KEY>' \
3  -d \
4  '{
5    "bootstrap_data": {
6      "id.email": "jane.doe@acme.com",
7      "id.phone_number": "+1 (555) 555-0100",
8      "id.first_name": "Jane",
9      "id.last_name": "Doe",
10      "id.dob": "2000-01-01",
11      "id.address_line1": "1 Main St",
12      "id.city": "San Francisco",
13      "id.state": "CA",
14      "id.zip": "11111",
15      "id.country": "US",
16      "id.ssn9": "123-45-6789"
17    },
18    "kind": "onboard",
19    "key": "<PLAYBOOK_KEY>",
20    "user_external_id": "12345678901"
21  }'

For more details on starting the onboarding and getting an onboarding token, see the definitive integration guide.

Available user data

The following identity fields are available to bootstrap.

Note, any bootstrap attributes that fail validation or are not collected by the provided playbook will be ignored.

Variable	Description	Format
`id.phone_number`	Primary phone number	E.164 formatted phone number
`id.email`	Primary email address	Email address
`id.first_name`	First name	Any valid UTF-8 string <1KB
`id.middle_name`	Middle name	Any valid UTF-8 string <1KB
`id.last_name`	Last name	Any valid UTF-8 string <1KB
`id.ssn9`	Full SSN	9-digit string (hyphens will be ignored and stripped out)
`id.ssn4`	Last four of the SSN	4-digit string
`id.dob`	Date of birth	Formatted as `YYYY-MM-DD`
`id.address_line1`	First line of the user's street address	Any valid UTF-8 string <1KB
`id.address_line2`	Second line of the user's street address	Any valid UTF-8 string <1KB
`id.city`	City of the user's street address	Any valid UTF-8 string <1KB
`id.state`	State of the user's street address	For US addresses, 2-character USPS format. Otherwise, any valid UTF-8 string <1KB
`id.zip`	Postal code for the user's street address	Postal code `^([A-Za-z0-9- ]*)$`
`id.country`	Country for the user's street address	Any valid ISO3166-alpha-2 Country Code
`id.us_legal_status`	The user's legal status in the US	`citizen`, `permanent_resident`, or `visa`
`id.nationality`	The user's nationality	Any valid ISO3166-alpha-2 Country Code
`id.citizenships`	A list of countries for which the user holds citizenship	A list of valid ISO3166-alpha-2 Country Codes
`id.visa_kind`	The type of US visa held by the user	One of `e1`, `e2`, `e3`, `f1`, `g4`, `h1b`, `l1`, `o1`, `tn1`, or `other`
`id.visa_expiration_date`	The expiration date of the user's visa	Formatted as `YYYY-MM-DD`

Bootstrapping KYB data

When initiating a KYB flow, you can bootstrap both any precollected user information and precollected business information by including both types of fields in the bootstrap_data object.

Example KYB API call

bash
1curl -X POST https://api.onefootprint.com/onboarding/session \
2  -H 'X-Footprint-Secret-Key: <SECRET_API_KEY>' \
3  -d \
4  '{
5    "bootstrap_data": {
6      "id.first_name": "Jane",
7      "id.last_name": "Doe",
8      "id.dob": "2001-12-30",
9      "id.ssn9": "123456789",
10      "business.name": "Acme Bank",
11      "business.dba": "Acme",
12      "business.tin": "12-3456789",
13      "business.website": "www.google.com",
14      "business.phone_number": "+12025550179",
15      "business.address_line1": "123 Main St",
16      "business.address_line2": "Apt 123",
17      "business.city": "Boston",
18      "business.state": "MA",
19      "business.zip": "02117",
20      "business.country": "US",
21      "business.corporation_type": "c_corporation"
22    },
23    "kind": "onboard",
24    "key": "<PLAYBOOK_KEY>",
25    "user_external_id": "12345678901"
26  }'

Available business data

In addition to all of the identity fields, you may also provide the following bootstrap fields when onboarding onto a KYB playbook.

Note, any bootstrap attributes that fail validation or are not collected by the provided playbook will be ignored.

Variable	Description	Format
`business.name`	Name of the business	Any valid UTF-8 string <1KB
`business.dba`	Doing-business-as alias	Any valid UTF-8 string <1KB
`business.website`	Website of the business	A valid absolute URL.
`business.phone_number`	Phone number	E.164 formatted phone number
`business.tin`	Taxpayer identification number	9-digit string (hyphens will be ignored and stripped out)
`business.address_line1`	First line of the business's street address	Any valid UTF-8 string <1KB
`business.address_line2`	Second line of the business's street address	Any valid UTF-8 string <1KB
`business.city`	City of the business's street address	Any valid UTF-8 string <1KB
`business.state`	State of the business's street address	For US addresses, 2-character USPS format. Otherwise, any valid UTF-8 string <1KB
`business.zip`	Postal code for the business's street address	Postal code `^([A-Za-z0-9- ]*)$`
`business.country`	Country for the business's street address	Any valid ISO3166-alpha-2 Country Code
`business.corporation_type`	The type of corporation	One of `c_corporation`, `s_corporation`, `b_corporation`, `llc`, `llp`, `partnership`, `sole_proprietorship`, `non_profit`, `unknown`, `trust`, `agent`
`business.primary_owner_stake`	The ownership stake of the primary beneficial owner. The remaining info for the primary owner is specified in the `id.*` attributes	Integer between 0-100
`business.secondary_owners`	A list of the other beneficial owners of the business.	An array of objects with `first_name` (string), `last_name` (string), `email` (email address string), `phone_number` (E.164 string), and `ownership_stake` (integer between 0-100) fields

Beneficial owners

When filling out a KYB playbook, the initial user who fills out the business information is always considered the first beneficial owner of the business. If you'd like to prefill any of the first beneficial owner's attributes, use the id.* attributes. To bootstrap the primary owner's ownership stake, pass in business.primary_owner_stake.

Remaining beneficial owners' information may be provided as a list of business.secondary_owners.

For example, to bootstrap information on a business that has two beneficial owners:

json
1{
2  "bootstrap_data": {
3    "id.first_name": "Primary",
4    "id.last_name": "Owner",
5    "business.primary_owner_stake": 50,
6    "business.secondary_owners": [
7      {
8        "first_name": "Secondary",
9        "last_name": "Owner",
10        "ownership_stake": 40
11      }
12    ]
13  }
14}