Use the PII Vault

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

Footprint user vaults store two types of data: identity data and custom key-values. Identity data comes from user onboardings is verified with our verification and decisioning platform. Identity data is comprised of first-class attributes that are validated, vaulted, tokenized, and in some cases fingerprinted to make searchable.

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 PII information on your users using our simple APIs.

bash
curl https://api.onefootprint.com/users/fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX/vault \
    -X PUT \
    -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: \
    -d '{
            "custom.ach_account": "111122224444",
            "custom.cc4": "4242"
        }'

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

json
{
  "id.ssn9": true,
  "custom.ach_account": 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 -X POST https://api.onefootprint.com/users?fingerprint=10014 \
      -u sk_test_CJvsN1kaZH3GGtYkaZH3GGtY:

json
{
  "data": [
    {
      "footprint_user_id": "fp_id_XyEJ6CF7UNl6K2ymIq8YQS",
      "start_timestamp": "2022-08-26T17:19:55.048883Z",
      "is_portable": false
    }
  ],
  "meta": {
    "next": null,
    "count": 1
  }
}

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
{
  "footprint_user_id": "fp_id_K0q6Eh6Rr3WOOfFBLPiHsr",
  "start_timestamp": "2022-08-26T14:05:35.200031Z",
  "is_portable": false
}

Save this footprint_user_id, associate it with the corresponding user in your database.

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.

bash
curl https://api.onefootprint.com/users/fp_id_GSxJr68GAf5jUT3pdL9ndjf7TLkA3GCX/vault \
    -X PUT \
    -u sk_test_CXUsbCR8j2kH6e5GeEl8eSBnQTIPCUaKpv: \
    -d '{
            "id.first_name": "Jane",
            "id.last_name": "Joe"
            "id.dob": "1988-12-30",
            "id.ssn9": "12-121-1212",
            "custom.ach_account": "111122224444",
            "custom.cc4": "4242"
        }'

For listing, decrypting, and updating -- all the APIs above are identical for standalone user vaults.