Vault PII, PCI, and more

Footprint vaults store three types of data: identity data, payment card data, and custom key-value data.

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.

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.

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.

Please ensure you are familiar with our server-side API authentication guide to securely connect to the Footprint API from your backend.

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"
        }'

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
}

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": "Smith",
  "id.dob": "1988-12-25",
  "id.ssn9": "121211212",
  "custom.ach_account": "111122224444"
}

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=Smith \
      -u sk_test_CJvsN1kaZH3GGtYkaZH3GGtY:

json
{
  "data": [
    {
      "id": "fp_id_XyEJ6CF7UNl6K2ymIq8YQS"
    }
  ],
  "meta": {
    "next": null,
    "count": 1
  }
}

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.<key> in Footprint’s API requests.

The first step is to create a new vault for one of your users. You may optionally initialize it with any data you already have for the user:

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"
}

Save this id and associate it with the corresponding user in your database.

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.