Loan Pricing: Rate Lock

Loan program rate lock actions enable pricing engine integrations under the Product & Pricing Engine (PPE) category to initiate special operations relating to mortgage transaction interest rate locks. This section details how an integration can implement the different rate lock actions supported by EPC.


Rate Lock Request


An integration listed in the PPE category can request a 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:

  1. $.result.details.baseRate
  2. 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.",
    "datePattern": "Date should be in the format MM/DD/YYYY."
  },
  "properties": {
    "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."
    },
    "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"],
      "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."
    },
    "adjustments": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/adjustmentItem"
      },
      "minItems": 1,
      "description": "Loan interest rate adjustments."
    }
  },
  "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",
      "minimum": 0.001,
      "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"
      }
    },
    "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
    }
  }
}

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": "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 and Confirm


The LOCK_CONFIRM action enables Pricing Engine integrations to both initiate and confirm a rate lock request in a single operation.

To implement the LOCK_CONFIRM action, the integration needs to send additional buySide information in addition to the core LOCK result information described in the previous section. The buySide object includes some of the same fields as delivered in a standard lock request operation - integrations have the option to either echo back those same lock request fields, or adjust their values as appropriate while confirming the rate lock. In addition, the action also supports delivering other fields into the lock request confirmation, such as profitability information in the form of a ProfitMargin adjustment, to fully specify the rate lock parameters.

Below you will find the JSON schema definition for the details of a lock and confirm transaction result, followed by a sample transaction result payload. The LOCK_CONFIRM action does not support sending sell-side and comparison information.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "validationMessage": {
    "oneOf": "Two of lockDate, lockNumberOfDays and lockExpirationDate are required.",
    "oneOfSub": "Two of lockDate, lockNumberOfDays and lockExpirationDate are required.",
    "oneOfBuySideSub": "Two of lockDate, lockNumberOfDays and lockExpirationDate are required.",
    "datePattern": "Date should be in the format MM/DD/YYYY."
  },
  "properties": {
    "programNotes": {
      "type": "string",
      "description": "Free form Rate Lock Request Program Notes."
    },
    "planCode": {
      "type": "string",
      "description": ""
    },
    "lockDate": {
      "$ref": "#/definitions/datePattern",
      "description": ""
    },
    "lockExpirationDate": {
      "$ref": "#/definitions/datePattern",
      "description": ""
    },
    "lockNumberOfDays": {
      "$ref": "#/definitions/integerField",
      "description": ""
    },
    "adjustments": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/adjustmentItem"
      },
      "minItems": 1,
      "description": ""
    },
    "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": "Gets set based on the committment type."
    },
    "hedging": {
      "type": "boolean",
      "description": "A flag to indicate whether a loan is part of the hedge."
    },
    "onrpLock": {
      "type": "boolean",
      "description": ""
    },
    "onrpEligible": {
      "type": "boolean",
      "description": ""
    },
    "penaltyTerm": {
      "type": "string",
      "enum": [
        "1 Year",
        "2 Years",
        "3 Years"
      ],
      "description": "It is the period of the prepaid penalty."
    },
    "currentAcquisition": {
      "type": "boolean",
      "description": "The lot/land status of the property"
    },
    "currentConstructionRefi": {
      "type": "boolean",
      "description": "Indicated whether a refinance is being done on the construction."
    },
    "prepayPenalty": {
      "type": "boolean",
      "description": "Indicates whether there is a prepayment penalty on the loan."
    },
    "gpmRate": {
      "$ref": "#/definitions/numericField",
      "description": ""
    },
    "gpmYears": {
      "$ref": "#/definitions/integerField",
      "description": ""
    },
    "baseRate": {
      "$ref": "#/definitions/numericField",
      "description": ""
    },
    "basePrice": {
      "$ref": "#/definitions/numericField",
      "description": ""
    },
    "baseMarginRate": {
      "$ref": "#/definitions/numericField",
      "description": ""
    },
    "rateSheetId": {
      "type": "string",
      "description": ""
    },
    "requestImpoundWaived": {
      "type": "string",
      "enum": [
        "Waived",
        "Not Waived",
        ""
      ],
      "description": "Indicates whether any portion of the payment will be part of an escrow account."
    },
    "requestImpoundType": {
      "type": "string",
      "enum": [
        "No Impounds",
        "Insurance only",
        "Taxes only",
        "Taxes and Insurance",
        ""
      ],
      "description": "Describes what portion of the payment will have an escrow account."
    },
    "lenderFeeWaiverOption": {
      "type": "boolean",
      "description": "Indicates whether a lender will waive their fees."
    },
    "sellerPaidMiPremium": {
      "$ref": "#/definitions/integerField",
      "description": "Lock Request Seller Paid MI Premium"
    },
    "fhaUpfrontMiPremiumPercent": {
      "$ref": "#/definitions/integerField",
      "description": ""
    },
    "roundToNearest50": {
      "type": "boolean",
      "description": ""
    },
    "comments": {
      "type": "string",
      "description": ""
    },
    "buySide": {
      "type": "object",
      "properties": {
        "commitment": {
          "type": "object",
          "properties": {
            "number": {
              "type": "string",
              "description": "Commitment number associated with the trade."
            },
            "date": {
              "$ref": "#/definitions/datePattern",
              "description": ""
            },
            "masterCommitmentNumber": {
              "type": "string",
              "description": "Master commitment number associated with the trade."
            }
          },
          "additionalProperties": false
        },
        "expirationDate": {
          "$ref": "#/definitions/datePattern",
          "description": ""
        },
        "delivery": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "description": ""
            },
            "expirationDate": {
              "$ref": "#/definitions/datePattern",
              "description": ""
            }
          },
          "additionalProperties": false
        },
        "startingAdjustPrice": {
          "$ref": "#/definitions/numericField",
          "description": ""
        },
        "unDiscountedRate": {
          "$ref": "#/definitions/numericField",
          "description": ""
        },
        "startingAdjustRate": {
          "$ref": "#/definitions/numericField",
          "description": ""
        },
        "startingAdjPrice": {
          "$ref": "#/definitions/numericField",
          "description": ""
        },
        "branch": {
          "type": "object",
          "properties": {
            "approvalDate": {
              "$ref": "#/definitions/datePattern",
              "description": ""
            },
            "approvedBy": {
              "type": "string",
              "description": ""
            },
            "price": {
              "$ref": "#/definitions/numericField",
              "description": ""
            },
            "reasonForApproval": {
              "type": "string",
              "description": ""
            }
          },
          "additionalProperties": false
        },
        "corporate": {
          "type": "object",
          "properties": {
            "approvalDate": {
              "$ref": "#/definitions/datePattern",
              "description": ""
            },
            "approvedBy": {
              "type": "string",
              "description": ""
            },
            "price": {
              "$ref": "#/definitions/numericField",
              "description": ""
            },
            "reasonForApproval": {
              "type": "string",
              "description": ""
            }
          },
          "additionalProperties": false
        },
        "profitMarginAdjustedBuyPrice": {
          "$ref": "#/definitions/numericField"
        },
        "correspondent": {
          "type": "object",
          "properties": {
            "tradeId": {
              "type": "string",
              "description": ""
            },
            "tradeNumber": {
              "type": "string",
              "description": ""
            }
          },
          "additionalProperties": false
        },
        "lockDate": {
          "$ref": "#/definitions/datePattern",
          "description": ""
        },
        "lockExpirationDate": {
          "$ref": "#/definitions/datePattern",
          "description": ""
        },
        "lockNumberOfDays": {
          "$ref": "#/definitions/integerField",
          "description": ""
        },
        "baseRate": {
          "$ref": "#/definitions/numericField",
          "description": ""
        },
        "baseMarginRate": {
          "$ref": "#/definitions/numericField",
          "description": ""
        },
        "srpPaidOut": {
          "$ref": "#/definitions/numericField",
          "description": ""
        },
        "rateSheetId": {
          "type": "string",
          "description": ""
        },
        "lastRateSetDate": {
          "$ref": "#/definitions/datePattern",
          "description": ""
        },
        "adjustments": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/adjustmentItem"
          },
          "minItems": 1,
          "description": ""
        }
      },
      "additionalProperties": false,
      "required": [
        "baseRate"
      ],
      "oneOf": [
        {
          "required": [
            "lockDate",
            "lockNumberOfDays"
          ],
          "validationMessage": {
            "$ref": "#/validationMessage/oneOfBuySideSub"
          }
        },
        {
          "required": [
            "lockDate",
            "lockExpirationDate"
          ],
          "validationMessage": {
            "$ref": "#/validationMessage/oneOfBuySideSub"
          }
        },
        {
          "required": [
            "lockExpirationDate",
            "lockNumberOfDays"
          ],
          "validationMessage": {
            "$ref": "#/validationMessage/oneOfBuySideSub"
          }
        }
      ]
    }
  },
  "required": [
    "baseRate",
    "buySide"
  ],
  "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",
      "minimum": 0.001,
      "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"
      }
    },
    "adjustmentItem": {
      "type": "object",
      "properties": {
        "adjustmentType": {
          "type": "string",
          "enum": [
            "Adjustment",
            "LockExtensionAdjustment",
            "ReLockFeeAdjustment",
            "CustomPriceAdjustment"
          ],
          "description": ""
        },
        "description": {
          "type": "string",
          "description": ""
        },
        "priceAdjustmentType": {
          "type": "string",
          "enum": [
            "BasePrice",
            "BaseMargin",
            "BaseRate",
            "ProfitMargin"
          ],
          "description": ""
        },
        "adjustment": {
          "$ref": "#/definitions/numericField",
          "description": ""
        }
      },
      "required": [
        "adjustmentType",
        "description",
        "priceAdjustmentType"
      ],
      "additionalProperties": false
    }
  }
}

Below is a sample rate lock and confirm transaction result payload with most of the fields supported in the lock and confirm operation:

{
  "status": "completed",
  "loanFormat": "application/vnd.plm-2.0.0+json",
  "loan": {
    "applications": [
      {
        "borrower": {
          "equifaxScore": 750,
          "transUnionScore": 770,
          "firstName": "John",
          "lastName": "Smith",
          "firstNameWithMiddleName": "John Tyler",
          "fullName": "John Tyler Smith"
        },
        "coborrower": {
          "equifaxScore": 730,
          "transUnionScore": 740,
          "firstName": "Jane",
          "lastName": "Smith",
          "firstNameWithMiddleName": "Jane Mary",
          "fullName": "Jane Mary Smith"
        }
      }
    ],
    "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-and-confirm-1.0.0.json",
    "action": "LOCK_CONFIRM",
    "details": {
      "programNotes": "FreeForm Field to enter Program Notes blah blah",
      "planCode": "30-FIXED",
      "lockDate": "07/24/2020",
      "lockExpirationDate": "08/21/2020",
      "hedging": true,
      "penaltyTerm": "1 Year",
      "prepayPenalty": true,
      "baseRate": 1.65,
      "baseMarginRate": 0.5,
      "requestImpoundWaived": "Not Waived",
      "requestImpoundType": "Taxes only",
      "lenderFeeWaiverOption": true,
      "fhaUpfrontMiPremiumPercent": 2,
      "roundToNearest50": true,
      "adjustments": [
        {
          "adjustmentType": "Adjustment",
          "description": "Waive Escrow and Impounds",
          "priceAdjustmentType": "BasePrice",
          "adjustment": 0.75
        },
        {
          "adjustmentType": "Adjustment",
          "description": "Mobile Margin",
          "priceAdjustmentType": "BaseMargin",
          "adjustment": 0.5
        },
        {
          "adjustmentType": "Adjustment",
          "description": "60 Day Lock Period",
          "priceAdjustmentType": "BaseRate",
          "adjustment": 0.004
        },
        {
          "adjustmentType": "Adjustment",
          "description": "Extended Payment Option",
          "priceAdjustmentType": "BaseRate",
          "adjustment": 0.003
        }
      ],
      "rateSheetId": "RS9110",
      "lastRateSetDate": "06/05/2020",
      "basePrice": 12.11,
      "comments": "Testing lock and confirm",
      "buySide": {
        "expirationDate": "07/21/2020",
        "delivery": {
          "type": "hello",
          "expirationDate": "07/21/2020"
        },
        "startingAdjustPrice": 1.3,
        "unDiscountedRate": 1.1,
        "startingAdjustRate": 1.2,
        "startingAdjPrice": 1.3,
        "branch": {
          "approvalDate": "07/08/2020",
          "approvedBy": "someone",
          "price": 21.21,
          "reasonForApproval": "some reason"
        },
        "corporate": {
          "approvalDate": "07/08/2020",
          "approvedBy": "someone",
          "price": 11.21,
          "reasonForApproval": "dont know"
        },
        "profitMarginAdjustedBuyPrice": 0.26,
        "correspondent": {
          "tradeId": "3242",
          "tradeNumber": "Trade-1234"
        },
        "lockDate": "07/21/2020",
        "lockExpirationDate": "08/30/2020",
        "baseRate": 4.3,
        "baseMarginRate": 12.14,
        "rateSheetId": "New ratesheet Id",
        "lastRateSetDate": "05/07/2020",
        "srpPaidOut": 41.5,
        "adjustments": [
          {
            "adjustmentType": "Adjustment",
            "description": "Waive Escrow and Impounds 1",
            "priceAdjustmentType": "BasePrice",
            "adjustment": 0.11
          },
          {
            "adjustmentType": "Adjustment",
            "description": "Mobile Margin 1",
            "priceAdjustmentType": "BaseMargin",
            "adjustment": 0.22
          },
          {
            "adjustmentType": "Adjustment",
            "description": "60 Day Lock Period 1",
            "priceAdjustmentType": "BaseRate",
            "adjustment": 0.33
          },
          {
            "adjustmentType": "Adjustment",
            "description": "",
            "priceAdjustmentType": "ProfitMargin"
          },
          {
            "adjustmentType": "Adjustment",
            "description": "LO Comp",
            "priceAdjustmentType": "ProfitMargin",
            "adjustment": 0.99
          }
        ]
      }
    }
  },
  "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"
}

Cancel Lock Request


Pricing engine integrations can request to cancel a confirmed lock by implementing the CANCEL action supported by our custom transaction result operations. The CANCEL action uses a comment attribute, where the integration can provide cancellation reasons or other free form text they would like to be recorded.

Below is the JSON-schema specification for the CANCEL transaction results details object:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "comments": {
      "type": "string",
      "description": "Reason for cancellation"
    }
  },
  "required": [
    "comments"
  ],
  "additionalProperties": false
}

🚧

Rate lock CANCEL operation constraints

The CANCEL result action can be performed only if there is a confirmed rate lock on the subject loan. If the loan does not have a confirmed rate lock, the cancel request is not applicable and will error out.

Below is a sample payload for the cancel request operation:

{
  "status": "completed",
  "result": {
    "format": "application/vnd.productpricing-cancellock-1.0.0.json",
    "action": "CANCEL",
    "details": {
      "comments": "Cancelling lock, as borrower changed their mind"
    }
  }
}

Extend Rate Lock Request


The EXTEND action allows EPC integrations to extend the expiration date for an existing confirmed rate lock. In the process of extending the rate lock expiration, the integrations can also send Price Adjustments in $.result.details.lockExtendPriceAdjustment and an extension reason in $.result.details.comments attribute. The JSON-schema definition below details supported attributes for the extend operation:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "comments": {
      "type": "string",
      "description": ""
    },
    "daysToExtend": {
      "$ref": "#/definitions/integerField",
      "description": ""
    },
    "lockExtendPriceAdjustment": {
      "$ref": "#/definitions/numericField",
      "description": ""
    }
  },
  "required": [
    "daysToExtend",
    "lockExtendPriceAdjustment"
  ],
  "additionalProperties": false,
  "definitions": {
    "integerField": {
      "type": "integer",
      "minimum": 1
    },
    "numericField": {
      "type": "number",
      "minimum": 0.001,
      "multipleOf": 0.001
    }
  }
}

🚧

Rate lock EXTEND result constraints

Rate lock extensions can be requested only on confirmed and not yet expired rate locks.

Below is a sample payload for the extend request operation:

{
  "status": "completed",
  "result": {
    "format": "application/vnd.productpricing-extendlock1.0.0.json",
    "details": {
      "comments": "Extending by 10 days to accomodate for delays in closing",
      "daysToExtend": 10,
      "lockExtendPriceAdjustment": 0.025
    }
  }
}

Rate Relock Request


EPC supports making changes to an existing locked rate on a loan via the RELOCK action. An integration can use RELOCK to update rates, pricing, and adjustments. The relock operation inputs are similar to those of the lock request operation; however, the relock operation is handled differently whether it is performed on a Cancelled rate lock or Confirmed rate lock.

📘

Relock validations on a cancelled lock

If the rate lock is in a cancelled state, the relock action requires a base rate and at least two of the $.result.details.lockDate, $.result.details.lockNumberOfDays, and $.result.details.lockExpirationDate fields.

📘

Relock on a confirmed lock

The relock action on confirmed locks does not have any required fields and accepts all of the fields supported in the lock request. The field values that are not included are carried over from the existing confirmed lock.

The JSON-schema definition below details supported attributes for the re-lock operation:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "comments": {
      "type": "string",
      "description": ""
    },
    "programNotes": {
      "type": "string",
      "description": ""
    },
    "planCode": {
      "type": "string",
      "description": ""
    },
    "lockDate": {
      "$ref": "#/definitions/datePattern",
      "description": ""
    },
    "lockExpirationDate": {
      "$ref": "#/definitions/datePattern",
      "description": ""
    },
    "lockNumberOfDays": {
      "$ref": "#/definitions/integerField",
      "description": ""
    },
    "gpmRate": {
      "$ref": "#/definitions/numericField",
      "description": ""
    },
    "gpmYears": {
      "$ref": "#/definitions/integerField",
      "description": ""
    },
    "lastRateSetDate": {
      "$ref": "#/definitions/datePattern",
      "description": ""
    },
    "correspondentCommitmentType": {
      "type": "string",
      "enum": [
        "Best Efforts",
        "Mandatory"
      ],
      "description": ""
    },
    "correspondentDeliveryType": {
      "type": "string",
      "description": ""
    },
    "isDeliveryType": {
      "type": "boolean",
      "description": ""
    },
    "hedging": {
      "type": "boolean",
      "description": ""
    },
    "penaltyTerm": {
      "type": "string",
      "enum": [
        "1 Year",
        "2 Years",
        "3 Years"
      ],
      "description": ""
    },
    "currentAcquisition": {
      "type": "boolean",
      "description": ""
    },
    "currentConstructionRefi": {
      "type": "boolean",
      "description": ""
    },
    "prepayPenalty": {
      "type": "boolean",
      "description": ""
    },
    "baseRate": {
      "$ref": "#/definitions/numericField",
      "description": ""
    },
    "basePrice": {
      "$ref": "#/definitions/numericField",
      "description": ""
    },
    "baseMarginRate": {
      "$ref": "#/definitions/numericField",
      "description": ""
    },
    "rateSheetId": {
      "type": "string",
      "description": ""
    },
    "requestImpoundWaived": {
      "type": "string",
      "enum": [
        "Waived",
        "Not Waived",
        ""
      ],
      "description": ""
    },
    "requestImpoundType": {
      "type": "string",
      "enum": [
        "No Impounds",
        "Insurance only",
        "Taxes only",
        "Taxes and Insurance",
        ""
      ],
      "description": ""
    },
    "lenderFeeWaiverOption": {
      "type": "boolean",
      "description": ""
    },
    "sellerPaidMiPremium": {
      "$ref": "#/definitions/integerField",
      "description": ""
    },
    "fhaUpfrontMiPremiumPercent": {
      "$ref": "#/definitions/integerField",
      "description": ""
    },
    "roundToNearest50": {
      "type": "boolean",
      "description": ""
    },
    "adjustments": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/adjustmentItem"
      },
      "minItems": 1,
      "description": ""
    }
  },
  "additionalProperties": false,
  "definitions": {
    "integerField": {
      "type": "integer",
      "minimum": 1
    },
    "numericField": {
      "type": "number",
      "minimum": 0.001,
      "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": "Date should be in the format MM/DD/YYYY."
    },
    "adjustmentItem": {
      "type": "object",
      "properties": {
        "adjustmentType": {
          "type": "string",
          "enum": [
            "Adjustment",
            "LockExtensionAdjustment",
            "ReLockFeeAdjustment",
            "CustomPriceAdjustment"
          ],
          "description": ""
        },
        "description": {
          "type": "string",
          "description": ""
        },
        "priceAdjustmentType": {
          "type": "string",
          "enum": [
            "BasePrice",
            "BaseMargin",
            "BaseRate",
            "ProfitMargin"
          ],
          "description": ""
        },
        "adjustment": {
          "$ref": "#/definitions/numericField",
          "description": ""
        }
      },
      "required": [
        "adjustmentType",
        "description",
        "priceAdjustmentType",
        "adjustment"
      ],
      "additionalProperties": false
    }
  }
}

As mentioned above, the re-lock operation is very similar to the rate lock operation. In the sample payload illustrated below, the only difference from the rate lock sample seen above is the value in the $.result.resultFormat` field:

{
  "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-relock-1.0.0.json",
    "action": "RELOCK",
    "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"
}

Deny Lock Request


A lock request can be cancelled by the secondary desk officer if it does not meet the required criteria.

📘

Deny Lock Action Details

Deny Lock accepts the lock id.

  • When no lock id is passed by the consumer, EPC treats that as request to deny lock in requested state only, i.e. EPC only tries to find an active lock in requested state and denies that. This is to prevent the integration from inadvertently denying a confirmed lock.
  • If the integration explicitly passes the lockId, then EPC does not check if the lock is in requested or confirmed state, and passes through for Encompass APIs. It is recommended that you exercise additional caution when using this functionality.

The JSON-schema definition below details supported attributes for the Deny Lock operation:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "description": "JSON representation of a deny lock request transaction result.",
  "validationMessage": {
    "uuidPattern": "UUID. It must be a valid UUID format"
  },
  "properties": {
    "lockId": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "validationMessage": {
        "$ref": "#/validationMessage/uuidPattern"
      }
    },
    "comments": {
      "type": "string"
    }
  },
  "required": [
    "comments"
  ],
  "additionalProperties": false
}

Below is a sample payload for the Deny Lock request operation:

{
  "status": "Completed",
  "result": {
    "format": "application/vnd.productpricing-denylock-1.0.0.json",
    "action": "DENY",
    "details": {
      "lockId": "84dc19a5-24be-485a-831e-2420b92608e2",
      "comments": ""
    }
  }
}

If you need any help implementing the custom result operations detailed above in your integration, you can post your questions and/or look for answers on our Discussion board. Our discussion board is actively tracked by a community of experts who are available to help you out when you get stuck. You can also send your questions and issues to the EPC core development team at [email protected]. Happy hacking!


Did this page help you?