Download Postman Collection
Guides

Breaking Change Notices

Suggest Edits

🚧

Breaking Changes

Please review these notices and make the necessary changes to your integration before the specified release to avoid disruptions.

Encompass Developer Connect 25.4

Performance Improvements - Get External Users

In the upcoming 25.4 release, the V3 Get All External Users API is scheduled for the following enhancements for improved performance:

  • The API will return the response with minimal data. A new query parameter will be added to retrieve either the summary or full payload.
  • The pagination for this API will be enhanced to enforce a maximum limit.
  • The default list response will exclude disabled users. A new query parameter will be added to enable retrieving all users, including disabled users.

EDC-1143

Encompass Developer Connect 25.3

Settings: External Users

The ‘designatedRoles’ attribute in the External Users Contract will be deprecated in the upcoming 25.3 release scheduled for Q4 of 2025. This attribute is being replaced with the ‘designatedRoleRefs’ attribute.

Deprecating "status" Attribute in eFolder Document Contract

ICE Mortgage Technology will be deprecating the "status" attribute in the eFolder Document Contract in the upcoming 25.3 release scheduled for Q4 of 2025. The following API endpoints now use the more relevant "documentStatus" attribute in favor of the "status" attribute:

🚧

Please begin efforts to discontinue further usage of the "status" attribute before release 25.3.

EDC-1121

Extra Payload for ‘move’ Webhook Event

In the upcoming 25.3 release, extra payload is being added to the 'move' event that is part of the Loan Resources Events for webhooks. Extra payload will include the previous loan folder (previousLoanFolder) and new loan folder (newLoanFolder). This will enable you to see the folder that the loan was in before, and after, the move event occurred. No change is needed to any existing 'move' event subscriptions. Once this change is released in 25.3, the extra payload will be included in any 'move' event received from that point forward. Customers and partners that strictly validate the webhook schema to reject unknown fields will need to adopt their process to retrieve the extra payload in the ‘move’ webhook event.

EDC-1144

External Organizations Access Controls

A series of External Organization API endpoints have been updated to include the following additional access controls:

The logged in user must satisfy either of the following three conditions for the organization:
The user is a primary sales rep/AE.
The user is an additional sales rep/AE.
The user is having persona check 'Global company/user delegation access' enabled.

The affected API endpoints are the following:

EDC-1154

Encompass Developer Connect 25.2

40 MB Loan File Size Limitation

All API endpoints that require opening the loan file have been updated to limit read/write operations to loan file sizes less than 40 MB. The following error will be returned if the limit is reached:
EBS-5006 - Loan file size exceeded max limit
The possibility of reaching this limit is very low. However, if you do receive this error, you can still retrieve the loan using the Encompass desktop application.

📘

The supported loan file size limit is different from the gateway response payload limit. No matter the loan file size, Encompass Developer Connect APIs cannot send a response that exceeds 6 MB.

Although uncommon, you may run into a situation where the response payload for a loan PATCH call is greater than the 6 MB limit, but less than 40MB loan file size. In this scenario, the loan will be successfully updated as indicated in the request, however, you will see a 400 "Response exceeds maximum size (6 MB)" error indicating that the response is too large.

Therefore, it is encouraged to compress the response by sending the Accept-Encoding: gzip header in the HTTP request. If the header is present, the response will be compressed using gzip and will include the Content-Encoding: gzip header in the response. You will then decompress the response before processing.

Please note, the compression doesn't always result in dramatic reductions - like shrinking a 35MB file down to 5MB, the savings depend on the content type and if its already in compressed mode (e.g., documents).

See API Pagination - Response Payload Size Limit for more details.

EDC-1099

EditBidTapeManagement Persona Rename

The following API endpoints have been updated to have the "BidTapeManagement" personas renamed to "EditBidTapeManagement" in the response payload to comply with a recent Encompass Admin enhancement that renamed the Edit Bid Tape Management tab to Edit Bid Tape Acquisitions.

EDC-1130

Disclosure Tracking ‘contents’ Array Error Handling

Previously, the V3 Add a Disclosure Tracking Log and V3 Update a Disclosure Tracking Log APIs had no error handling to ensure that items in the 'contents' array in the request payload be unique. This could lead to subsequent errors in displaying disclosure tracking records in the Encompass user interface. In release 25.2, these APIs have been updated to include ‘contents’ array error handling. If duplicate values are provided in the ‘contents’ array, the APIs will now return the following error:

{
    "summary": "Bad Request",
    "details": "Request Payload has errors",
    "errors": [
        {
            "summary": "contract.contents",
            "details": "Items in the collection should be unique. The value 'LE' appears multiple times in the collection."
        }
    ]
}

EDC-1148

Encompass Developer Connect 25.1

Get External User API Change in Behavior when Query Parameter isRecursive=true

When external users are added to an external organization in one of the child orgs of type company extension, branch, branch extension, and if the “Visible in TPOWC site” check box is not set, then when calling the Get External Users API for a given orgId with a query parameter isRecursive=true, the users from the child orgs are not returned. However, when the TPOWC site checkbox is checked, all users for parent and the child orgs are returned.

The API behavior will be fixed to get external users from all companies, branches and extensions without having to mark the setting "Visible in TPOWC site" in the company settings. All external users including those that are added to a child organization will be returned when query parameter isRecursive=true is passed.

What is changing?

API Endpoint: V3 Get All External Users

Currently, when external users are added to an external organization in one of the child orgs of type company extension, branch, branch extension, and if the “Visible in TPOWC site” check box is not set, then when calling the Get External Users API for a given orgId with a query parameter isRecursive=true, the users from the child orgs are not returned. However, when the TPOWC site checkbox is checked (or query parameter "includeInVisibleInTpowcSite=true”), all users for parent and the child orgs are returned.

The API behavior will be fixed to get external users from all companies, branches and extensions without having to mark the setting "Visible in TPOWC site" in the company settings (or having to pass "includeInVisibleInTpowcSite=true" as a query parameter). All external users including those that are added to a child organization will be returned when query parameter isRecursive=true is passed.

Example:

  • Before 25.1 Release
    Example: /encompass/v3/externalUsers?orgId=6263&isRecursive=true&includeInVisibleInTpowcSite=true
  • After 25.1 Release
    Example: /encompass/v3/externalUsers?orgId=6263&isRecursive=true

EBSP-53154, EDC-986

Channel Option Controls 

When creating a new loan or updating an existing loan using V3 APIs, the “channel” request attribute currently accepts any value, including the options not enabled for use in the Encompass Loan Setup > Channel Options setup screen. Since this is not expected behavior, the V3 Loan API will be updated to enforce the validation of the Channel Options settings when creating or updating the loan via an API. If the user attempts to pass a Channel Option not enabled for use for your version of Encompass, an error will be returned.

EBSP-54046

Encompass Developer Connect 24.3

Settings of External Organizations

EDC-1056

The following API endpoints are being updated to align with an upcoming new GET API being released in 24.3. Therefore, breaking changes need to be made to the contract for the following External Organization APIs that are available as of release 24.2:

The following fields will no longer be returned in the response of the Custom Fields object:

  • description
  • format
  • loanFieldId

Previously, the persona check was applied at the root level. Now, we are implementing more granular controls and applying the persona check at a tab level.


Encompass Developer Connect 24.2

V3 Loan APIs

EBSP-49691

Change to Payload Response Behavior

The following log entities are currently being returned in the V3 Loan APIs response when no view parameters are passed OR if view = entity OR if view=full. These entities are not returned when view=logs. This is not expected behavior, and therefore a change will be made effective 24.2 release to return the mentioned entities only when view=logs or view=full. Log entities will not be included when view is not passed. If your application is counting on the presence of these entities, you can leverage the query parameter view=logs or view=full to receive the log data.

  • PostClosingConditions
  • PreliminaryConditions
  • UnderwritingConditions
  • LoanActionLogs
  • LockRequests
  • MilestoneFreeRoles
  • MilestoneTasks
  • LockDenials
  • LockConfirms

As a result of this update, users will experience a faster response time when using the V3 Loan APIs. For example:

  • The V3 Get Loan calls with includeEmpty=false were observed to be performing ~20% faster than includeEmpty=true.
    • Please note, the includeEmpty=false query parameter is the default value for the V3 Get loan API.
  • The V3 Update Loan calls also show ~7% better response time with includeEmpty=false.
  • The V3 Create Loan calls show marginal improvement of ~1% with includeEmpty=false.

Loan Field Reader API

EBSP-45807

The default value for invalid field behavior will be to fail the request, if invalid fields are provided, and the query parameters are not provided. If you need to provide invalid field IDs and receive a blank response back for any reason, field reader can be called with parameter “invalidFieldBehavior” as “Include”.

Channel Option Controls

EBSP-54046

When creating a new loan or updating an existing loan using V3 APIs, the “channel” request attribute currently accepts any value, including the options not enabled for use in the Encompass Loan Setup > Channel Options setup screen. This is not expected behavior, and therefore, the V3 Loan API will be updated to enforce the validation of the Channel Options settings when creating or updating the loan via an API. If the user attempts to pass a Channel Option not enabled for use for your version of Encompass, an error will be returned.

SCIM Provisioning API

EDC-928

  • The SCIM User Provisioning API is now enforcing only one product schema to be passed for all CRUD operations, supporting user management for one product at a time.
  • The “schemas” query parameter is renamed to “schema” for all GET and DELETE calls to support user management for one product at a time.
  • The structure of the error response payload will be streamlined to support user management for one product at a time.
  • The core SCIM user schema 'urn:ietf:params:scim:schemas:core:2.0:User' must now be included for all POST/users, POST/accounts and PATCH/accounts API calls.
  • The default behavior for DELETE scim2/v1/users API will be modified to trigger a soft delete to deactivate the user profile in Encompass/DDA. Hard user delete will not be feasible via the SCIM API.
  • Now enforcing path attribute for all remove operations when updating users and groups.
  • The SCIM GET User/Users API previously returned all SCIM and non-SCIM users in the response. The API response now only returns users with SCIM globalUserId.

External User State License Contract Correction for "stateAbbreviation"

EBSP-54853, EDC-985

The External User State License Contract is updated to correct a typographical error in the 24.2 release. The contract attribute "stateAbbrevation" is renamed to "stateAbbreviation" to correct the typographical error. The following APIs are impacted by this change:

  • V3 Get All External Users
    GET encompass/v3/externalUsers
  • V3 Get an External User
    GET encompass/v3/externalUsers/{userId}
  • V3 Manage External Users
    PATCH encompass/v3/externalUsers

In addition, the legacy V3 External Organizations and V3 Get an External Organization API response payload is updated to rename stateAbbrevation to stateAbbreviation. This change impacts the following endpoints.

  • GET /encompass/v3/externalOrganizations/tpos
  • GET /encompass/v3/externalOrganizations/tpos/{orgId}

Additional Payload Added for EPC Service Order Resource

EDC-1011

The Service Order webhook resource will be updated to include extra payload in the event notification. This change is applicable to all Service Order webhook events. Using the added attributes, lenders can filter out webhooks that they need to work on based on the webhook itself, instead of polling the GET Service Order Status API for every Service Order webhook they receive.

The following attributes will be added:

  • productListingName - The name of the product as listed by the EPC partner.
  • productId - The unique identifier of the EPC partner product.
  • partnerId - The unique identifier of the EPC partner.

Subscribers of the Service Order webhook notifications need to update their implementation to account for the newly added attributes to avoid disruptions.

Encompass Developer Connect 23.3

Loan Schema updates

EDC-923, CBIZ-52826

To help ensure the logic to populate the Counseling Confirmation and Counseling Format type information on the Fannie Mae ULDD XML adheres to Fannie Mae’s Appendix D requirements, the loan-level First-Time Homebuyer field (field ID 934) on the ULDD/PDD input form has been replaced with two new borrower-level fields: Borrower First-Time Homebuyer (field ID 4973) and Co-Borrower First Time Homebuyer (field ID 4974). Utilizing these two new borrower-level fields enables Encompass to capture separate values for the borrower and co-borrower as opposed to capturing just one value for first-time borrower status with the singular loan-level field. The field ID 934 is still provided on other Encompass input forms, such as the Borrower Summary - Origination, Property Information, Fannie Mae Additional Data, and Freddie Mac Additional Data input form forms, however, this field is now padlocked.

Impact to API Users

  • Starting with the 23.3 release, this will be a breaking change if you are currently writing to the First Time Home Buyers field ID 934. If you need to update field ID 934 via the loan update API, you can do so using one of the following options:

Option 1 (Recommended)

Send the corresponding borrower (field ID 4973) or coborrower (field ID 4974) first time home buyer indicator fields in the payload in order for Encompass to calculate the value of field ID 934.

{
    "applications": [
        {
            "id": "{ApplicationId}",
            "borrower": {
                "firstTimeHomebuyerIndicator": true
            },
            "coborrower": {
                "firstTimeHomebuyerIndicator": false
            }
        }
    ]
}

OR

Option 2

Padlock the field ID 934 to write to the prior value by adding it to the FieldLockData collection. 

{
    "firstTimeHomebuyersIndicator": true,
    "fieldLockData":[
        "loan.firstTimeHomebuyersIndicator"
    ]
}

{
    "firstTimeHomebuyersIndicator": true,
    "fieldLockData": [
        {
            //"lockRemoved": true,
            "modelPath": "loan.firstTimeHomebuyersIndicator"
            
        }
    ]
}

Encompass Developer Connect 23.1

Upcoming Changes to V3 Loan Contract Attributes

With the release of Developer Connect 23.1 in 2023, the attribute type for V3 Loan contract attributes ApplicantType and isBorrower will change to ReadOnly. ICE Mortgage Technology recommends removing usage of these fields prior to the 23.1 release.

The following error will be thrown if either attribute is passed in the payload after the release of 23.1.

{
    "summary": "Bad Request",
    "details": "Request Payload has errors",
    "errors": [
        {
            "summary": "loanContract.applications[0].borrower.applicantType",
            "details": "The ApplicantType field is readonly."
        },
        {
            "summary": "loanContract.applications[0].borrower.isBorrower",
            "details": "The IsBorrower field is readonly."
        }
    ]
}

Encompass Developer Connect 22.2

Change Made to V1 Loan Contract

With the release of Developer Connect 22.2, the attribute type for V1 Loan contract attributes ApplicantType and BorrowerIndex was changed to ReadOnly. These attributes now have the same behavior as other ReadOnly properties in V1 Create/Update Loan.

Updated about 1 month ago

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