Vault fields

9 min read

Footprint validates structured vault fields, such as identity and card data, against a base-level format on write; custom fields accept any JSON value. This page lists every field by namespace, with the format each value must match. Not every field is populated in every vault.

Identity fields

Field Description Format
id.phone_number Primary phone number E.164 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 are stripped
id.ssn4 Last 4 digits of the SSN 4-digit string
id.itin Individual taxpayer identification number 9-digit string beginning with 9; hyphens are stripped
id.dob Date of birth %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 2-character USPS code for US addresses; otherwise any valid UTF-8 string <1KB
id.zip Postal code of the user's street address Postal code ^([A-Za-z0-9- ]*)$
id.country Country of the user's street address Any valid ISO 3166 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 ISO 3166 alpha-2 country code
id.citizenships Countries where the user holds citizenship A list of valid ISO 3166 alpha-2 country codes
id.visa_kind Type of US visa the user holds One of j1, b1, b2, e1, e2, e3, f1, g4, h1b, l1, o1, tn1, or other
id.visa_expiration_date Expiration date of the user's visa %Y-%m-%d

Business fields

Field 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 phone number
business.tin Taxpayer identification number 9-digit string; hyphens are stripped
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 2-character USPS code for US addresses; otherwise any valid UTF-8 string <1KB
business.zip Postal code of the business's street address Postal code ^([A-Za-z0-9- ]*)$
business.country Country of the business's street address Any valid ISO 3166 alpha-2 country code
business.corporation_type 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 Any valid 2-character US state code
business.formation_date Date of formation YYYY-MM-DD

Investor profile fields

Field Description Format
investor_profile.employment_status The user's employment status One of employed, unemployed, student, retired
investor_profile.employer Name of the user's employer, if any Any valid UTF-8 string <1KB
investor_profile.occupation The user's occupation, if any Any valid UTF-8 string <1KB
investor_profile.annual_income 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 The user's net worth One of le50k, gt50k_le100k, gt100k_le200k, gt200k_le500k, gt500k_le1m, gt1m_le5m, or gt5m
investor_profile.funding_sources The user's funding sources One of employment_income, investments, inheritance, business_income, savings, or family
investor_profile.investment_goals 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 Declarations the user makes about themselves An array of affiliated_with_us_broker, senior_executive, or senior_political_figure; empty if none apply
investor_profile.brokerage_firm_employer Name of the brokerage, when declarations include affiliated_with_us_broker Any valid UTF-8 string <1KB
document.finra_compliance_letter Uploaded FINRA compliance document, when declarations include affiliated_with_us_broker PDF document
investor_profile.senior_executive_symbols Symbols of the companies where the user is a senior executive, when declarations include senior_executive An array of symbols, each 3-5 ASCII alphabetic characters
investor_profile.family_member_names Names of the user's immediate family members, when declarations include senior_political_figure An array of names, each a UTF-8 string <1KB
investor_profile.political_organization Name of the political organization, when declarations include senior_political_figure Any valid UTF-8 string <1KB

Document extracted fields

When a user uploads an identity document during onboarding, Footprint attempts to extract these fields from it. Replace * with the document type: id_card, drivers_license, passport, permit, visa, or residence_document. For example, document.drivers_license.document_number is the number on a driver's license.

Field Description Format
document.*.full_name Extracted name Any UTF-8 string <200B
document.*.dob Extracted date of birth %Y-%m-%d
document.*.gender Extracted gender Any UTF-8 string <200B
document.*.full_address Extracted full address Any UTF-8 string <200B
document.*.document_number Extracted document number Any UTF-8 string <200B
document.*.issued_at Date the document was issued %Y-%m-%d
document.*.expires_at Date the document expires %Y-%m-%d
document.*.issuing_state Name of the state that issued the document Any UTF-8 string <200B
document.*.issuing_country Country that issued the document Any valid ISO 3166 alpha-2 country code
document.*.nationality Nationality extracted from the document Any UTF-8 string <200B

Document images

When a document is uploaded during onboarding or vaulted through the API, its images are available under these fields. Replace * with the document type: id_card, drivers_license, passport, permit, visa, or residence_document.

Field Description Format
document.*.front.image Front image of the document Base64 encoded image
document.*.back.image Back image of the document; not every document type has a back Base64 encoded image

Card fields

Your app assigns each card an alias, which replaces * and must match ^([A-Za-z0-9-_]+)$.

Field Description Format
card.*.name Name of the cardholder Any UTF-8 string <200B
card.*.number 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 Verification code of the card Valid 3- or 4-digit numeric code
card.*.expiration Date the card expires MM/YYYY. Accepts as input any of MM/YYYY, MM-YYYY, MM/YY, MM-YY, M/YY, or M-YY, canonicalized to MM/YYYY before vaulting, with MM/YY read as MM/20YY.
card.*.billing_address.zip Billing ZIP code of the card Postal code ^([A-Za-z0-9- ]*)$
card.*.billing_address.country Billing country of the card Any valid ISO 3166 alpha-2 country code
card.*.number_last4 Last 4 digits of the card number; populated by Footprint 4-digit string; read-only
card.*.issuer Issuer of the card; populated by Footprint One of visa, master_card, amex, discover, mir, diners_club, union_pay, jcb, visa_electron, maestro, forbrugsforeningen, dankort, or unknown

Bank account fields

Your app assigns each bank account an alias, which replaces * and must match ^([A-Za-z0-9-_]+)$.

Field Description Format
bank.*.name Name of the bank account Any UTF-8 string <200B
bank.*.account_type Type of the bank account, usually checking or savings Any UTF-8 string <200B
bank.*.account_last4 Last 4 characters or digits of the account Any UTF-8 string <200B
bank.*.ach_routing_number ACH routing number, as a string Any UTF-8 string <200B
bank.*.ach_account_number ACH account number, as a string Any UTF-8 string <200B
bank.*.ach_account_id Identifier of the ACH account Any UTF-8 string <200B
bank.*.institution_id Identifier of the financial institution Any UTF-8 string <200B
bank.*.institution_name Name of the financial institution Any UTF-8 string <200B
bank.*.iban IBAN account number Any UTF-8 string <200B
bank.*.bic BIC bank code Any UTF-8 string <200B
bank.*.owners JSON object describing the owners of the account Any JSON object
bank.*.link_id Link ID, when the account was connected through Bank Account Linking Any UTF-8 string <200B
bank.*.closed Whether the account is closed true or false

Custom fields

Your app names each custom field; the name replaces * and must match ^([A-Za-z0-9-_.]+)$.

Field Description Format
custom.* Any data you choose to store Any JSON value: string, number, list, or object