Developer Guides

Rate Relock

Suggest Edits

EPC supports making changes to an existing locked rate on a loan through 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 depending on whether it is performed on a cancelled or a confirmed rate lock.

📘

Schema versions

This page documents application/vnd.productpricing-relock-1.0.0.json. Other versions of the RELOCK action:

  • Rate Relock v1.1 (application/vnd.productpricing-relock-1.1.0.json): adds investor, impoundWaived, and impoundType, and allows an empty penaltyTerm.
  • Rate Relock v2 (application/vnd.productpricing-relock-2.0.0.json): restructures details into request, buy, sell, and comparison sides.

📘

Relock validations on a cancelled lock

If the rate lock is in a cancelled state, the relock action requires a base rate and 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. Field values that are not included are carried over from the existing confirmed lock.

The JSON schema below details the supported attributes for the relock operation:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "validationMessage": {
    "datePattern": "Date should be in the format MM/DD/YYYY.",
    "timePattern": "Time should be in the format HH:MM",
    "oneOfAdditionalFields": "fieldName and one of stringValue, numericValue and dateValue is required."
  },
  "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": ""
    },
    "programNotes": {
      "type": "string",
      "description": ""
    },
    "planCode": {
      "type": "string",
      "description": ""
    },
    "lockDate": {
      "$ref": "#/definitions/datePattern",
      "description": ""
    },
    "lockExpirationDate": {
      "$ref": "#/definitions/datePattern",
      "description": ""
    },
    "lockNumberOfDays": {
      "$ref": "#/definitions/integerField",
      "description": ""
    },
    "startingAdjustRate": {
      "$ref": "#/definitions/numericField",
      "description": ""
    },
    "startingAdjustPrice": {
      "$ref": "#/definitions/numericField",
      "description": ""
    },
    "unDiscountedRate": {
      "$ref": "#/definitions/numericField",
      "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",
        "4 Years",
        "5 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/numericField",
      "description": ""
    },
    "roundToNearest50": {
      "type": "boolean",
      "description": ""
    },
    "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": ""
    },
    "additionalFields": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/additionalFieldItem"
      },
      "minItems": 1,
      "description": "Additional fields in the rate lock."
    }
  },
  "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": ""
        },
        "description": {
          "type": "string",
          "description": ""
        },
        "priceAdjustmentType": {
          "type": "string",
          "enum": [
            "BasePrice",
            "BaseMargin",
            "BaseRate",
            "ProfitMargin"
          ],
          "description": ""
        },
        "adjustment": {
          "$ref": "#/definitions/adjustmentNumericField",
          "description": ""
        }
      },
      "required": [
        "adjustmentType",
        "description",
        "priceAdjustmentType"
      ],
      "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 additonal field"
        },
        "stringValue": {
          "type": "string",
          "minLength": 1,
          "description": "String value for the additonal field"
        },
        "dateValue": {
          "$ref": "#/definitions/datePattern",
          "description": "Date value for the additonal 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
    }
  }
}

The relock sample payload below is similar to the rate lock sample. The $.result.format and $.result.action values identify the request as a relock:

{
  "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": "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"
}

To deny a lock request, use the DENY action.

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

Updated about 24 hours ago