Introduction

Footprint vaults are structured as a key-value store. We define a fixed set of predefined keys that you can use for structured data: like SSN (id.ssn9), address (id.address_line1, id.address_line2, etc), and card number (card.*.number). These fields have validation specific to the type of data that they're storing, allowing you to read and write data to these fields with confidence that the data is in the correct format.

For any other kinds of unstructred data, you may always use custom.* attributes.

You'll find the list of supported structured data keys and their validators here.

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.<key> 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.

Update a user vault

bash
1curl https://api.onefootprint.com/users/fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX/vault \
2    -X PATCH \
3    -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: \
4    -d '{
5            "custom.ach_account": "111122224444",
6            "card.primary.expiration": "10/2025",
7            "card.primary.cvc": "424"
8        }'

Store large objects in a user vault

For custom objects that are larger (up to 10MB), use the POST /users/<fp_id>/vault/<data_identifier>/upload API.

bash
1curl https://api.onefootprint.com/users/fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX/vault/custom.card_transaction_history/upload \
2    -X POST \
3    -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: \
4    --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.

List available data in a user's vault

Check what fields exist on a user's vault.

bash
1curl https://api.onefootprint.com/users/fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX/vault?fields=id.ssn9,custom.ach_account,card.primary.number \
2      -u sk_test_CJvsN1kaZH3GGtYkaZH3GGtY:

json
1{
2  "id.ssn9": true,
3  "custom.ach_account": true,
4  "card.primary.number": true
5}

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
1curl https://api.onefootprint.com/users/fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX/vault/decrypt \
2    -X POST \
3    -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: \
4    -d '{
5            "fields": ["id.last_name", "id.dob", "id.ssn9", "custom.ach_account"],
6            "reason": "direct deposit verification"
7        }'

json
1{
2  "id.last_name": "Doe",
3  "id.dob": "1988-12-25",
4  "id.ssn9": "121211212",
5  "custom.ach_account": "111122224444"
6}

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
1curl https://api.onefootprint.com/users/search -X POST -d '{"search": "Doe"}' \
2      -u sk_test_CJvsN1kaZH3GGtYkaZH3GGtY:

json
1{
2  "data": [
3    {
4      "id": "fp_id_XyEJ6CF7UNl6K2ymIq8YQS"
5    }
6  ],
7  "meta": {
8    "next": null,
9    "count": 1
10  }
11}