|

Docs

Vault fields

9 min read

Footprint's vaulting aims to be flexible while providing base-level validation logic for structured vault data such as Identity or PCI data. Below we outline the allowed data identifiers and any validation rules enforced.

Note that not all fields may be populated in the vault.

Identity fields

Data Identifier 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.itin Individual taxpayer identification number 9-digit string beginning with a 9 (hyphens will be ignored and stripped out)
id.dob Date of birth Formatted as %Y-%m-%d
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 j1, b1, b2, 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 %Y-%m-%d

Business fields

Data Identifier 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.formation_state US State of formation for the Business Any valid 2 Character US State Code
business.formation_date Date of business formation YYYY-MM-DD date format

Investor profile fields

Data Identifier Description Format
investor_profile.employment_status Information on the user's employment status One of employed, unemployed, student, retired
investor_profile.employer The name of the user's employer, if any Any valid UTF-8 string <1KB
investor_profile.occupation The name of the user's occupation, if any Any valid UTF-8 string <1KB
investor_profile.annual_income Information on the user's annual income One of le25k, gt25k_le50k,, gt50k_le100k, gt100k_le200k, gt200k_le300k, gt300k_le500k or gt500k_le1200k
investor_profile.net_worth Information on the user's net worth income One of le50k, gt50k_le100k, gt100k_le200k, gt200k_le500k, gt500k_le1m, gt1m_le5m or gt5m
investor_profile.funding_sources Information on the user's funding sources One of employment_income, investments, inheritance, business_income, savings or family
investor_profile.investment_goals Information on the user's investment goals. List with at least one of growth, income, preserve_capital, speculation, diversification, or other
investor_profile.risk_tolerance The user's stated risk tolerance One of conservative, moderate, aggressive
investor_profile.declarations Self-proclaimed declarations An array of affiliated_with_us_broker, senior_executive or senior_political_figure. May be empty if none apply
investor_profile.brokerage_firm_employer If the user selected affiliated_with_us_broker in declarations, the name of the brokerage Any valid UTF-8 string <1KB
document.finra_compliance_letter If the user selected affiliated_with_us_broker in declarations, the uploaded FINRA compliance document PDF document
investor_profile.senior_executive_symbols If the user selected senior_executive in declarations, the list of associated symbols for which the user is a senior executive An array of symbols, each 3-5 ASCII alphabetic characters
investor_profile.family_member_names If the user selected senior_political_figure in declarations, the names of the user's immediate family members An array of names, each UTF-8 strings <1KB
investor_profile.political_organization If the user selected senior_political_figure in declarations, the name of the political organization Any valid UTF-8 string <1KB

Document extracted fields

If a document is uploaded during onboarding, Footprint will attempt to extract the following fields from respective documents. These extracted fields can be accessed through the document's type, which is one of id_card, drivers_license, passport, permit, visa, or residence_document. For example, document.drivers_license.document_number represents the driver's license document number.

Data Identifier Description Format
document.*.full_name The extracted name Any UTF-8 string <200B
document.*.dob The extracted date of birth Formatted as %Y-%m-%d
document.*.gender The extracted gender Any UTF-8 string <200B
document.*.full_address The extracted full address Any UTF-8 string <200B
document.*.document_number The extracted document number Any UTF-8 string <200B
document.*.issued_at The date on which the document was issued Formatted as %Y-%m-%d
document.*.expires_at The date at which the document expires Formatted as %Y-%m-%d
document.*.issuing_state The name of the state that issued the document Any UTF-8 string <200B
document.*.issuing_country The country that issued the document Any valid ISO3166-alpha-2 Country Code
document.*.nationality The nationality extracted from the document Any UTF-8 string <200B

Document images

If a document is uploaded during onboarding or vaulted via the API, the document images can be accessed via the following data identifiers. Fields can be accessed through the document's type, which is one of id_card, drivers_license, passport, permit, visa, or residence_document

Data Identifier Description Format
document.*.front.image The front image of the document Base64 encoded image
document.*.back.image The back image of the document (note: not all document types have backs) Base64 encoded image

Card fields

Each individual card is assigned an alias by your application. Each card alias must match ^([A-Za-z0-9-_]+)$.

Data Identifier Description Format
card.*.name The name of the cardholder Any UTF-8 string <200B
card.*.number The full card number Valid credit or debit card number (length and Luhn check). Supports Visa, Mastercard, Amex, MIR, Diners Club, Discover, UnionPay, JCB, Visa Electron, Maestro, Forbrugsforeningen, Dankort.
card.*.cvc The verification code for the credit card Valid 3- or 4-digit numeric code
card.*.expiration The date at which the card expires MM/YYYY. Accepts as input any of MM/YYYY, MM-YYYY, MM/YY, MM-YY, M/YY, or M-YY, and canonicalized as MM/YYYY before vaulting, with MM/YY interpreted as MM/20YY.
card.*.billing_address.zip The billing ZIP code for the card Postal code ^([A-Za-z0-9- ]*)$
card.*.billing_address.country The billing country for the card Any valid ISO3166-alpha-2 Country Code
card.*.number_last4 The last four digits of the card number. Automatically populated 4-digit string. Cannot be specified, can only be read.
card.*.issuer The issuer of the card. Automatically populated One of visa, master_card, amex, discover, mir, diners_club, union_pay, jcb, visa_electron, maestro, forbrugsforeningen, dankort, or unknown

Bank account fields

Each individual bank account is assigned an alias by your application. Each bank alias must match ^([A-Za-z0-9-_]+)$.

Data Identifier Description Format
bank.*.name The name of the bank account Any UTF-8 string <200B
bank.*.account_type The type of the bank account; usually 'checking or 'savings' Any UTF-8 string <200B
bank.*.account_last4 The last four characters/digits of the account Any UTF-8 string <200B
bank.*.ach_routing_number The ACH routing number as a string Any UTF-8 string <200B
bank.*.ach_account_number The ACH account number as a string Any UTF-8 string <200B
bank.*.ach_account_id The identifier of the ach account Any UTF-8 string <200B
bank.*.institution_id The identifier of the financial institution Any UTF-8 string <200B
bank.*.institution_name The name of the financial institution Any UTF-8 string <200B
bank.*.iban The IBAN account number Any UTF-8 string <200B
bank.*.bic The BIC bank code Any UTF-8 string <200B
bank.*.owners An JSON object representing the owners on the account Any JSON object
bank.*.link_id The corresponding link id if this account was connected via BAL Any UTF-8 string <200B
bank.*.closed Boolean string representing if this account is open or closed 'true' or 'false

Custom fields

Each piece of custom data is assigned an alias by your application. Each custom data alias must match ^([A-Za-z0-9-_.]+)$.

Data Identifier Description Format
custom.* Any piece of data you'd like to provide. Any UTF-8 string. Note that custom field name represented by * can be any UTF-8 string matching ^([A-Za-z0-9-_.]+)$.