Getting Started

Making Requests with Required Headers

warning

Each request must have an API key supplied and a User-Agent or the request will be rejected.

Specify your API key in the apikey header of your request.

It is also necessary to set a User-Agent header for your requests, if it is missing. Many web clients will automatically add this.

Common Request Payload

Each PUT/POST request has a common object that must be supplied with at the top level of the request payload:

Common Request Format

{
  "request": {
    "loanOriginatorUuid": string, // UUID format
    "async": boolean, // default: false
  }
}

The loanOriginatorUuid is the UUID of the loan originator (loan officer) making the request. This UUID will be predetermined during onboarding into the Figure system (and maintained separately from this API). 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.

tip

Optional fields in request payloads will be highlighted in green.

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.

The optional async field determines how the system will respond to the request. (See the Request/Response Flow (Sync vs Async) section.)

Common Response Format

All responses will be returned in a common wrapper format.

Common Response Format

{
  "data": { ... }, // Context-specific
  "messages": [
    {
      "level": string,
      "message": string,
    },
  ],
  "appDetails": { ... },  // async=false requests only
}

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 synchronous requests. (See the Request/Response Flow (Sync vs Async) section.)

Request/Response Flow (Sync vs Async)

PUT/POST requests intended to drive an action may return contextual data. Often, background processing will take place that may cause timeouts on a request.

Most requests will resolve within a few seconds, but when certain edge cases are encountered, requests may take longer (potentially, up to 30 seconds).

There are two ways to resolve this:

1. Specify a sync request (the default) and wait for the response; if the response times out, you can poll the Fetch App/Inquiry Details endpoint for the updated info. (You may need to compare against previously polled requests to detect the changes.)
2. Specify an async request and Figure will notify the partner via a webhook when ready to proceed. Webhook responses will specify the next action to take, along with the corresponding endpoint to proceed.

Both sync and async requests can be supported.

Encryption

warning

Some request payloads require encryption of PII. Unencrypted requests will be rejected.

See the JSON Web Encryption (JWE) section for more details. Our team will work with you to exchange encryption keys.

Our sandbox environment supports both encrypted and non-encrypted requests, for ease of testing, but our production environment strictly prohibits unencrypted requests.

tip

All payload requests can optionally be encrypted, even where not required.

In addition, API responses can be encrypted by the same public PGP key, by applying a header of X-Encrypt-Response with value of true.

Dollars and Rates

All dollar amounts are represented as a decimal number down to the cents.

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.