Introduction

A Footprint vault is a key-value store for a user's or a business's sensitive data. Footprint defines a fixed set of keys for structured data, such as the SSN (id.ssn9), the address (id.address_line1, id.address_line2, and so on), and the card number (card.*.number). Each of these vault fields is validated against the type of data it holds, so a value you read or write is in the format that field expects.

For any other kind of unstructured data, use custom.* fields.

Vault fields lists every structured key and its validator.

Identity

Identity data collected in an embedded user or business onboarding (KYC or KYB) is verified by Footprint's decisioning platform and then vaulted. Each identity attribute is validated, vaulted, and tokenized, and some attribute types are also fingerprinted so they can be matched. You can also create a standalone identity vault through the API or the Vault Proxy, which is useful when migrating sensitive user data. The APIs are the same however the data arrived. Identity fields use the id. prefix.

Payment cards

Many financial applications collect or store payment card data for the users they onboard, with or without KYC. Footprint vaults cardholder data such as the card number, the expiration date, and the security code (CVV) in a PCI-compliant way. The card APIs are the same as the rest of the vaulting APIs and use the card.* namespace. Unlike identity data, a user can have several cards, so each card gets an alias such as card.primary.*. Like identity data, card data is validated before it is vaulted.

Custom key-value

Custom fields hold data you define, and Footprint does not validate them. In API requests the key is custom.<key>. Use custom fields to vault any other sensitive data about a user or a business through the same vaulting API.

Update a user vault

PATCH /users/<fp_id>/vault writes the fields in the request body to the user's 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 larger custom objects (up to 25MB), use POST /users/<fp_id>/vault/<data_identifier>/upload.

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

Footprint encrypts the raw request body and stores it in the user's vault. Retrieve it with the decrypt call below.

List available data in a user's vault

Check which fields exist in the user's vault. Pass fields to check only some of them.

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

Decryption is per field, and you can scope an API key to groups of fields, such as the full address or the last four digits of the SSN.

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

Search across all of your users' vaults by the fields that are fingerprinted. The search is private and needs no decryption on your side.

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}

Next steps

The full list of fields and their formats is in Vault fields. For a user who did not onboard through Footprint, see Creating new vaults; to vault data straight from a mobile or web app without it passing through your backend, see Client-side vaulting.