Overview

ICE Mortgage Technology (ICE MT) customers and partners leverage the Encompass Software Development Kit (SDK) to integrate, customize and extend the Encompass LOS. Some of the common use cases for the use of the SDK include the following:

• Automating the loan origination process.
• Integration with third party systems like credit bureaus, service ordering and underwriting systems.
• Custom business logic to create custom fields and calculations to loan records.
• Scripting and plugins extending Encompass with custom tools, plugins, etc.
• Customization of the user interface with the user of custom tools and plugins for enhanced user experience.

The Encompass SDK was introduced in the early 2000’s and since then has been widely adopted by the mortgage industry. However, both the mortgage industry and the Encompass platform have undergone significant evolution. Various regulations, technology innovations and industry changes have impacted how lenders originate. In recent years, the Encompass platform has shifted towards cloud-based APIs to provide better flexibility, scalability and easier integrations.

In the sections below, you will learn more about the benefits of migrating from Encompass SDK to Encompass Developer Connect (EDC) APIs, as well as resources for getting started with your migration journey.

Benefits of Migrating from Encompass SDK to APIs

Migrating from SDK to APIs comes with key advantages prioritizing flexibility, scalability and easier integration with Encompass. The table below highlights the value add and the differences between the two approaches.

Getting Started on SDK to API Migration

Migrating from Encompass SDK to APIs involves several steps to ensure that your current functionality is replicated or improved using the API architecture. Here are a few starting steps to get you started.

Review additional steps below to aid in your migration journey.

Step 1: Audit Current SDK Usage

Identify all custom workflows, automations and integrations currently built using the Encompass SDK.

On the Encompass Home page in the Customization Reporting module, the SDK and Plugin tabs are listed. This provides lists of each SDK app and plugin name, the date when the app or plugin was last launched or run, and the number of times the app or plugin was launched or run within the specified date range.

📘

Customers with Premier Support can also submit a request for a list of SDK usage specifically for your Encompass instance. Please reach out to your Premier Support team for more information.

Focus on critical functions that need to be migrated, such as field updates, data exports.

In addition, please review the Partner Marketplace for all Encompass Partner Connect (EPC) integrations available for 3rd party service ordering integrations. The EPC integrations leverage our “Build Once, Use Everywhere” methodology. Once partners build and release an integrated product, Lenders can use it in all IMT's Lender-facing applications.

Step 2: Identify API Alternatives

Review the API documentation in Encompass Developer Connect to find the alternative API endpoints that replace the SDK functionality. The sections below provide links to API alternatives for the most commonly used SDK methods and operations.

Where the SDK might have been used to poll for data changes, you can replace that with webhook events such as Enhanced Field Change to push real-time updates when fields change. Please see the Migration Strategy Using Enhanced Field Change Webhook Event section below for details.

Step 3: Refactor Business Logic

Convert custom logic previously running through the SDK into API calls.

In addition, shift to Event-Driven Architecture by subscribing to webhook events. Encompass Developer Connect provides webhook resources for all major features of the Encompass application including the following: Loan, Document Delivery, Document Order, Enhanced Conditions, Organizations and Users, EPC Service Orders, Schedulers, Trades, Workflow Tasks and Data & Document Automation

For a list of all webhook resources and events, please review the Resources and Events list in Encompass Developer Connect.

Step 4: Setup API Authentication

Unlike the SDK, which relies on internal authentication methods, the API uses modern authentication protocols such as OAuth 2.0.

You will need to configure your client to authenticate using OAuth token when making API calls to Encompass. See more information on the supported authorization flows and API Key provisioning in Encompass Developer Connect.

Step 5: Make your First API Call

Once you have obtained your API keys, you are now ready to start working with the APIs.

Review the API Reference in Encompass Developer Connect for the detailed endpoint documentation including code samples.

Download Postman Files

Download the latest Postman Collection and Environment Variables for a library of pre-built API requests for common use cases to get your started on your automation journey. The Postman Collection is updated with every major release of Encompass, so be sure to check the Release Notes for the latest updates.

Get Your Access Token

Open the postman collection and find the authentication folder > Get Access Token folder > locate the Resource Owner Password Credentials sample that you can use to get your access token. Plugin your input variables in the path and request body and Send the call.

Here’s the cURL snippet for the Access Token API call:

curl --location 'https://api.elliemae.com/oauth2/v1/token' \ 
--header 'Content-Type: application/x-www-form-urlencoded' \ 
--data-urlencode 'grant_type=password' \ 
--data-urlencode 'username=admin@encompass:{{instnace_Id}}' \ 
--data-urlencode 'password={{password}}' \ 
--data-urlencode 'client_id={{Oauth clientId}}' \ 
--data-urlencode 'client_secret={{oauthSecret}}' 

If the call is successful, you will see the access_token in the API response.

📘

The access token is active for 15 minutes unless continuously refreshed. You can keep the token alive for up to 24 hrs.

Make an API Service Call

Now that you got your access token, you can make a service call. If you are using the postman collection in Encompass Developer Connect, the access token variable is saved from your last call.

In this example, we are calling the Get Loan API to return the details of a specific loan record. The “loanId” is included as a path parameter. You can use query parameters such as entities and view to limit the API response to focused entities. See V3 Get Loan API for more details.

Here’s the cURL snippet for the V3 Get Loan API without passing any query parameters:

curl --location 'https://api.elliemae.com/encompass/v3/loans/{{loanId}}' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer {{access_tToken}}' 

If the call is successful, the payload will include all details of the loan record.

HTTP Status Codes

Review the list of HTTP status codes page for common successful and invalid requests including a description and use cases for each status.

Common Encompass SDK Methods and API Alternatives

The following table highlights the most common SDK supported operations, with the quick links to documentation for API alternatives.

Most Frequently Used SDK Operations and API Alternatives

The following list includes the most frequently used SDK operations and the API alternatives for migration.

Migration Strategy Using Event Driven Architecture

Using the Webhook event from Encompass to aid in migrating away from the SDK is a strategic way to modernize your integration while leveraging API-driven functionality.

The webhook events in Encompass are designed to notify external systems when a certain event or an update occurs on the loan. These webhooks work in near real-time, pushing data and event updates which is ideal for cloud-based architectures.

For example, instead of running a job through the SDK to poll for changes, you can subscribe to a webhook that triggers an API call whenever a field like “loan amount” is updated and trigger downstream process automation, eliminating the need for manual checks.

In addition, the EFC webhook event in Encompass is designed to notify external systems whenever any field is updated in the loan file. The payload includes the previous and the new value of the updated field, eliminating the need to do another GET API call to retrieve the updated values.

How it Helps in SDK Migration

Automating Workflows with APIs

In the SDK, handling field changes often requires polling or manually updating data, which could lead to inefficiencies. With webhooks, you can shift to near real-time updates where the API sends a notification when specific fields are modified. This simplifies data integration and eliminates the need for continuous polling or scheduled tasks, improving efficiency and performance.

Event-Driven Architecture

Webhooks support a more modern, event-driven approach. By triggering events on field changes, document orders and delivery, enhanced conditions, service order status and so forth, you can replace SDK-based methods with API calls that respond to these events. This enables you to automate downstream workflows in near real time.

Scalability and Reduced Maintenance

The webhook approach reduces the complexity and overhead of maintaining custom SDK-based code, allowing Encompass to handle field change events. Webhook-driven architecture is also more scalable than SDK, as webhooks are managed in the cloud, handling near real-time notifications without the need for constant SDK system checks.

Improved Monitoring and Security

With APIs and webhooks, you can set up monitoring for all field changes in the loan, tracking which updates have been made, and log every transaction for audit purposes. In addition, webhooks support modern and improved security protocols. For example, webhook notifications are signed by the Encompass platform, so that the subscriber can verify the identity of the sender and integrity of the message upon receiving the notification. 

The Get All Events API allows the subscriber to track the status of all events that have occurred on the Lender Platform. The event history simplifies reconciliation and troubleshooting. You can use this API to identify misconfigured subscriptions and undelivered notifications.

Example for Leveraging the Loan Milestone Webhook for SDK Migration

In the Encompass SDK-based workflow, a mortgage lender may be using the custom SDK scripts to monitor changes to the loan milestones, and after detecting a milestone update use the SDK scripts to trigger task assignments. The SDK based workflow requires regular checks for milestone changes, leading to delays and resource overhead.

Migrating to the Event Driven Architecture eliminates the need for the SDK to regularly poll for milestone updates and switch to near real-time notifications when a milestone changes. Upon receiving the webhook notification, you can trigger internal workflows and automate task assignment using APIs without relying on custom SDK scripts.

Steps for Migration to Milestone Upload Webhook

1. Identity how the SDK currently detects milestone changes and which tasks are triggered when a certain milestone (e.g. Underwriting) is reached.
2. Map out the specific triggers and assignments made when milestones change (assigning tasks to underwriters, notifying borrowers, etc.)
3. Subscribe to the Loan Milestone Update Webhook event using the Create a Subscription API.
   
   Here’s an example of a cURL snippet for subscribing to the Loan Milestone webhook event.
   Subscribe to Loan Milestone Webhook Event

    curl --location 'https://api.elliemae.com/webhook/v1/subscriptions' \ 
   --header 'Content-Type: application/json' \ 
   --header 'Authorization: Bearer 0004gjyIsvQkdrSXVLtBqYlDHwOl' \ 
   --data '{ 
       "events": [ 
           "milestone" 
       ], 
       "endpoint": "{{callbackURL}}", 
       "resource": "Loan", 
       "enableSubscription": true 
   }' 
   

4. Configure your client application to receive webhook notifications when loan milestones are updated.
5. When the milestone is updated, the webhook triggers and sends a notification to the endpoint that you specified in the webhook subscription. The payload includes the resourceRef for the loan that was updated, as well as the milestone ID and the updated status.
   
   Here's an example of the notification payload for the milestone webhook event:
   Notification Payload for Milestone Webhook Event

   { 
     "eventId":"3c8e2d53-0ab9-40c0-88a6-74d521dde5de", 
     "eventTime":"2020-02-11T19:42:23.262Z", 
     "eventType":"milestone", 
     "meta": 
     { 
       "userId":"admin", 
         "resourceType":"Loan", 
         "resourceId":"af43e4cd-cf58-4a7f-ba8a-5bea2496ec2d", 
         "instanceId":"bexxxxxxxx", 
         "resourceRef":"/encompass/v3/loans/af43e4cd-cf58-4a7f-ba8a-5bea2496ec2d", 
         "payload": 
         { 
           "correlationId":"8e4bfd03-5af6-400b-9c77-0a0fe48396b4", 
           "event": 
           { 
             "updateMilestones": 
             [ 
               { 
                 "id":"dc66f3ae-4ee3-4150-b3eb-69683bb48ad9", 
                 "title":"Started" 
               } 
             ] 
           } 
         } 
     } 
   } 
   

   
   
6. On the client side, write logic to filter for milestone updates that are relevant to your business processes. For example, trigger actions only when the loan reached key stages like Underwriting, Pre-Approval, Closing, etc.
7. Use the information in the webhook payload to automate task assignments. For example, when the milestone reaches “Underwriting”, assign an underwriter to the loan using the V3 Update Milestone Log API.
   
   Here's an example of the cURL snippet for assigning a loan associate:
   Assigning a Loan Associate

   curl --location --request PATCH 'https://qa.api.ellielabs.com/encompass/v3/loans/1a88e27a-7d12-44b9-8eb4-5258c05c1d8a/milestones/4f049bab-dc59-40b1-a8f9-199babe21022' \ 
   --header 'Accept: application/json' \ 
   --header 'Content-Type: application/json' \ 
   --header 'Authorization: Bearer 0004lwov92ap4LvlSg7HAFtqvXDz' \ 
   --data '{ 
       "startDate": "2024-03-28T10:51:00Z", 
       "loanAssociate": { 
           "loanAssociateType": "User", 
           "user": { 
               "entityId": "underwriter", 
               "entityType": "User" 
           }, 
           "cellPhone": "124-567-1258", 
           "email": {{EMAIL_ADDR}}, 
           "fax": "123-567-1234", 
           "phone": "123-567-1234" 
       } 
   }' 
   

Please review the webhook documentation for endpoint requirements, signing keys, access controls and retry logic for important details before subscribing to an Encompass webhook event.

Helpful Resources in your Migration Journey

If your organization requires assistance with your SDK to API migration journey, please reach out to your account manager for a Professional Services Organization (PSO) engagement.

Additional Resources

• ICE's Encompass SDK Transition Information Page

The following links require you to first log in to the ICE Resource Center.

• Resource Center Article Number: 000115647 - Encompass Innovation Playbook: Automating Conditions and Task Workflows for Service Orders
• Resource Center Article Number: 000115613 - Transitioning from SDKs and Legacy Integrations - FAQs (Frequently Asked Questions)
• Resource Center Article Number: 000115625 - Scheduler Service Best Practice Guide