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. 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 sent inside the loan attribute are saved as part of the lock snapshot.
Schema versions
This page documents
application/vnd.productpricing-lock-1.0.0.json. Other versions of theLOCKaction:
- Rate Lock v1.1 (
application/vnd.productpricing-lock-1.1.0.json): addsinvestor,impoundWaived, andimpoundType, and allows an emptypenaltyTerm.- Rate Lock v2 (
application/vnd.productpricing-lock-2.0.0.json): restructuresdetailsinto request, buy, sell, and comparison sides.
{
"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 in the
resultsection and the loan fields listed in the table below are saved in the lock request snapshot.
The following loan fields are saved in the lock snapshot when they are sent as part of a rate lock operation:
| 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 minimum information that a pricing engine integration must send to initiate a rate lock request with an EPC transaction response LOCK result:
$.result.details.baseRate- Two of
$.result.details.lockDate,$.result.details.lockNumberOfDays, and$.result.details.lockExpirationDate. EPC calculates the third value from the two that the integration provides.
Dates use the MM/DD/YYYY format.
The complete list of supported fields in the lock request action details object is defined in the JSON schema below. You can use online tools such as JSON Schema Validator to manually validate the contents of a details object.
{
"$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": "describes whether the rate lock is an extension of a previous lock."
},
"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."
},
"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."
},
"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.0000000001
},
"adjustmentNumericField": {
"type": "number",
"multipleOf": 0.0000000001
},
"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.0000000001,
"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.0.0.json",
"action": "LOCK",
"details": {
"comments": "Lock requested at borrower request",
"programNotes": "30 year fixed conforming program",
"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",
"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": "Lock extension, 15 days",
"priceAdjustmentType": "BasePrice",
"adjustment": 0.125
},
{
"adjustmentType": "ReLockFeeAdjustment",
"description": "Relock fee",
"priceAdjustmentType": "BasePrice",
"adjustment": 0.25
},
{
"adjustmentType": "CustomPriceAdjustment",
"description": "Custom price adjustment",
"priceAdjustmentType": "BasePrice",
"adjustment": 0.05
}
]
}
},
"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"
}
Updated about 24 hours ago