Skip to main content

HELOC Inquiries

Welcome to Figures's HELOC Inquiries API guide. This documentation provides all the necessary information for integrating and utilizing our Home Equity Line of Credit (HELOC) API, designed to streamline the inquiry process for partner systems.

note

You must be onboarded before using the API. Please visit the Partner Onboarding Page for more information.

Overview​

The HELOC Inquiries API allows you to initiate and manage HELOC inquiries efficiently. It offers the following capabilities:

  • Start Inquiry: Initiate a HELOC inquiry by submitting applicant and property information. This prefilled data is used to generate potential offers.
  • Generate Offers: Based on the provided data, the system will generate and return a set of offers.
  • Select Offer: Once offers are generated, select an appropriate offer to proceed with the application.
  • Fetch Inquiry Details: Retrieve detailed information about an ongoing or completed inquiry at any point in the process.
  • Resolve Unhappy Paths: Handle various issues such as credit matching, lien verification, and additional income asset submission to ensure smooth processing of the inquiry.

The following sequence diagram illustrates the typical flow of a HELOC inquiry using the API:

HELOC Inquiry Flow​

Webhooks​

See webhooks for information.

Create an Inquiry​

A partner can create an inquiry ( created by a loan officer) to prefill borrower information and potentially test different scenarios before a legal application is started.

Creating an inquiry begins by prefilling some applicant and property information. The system uses this data for further processing before presenting offers to the user.

tip

Fields in the request/response that are colored yellowgreen are optional.

Request:​

This endpoint requires an encrypted payload. The incoming payload should match the following format:

URL
POST https://api.figure.com/products/heloc/v1/inquiry/start
Payload
{
  "encrypted": string // encrypted PII payload
}

When decrypted, the encrypted field of the payload should match the following format:

Decrypted Payload
{
  "request": {
    "loanOriginatorUuid": string,  // UUID format
  },
  "applicant": {
    "name": {
      "firstName": string,
      "lastName": string,
      "prefix": string,
      "middleName": string,
      "suffix": string
    },
    "dob": string,  // YYYY-MM-DD
    "phone": string,
    "email": string,
    "ssn": string,  // nnn-nn-nnnn format
    "homeAddress": {
      "street1": string,
      "street2": string,  // apt # or other street identifier
      "city": string,
      "state": string,  // 2-letter state code
      "zip": string
    },
    "income": {
      "employmentType": string,  // enum EmploymentType
      "grossAnnualIncome": number,
      "otherAnnualIncome": number,
      "annualRetirementIncome": number,
      "annualInvestmentIncome": number,
      "savingsAmount": number,
      "otherAnnualIncome": number
    }
  },
  "property": {
    "address": {
      "street1": string,
      "street2": string,  // apt # or other street identifier
      "city": string,
      "state": string,  // 2-letter state code
      "zip": string
    },
    "occupancyType": string,  // enum OccupancyType
    "propertyType": string,  // enum PropertyType
    "isListedForSale": boolean,
    "borrowerEstimatedValue": number,
    "liens": [
      {
        "originationDate": string,  // YYYY-MM-DD
        "lenderName": string,
        "originalBalance": number,
        "currentBalance": number,
        "monthlyPayment": number
      }
    ]
  },
  "partnerDataRequest": {
    "externalAppId": string,
    "utmParameters": {
      "source": string,
      "medium": string,
      "campaign": string,
      "term": string,
      "content": string
    },
  }
}

The optional partnerDataRequest block can be used to capture partner-specific data for reference on the Figure application. For example, utmParameters can be utilized for tracking marketing campaigns. These will be aggregated in data reports.

Response:​

Payload
{
  "appUuid": string // UUID format
}

The generated inquiry/app UUID will be returned in the contextual data of the response. This UUID will be required when submitting requests to all other endpoints.

At this point, background processing will have started. When the inquiry processing has completed and the next step is ready, the partner will be notified via a webhook (if configured).

Select an Offer​

After creating an inquiry, underwriting and other background processes will run. When processing is complete, the borrower must select an offer to proceed with the application.

Request:​

URL
PUT https://api.figure.com/products/heloc/v1/inquiry/{appUuid}/select-offer
Payload
{
  "request": {
    "loanOriginatorUuid": string,  // UUID format
    "async": boolean
  },
  "offer": {
    "offerUuid": string,  // UUID format
    "selectedOfferAmount": number,
    "selectedDiscounts": [
      string
    ] // partner-specific enum
    "selectedAccountsToPayoff": [string]
  }
}

The offerUuid must match an offer that was previously supplied by a Fetch App/Inquiry Details response.

The selectedDiscounts must match a provided type from the available offers or will be ignored.

The async field is required to be true when selectedAccountsToPayoff is populated. Please note that this will be removed from all requests in a future release and will no longer an option.

The selectedAccountsToPayoff is a list of accountIds which can be found in the Fetch App/Inquiry Details response under the ddpDetails object.

Response:​

No contextual data in the response.

At this point, background processing will have started. When the inquiry processing has completed and the next step is ready, the partner will be notified via a webhook (if configured).

Cancel Inquiry​

If a borrower chooses not to proceed with the HELOC after reviewing the offers or if their financial situation changes, you may want to cancel the inquiry. Please note that once the inquiry has been converted into a full application, it can not be canceled. In such cases, the borrower will need to contact Figure support directly for assistance.

Request:​

URL
PUT https://api.figure.com/products/heloc/v1/inquiry/{appUuid}/cancel
Payload
{
  "request": {
    "loanOriginatorUuid": string,  // UUID format
  }
}

Response:​

No contextual data in the response.

At this point, background processing will have started. When the inquiry processing has completed and the next step is ready, the partner will be notified via a webhook (if configured).

Set Attributions​

Marketing and other external attributions can be set at any time in the flow.

All fields in the attributions request are optional; any fields not specified will remain unchanged from prior values. To un-set an existing attribution, simply provide the key to update set as null.

The API does not require this endpoint to be used; partners may use any of this information to link data with their own systems.

Request:​

URL
PATCH https://api.figure.com/products/heloc/v1/inquiry/{appUuid}/attributions
Payload
{
  "request": {
    "loanOriginatorUuid": string,  // UUID format
  },
  "attributions": {
    "utmParameters": {
      "source": string,
      "medium": string,
      "campaign": string,
      "term": string,
      "content": string,
    },
    "externalReferenceData": {
      "externalApplicationId": string,
      "externalReferenceId": string,
    }
  }
}

Response:​

No contextual data in the response.

Fetch App/Inquiry Details​

See HELOC Details for information.

Get Direct Debt Payoff Offers​

When selecting an offer, a borrower may be presented with Direct Debt Payoff options (if enabled) to directly pay off their liabilities through our flow.

This generates offers given liabilities that want to be paid off are passed in.

You can find the accountIds associated with these liabilities in the Fetch App/Inquiry Details response.

note

If liabilities were marked for payoff during asset depletion and different liabilities want to be selected after receiving offers, there is an opportunity that no offers may be returned in the response. If this occurs, either use one of the existing offers or select different accounts to get off offers for.

Request:​

URL
GET https://api.figure.com/products/heloc/v1/inquiry/{{appUuid}}/direct-debt-payoff-offers?accountId={{listOfAccountIds}}

Examples of what listOfAccountIds could look like:

accountId=acc_YpHcFjTpkbArL,acc_8K4YWpeP4qypX
accountId=acc_YpHcFjTpkbArL

Response:​

Payload
{
  "data": {
    "organization": string,
    "appUuid": string, // UUID format
    "offers": [
      {
        "uuid": string, // UUID format
        "minAmount": number,
        "maxAmount": number,
        "rate": number,
        "primeRate": number,
        "term": number,
        "rateType": string,  // enum OfferRateType
        "originationFeePercent": number,
        "discounts": [
          {
            "type": string,  // partner-specific enum
            "rateDiscountAmount": number
          }
        ]
      }
    ]
  }
}

Handling Unhappy Paths​

There are several possible roadblocks that an inquiry may encounter before being able to generate offers. The following endpoints can be used when indicated to manually resolve various issues.

Multiple Properties​

This unhappy path will be indicated by a NextInquiryStepType=SELECT_PROPERTY.

There are situations where an inquiry was started with an address that was not specific enough. For example, an address for a condo did not include the unit number. The following two endpoints provide a resolution opportunity for when this occurs.

Fetch Matched Properties​

When the next step is SELECT_PROPERTY, use this endpoint to retrieve the list of candidate properties that match the submitted address. If the address is too ambiguous (e.g. a large multi-unit building without a unit number), the service may be unable to return matches and will respond with an error. In that case, restart the inquiry with a more specific address.

Request:​

URL
GET https://api.figure.com/products/heloc/v1/inquiry/{appUuid}/properties

Response:​

Payload
{
  "properties": [
    {
      "id": string, // This is an opaque id used later to select the applicable property
      "address": {
        "street1": string,
        "street2": string,
        "city": string,
        "state": string,  // 2-letter state code
        "zip": string
      },
      "apn": string,
      "longitude": number,
      "latitude": number
    }
    ...
  ],
  "messages": [
    {
      "level": string,
      "message": string
    }
  ]
}
Note

street1 will include the unit number when applicable. Although part of the API spec object, street2 will not be populated by this API.

Select Property​

After determining which property should be used for the inquiry from Fetch Matched Properties, the select property api should be called with the selected property id.

Request:​

URL
PUT https://api.figure.com/products/heloc/v1/inquiry/{appUuid}/select-property
Payload
{
  "request": {
    "loanOriginatorUuid": string,  // UUID format
  },
  "property": {
    "propertyId": string,
  }
}

Response:​

No contextual data in the response.

At this point, background processing will have started. When the inquiry processing has completed and the next step is ready, the partner will be notified via a webhook (if configured).

Submit SSN​

In the initial inquiry creation request, submitting the borrower’s SSN is optional.

However, if we are unable to make a soft credit match to an individual, we may ask for the SSN to help resolve the match. No hard credit pull will be applied at this time.

This unhappy path will be indicated by a NextInquiryStepType=CREDIT_MATCH_REQUIRED.

Request:​

This endpoint requires an encrypted payload. The incoming payload should match the following format:

URL
PUT https://api.figure.com/products/heloc/v1/inquiry/{appUuid}/add-ssn
Payload
{
  "encrypted": string // encrypted PII payload
}

When decrypted, the encrypted field of the payload should match the following format:

Payload
{
  "request": {
    "loanOriginatorUuid": string,  // UUID format
  },
  "applicant": {
    "ssn": string // nnn-nn-nnnn format
  }
}

Response:​

No contextual data in the response.

At this point, background processing will have started. When the inquiry processing has completed and the next step is ready, the partner will be notified via a webhook (if configured).

Credit Frozen​

After submitting the initial inquiry creation request, the applicant's credit may be inaccesible due to frozen credit.

This unhappy path will be indicated by a NextInquiryStepType=UNFREEZE_CREDIT.

Request:​

URL
POST https://api.figure.com/products/heloc/v1/inquiry/{appUuid}/repull-credit
Payload
{
  "request": {
    "loanOriginatorUuid": string,  // UUID format
  }
}

Response:​

No contextual data in the response.

At this point, background processing will have started. When the inquiry processing has completed and the next step is ready, the partner will be notified via a webhook (if configured).

Verify Outstanding Liens​

After submitting the initial inquiry creation request, underwriting may not be able to proceed before resolving potential liens on the property.

Existing liens detected by our system are available from the common Fetch App/Inquiry Details request.

This unhappy path will be indicated by a NextInquiryStepType=LIEN_MATCHING_REQUIRED.

Request:​

URL
PUT https://api.figure.com/products/heloc/v1/inquiry/{appUuid}/verify-liens
Payload
{
  "request": {
    "loanOriginatorUuid": string,  // UUID format
  },
  "liens": [
    {
      "originationDate": string,  // YYYY-MM-DD
      "originalBalance": number,
      "lienUuid": string,  // UUID format
      "lenderName": string,
      "currentBalance": number,
      "monthlyPayment": number
    }
  ]
}

The lienUuid field, if supplied, should match a lien that was previously supplied by a Figure response. Liens manually added do not need to supply a lienUuid.

Response:​

No contextual data in the response.

At this point, background processing will have started. When the inquiry processing has completed and the next step is ready, the partner will be notified via a webhook (if configured).

Add More Income Assets​

warning

This is deprecated, please see the new Asset Depletion section below.

A borrower may not be given offers based on income assets submitted with the initial inquiry creation request.

Previously entered income details are available from the common Fetch App/Inquiry Details request, if not stored on the partner system.

This unhappy path will be indicated by a NextInquiryStepType=MORE_ASSETS_REQUIRED.

Request:​

URL
PUT https://api.figure.com/products/heloc/v1/inquiry/{appUuid}/add-income
Payload
{
  "request": {
    "loanOriginatorUuid": string,  // UUID format
  },
  "income": {
    "employmentType": string, // enum EmploymentType
    "grossAnnualIncome": number,
    "annualRetirementIncome": number,
    "annualInvestmentIncome": number,
    "savingsAmount": number,
    "otherAnnualIncome": number
  }
}

Response:​

No contextual data in the response.

At this point, background processing will have started. When the inquiry processing has completed and the next step is ready, the partner will be notified via a webhook (if configured).

Asset Depletion​

A borrower may not be given offers based on income assets submitted with the initial inquiry creation request.

Selecting one or many of the current liabilities to pay off with the Heloc may also help qualify for offers.

Previously entered income details are available from the common Fetch App/Inquiry Details request, if not stored on the partner system.

This unhappy path will be indicated by a NextInquiryStepType=MORE_ASSETS_REQUIRED.

Request:​

URL
PUT https://api.figure.com/products/heloc/v1/inquiry/{{appUuid}}/asset-depletion
Payload
{
  "request": {
    "loanOriginatorUuid": string,  // UUID format
  },
  "income": {
    "employmentType": string, // enum EmploymentType
    "grossAnnualIncome": number,
    "annualRetirementIncome": number,
    "annualInvestmentIncome": number,
    "savingsAmount": number,
    "otherAnnualIncome": number
  },
  "liabilityPayoff": {
    "selectedAccountsToPayoff": [string]
  },
}

The selectedAccountsToPayoff is a list of accountIds which can be found in the Fetch App/Inquiry Details response under the ddpDetails object.

There is an opportunity to update the selectedAccountsToPayoff again when selecting an offer.

Response:​

No contextual data in the response. At this point, background processing will have started. When the inquiry processing has completed and the next step is ready, the partner will be notified via a webhook (if configured).

Set Estimated Property Value​

A borrower may not be given offers with the initial inquiry creation request if a BPO is required without providing an estimated property value.

This unhappy path will be indicated by a NextInquiryStepType=PROPERTY_VALUE_REQUIRED.

Request:​

URL
PUT https://api.figure.com/products/heloc/v1/inquiry/{appUuid}/add-property-estimate
Payload
{
  "request": {
    "loanOriginatorUuid": string,  // UUID format
  },
  "propertyEstimate": {
    "borrowerEstimatedValue": number
  }
}

Response:​

No contextual data in the response.

At this point, background processing will have started. When the inquiry processing has completed and the next step is ready, the partner will be notified via a webhook (if configured).