Footprint vaults store three types of data: identity data, payment card data, and custom key-value data. ### Identity Identity data that originates from user and business embedded onboarding flows (KYC and KYB) is verified with our decisioning platform and then vaulted. Identity data is comprised of specific attributes that are validated, vaulted, tokenized, and in some attribute types fingerprinted to become matchable. Identity vaults can also be standalone and provisioned via API or vault-proxy, which can be useful when migrating sensitive user data. Regardless of origination, the APIs are identical to provide unified secure PII vaulting. PII reserves the namespace of vault data identifiers prefixed with `id.` ### Payment Cards In many financial applications, it's required to collect or store payment card data associated with users that your onboard (KYC or not). Footprint provides a PCI-compliant vaulting solution for payment card holder data like: card number, expiration authorization/security code (CVV), and more. The payment card vaulting APIs are consistent with all Footprint vaulting APIs and reserve a specific namespace of vault data identifiers: `card.`. Unlike identity data, users may have multiple cards, so you can give each card type an alias namespace such as `card.primary.`. Like identity data, card data is validated prior to vaulting. ### Custom Key-Value Footprint also supports custom key-value attributes that are provided by you and are not validated. Unstructured data are keyed by the format: `custom.` in Footprint’s API requests. You can use custom data to **securely vault** any associated sensitive user or businesses in the vault using a unified vaulting API. ### Setup and authentication Please ensure you are familiar with our [server-side API authentication guide](/integrate/api-auth) to securely connect to the Footprint API from your backend. ### Update a user vault ```bash curl https://api.onefootprint.com/users/fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX/vault \ -X PATCH \ -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: \ -d '{ "custom.ach_account": "111122224444", "card.primary.expiration": "10/2025", "card.primary.cvc": "424" }' ``` This endpoint has a JSON body limit of 32KB. ### Store large objects in a user vault For custom objects that are larger (up to 10MB), use the `POST /users//vault//upload` API. ```bash curl https://api.onefootprint.com/users/fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX/vault/custom.card_transaction_history/upload \ -X POST \ -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: \ --data-binary @transactions.csv ``` The raw contents of body will be encrypted and stored in the user vault. Use the same decrypt method as defined below to retrieve the contents. Note that upon decryption, the raw contents of the large object are `base64` encoded. Note, multipart uploads for even larger objects are coming soon! ## List available data in a user's vault Check what fields exist on a user's vault. ```bash curl https://api.onefootprint.com/users/fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX/vault?fields=id.ssn9,custom.ach_account,card.primary.number \ -u sk_test_CJvsN1kaZH3GGtYkaZH3GGtY: ``` ```json { "id.ssn9": true, "custom.ach_account": true, "card.primary.number": true } ``` ## Decrypt data from a user's vault Footprint’s API provides attribute-level decryption. API keys are configurable to have certain attribute-level scopes. ```bash curl https://api.onefootprint.com/users/fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX/vault/decrypt \ -X POST \ -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: \ -d '{ "fields": ["id.last_name", "id.dob", "id.ssn9", "custom.ach_account"], "reason": "direct deposit verification" }' ``` ```json { "id.last_name": "Doe", "id.dob": "1988-12-25", "id.ssn9": "121211212", "custom.ach_account": "111122224444" } ``` ## Search across users' vaults Footprint lets you search across all of your users' vaults by specific fields that are fingerprinted. This lets you easily search across all of your users vaults privately without building complicated decryption procedures. ```bash curl https://api.onefootprint.com/users?search=Doe \ -u sk_test_CJvsN1kaZH3GGtYkaZH3GGtY: ``` ```json { "data": [ { "id": "fp_id_XyEJ6CF7UNl6K2ymIq8YQS" } ], "meta": { "next": null, "count": 1 } } ``` ## Create "Standalone" user vaults In some circumstances, you may need to vault PII user data for users that did not onboard through Footprint's KYC/IDV flow. In this case, Footprint supports the concept of "Standalone" user vaults. Standalone Footprint user vaults can store two types of data attributes: structured and unstructured. Structured data are first-class attributes that Footprint automatically validates, tokenizes, and in some cases fingerprints to make searchable. Unstructured data are custom key-value attributes that are provided by you and are not validated. Unstructured data are keyed by the format: `custom.` in Footprint’s API requests. The first step is to create a new vault for one of your users. ```bash curl https://api.onefootprint.com/users \ -X POST \ -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: ``` ```json { "id": "fp_id_K0q6Eh6Rr3WOOfFBLPiHsr" } ``` Save this `id` and associate it with the corresponding user in your database. ### Initial data If you have initial data to seed in the vault, you may provide it in the HTTP body: ```bash curl https://api.onefootprint.com/users \ -X POST \ -d '{ "id.first_name": "Jane", "id.last_name": "Joe", "id.dob": "1988-12-30", "id.ssn9": "12-121-1212", "custom.ach_account": "111122224444" }' \ -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: ``` ```json { "id": "fp_id_K0q6Eh6Rr3WOOfFBLPiHsr" } ``` ### Idempotency ID To safely support retrying this `POST /user` request without creating a second user, we support an `x-idempotency-id` header. Requests made with the same `x-idempotency-id` value will no-op and return the same `fp_id`. If you are creating a user vault in Footprint for an existing user record in your database, we recommend using your user record's unique ID as the `x-idempotency-id` to guarantee that only one Footprint user vault is ever created per user. Note, when using `x-idempotency-id`, you are not able to provide initial data in the HTTP body. ```bash curl https://api.onefootprint.com/users \ -X POST \ -H 'x-idempotency-id: my_user_id_1234' -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: ``` ```json { "id": "fp_id_K0q6Eh6Rr3WOOfFBLPiHsr" } ``` This value is safe to store in plaintext! ### Update a standalone user vault With the `id` given from creating a user, you may always update and add new data to your standalone vaults: ```bash curl https://api.onefootprint.com/users/fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX/vault \ -X PATCH \ -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: \ -d '{ "id.email": "jane@acmebank.com", "custom.ach_account": "111122224444" }' ``` For listing, decrypting, and updating -- all the APIs above are identical for standalone user vaults. ## Vault fields 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](https://www.twilio.com/docs/glossary/what-e164) formatted phone number | | `id.email` | Primary email address | [Email address](https://datatracker.ietf.org/doc/html/rfc3696) | | `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 `%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 | 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](https://datahub.io/core/country-codes) | | `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](https://datahub.io/core/country-codes) | | `id.citizenships` | A list of countries for which the user holds citizenship | A list of valid [ISO3166-alpha-2 Country Codes](https://datahub.io/core/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 `%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](https://www.twilio.com/docs/glossary/what-e164) 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 | 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](https://datahub.io/core/country-codes) | | `business.beneficial_owners` | Information about owners of the business. Available when not KYC-ing every businss owner | An array of objects with `first_name` (string), `last_name` (string), and `ownership_stake` (numeric > 0) fields | | `business.kyced_beneficial_owners` | Information about owners of the business. Available when KYC-ing every businss owner | An array of objects with `first_name` (string), `last_name` (string), `email` (string), `phone_number` (string), and `ownership_stake` (numeric > 0) fields. Email and phone will be absent for the first business owner | | `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` | ### 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.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 extracted 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 the country that issued the document | Any valid [ISO3166-alpha-2 Country Code](https://datahub.io/core/country-codes) | | `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 any of `MM/YYYY`, `MM/YY`, `MM-YY`, or `MM-YYYY` | | `card.*.billing_address.zip` | The billing ZIP code for the card | Postal code `^([A-Za-z0-9\- ]*)$` | | `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` | ### 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\-_\.]+)$`. |