Developer Guides

Rate Relock

Suggest Edits

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!

Updated 12 months ago