Bootstrap data

5 min read

Bootstrap data is data about the user that you already hold and share with Footprint when you create an onboarding session, to shorten the onboarding. The flow prefills it: the user skips the sections you completed and can still edit or correct any value.

Footprint validates bootstrap data with the same validations it applies to user-entered data. A value that fails validation is ignored, and the flow asks the user for it again.

Only fields the playbook collects can be bootstrapped.

Pass bootstrap data

Pass bootstrap data when you create an onboarding session token through the API, so the data is transmitted securely and validated before the user starts the flow. This request creates 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  }'

The Integration Guide covers starting the onboarding and getting an onboarding token.

User fields

These identity fields can be bootstrapped.

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

For a KYB (Know Your Business) onboarding, bootstrap user information and business information together by including both kinds of field in 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.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  }'

Business fields

Alongside the identity fields, a KYB playbook accepts these bootstrap fields.

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

In a KYB playbook, the user who fills out the business information is always considered the first beneficial owner of the business. To prefill the first beneficial owner's attributes, use the id.* fields; to bootstrap their ownership stake, pass business.primary_owner_stake. Provide the remaining beneficial owners as a list in business.secondary_owners.

For example, to bootstrap a business with 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}