Download Postman Collection
Guides

Compliance Calendar Date Calculator API User Guide

Suggest Edits

Overview

Use the Compliance Calendar Date Calculator API to calculate a date (completionDateTime). The calendars available in Encompass Settings can be used for the calculation. The source (starting point) of the calculation can either be a specified date and time, or a date field value that exists on a loan.

📘

Scheduler Service Best Practice Guide

This calculator is used as part of the Scheduler Service in Encompass. For more details, also see the Scheduler Service Best Practice Guide located in the Scheduler Templates Encompass Help topic. This best practice guide also contains a use cases configuration matrix.

This API is published as a standalone calculator in Encompass Developer Connect to enable you to calculate dates using the Compliance Calendars in the same way that the Encompass Scheduler Service performs this task.

🚧

This calculator will not trigger Scheduler Service Webhooks.

This API includes the following documentation pages:

Special Usage Notes

  • The only calculation duration that is currently supported is ‘days’. The calculator will add, or subtract, the number of days you input into the request. You can also specify a Time of Day and Time Zone, which will be appended to the calculated date.
  • The calculator can be used as a tool to confirm your Scheduler Template configurations in Encompass. You can simulate the calculation that will occur on a loan, when the Scheduler Template is applied at runtime to see the date the Scheduler would complete.

Request Payload

The request payload contains the completionBasis object with all the attributes that will be used by the calculator to derive the completionTime.

Date Source

Object containing the source data used for the Completion Date calculation. The source data will identify the starting point used in the calculation.

The two types of date sources in the request payload are the following:

Date Source = “event”

When date source = “event”, you must specify a date/time in the “eventDate” attribute. This date/time must be in UTC format, example: 2025-01-31T00:00:00Z.

📘

The duration of the calculation is days. Shorter intervals (e.g., hours, minutes) are not supported. When date source = “event”, consider always using midnight UTC (00:00:00Z) as the time portion of the event date/time.

        "dateSrc": { 
            "source": "event",
            "eventDate": "2025-02-03T00:00:00Z"//specified date/time in UTC
        }

Date Source = “loan”

When date source = “loan”, you must specify a loanId (Loan GUID) and loan date field (e.g., Field 3142 GFE Application Date) that will be used as the starting point for the calculation. The field ID must be for a date field.

        "dateSrc": { 
            "source": "loan",
            "loanId": "{{loanId}}",//the Loan GUID for the specified loan
            "fieldKey": "3142"//the field ID for the date field you want to use.
        }

Calendar

Calendar to be used for the completion date calculation. The following calendars are supported:

  • Postal - U.S Postal Calendar
  • Business - Our Company Calendar
  • Custom - Custom Lock Desk Calendar
  • RegZ - Reg-Z Business Day Calendar
  • AllDays - No Encompass Calendar is used. Full 365/366 day calendar, depending on whether it is a leap year. This is the default.

Offset

The number of days to add or subtract from the source date, positive or negative.

  • The only calculation duration currently supported is “days”.
  • The “offset” provided is an integer representing the number of days before, or after, the date source.
  • The calculator will add or subtract those number of days from the Date Source, using the Encompass Calendar provided.

Start from Closest Business Day

With this attribute, you can specify what to do when the source date is on a non-business day per the calendar specified (e.g., Sunday, February 2nd, 2025).

  • startFromClosestBusinessDay = true
    • This property is optional. When not provided, this is the default value.
    • If the source date falls on a non-business day, per the Compliance Calendar, the next business day (e.g. Monday, February 3rd, 2025) will be used as the starting point (time zero) for the calculation.
  • startFromClosestBusinessDay = false
    • The source date provided will be used, even if it falls on a non-business day.

      📘

      This option can be useful when using compliance dates that can fall on non-business days as your date source, such as field 3142 GFE Application Date. If you want to make sure the starting point is the GFE Application Date, even when it’s on a non-business day, then use startFromClosestBusinessDay = false in your request.

Time Zone

Time Zone is required. The following Time Zones are supported:

  • AKT - Alaska Time
  • MST - Arizona Time
  • CT - Central Time
  • ET - Eastern Time
  • HST - Hawaii Time
  • MT - Mountain Time
  • PT - Pacific Time
  • UTC - Coordinated Universal Time

📘

Special Notes

  • UTC can be used to support any other worldwide time zone.
  • To adjust to any other time zone, you must also provide the Time of Day.
  • Convert the Time of Day for that region to the equivalent time in UTC.

    Example: For 8:00 AM AST (Atlantic Standard Time), configure the equivalent time in UTC – Time of Day “12:00” AND Time Zone “UTC”.

🚧

Time zones that use Daylight Savings time automatically adjust when the time switch occurs.

Time of Day

Time of Day is Required. The Time of Day (timeOfDay) specified in the request will be appended to calculated Completion Date to make the full completionTime.

Example: If Completion Date is February 5th 2025 (Feb. 3rd + 2 days), the timeZone provided is ‘PT’, and the Time Of Day is 09:00, then the completionTime will be February 5th 9:00 am PT, which will be output in UTC as 2025-02-05T17:00:00:00Z

Request Sample Payload - dateSrc = event

{
    "completionBasis": {
        "dateSrc": { 
            "source": "event",
            "eventDate": "2025-02-04T00:00:00Z"
        },
        "calendar": "RegZ",
        "offset": "5",
        "startFromClosestBusinessDay": true
        "timezoneCode": "UTC",
        "TimeOfDay": "00:00"
    }
}

Request Sample Payload - dateSrc = loan

{
    "completionBasis": {
        "dateSrc": { 
            "source": "loan",
            "loanId": "{{loanId}}",
            "fieldKey": "3142"
        },
        "calendar": "RegZ",
        "offset": "5",
        "startFromClosestBusinessDay": false, 
        "timezoneCode": "UTC",
        "TimeOfDay": "08:00"
    }
}

Response

The response is the calculated Completion Date/Time (completionTime), based on the attributes provided in the Request Payload.

Completion Time (Date/Time)

The calculator will convert the date and time to UTC. You must convert that UTC to the desired time and timezone for any downstream processes.

Example:

  • In the request you indicate that the Time of Day and Time Zone are 16:00 PT (4:00 pm PT).
  • The calculated Completion Date is 2/14/2025.
  • 16:00 PT is actually midnight the next day in UTC. So, the completionTime will show as 2025-02-15T00:00:00Z. Notice that it is 2/15/2025, but when converted back to PT, it is actually 2/14/2025 at 4:00 pm PT.

The calculated completionTime cannot be for a date that is in the past. If the calculation results in a past date, one of the following things will happen:

  • If the date source (dateSrc) is today’s date AND the offset = 0 AND the timeOfDay is in the past, the completionTime will be converted to the current date/time (Time = Now).
  • Else if the date source is not today’s date, you will receive the following error message: "409 - Calculated completion date is past date."

The completionTime cannot be calculated when it exceeds the maximum date allowed by the calendars in Encompass Settings. If a calculation results in a date that goes beyond the maximum date allowed by Encompass Settings, you will receive the following error message: "409 - Calculated completion date is outside the range of the configured Compliance Calendar: '2000-01-01' - 'yyyy-mm-dd'."

Validation of Completion Date

  1. To manually validate the completionTime, use the properties provided in the request payload.

  2. Find the Encompass calendar you are using in Encompass Settings. Then, count the number of days (offset) on the calendar. Exclude any dates that are shaded pink from the calculation. The date of the completionTime date should match your manual calculation.

  3. Finally, append the Time of Day and Time Zone to the calculated Completion Date, converting back to UTC.

    • Time Zone = PT
    • Time of Day = 08:00
    • Completion Date/Time = Completion Date 2/19/2025 + Append 08:00 PT, and then convert back to UTC = 2025-02-19T16:00:00Z

Updated 20 days ago

© ICE Mortgage Technology, Inc. All rights reserved. Terms of Use