Rate Lock

An integration listed under the Product & Pricing Engine (PPE) category can request an interest rate lock by creating a transaction with a response that returns the required field values, and with a response result object with the action LOCK. In addition, within the same transaction response, the integration can also send additional loan data to be updated in Encompass. The specific fields that are sent as part of the response loan data follow the standard data entitlement model and process. However, not all of the loan data fields that are send inside the loan attribute are saved as part of the lock snapshot.

{
   "status": "completed",
   "loanFormat": "application/vnd.plm-2.0.0+json",
   "loan": {
      ... // Additional loan data, sent as part of standard transaction loan update
   },
   "result": {
      "format": "application/vnd.productpricing-lock-1.0.0.json",
      "action": "LOCK",
      "details": {
         ... // Rate lock action details
   },
   "partnerStatus": "partner status",
   "respondingParty": {
      "name": "PPE partner",
      "address": "P.O. BOX 509124, SUITE 300",
      "city": "SAN DIEGO",
      "state": "CA",
      "postalCode":" 92150",
      "pointOfContact": {
         "fax": "8002376526",
         "phone": "8009864343",
         "email": "[email protected]"
      }
   },
   "referenceNumber": "000901"
}

📘
Lock Snapshot Fields
Only the data sent as part of result section and the loan fields listed in the table are saved in the lock request snapshot

Below is the list of loan fields which when sent as part of rate lock operation is saved in the lock snapshot.

Loan Fields	Additional Information
`$.loan.loanProductData.loanDocumentationType`
`$.loan.creditScoreToUse`
`$.loan.firstTimeHomebuyersIndicator`
`$.loan.twelveMonthMortgageRentalHistoryIndicator`
`$.loan.property.loanPurposeType`
`$.loan.hudLoanData.loanFor203KIndicator`
`$.loan.hudLoanData.totalForLesserOfSumAsIs`
`$.loan.loanProductData.lienPriorityType`
`$.loan.mortgageType`	Possible Values: `Conventional`, `VA`, `FHA`, `FarmersHomeAdministration`, `HELOC`, `Other`
`$.loan.loanAmortizationType`
`$.loan.loanProductData.fnmProductPlanIdentifier`
`$.loan.otherAmortizationTypeDescription`
`$.loan.noClosingCostOption`
`$.loan.loanProductData.borrowerEstimatedClosingDate`
`$.loan.gfe.fundingAmount`
`$.loan.mipPaidInCashAmount`
`$.loan.loanProductData.balloonLoanMaturityTermMonthsCount`
`$.loan.loanAmortizationTermMonths`
`$.loan.baseLoanAmount`
`$.loan.borrowerRequestedLoanAmount`
`$.loan.freddieMac.helocActualBalance`	To be sent only if it is a HELOC loan
`$.loan.firstSubordinateLienAmount`
`$.loan.secondSubordinateAmount`
`$.loan.otherSubordinateAmount`
`$.loan.regulationZ.lenderPaidMortgageInsuranceIndicator`
`$.loan.property.city`
`$.loan.property.state`
`$.loan.property.postalCode`
`$.loan.property.county`
`$.loan.propertyEstimatedValueAmount`
`$.loan.propertyAppraisedValueAmount`
`$.loan.purchasePriceAmount`
`$.loan.property.propertyUsageType`
`$.loan.property.financedNumberOfUnits`
`$.loan.loanProductData.gsePropertyType`
`$.loan.property.condotelIndicator`
`$.loan.property.nonwarrantableProjectIndicator`
`$.loan.property.streetAddress`
`$.loan.property.unitType`
`$.loan.property.unitNumber`

The following attributes are the minimal information that are required to be sent by a pricing engine integration to initiate a rate lock request via an EPC transaction response LOCK result:

$.result.details.baseRate

Two of $.result.details.lockDate, $.result.details.lockNumberOfDays and $.result.details.lockExpirationDate - the third being calculated based on the two provided by the integration

The full list of supported fields in the lock request action details are captured in the JSON-schema object definition below. There are several resources available online, such as https://www.jsonschemavalidator.net/, where a result details objects content can be manually validated.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "description": "JSON representation of a rate lock request initiation transaction result.",
  "validationMessage": {
    "oneOf": "Two of lockDate, lockNumberOfDays and lockExpirationDate are required.",
    "oneOfSub": "Two of lockDate, lockNumberOfDays and lockExpirationDate are required.",
    "oneOfAdditionalFields": "fieldName and one of stringValue, numericValue and dateValue is required.",
    "datePattern": "Date should be in the format MM/DD/YYYY.",
    "timePattern": "Time should be in the format HH:MM"
  },
  "properties": {
    "extensionIndicator": {
      "type": "boolean",
      "description": ""
    },
    "priceConcession": {
      "type": "object",
      "properties": {
        "indicator": {
          "type": "boolean",
          "description": ""
        },
        "requestStatus": {
          "type": "string",
          "enum": [
            "Approved",
            "Denied"
          ],
          "description": ""
        },
        "requestedAmount": {
          "$ref": "#/definitions/numericField",
          "description": ""
        }
      }
    },
    "borrLenderPaid": {
      "type": "string",
      "enum": [
        "Lender Paid",
        "Borrower Paid",
        "Exempt"
      ],
      "description": ""
    },
    "onrpDate": {
      "$ref": "#/definitions/datePattern",
      "description": ""
    },
    "onrpTime": {
      "type": "string",
      "$ref": "#/definitions/timePattern",
      "description": ""
    },
    "onrpLock": {
      "type": "boolean",
      "description": ""
    },
    "onrpEligible": {
      "type": "boolean",
      "description": ""
    },
    "teaserRate": {
      "$ref": "#/definitions/numericField",
      "description": ""
    },
    "disclosureType": {
      "type": "string",
      "description": ""
    },
    "indexCurrentValuePercent": {
      "$ref": "#/definitions/numericField",
      "description": ""
    },
    "buydownType": {
      "type": "string",
      "description": ""
    },
    "pudIndicator": {
      "type": "boolean",
      "description": ""
    },
    "notInProjectIndicator": {
      "type": "boolean",
      "description": ""
    },
    "comments": {
      "type": "string",
      "description": "Free form comments for the rate lock operation."
    },
    "investor": {
      "type": "string",
      "description": ""
    },
    "programNotes": {
      "type": "string",
      "description": "Free form Rate Lock Request Program Notes."
    },
    "planCode": {
      "type": "string",
      "description": "Alpha-numeric code that represents the specific loan program."
    },
    "lockDate": {
      "$ref": "#/definitions/datePattern",
      "description": "Effective date for the rate lock."
    },
    "lockExpirationDate": {
      "$ref": "#/definitions/datePattern",
      "description": "Expiration date for the rate lock."
    },
    "lockNumberOfDays": {
      "$ref": "#/definitions/integerField",
      "description": "Lock period number of days for the rate lock."
    },
    "startingAdjustRate": {
      "$ref": "#/definitions/numericField",
      "description": ""
    },
    "startingAdjustPrice": {
      "$ref": "#/definitions/numericField",
      "description": ""
    },
    "unDiscountedRate": {
      "$ref": "#/definitions/numericField",
      "description": ""
    },
    "gpmRate": {
      "$ref": "#/definitions/numericField",
      "description": "Graduated payment mortgage rate."
    },
    "gpmYears": {
      "$ref": "#/definitions/integerField",
      "description": "Graduated payment mortgage number of years."
    },
    "lastRateSetDate": {
      "$ref": "#/definitions/datePattern",
      "description": ""
    },
    "correspondentCommitmentType": {
      "type": "string",
      "enum": [
        "Best Efforts",
        "Mandatory"
      ],
      "description": "Type of lock associated with the correspondent trade."
    },
    "correspondentDeliveryType": {
      "type": "string",
      "description": "The processing method of the commitment."
    },
    "isDeliveryType": {
      "type": "boolean",
      "description": "Indicates whether the correspondent delivery type has been determined."
    },
    "hedging": {
      "type": "boolean",
      "description": "Indicates if the subject loan is part of the lenders interest rate risk hedging program."
    },
    "penaltyTerm": {
      "type": "string",
      "enum": [
        "1 Year",
        "2 Years",
        "3 Years",
        "4 Years",
        "5 Years",
        ""
      ],
      "description": "The period for the pre-payment penalty."
    },
    "currentAcquisition": {
      "type": "boolean",
      "description": "The lot/land status of the property"
    },
    "currentConstructionRefi": {
      "type": "boolean",
      "description": "Indicates whether a refinance is being done on the construction."
    },
    "prepayPenalty": {
      "type": "boolean",
      "description": "Indicates whether there is a pre-payment penalty on the loan."
    },
    "baseRate": {
      "$ref": "#/definitions/numericField",
      "description": "The base interest rate defined in the requested lock."
    },
    "basePrice": {
      "$ref": "#/definitions/numericField",
      "description": "The base loan price defined in the requested lock."
    },
    "baseMarginRate": {
      "$ref": "#/definitions/numericField",
      "description": "The lenders marginal interest rate defined in the requested lock."
    },
    "rateSheetId": {
      "type": "string",
      "description": "The identifier for the source loan pricing rate sheet."
    },
    "requestImpoundWaived": {
      "type": "string",
      "enum": [
        "Waived",
        "Not Waived",
        ""
      ],
      "description": "Indicates waiver of impound/escrow account requirement for the subject mortgage transaction."
    },
    "requestImpoundType": {
      "type": "string",
      "enum": [
        "No Impounds",
        "Insurance only",
        "Taxes only",
        "Taxes and Insurance",
        ""
      ],
      "description": "Waiver type of impound/escrow account requirement for the subject mortgage transaction."
    },
    "impoundWaived": {
      "type": "string",
      "enum": [
        "Waived",
        "Not Waived",
        ""
      ],
      "description": "Indicates waiver of impound/escrow account requirement for the subject mortgage transaction."
    },
    "impoundType": {
      "type": "string",
      "enum": [
        "No Impounds",
        "Insurance only",
        "Taxes only",
        "Taxes and Insurance",
        ""
      ],
      "description": "Waiver type of impound/escrow account requirement for the subject mortgage transaction."
    },
    "lenderFeeWaiverOption": {
      "type": "boolean",
      "description": "Indicates whether the fee waiver is covered by the lender."
    },
    "sellerPaidMiPremium": {
      "$ref": "#/definitions/integerField",
      "description": "MI premium amount paid by the subject property seller."
    },
    "fhaUpfrontMiPremiumPercent": {
      "$ref": "#/definitions/numericField",
      "description": "FHA-only upfront MI premium percentage."
    },
    "roundToNearest50": {
      "type": "boolean",
      "description": "Indicates whether to round the loan amount to the nearest multiple of $50."
    },
    "pricing": {
      "type": "object",
      "properties": {
        "historyData": {
          "type": "string",
          "minLength": 1
        },
        "updated": {
          "type": "string",
          "minLength": 1
        }
      },
      "required": [
        "historyData"
      ],
      "additionalProperties": false
    },
    "adjustments": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/adjustmentItem"
      },
      "minItems": 1,
      "description": "Loan interest rate adjustments."
    },
    "additionalFields": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/additionalFieldItem"
      },
      "minItems": 1,
      "description": "Additional fields in the rate lock."
    }
  },
  "required": [
    "baseRate"
  ],
  "oneOf": [
    {
      "required": [
        "lockDate",
        "lockNumberOfDays"
      ],
      "validationMessage": {
        "$ref": "#/validationMessage/oneOfSub"
      }
    },
    {
      "required": [
        "lockDate",
        "lockExpirationDate"
      ],
      "validationMessage": {
        "$ref": "#/validationMessage/oneOfSub"
      }
    },
    {
      "required": [
        "lockExpirationDate",
        "lockNumberOfDays"
      ],
      "validationMessage": {
        "$ref": "#/validationMessage/oneOfSub"
      }
    }
  ],
  "additionalProperties": false,
  "definitions": {
    "integerField": {
      "type": "integer",
      "minimum": 1
    },
    "numericField": {
      "type": "number",
      "multipleOf": 0.001
    },
    "adjustmentNumericField": {
      "type": "number",
      "multipleOf": 0.001
    },
    "datePattern": {
      "type": "string",
      "pattern": "^^(?:(?:(?:0?[13578]|1[02])(\\/)31)\\1|(?:(?:0?[1,3-9]|1[0-2])(\\/)(?:29|30)\\2))(?:(?:1[6-9]|[2-9]\\d)?\\d{2})$|^(?:0?2(\\/)29\\3(?:(?:(?:1[6-9]|[2-9]\\d)?(?:0[48]|[2468][048]|[13579][26])|(?:(?:16|[2468][048]|[3579][26])00))))$|^(?:(?:0?[1-9])|(?:1[0-2]))(\\/)(?:0?[1-9]|1\\d|2[0-8])\\4(?:(?:1[6-9]|[2-9]\\d)?\\d{2})$",
      "validationMessage": {
        "$ref": "#/validationMessage/datePattern"
      }
    },
    "timePattern": {
      "type": "string",
      "pattern": "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$",
      "validationMessage": {
        "$ref": "#/validationMessage/timePattern"
      }
    },
    "adjustmentItem": {
      "type": "object",
      "properties": {
        "adjustmentType": {
          "type": "string",
          "enum": [
            "Adjustment",
            "LockExtensionAdjustment",
            "ReLockFeeAdjustment",
            "CustomPriceAdjustment"
          ],
          "description": "The type of the subject interest rate adjustment."
        },
        "description": {
          "type": "string",
          "description": ""
        },
        "priceAdjustmentType": {
          "type": "string",
          "enum": [
            "BasePrice",
            "BaseMargin",
            "BaseRate",
            "ProfitMargin"
          ],
          "description": "If the adjustment affects the loan price - the type of the pricing adjustment."
        },
        "adjustment": {
          "$ref": "#/definitions/adjustmentNumericField",
          "description": "The adjustment amount."
        }
      },
      "required": [
        "adjustmentType",
        "description",
        "priceAdjustmentType",
        "adjustment"
      ],
      "additionalProperties": false
    },
    "additionalFieldItem": {
      "type": "object",
      "properties": {
        "fieldName": {
          "type": "string",
          "minLength": 1,
          "pattern": "^[a-zA-Z0-9.]*$",
          "description": "Identifier of the additional field in encompass"
        },
        "numericValue": {
          "type": "number",
          "multipleOf": 0.001,
          "description": "Numeric value for the additional field"
        },
        "stringValue": {
          "type": "string",
          "minLength": 1,
          "description": "String value for the additional field"
        },
        "dateValue": {
          "$ref": "#/definitions/datePattern",
          "description": "Date value for the additional field."
        }
      },
      "oneOf": [
        {
          "required": [
            "fieldName",
            "stringValue"
          ],
          "validationMessage": {
            "$ref": "#/validationMessage/oneOfAdditionalFields"
          }
        },
        {
          "required": [
            "fieldName",
            "numericValue"
          ],
          "validationMessage": {
            "$ref": "#/validationMessage/oneOfAdditionalFields"
          }
        },
        {
          "required": [
            "fieldName",
            "dateValue"
          ],
          "validationMessage": {
            "$ref": "#/validationMessage/oneOfAdditionalFields"
          }
        }
      ],
      "additionalProperties": false
    }
  }
}

Below is a sample rate lock request payload with most of the fields supported in the rate lock request operation:

{
  "status": "completed",
  "loanFormat": "application/vnd.plm-2.0.0+json",
  "loan": {
    "property": {
      "addressLineText": "Test address",
      "loanPurposeType": "ConstructionOnly",
      "AppraisedValueAmount": 50000,
      "propertyUsageType": "PrimaryResidence",
      "condotelIndicator": true,
      "nonwarrantableProjectIndicator": true,
      "city": "Pleasanton",
      "state": "California",
      "postalCode": "94588",
      "county": "Alameda",
      "financedNumberOfUnits": 10,
      "streetAddress": "4420 Rosewood Drive",
      "unitType": "Apartment",
      "unitNumber": 7
    },
    "loanProductData": {
      "loanDocumentationType": "FullDocumentation",
      "lienPriorityType": "FirstLien",
      "fnmProductPlanIdentifier": "N",
      "borrowerEstimatedClosingDate": "06/01/2020",
      "balloonLoanMaturityTermMonthsCount": 18,
      "gsePropertyType": "Attached"
    },
    "gfe": {
      "fundingAmount": 41000
    },
    "freddieMac": {
      "helocActualBalance": "5000"
    },
    "regulationZ": {
      "lenderPaidMortgageInsuranceIndicator": true
    },
    "hudLoanData": {
      "loanFor203KIndicator": true,
      "totalForLesserOfSumAsIs": 3
    },
    "propertyUsageType": "PrimaryResidence",
    "creditScoreToUse": "750",
    "mortgageType": "Conventional",
    "loanAmortizationType": "Fixed Rate",
    "otherAmortizationTypeDescription": "Desc",
    "noClosingCostOption": true,
    "loanAmortizationTermMonths": 180,
    "baseLoanAmount": 450000,
    "borrowerRequestedLoanAmount": 460000,
    "firstSubordinateLienAmount": 450000,
    "secondSubordinateAmount": 44334433,
    "propertyAppraisedValueAmount": 650000,
    "purchasePriceAmount": 600000,
    "firstTimeHomebuyersIndicator": true,
    "otherSubordinateAmount": 1200,
    "twelveMonthMortgageRentalHistoryIndicator": true,
    "loanProgramName": "30 Year Fixed",
    "mipPaidInCashAmount": 3000
  },
  "result": {
    "format": "application/vnd.productpricing-lock-1.1.0.json",
    "action": "LOCK",
    "details": {
      "comments": "FreeForm Field to enter any comments",
      "programNotes": "FreeForm Field to enter Program Notes",
      "planCode": "99999",
      "lockDate": "07/24/2020",
      "lockExpirationDate": "08/30/2020",
      "lastRateSetDate": "05/19/2020",
      "hedging": true,
      "penaltyTerm": "1 Year",
      "prepayPenalty": "true",
      "baseRate": 5.2,
      "basePrice": 4.5,
      "baseMarginRate": 1.5,
      "rateSheetId": "Sheet-ID-4555",
      "netPrice": 3,
      "expectedNetPrice": 266666,
      "currentAcquisition": true,
      "currentConstructionRefi": false,
      "gpmRate": "5.5",
      "gpmYears": "10",
      "requestImpoundWaived": "Waived",
      "requestImpoundType": "No Impounds",
      "lenderFeeWaiverOption": true,
      "sellerPaidMiPremium": 1555,
      "fhaUpfrontMiPremiumPercent": 2,
      "roundToNearest50": true,
      "adjustments": [
        {
          "adjustmentType": "Adjustment",
          "description": "No FICO",
          "priceAdjustmentType": "BasePrice",
          "adjustment": 0.02
        },
        {
          "adjustmentType": "Adjustment",
          "description": "1 Year Payment Option",
          "priceAdjustmentType": "BaseMargin",
          "adjustment": 0.25
        },
        {
          "adjustmentType": "Adjustment",
          "description": "15 Day Lock Period",
          "priceAdjustmentType": "BaseRate",
          "adjustment": 0.002
        },
        {
          "adjustmentType": "Adjustment",
          "description": "Extended Payment Option",
          "priceAdjustmentType": "BaseRate",
          "adjustment": 0.001
        },
        {
          "adjustmentType": "LockExtensionAdjustment",
          "description": "LockExtensionAdjustment22",
          "priceAdjustmentType": "BasePrice",
          "adjustment": 22
        },
        {
          "adjustmentType": "ReLockFeeAdjustment",
          "description": "ReLockFeeAdjustment133",
          "priceAdjustmentType": "BasePrice",
          "adjustment": 33
        },
        {
          "adjustmentType": "CustomPriceAdjustment",
          "description": "CustomPriceAdjustment55",
          "priceAdjustmentType": "BasePrice",
          "adjustment": 55
        }
      ]
    }
  },
  "partnerStatus": "partner status",
  "respondingParty ": {
    "name": "PPE partner",
    "address": "P.O. BOX 509124, SUITE 300",
    "city": "SAN DIEGO",
    "state": "CA",
    "postalCode": "92150",
    "pointOfContact": {
      "fax": "8002376526",
      "phone": "8009864343",
      "email": "[email protected]"
    }
  },
  "referenceNumber": "000901"
}

📘Lock Snapshot Fields

📘
Lock Snapshot Fields