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.

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,

    // 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,
}