---
title: API basics
description: Headers, encryption, request and response formats, and versioning
  shared by every Figure API.
---

## Required request headers

{% callout type="warning" %}
Any request without the required headers will be rejected.
{% /callout %}

Every request needs two headers:

- `apikey`: the API key Figure gives you during onboarding.
- `User-Agent`: identifies your client. Most HTTP clients add it for you.

## Encryption

Some endpoints require an encrypted request body; each endpoint's page in the [API reference](/api) says whether it does. Encrypt request bodies with [Figure's public key](/jwe-data-protection/rsa-secret-exchange).

Responses can be encrypted too: add `X-Encrypt-Response: true` as a request header.
Our team will work with you to exchange PGP keys necessary to encrypt the response.
Webhooks may also use these PGP keys if desired.

See the [JSON Web Encryption (JWE)](/jwe-data-protection/intro) section for more details.

{% callout type="tip" %}
If you are unable to encrypt payloads client-side, you can use Figure's [Encryption API](/jwe-data-protection/encryption-api) to encrypt JSON payloads on your behalf or create a stored payload request with a URL for a customer to be redirected to.
{% /callout %}

## Common request payload
{% callout type="warning" title="Loan originators must be onboarded first" %}
Figure has to onboard each loan originator before you can send requests for them. To onboard one, [contact us](/contact) or email [partner-help@figure.com](mailto:partner-help@figure.com).
{% /callout %}

Many `PUT` and `POST` requests include this common object at the top level of the payload. Each endpoint's request body in the [API reference](/api) shows exactly what it takes.

```json {% title="Common request object" %}
{
  "request": {
    "loanOriginatorUuid": "4f8c2e1a-93b7-4d2c-8a5e-0c1b7e6f2d90"
  }
}
```

The `loanOriginatorUuid` identifies the loan officer to be applied for the request. You must determine and supply the appropriate `loanOriginatorUuid` for the state and situation relevant to each request. This UUID will be predetermined during onboarding into the Figure system (and maintained separately from this API) and can be found in lead portal. If you have more than one loan officer who will be able to make API requests, these UUID values will be different for each loan officer. Also keep in mind that these UUID values will differ between the test and production environments.

{% callout type="tip" %}

In the request examples in these guides, optional fields are highlighted in green. The [API reference](/api) marks required fields instead.

{% /callout %}

Reasons why there may be different loan officer UUIDs may include:
- Different states having different licensed loan officers available.
- Loan officers leaving/joining your company or their licenses changing.

While Figure validates that a valid set of licenses can be applied to the closing documents, it is the partner’s responsibility to provide Figure with the loan officer to be applied.

## Common response format
All responses use the same wrapper. The block below shows its shape, with types in place of values.

```json5 {% title="Response shape (types, not literal values)" %}
{
  "data": { ... }, // Context-specific
  "messages": [
    {
      "level": string,
      "message": string,
    },
  ],
  "appDetails": { ... },
}
```

The `data` field will be context-specific to the endpoint called.

The `messages` field may include information, warnings, or error messages.

The `appDetails` field contains the full details of the app/inquiry. This field will only be populated on the [Inquiry details](/heloc-inquiries/details) endpoint.

## Request/response flow
`PUT` and `POST` requests that start an action may return data right away, and often continue processing in the background. That usually takes a few seconds, but some edge cases take longer, up to about 30 seconds.

There are two ways to find out when it's done:
1. **Recommended:** Figure sends a [webhook](/webhooks) when the inquiry is ready for its next step. It tells you the next action, or that the inquiry has moved to the borrower.
2. Poll [Inquiry details](/heloc-inquiries/details) for the latest state.

## Dollars and rates
All dollar amounts are represented as a decimal number down to the cents, e.g. `99.99`.

All rates are represented as decimal numbers. For example, `0.98765` would represent `98.765%`.

## API versioning
Each endpoint contains a major version code in the URL.

In the case of a new major version, old endpoints will return a deprecation message with any responses.
