Introduction

Use the Footprint API to work with the users who have onboarded onto your product.

The API has resource-oriented URLs. Most endpoints accept JSON-encoded request bodies and return JSON-encoded responses, and the API uses standard HTTP response codes, authentication, and verbs.

You can call the Footprint API in sandbox mode, which doesn't affect your live data, incur costs, or contact production identity verification vendors. The API key you authenticate with determines whether a request runs in sandbox or live mode.

The Footprint API can differ from one account to another as Footprint releases new versions and tailors functionality. Log in to see the documentation for your account.

Base URL
1https://api.onefootprint.com

Authentication

The Footprint API authenticates requests with API keys. View and manage your API keys in the developer dashboard.

You have separate API keys for sandbox and live. Each key only accesses its own environment, and sandbox keys are safe to use in development. The prefix tells you which environment a key belongs to:

  • sk_test: Sandbox API keys. Requests made with these keys incur no costs.
  • sk_live: Production API keys.

Your backend authenticates each request to the Footprint API with the X-Footprint-Secret-Key header, whose value is an API key from the developer dashboard.

HTTP Basic authentication
1curl https://api.onefootprint.com/users \
2  -u sk_test_xxxxx:
3# The colon prevents curl from asking for a password.

Header authentication
1curl https://api.onefootprint.com/users \
2  -H "X-Footprint-Secret-Key: sk_test_xxxxx"
3# Alternatively, you may provide the X-Footprint-Secret-Key header

Errors

Footprint uses conventional HTTP response codes to signal whether an API request succeeded. Codes in the 2xx range mean the request succeeded. Codes in the 4xx range mean the request failed because of the information provided (for example, a required parameter was missing or a parameter was invalid). Codes in the 5xx range mean something went wrong on Footprint's servers; these are rare.

Some 4xx errors that your code can handle include an error code and an optional context that describe the error.

Error responses

code·

optional string

For some errors that can be handled programatically, a short string indicating the error reported.
context·

optional object

For some errors that can be handled programatically, an optional object with relevant context.
message·

string

Human-readable description of the error.
HTTP status code Summary Description
200 OK Everything worked as expected.
400 Bad request The request was unacceptable, perhaps due to a missing required parameter or invalid parameter value.
401 Unauthorized The API key provided is invalid.
403 Forbidden The API key provided doesn't have permission to access the resource.
404 Not found The requested resource does not exist.
409 Conflict The request conflicts with another request (perhaps due to using the same idempotency key).
500, 502, 503, 504 Server error Something went wrong on Footprint's end. (These are rare)

External IDs

Footprint assigns every user, business, and onboarding a Footprint-generated ID (fp_id_..., fp_bid_..., and ob_..., respectively). You can track these resources with your own identifier from your database by supplying it at creation time as an external_id, user_external_id, or onboarding_external_id. This also helps guarantee that you create, for example, only one user in Footprint for each user in your database.

Any API path that accepts one of these resource IDs also accepts the corresponding external ID, prefixed with ext_id:. The prefix tells the API to resolve the value as an external ID within your organization rather than as a Footprint ID. External IDs must be unique within your organization.

Only users, businesses, and onboardings support the ext_id: prefix. Other path parameters, such as document, annotation, or rule-set-result IDs, must be Footprint IDs.

Example External ID usage
1# Retrieve a user by Footprint ID
2GET /users/fp_id_LTBHFU5Z4jQmSsltuNtqCU
3
4# ...or by external ID
5GET /users/ext_id:my_user_42
6
7# Retrieve a business
8GET /businesses/fp_bid_fr7JHcV3hIzC7KbqTAsD3n
9GET /businesses/ext_id:my_biz_42
10
11# Retrieve an onboarding — both path params accept ext_id:
12GET /users/fp_id_LTBHFU5Z4jQmSsltuNtqCU/onboardings/ob_abVwQ7Mqj8EER1TP8XC4J2
13GET /users/ext_id:my_user_42/onboardings/ext_id:signup_2026_q1