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.

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​

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.

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
    "async": boolean  // default: false
  },
  "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
    }
  },
  "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.

Depending on the value of the async parameter of the request:

  • async: false - The appDetails section of the response will be populated with the corresponding data from the * Fetch App/Inquiry Details* endpoint.
  • async: true - At this point, background processing will have started and the appDetails section of the response will not be populated. When the inquiry processing has completed and the next step is ready, the partner will be notified via a webhook.

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  // default: false
  },
  "offer": {
    "offerUuid": string,  // UUID format
    "selectedOfferAmount": number,
    "selectedDiscounts": [
      string
    ] // partner-specific enum
  }
}

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.

Response:​

No contextual data in the response.

Depending on the value of the async parameter of the request:

  • async: false - The appDetails section of the response will be populated with the corresponding data from the * Fetch App/Inquiry Details* request.
  • async: true - At this point, background processing will have started and the appDetails section of the response will not be populated. When the inquiry processing has completed and the next step is ready, the partner will be notified via a webhook.

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
    "async": boolean  // default: false
  }
}

Response:​

No contextual data in the response.

Depending on the value of the async parameter of the request:

  • async: false - The appDetails section of the response will be populated with the corresponding data from the * Fetch App/Inquiry Details* request.
  • async: true - At this point, background processing will have started and the appDetails section of the response will not be populated. When the inquiry cancelation has completed, the partner will be notified via a webhook.

Fetch App/Inquiry Details​

Anywhere in the flow of an inquiry or app, the existing details can be fetched for processing or display.

Any of these fields may be null, depending on whether data is yet available.

Additionally, the app/inquiry details are returned as a response to other requests when synchronous requests are made.

Request:​

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

Response:​

Payload
{
  "appUuid": string,  // UUID format
  "appShortId": string,  // User-friendly ID
  "borrowerAppLink": string,
  "appData": {
    "status": string,
    "overallStatus": string,
    "nextInquiryStep": string,  // enum NextInquiryStepType
    "keyDates": {
      "createdDate": string,  // YYYY-MM-DD format
      "expirationDate": string,  // YYYY-MM-DD format
      "recissionEndDate": string,  // YYYY-MM-DD format
      "signingDate": string,  // YYYY-MM-DD format
      "completedDate": string,  // YYYY-MM-DD format
      "canceledDate": string,  // YYYY-MM-DD format
      "declinedDate": string // YYYY-MM-DD format
    },
    "propertyAddress": {
      "street1": string,
      "street2": string,  // apt # or other street identifier
      "city": string,
      "state": string,  // 2-letter state code
      "zip": string
    },
    "statusReasons": [
      string
    ],
    "ownershipType": string,  // enum OwnershipType
    "financingPurpose": string,  // enum FinancingPurposeType
    "propertyLiens": [
      {
        "lienUuid": string,  // UUID format
        "originationDate": string,  // YYYY-MM-DD
        "lenderName": string,
        "originalBalance": number,
        "currentBalance": number,
        "monthlyPayment": number
      },
      ...
    ],
    "underwriting": {
      "decision": string,
      "minOfferAmount": number,
      "maxOfferAmount": number,
      "offers": [
        {
          "uuid": string,  // UUID format
          "minAmount": number,
          "maxAmount": number,
          "rate": number,
          "primeRate": number,
          "term": number,
          "rateType": string,  // enum OfferRateType
          "originationFeePercent": number,
          "discountList": [
            {
              "type": string,  // partner-specific enum
              "rateDiscountAmount": number
            }
          ]
        },
        ...
      ],
      "selectedOffer": {
        "offerUuid": string,  // UUID format
        "loanAmount": number,
        "drawAmount": number,
        "estimatedMonthlyPayment": number,
        "rate": number,
        "primeRate": number,
        "term": number,
        "rateType": string,  // enum OfferRateType
        "originationFeePercent": number,
        "selectedDiscounts": [
          {
            "type": string,  // partner-specific enum
            "rateDiscountAmount": number
          }
        ]
      }
    },
    "propertyValue": {
      "borrowerEstimatedValue": number,
      "propertyAvmValue": number,
      "preLoanCltv": number,
      "postLoanCltv": number
    },
    "manualNotary": {
      "manualNotaryDate": string,  // YYYY-MM-DD format
      "manualNotaryFee": number
    }
  },
  "loanOriginatorData": {
    "loanOriginatorUuid": string,  // UUID format
    "brokerUuid": string,  // UUID format
    "licenses": { // Each sub-object follows a common license format
      "lenderLicense": {
        "licenseHolder": {
          "type": string,  // enum LicenseHolderType
          "uuid": string,  // UUID format
          "name": string,
          "nmls": string
        },
        "stateLicense": {
          "type": string,  // enum LicenseStateType
          "uuid": string,  // UUID format
          "licenseNumber": string,
          "licenseName": string,
          "state": string // 2-letter state code
        }
      },
      "loanOriginatorLicense": {
        ... // Same as lenderLicense
      },
      "brokerLicense": {
        ... // Same as lenderLicense
      }
    }
  }
}
Attention

Note that borrower information is not returned with the application details, to avoid transmitting PII.

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.

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
    "async": boolean  // default: false
  },
  "applicant": {
    "ssn": string // nnn-nn-nnnn format
  }
}

Response:​

No contextual data in the response.

Depending on the value of the async parameter of the request:

  • async: false - The appDetails section of the response will be populated with the corresponding data from the * Fetch App/Inquiry Details* endpoint.
  • async: true - At this point, background processing will have started and the appDetails section of the response will not be populated. When the inquiry processing has completed and the next step is ready, the partner will be notified via a webhook.

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
    "async": boolean  // default: false
  },
  "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.

Depending on the value of the async parameter of the request:

  • async: false - The appDetails section of the response will be populated with the corresponding data from the * Fetch App/Inquiry Details* endpoint.
  • async: true - At this point, background processing will have started and the appDetails section of the response will not be populated. When the inquiry processing has completed and the next step is ready, the partner will be notified via a webhook.

Add More Income Assets​

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
    "async": boolean  // default: false
  },
  "income": {
    "employmentType": string, // enum EmploymentType
    "grossAnnualIncome": number,
    "annualRetirementIncome": number,
    "annualInvestmentIncome": number,
    "savingsAmount": number,
    "otherAnnualIncome": number
  }
}

Response:​

No contextual data in the response.

Depending on the value of the async parameter of the request:

  • async: false - The appDetails section of the response will be populated with the corresponding data from the * Fetch App/Inquiry Details* endpoint.
  • async: true - At this point, background processing will have started and the appDetails section of the response will not be populated. When the inquiry processing has completed and the next step is ready, the partner will be notified via a webhook.

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
    "async": boolean  // default: false
  },
  "property": {
    "borrowerEstimatedValue": number
  }
}

Response:​

No contextual data in the response.

Depending on the value of the async parameter of the request:

  • async: false - The appDetails section of the response will be populated with the corresponding data from the * Fetch App/Inquiry Details* endpoint.
  • async: true - At this point, background processing will have started and the appDetails section of the response will not be populated. When the inquiry processing has completed and the next step is ready, the partner will be notified via a webhook.

Enum Types​

A variety of enum types are specified in the payloads listed above. For simplification, all enum types are defined here.

Enum type definitions should be considered non-exhaustive and may be subject to extension.

EmploymentType​

enum EmploymentType {
    UNKNOWN,
    SELF_EMPLOYED,
    OTHER,
    FULL_TIME,
    PART_TIME,
    RETIRED,
    UNEMPLOYED,
    SEPARATE_MAINTENANCE_PAYMENTS,
}

OccupancyType​

enum OccupancyType {
    UNKNOWN,
    SOLD,
    PENDING_SALE,
    RENTAL,
    PRIMARY_RESIDENCE,
    SECONDARY_RESIDENCE,
    INVESTMENT,
    OTHER,
    RETAINED,
}

PropertyType​

enum PropertyType {
    UNKNOWN,
    PRIMARY,
    SECONDARY,
    INVESTMENT,
}

NextInquiryStepType​

enum NextInquiryStepType {
    UNKNOWN,
    NO_OFFERS,
    OFFERS_AVAILABLE,
    INQUIRY_COMPLETE,
    INQUIRY_CLOSED, // The inquiry has been closed through a manual action. e.g. cancellation
    INQUIRY_WITHDRAWN, // The inquiry is no longer active through an automated process. e.g. expired

    // Unhappy paths follow
    CREDIT_MATCH_REQUIRED,  // requires resolution or treat as NO_OFFERS
    MORE_ASSETS_REQUIRED,  // requires resolution or treat as NO_OFFERS
    LIEN_MATCHING_REQUIRED,  // requires resolution or treat as NO_OFFERS
    PROPERTY_VALUE_REQUIRED,  // requires resolution or treat as NO_OFFERS
}

OwnershipType​

enum OwnershipType {
    UNKNOWN,
    SOLE,
    JOINT,
    TRUST,
    LLC,
    OTHER,
}

FinancingPurposeType​

enum FinancingPurposeType {
    UNKNOWN,
    PERSONAL,
    BUSINESS_OR_COMMERCIAL,
}

OfferRateType​

enum OfferRateType {
    UNKNOWN,
    FIXED,
    FLOATING,
}

LicenseHolderType​

enum LicenseHolderType {
    UNKNOWN,
    LENDER,
    BROKER,
    LOAN_OFFICER,
}

LicenseStateType​

enum LicenseStateType {
    UNKNOWN,
    UNSPECIFIED,
    FEDERAL_LICENSE,
    CA_RMLA_STATE_LICENSE,
    CA_CFL_STATE_LICENSE,
    CA_DRE_STATE_LICENSE,
}