openapi: 3.0.1
info:
  title: HELOC Inquiries
  version: v1
servers:
  - url: https://api.test.figure.com
    description: Test environment
  - url: https://api.figure.com
    description: Production environment
security:
  - apikey: []
paths:
  /products/heloc/v1/inquiry/{appUuid}/verify-liens:
    put:
      tags:
        - HELOC application requests
      summary: Verify liens for a HELOC inquiry
      operationId: verifyInquiryLiens
      parameters:
        - name: appUuid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/VerifyLiensRequest"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VerifyLiensResponse"
  /products/heloc/v1/inquiry/{appUuid}/select-offer:
    put:
      tags:
        - HELOC application requests
      summary: Select an offer for a HELOC inquiry
      operationId: selectInquiryOffer
      parameters:
        - name: appUuid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SelectOfferRequest"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SelectOfferResponse"
  /products/heloc/v1/inquiry/{appUuid}/cancel:
    put:
      tags:
        - HELOC application requests
      summary: Cancel HELOC inquiry
      operationId: cancelInquiry
      parameters:
        - name: appUuid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CancelInquiryRequest"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CancelInquiryResponse"
  /products/heloc/v1/inquiry/{appUuid}/add-ssn:
    put:
      tags:
        - HELOC application requests
      summary: Add a borrower SSN to a HELOC inquiry
      operationId: addInquirySsn
      parameters:
        - name: appUuid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddSsnRequest"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddSsnResponse"
  /products/heloc/v1/inquiry/{appUuid}/add-property-estimate:
    put:
      tags:
        - HELOC application requests
      summary: Add borrower property estimate to a HELOC inquiry
      operationId: addInquiryPropertyEstimate
      parameters:
        - name: appUuid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddPropertyEstimateRequest"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddPropertyEstimateResponse"
  /products/heloc/v1/inquiry/{appUuid}/add-income:
    put:
      tags:
        - HELOC application requests
      summary: Add income to a HELOC inquiry
      operationId: addInquiryIncome
      parameters:
        - name: appUuid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddIncomeRequest"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddIncomeResponse"
  /products/heloc/v1/inquiry/start:
    post:
      tags:
        - HELOC application requests
      summary: Starts a new inquiry for a HELOC application
      operationId: startInquiry
      parameters:
        - name: User-Agent
          in: header
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StartInquiryRequest"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StartInquiryResponse"
  /products/heloc/v1/inquiry/{appUuid}/borrower-costs:
    get:
      tags:
        - HELOC application requests
      summary: Get borrower costs for an application
      operationId: getBorrowerCosts
      parameters:
        - name: appUuid
          in: path
          required: true
          schema:
            type: string
        - name: offerUuid
          in: query
          required: true
          schema:
            type: string
        - name: selectedOfferAmount
          in: query
          required: true
          schema:
            type: number
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BorrowerCostsResponse"
  /products/heloc/v1/details/{appUuid}:
    get:
      tags:
        - HELOC application requests
      summary: Fetch details about an application
      operationId: fetchAppDetails
      parameters:
        - name: appUuid
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FetchHelocDetailsResponse"
components:
  schemas:
    CommonHelocPayloadRequest:
      required:
        - async
        - loanOriginatorUuid
      type: object
      properties:
        loanOriginatorUuid:
          type: string
        async:
          type: boolean
    LienRequest:
      required:
        - lenderName
        - lienUuid
        - originalBalance
        - originationDate
      type: object
      properties:
        lienUuid:
          type: string
        originationDate:
          type: string
          format: date
        lenderName:
          pattern: "^[a-zA-Z\\s\\-']+$"
          type: string
        originalBalance:
          type: number
        currentBalance:
          type: number
        monthlyPayment:
          type: number
    VerifyLiensRequest:
      required:
        - liens
        - request
      type: object
      properties:
        request:
          $ref: "#/components/schemas/CommonHelocPayloadRequest"
        liens:
          type: array
          items:
            $ref: "#/components/schemas/LienRequest"
    AppDataResponse:
      required:
        - overallStatus
        - status
      type: object
      properties:
        status:
          type: string
        overallStatus:
          type: string
        nextInquiryStep:
          type: string
          enum:
            - UNKNOWN
            - NO_OFFERS
            - OFFERS_AVAILABLE
            - BORROWER_AUTH_REQUIRED
            - BROKER_DOC_SIGNING_REQUIRED
            - INQUIRY_COMPLETE
            - INQUIRY_CLOSED
            - INQUIRY_WITHDRAWN
            - CREDIT_MATCH_REQUIRED
            - MORE_ASSETS_REQUIRED
            - LIEN_MATCHING_REQUIRED
            - PROPERTY_VALUE_REQUIRED
            - PAYOFF_REQUIRED
        keyDates:
          $ref: "#/components/schemas/KeyDatesResponse"
        propertyAddress:
          $ref: "#/components/schemas/USAddress"
        statusReasons:
          type: array
          items:
            type: string
        ownershipType:
          type: string
          enum:
            - UNKNOWN
            - SOLE
            - JOINT
            - TRUST
            - LLC
            - OTHER
        financingPurpose:
          type: string
          enum:
            - UNKNOWN
            - PERSONAL
            - BUSINESS_OR_COMMERCIAL
        propertyLiens:
          type: array
          items:
            $ref: "#/components/schemas/PropertyLienResponse"
        underwriting:
          $ref: "#/components/schemas/UnderwritingResponse"
        propertyValue:
          $ref: "#/components/schemas/PropertyValueResponse"
        manualNotary:
          $ref: "#/components/schemas/ManualNotaryResponse"
        costs:
          $ref: "#/components/schemas/CostsResponse"
    CostResponse:
      required:
        - type
      type: object
      properties:
        type:
          type: string
          enum:
            - NOTARY_FEE
            - RECORDING_TAX
            - TITLE_FEE
            - BPO_FEE
            - DRIVE_BY_VALUATION_FEE
        borrowerPaidAmount:
          type: number
    CostsResponse:
      type: object
      properties:
        fixedCosts:
          type: array
          items:
            $ref: "#/components/schemas/CostResponse"
        dynamicCosts:
          type: array
          items:
            $ref: "#/components/schemas/CostResponse"
        totalPaidByBorrower:
          type: number
    HelocDetailsResponseData:
      required:
        - appData
        - appUuid
      type: object
      properties:
        appUuid:
          type: string
          format: uuid
        appShortId:
          type: string
        borrowerAppLink:
          type: string
        appData:
          $ref: "#/components/schemas/AppDataResponse"
        loanOriginatorData:
          $ref: "#/components/schemas/LoanOriginatorDataResponse"
    KeyDatesResponse:
      type: object
      properties:
        createdDate:
          type: string
          format: date-time
        expirationDate:
          type: string
          format: date-time
        rescissionEndDate:
          type: string
          format: date-time
        signingDate:
          type: string
          format: date-time
        completedDate:
          type: string
          format: date-time
        canceledDate:
          type: string
          format: date-time
        declinedDate:
          type: string
          format: date-time
    LicenseHolderResponse:
      required:
        - type
        - uuid
      type: object
      properties:
        type:
          type: string
          enum:
            - UNKNOWN
            - LENDER
            - BROKER
            - LOAN_OFFICER
        uuid:
          type: string
          format: uuid
        name:
          type: string
        nmls:
          type: string
    LicenseResponse:
      type: object
      properties:
        licenseHolder:
          $ref: "#/components/schemas/LicenseHolderResponse"
        stateLicense:
          $ref: "#/components/schemas/LicenseStateResponse"
    LicenseStateResponse:
      required:
        - type
        - uuid
      type: object
      properties:
        type:
          type: string
          enum:
            - UNKNOWN
            - UNSPECIFIED
            - FEDERAL_LICENSE
            - CA_RMLA_STATE_LICENSE
            - CA_CFL_STATE_LICENSE
            - CA_DRE_STATE_LICENSE
        uuid:
          type: string
          format: uuid
        licenseNumber:
          type: string
        licenseName:
          type: string
        state:
          type: string
    LicensesResponse:
      type: object
      properties:
        lenderLicense:
          $ref: "#/components/schemas/LicenseResponse"
        loanOriginatorLicense:
          $ref: "#/components/schemas/LicenseResponse"
        brokerLicense:
          $ref: "#/components/schemas/LicenseResponse"
    LoanOriginatorDataResponse:
      type: object
      properties:
        loanOriginatorUuid:
          type: string
          format: uuid
        brokerUuid:
          type: string
          format: uuid
        licenses:
          $ref: "#/components/schemas/LicensesResponse"
    ManualNotaryResponse:
      type: object
      properties:
        manualNotaryDate:
          type: string
          format: date-time
        manualNotaryFee:
          type: number
    MessageResponse:
      required:
        - level
        - message
      type: object
      properties:
        level:
          type: string
        message:
          type: string
    OfferDiscountResponse:
      required:
        - rateDiscountAmount
        - type
      type: object
      properties:
        type:
          type: string
        rateDiscountAmount:
          type: number
    PropertyLienResponse:
      required:
        - lienUuid
      type: object
      properties:
        lienUuid:
          type: string
          format: uuid
        originationDate:
          type: string
        lenderName:
          type: string
        originalBalance:
          type: number
        currentBalance:
          type: number
        monthlyPayment:
          type: number
    PropertyValueResponse:
      type: object
      properties:
        borrowerEstimatedValue:
          type: number
        propertyAvmValue:
          type: number
        preLoanCltv:
          type: number
        postLoanCltv:
          type: number
    USAddress:
      required:
        - city
        - state
        - street1
        - zip
      type: object
      properties:
        street1:
          pattern: "^[a-zA-Z0-9\\s\\-\\.']+$"
          type: string
        street2:
          pattern: "^[a-zA-Z0-9\\s\\-\\.']+$"
          type: string
        city:
          pattern: "^[a-zA-Z\\s\\-']+$"
          type: string
        state:
          pattern: "^[A-Z]{2}$"
          type: string
        zip:
          pattern: "^[0-9]{5}(?:-[0-9]{4})?$"
          type: string
    UnderwritingOfferResponse:
      required:
        - maxAmount
        - minAmount
        - originationFeePercent
        - primeRate
        - rate
        - rateType
        - term
        - uuid
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        minAmount:
          type: number
        maxAmount:
          type: number
        rate:
          type: number
        primeRate:
          type: number
        term:
          type: integer
          format: int32
        rateType:
          type: string
          enum:
            - UNKNOWN
            - FIXED
            - FLOATING
        originationFeePercent:
          type: number
        discounts:
          type: array
          items:
            $ref: "#/components/schemas/OfferDiscountResponse"
    UnderwritingResponse:
      required:
        - decision
        - maxOfferAmount
        - minOfferAmount
        - offers
      type: object
      properties:
        decision:
          type: string
        minOfferAmount:
          type: number
        maxOfferAmount:
          type: number
        offers:
          type: array
          items:
            $ref: "#/components/schemas/UnderwritingOfferResponse"
        selectedOffer:
          $ref: "#/components/schemas/UnderwritingSelectedOfferResponse"
    UnderwritingSelectedOfferResponse:
      required:
        - drawAmount
        - estimatedMonthlyPayment
        - loanAmount
        - offerUuid
        - originationFeePercent
        - primeRate
        - rate
        - rateType
        - term
      type: object
      properties:
        offerUuid:
          type: string
          format: uuid
        loanAmount:
          type: number
        drawAmount:
          type: number
        estimatedMonthlyPayment:
          type: number
        rate:
          type: number
        primeRate:
          type: number
        term:
          type: integer
          format: int32
        rateType:
          type: string
          enum:
            - UNKNOWN
            - FIXED
            - FLOATING
        originationFeePercent:
          type: number
        selectedDiscounts:
          type: array
          items:
            $ref: "#/components/schemas/OfferDiscountResponse"
    VerifyLiensResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: "#/components/schemas/MessageResponse"
        appDetails:
          $ref: "#/components/schemas/HelocDetailsResponseData"
    OfferRequest:
      required:
        - offerUuid
        - selectedDiscounts
        - selectedOfferAmount
      type: object
      properties:
        offerUuid:
          type: string
        selectedOfferAmount:
          type: number
        selectedDiscounts:
          type: array
          items:
            type: string
    SelectOfferRequest:
      required:
        - offer
        - request
      type: object
      properties:
        request:
          $ref: "#/components/schemas/CommonHelocPayloadRequest"
        offer:
          $ref: "#/components/schemas/OfferRequest"
    SelectOfferResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: "#/components/schemas/MessageResponse"
        appDetails:
          $ref: "#/components/schemas/HelocDetailsResponseData"
    CancelInquiryRequest:
      required:
        - request
      type: object
      properties:
        request:
          $ref: "#/components/schemas/CommonHelocPayloadRequest"
    CancelInquiryResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: "#/components/schemas/MessageResponse"
        appDetails:
          $ref: "#/components/schemas/HelocDetailsResponseData"
    AddSsnRequest:
      required:
        - applicant
        - request
      type: object
      properties:
        request:
          $ref: "#/components/schemas/CommonHelocPayloadRequest"
        applicant:
          $ref: "#/components/schemas/SsnRequest"
    SsnRequest:
      required:
        - ssn
      type: object
      properties:
        ssn:
          pattern: "^(([0-9]{9})|([0-9]{3}-[0-9]{2}-[0-9]{4}))$"
          type: string
    AddSsnResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: "#/components/schemas/MessageResponse"
        appDetails:
          $ref: "#/components/schemas/HelocDetailsResponseData"
    AddPropertyEstimateRequest:
      required:
        - propertyEstimate
        - request
      type: object
      properties:
        request:
          $ref: "#/components/schemas/CommonHelocPayloadRequest"
        propertyEstimate:
          $ref: "#/components/schemas/PropertyEstimateRequest"
    PropertyEstimateRequest:
      required:
        - borrowerEstimatedValue
      type: object
      properties:
        borrowerEstimatedValue:
          type: number
    AddPropertyEstimateResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: "#/components/schemas/MessageResponse"
        appDetails:
          $ref: "#/components/schemas/HelocDetailsResponseData"
    AddIncomeRequest:
      required:
        - income
        - request
      type: object
      properties:
        request:
          $ref: "#/components/schemas/CommonHelocPayloadRequest"
        income:
          $ref: "#/components/schemas/IncomeRequest"
    IncomeRequest:
      required:
        - employmentType
        - grossAnnualIncome
      type: object
      properties:
        employmentType:
          type: string
          enum:
            - UNKNOWN
            - SELF_EMPLOYED
            - OTHER
            - FULL_TIME
            - PART_TIME
            - RETIRED
            - UNEMPLOYED
            - SEPARATE_MAINTENANCE_PAYMENTS
        grossAnnualIncome:
          type: number
        annualRetirementIncome:
          type: number
        annualInvestmentIncome:
          type: number
        savingsAmount:
          type: number
        otherAnnualIncome:
          type: number
    AddIncomeResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: "#/components/schemas/MessageResponse"
        appDetails:
          $ref: "#/components/schemas/HelocDetailsResponseData"
    ApplicantRequest:
      required:
        - dob
        - email
        - homeAddress
        - income
        - name
        - phone
      type: object
      properties:
        name:
          $ref: "#/components/schemas/NameRequest"
        dob:
          type: string
          format: date
        phone:
          pattern: "^\\(?\\d{3}\\)?[\\s.-]?\\d{3}[\\s.-]?\\d{4}$"
          type: string
        email:
          pattern: "^(?:[a-zA-Z0-9!#\\$%&'*+/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#\\$%&'*+/=?^_`{|}~-]+)*|\\\"(?:[\\x01-\\x08\\x0b\\x0c\\x0e-\\x1f\\x21\\x23-\\x5b\\x5d-\\x7f]|\\\\[\\x01-\\x09\\x0b\\x0c\\x0e-\\x7f])*\\\")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\\x01-\\x08\\x0b\\x0c\\x0e-\\x1f\\x21-\\x5a\\x53-\\x7f]|\\\\[\\x01-\\x09\\x0b\\x0c\\x0e-\\x7f])+)\\])$"
          type: string
        ssn:
          pattern: "^(([0-9]{9})|([0-9]{3}-[0-9]{2}-[0-9]{4}))$"
          type: string
        homeAddress:
          $ref: "#/components/schemas/USAddress"
        income:
          $ref: "#/components/schemas/IncomeRequest"
    NameRequest:
      required:
        - firstName
        - lastName
      type: object
      properties:
        prefix:
          pattern: "^[a-zA-Z\\s\\-']+$"
          type: string
        firstName:
          pattern: "^[a-zA-Z\\s\\-']+$"
          type: string
        middleName:
          pattern: "^[a-zA-Z\\s\\-']+$"
          type: string
        lastName:
          pattern: "^[a-zA-Z\\s\\-']+$"
          type: string
        suffix:
          pattern: "^[a-zA-Z\\s\\-']+$"
          type: string
    PartnerDataRequest:
      type: object
      properties:
        externalAppId:
          type: string
        utmParameters:
          $ref: "#/components/schemas/UtmParametersRequest"
    PropertyLienRequest:
      required:
        - originalBalance
        - originationDate
      type: object
      properties:
        originationDate:
          type: string
          format: date
        originalBalance:
          type: number
        lenderName:
          type: string
        currentBalance:
          type: number
        monthlyPayment:
          type: number
    PropertyRequest:
      required:
        - address
        - isListedForSale
        - propertyType
      type: object
      properties:
        address:
          $ref: "#/components/schemas/USAddress"
        occupancyType:
          type: string
          enum:
            - UNKNOWN
            - SOLD
            - PENDING_SALE
            - RENTAL
            - PRIMARY_RESIDENCE
            - SECONDARY_RESIDENCE
            - INVESTMENT
            - OTHER
            - RETAINED
        propertyType:
          type: string
          enum:
            - UNKNOWN
            - PRIMARY
            - SECONDARY
            - INVESTMENT
        isListedForSale:
          type: boolean
        borrowerEstimatedValue:
          type: number
        liens:
          type: array
          items:
            $ref: "#/components/schemas/PropertyLienRequest"
    StartInquiryRequest:
      required:
        - applicant
        - property
        - request
      type: object
      properties:
        request:
          $ref: "#/components/schemas/CommonHelocPayloadRequest"
        applicant:
          $ref: "#/components/schemas/ApplicantRequest"
        property:
          $ref: "#/components/schemas/PropertyRequest"
        partnerDataRequest:
          $ref: "#/components/schemas/PartnerDataRequest"
    UtmParametersRequest:
      type: object
      properties:
        source:
          type: string
        medium:
          type: string
        campaign:
          type: string
        term:
          type: string
        content:
          type: string
    StartInquiryDetailsResponseData:
      required:
        - appUuid
      type: object
      properties:
        appUuid:
          type: string
          format: uuid
    StartInquiryResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/StartInquiryDetailsResponseData"
        messages:
          type: array
          items:
            $ref: "#/components/schemas/MessageResponse"
        appDetails:
          $ref: "#/components/schemas/HelocDetailsResponseData"
    BorrowerCostsResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: "#/components/schemas/MessageResponse"
        costs:
          $ref: "#/components/schemas/CostsResponse"
    FetchHelocDetailsResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/HelocDetailsResponseData"
        messages:
          type: array
          items:
            $ref: "#/components/schemas/MessageResponse"
  securitySchemes:
    apikey:
      type: apiKey
      name: apikey
      in: header
