The information contained in this document is confidential, privileged, and only for the use of internal Birdeye users. This document may not be used, published or redistributed.
This integration is supported for both SMB & Enterprise businesses.
NOTE: If there is an enterprise business to be set up and there are unique sign-in required for every location, such integration should be set up as an SMB i.e an integration group should be created for every location.
Integrating Birdeye with Encompass
User Manual - SUPPORT ARTICLE
Encompass is a digital mortgage CRM solution used by small and mid-sized businesses to manage the loan lifecycle and maintain a single system of records to close compliant loans. It helps lenders and investors generate leads, build relationships, stay compliant and grow faster. Integrating Encompass with Birdeye will automate the process of sending out review requests to clients on a daily basis.
Once Encompass is integrated with Birdeye, Birdeye will pull client information from Encompass once daily from the cases that were closed on the previous day. Birdeye collects the first name, last name, email address and phone number of your clients and automatically sends them review requests based on the preferences set within the Birdeye dashboard.
NOTE: If there are any Rule Configurations or some triggers in your Encompass instance, Birdeye will receive multiple events for the same action, which will trigger sending review requests to the same customer. To modify the frequency of review request emails to clients, refer to this help center article: How can I limit emails to go out to customers only 90 days after the first time they got a review request from us? In the aforementioned article, from the 'Limit email or SMS to maximum one every' drop-down, select a time limit as per your requirement.
Table of Contents
Triggers Supported
Information required from the Business
Information from Birdeye dashboard
Login
Manage Triggers
Manage Properties
Manage Locations
Setup Through Birdeye Dashboard
Integration Requirements
Triggers Supported
Birdeye allows you to fetch data from your PMS using a predefined trigger. Here is the supported trigger for Encompass:
Trigger Display Name | Trigger Name/Value | Trigger Description |
Encompass Loans Trigger | Loan | This trigger is used to fetch customer data based on custom milestones loan stages. |
Request for the integration with Encompass
To initiate the integration request, we have to register with the lender. Below are the steps:
Now the process has been updated, follow the new process here.
In response to the above mail, a Client ID and a Client Secret will be provided for this lender.
Send the above Client ID to the lender, requesting him to create an API Userwith appropriate access rights.
Navigate through the following path:
Encompass > Settings > Company/User Setup > Organisation/UsersClick on the ‘+’ icon to Add a new API user.
Fill in the Client ID provided by the Birdeye Support team in the API Client ID and the other required fields on this page. The email id should be encompass@Birdeye.com
Make sure to add access to all loans at any level of the organisation. You can ensure it by clicking on the Group Membership -> View Rights option:
The next step is to click on the ‘+ ‘ Add button under the Loans sections:
You need to add the Administration level user here so that the Birdeye user you are creating can access loans at any level of the organisation.
Another thing that should be ensured is not to forget to click on the ‘Access to all loans in the same level’ checkbox with the ‘View Only’ or ‘Edit’ option checked under the Access to Subordinates Loans header. You can refer to the screenshot below:
Do not give access to the Super Administrator Personas; however, the persona whose access is to be given must have access to Loan Officer Connect.
Details required from the Encompass dashboard
Trigger Details
Instance ID
NMLS Number
Milestone Stages (for which the client wants to send review request)
Details required from the Birdeye dashboard
Location Name
Business ID in case of an SMB Business
Steps to find Milestone Stages
Log in to your ‘Encompass’ account.
Navigate to Encompass > Settings > Company/User Setup > Milestones
Select the desired milestones for which a review request needs to be sent.
Information from Birdeye Dashboard
For single location SMB account - Business ID
Login to your Birdeye account, go to Left Navigation Rail and click on ‘Settings’. Once the new page appears, click on ‘Integrations’ and select ‘API.’
You will find the ‘Business ID’ and ‘API key’ shown in the image.
For multi-location accounts - Enterprise ID and Business IDs of all locations
Enterprise ID
Business IDs of all locations
Login to your Birdeye account, go to Left Navigation Rail and click on ‘Settings’. Once the new page appears, click on ‘Profile’ and select ‘Business Profiles.’
To view Location ID, hover over the ‘Status’ of location.
Integration process
Before you can integrate Encompass with Birdeye, you will need to set up the following configurations on the integrations support dashboard:
To set up native integration, we have an integration support dashboard, where we need to set up the integration and then follow these steps to complete the configuration.
Login
After successful login in the integration dashboard, you have to click on ‘BE integration’ and then click on ‘Add Integration’.
Search for the CRM in the search bar and select it. Click on ‘Next’.
Manage Triggers
The trigger is automatically selected as only one trigger is supported.
Note: To fetch information for all the triggers available using curl commands, use this command. To replace triggers, use this curl command.
Manage Properties
Here; you can manage group-level properties, which will be applied to all locations under a CRM.
Client ID: Provided by Encompass after the lender registration is complete.
Client Secret: Provided by Encompass after the lender registration is complete.
Milestones: Provided by the client during setup. These are the milestones stages upon the completion of which the client wants to send the review request to the related borrower of the loan.
Instance ID: It will be provided by the client.
Field ID: It should contain a comma-separated list (in case of multiple fields IDs) of IDs of fields for which the business wants to add values of those fields' IDs in additional parameters.
Note: This step will create a group for our integration. Alternatively, you can do it via curl commands.
For SMB accounts, you can access the curl command.
For Enterprise accounts, you can access the curl command.
Manage Locations
For Single Location/Multi-Location Accounts, select the drop-down and click on ‘Add.’
(In the case of Single Location accounts, it will give you only one option).
A drawer will appear on the right-hand side.
The Status will be set by default. You can make changes if required.
Status: It shows the status of integration (Active or inactive).
Loan Officer: This is an optional field, this represents the loan officers which are associated with this business, and you want to send review requests. You can provide multiple loan officers using a comma separator.
NMLS number: Enter the NMLS number mapped to this Birdeye business location as provided by the client during setup.
Add Loan Associates as Contact: Enter "true" if you want to add Loan Associates as contacts (Loan Officer, Closer, UnderWriter and Loan Processor) and send review requests based on configured MileStones for the respective loans, the way it's done for borrowers and co-borrowers.
Override Group Properties: The user can override any of the below-mentioned properties for a particular location.
Click on ‘Next’ and click on ‘Save.’
Note:
For SMB: You can use ‘manage the locations’ using this curl command.
For Enterprise: You can use ‘manage the locations’ using this curl command.
Authorize through Integration Dashboard
Upon creating a new encompass group for the first time from the integrations dashboard; the system will automatically attempt to authorize the group. If the group properties (like client_id, client_secret, instance_id and milestones) provided are correct, the authorization will succeed. This will be evident from the fact that the encompass group will be indicated as authorized, and no further action needs to be taken.
In case the group is unable to be authorised the first time it’s created or is unauthorised at a later stage, please authorise it again by following the steps below.
Setup through Integration Dashboard
The rest of the setup is to be completed within the Integration dashboard:
Once in the Birdeye dashboard, click on the ‘BE Integrations’ tab on the left navigation rail.
Scroll down to the ‘Encompass’ integration and hover over the three dots.
Click on the ‘Actions’ drop-down button and select the ‘Authorize’ option.
Once you select the authorize option, the integration will be authorized.
Curl Commands
Before you can integrate Encompass with Birdeye, you will need to set up the following configurations:
A business integration group is a configuration that supports the business hierarchy of individual businesses on the Birdeye platform. The common properties for all business integrations are entered at the group level. Setting up a business integration group allows you to associate multiple business locations with the Enterprise account. Below is the list of curl commands that you will need to run to set this up.
Create Integration Group (Curl Command)
Copy Curl Command:
curl-X PUT https://common-services.Birdeye.com/integration/add/businessintegrationgroup -H 'content-type: application/json' -d '{ "parentBusinessNumber": 145301438060509,"integrationSourceId": 41, "integrationGroupProperties": [{"propertyKey": "client_id","propertyValue": "g9ygvqk"},{ "propertyKey": "client_secret", "propertyValue":
"q33LLrk5hbJmpegnfK78reY6RGnZKAY4KcHuJ575F7c96Y@@3dk^xtvpH3vBEM45", "isSecure": true},{ "propertyKey": "milestones", "propertyValue": "Submittal,Completion"},{ "propertyKey": "instance_id","propertyValue": "be11211379"}], "integrationGroupTriggers": [{ "triggerId": 65,"triggerTypeId": 2}]}'145301438060509 - Business ID - This is Enterprise ID for a multi-location account and Business ID for a single location SMB account
g9ygvqk - Client ID: Provided by Encompass after the lender registration is complete.
q33LLrk5hbJmpegnfK78reY6RGnZKAY4KcHuJ575F7c96Y@@3dk^xtvpH3vBEM45 - Client Secret: Provided by Encompass after the lender registration is complete.
Submittal, Completion - Milestone Stages: Provided by the client during setup. These are the milestones stages upon the completion of which the client wants to send the review request to the related borrower of the loan.
65 - Integration Trigger ID - This can be one or more triggers. Ask the client what trigger they would like to integrate with, then run the curl command to fetch all possible triggers for Encompass. Identify the trigger ID(s) and insert (use commas) in case of multiple trigger IDs.
Fetch information for all the triggers available for Encompass (Curl Command)
Copy Curl Command:
curl -X GET https://common-services.Birdeye.com/integration/trigger/integrationtriggers/sourceid/41 -H 'cache-control: no-cache' -H 'content-type: application/json'
Sample response: A sample response like this would appear after you run the curl command. The response will have the trigger name, description and ID. This trigger ID will be utilized while creating the integration group. Integration can have one or more triggers. To use more than one trigger, enter comma-separated values while creating the integration group.
[
{
"id": 65,
"triggerService": "encompassLoansTriggerService",
"displayName": "Encompass Loans Trigger",
"description": "This trigger is used to fetch customer data based on custom milestones loan stages.",
"active": true,
"integrationTriggerType": [
{
"id": 2,
"name": "WEBHOOK"
}
],
"actionGroupId": 1
}
]65 - Trigger ID
Find business integration group details (Curl Command)
Copy Curl Command
curl -X GET https://common-services.Birdeye.com/integration/businessintegrationgroup/154416387790029 -H 'Cache-Control: no-cache'
154416387790029 - Business ID: Enter the Business ID here to get the integration group details for a business.
Sample:
[
{
"groupId": 2347,
"integrationSourceType": {
"id": 41,
"integrationSource": "ENCOMPASS",
"sourceCategory": "CRM",
"integrationType": "Birdeye API",
"oauthEnabled": true
},
"integrationGroupTriggers": [
{
"triggerId": 65,
"triggerTypeId": 2,
"actionIds": [
1
]
}
]
}
]2347 - Group ID: A group ID will be returned in the sample response with the details of the existing triggers for a business.
Trigger Information: Only required if a client wants a change (Curl Command)
Copy Curl Command
curl -X POST 'https://common-services.Birdeye.com/integration/update/businessintegrationgroup?replaceTriggers=true' -H 'cache-control: no-cache' -H 'content-type: application/json' -d '{ "groupId": 2347,"integrationGroupTriggers":[{"triggerId":65,"triggerTypeId":1}]}'replaceTriggers=true - To replace existing trigger(s), enter the value for replaceTriggers as true. To add a new trigger(s) to the existing list, the value for replaceTriggers should be false.
2347 - Group ID: The Group ID which was returned in the previous step will be entered here.
65 - Trigger ID: Enter the Trigger ID (s) which need to be added or updated to the integration.
Integration Mapping (SMB Businesses)
Once the Integration Group is created, the next step is to create the Integration Mapping.
Copy Curl Command:
curl -X PUT https://common-services.Birdeye.com/integration/add/businessintegrationmapping -H 'cache-control: no-cache' -H 'content-type: application/json' -d '{ "businessNumber": 151608516098228, "integrationGroupId" : 2347, "active": true }'151608516098228 - Business ID: Enter the Business ID for the SMB Business.
2347 - Group ID: Enter the Group ID, which was returned when the Integration group was created.
true - Active: Enter true for enabling the integration.
Integration Mapping (Enterprise Businesses)
Copy Curl Command:
curl -X PUT \https://common-services.Birdeye.com/integration/add/businessintegrationmapping \
-H 'Postman-Token: 5c364774-c207-438e-a4d3-6a2622090f50' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{
"businessNumber": 151608516098228,
"integrationGroupId": 32,
"active": true,
"integrationProperties": [
{
"propertyKey": "nmls.id",
"propertyValue": "1306344"
},
{
"propertyKey": "loan.officer",
"propertyValue": "Alex.Turner@example.com"
}
]
}'151608516098228 - Business Number: Enter the Business ID for the SMB Business.
32 - Group ID: Enter the Group ID, which was returned when the Integration group was created.
true - Active: Enter true for enabling the integration.
1306344 – NMLS Number: Enter the NMLS number mapped to this Birdeye business location as provided by the client during setup.
Turner@example.com - Loan Officer email id (Optional)- This is an optional field, this represents the loan officers which are associated with this business, and you want to send RR. You can provide multiple loan officers using comma separator(,) such as Alex.Turner@example.com,urner.getting@example.com
Note: For old integration mappings with a loan.officer property key, you can update the existing loan officer email id from the Integration dashboard. Otherwise, you are advised to enter only the NMLS number property. No need to provide both loan.officer and nmls.id
Troubleshooting Steps
In case of any support required from Encompass, you may reach out via Encompass Resource Center:
Log in to https://resourcecenter.elliemae.com/resourcecenter/default.aspx
Instance ID: BE11211379
Client ID: 11211379
User ID: admin
Password: Birdeye!123Click on Support Cases -> Submit A Case
Fill in all the details of your query and submit it.
Campaigns Tags
Campaign tags are used to set up campaigns within the Birdeye dashboard. These tags are either provided by the client or can be fetched from Kibana for already checked In contacts.
Encompass Campaign tags are:
FIELD ID: additional_param_loan_id
FIELD ID: {key} this key will be dependent on the field you have added in configurations. For Example - FIELD ID: LoanTeamMember.Name.Loan Processor
Applicant Type
Restriction Reason
Restriction reason is used to identify the contacts who have been opted-out(restricted) from sending a review request. This reason can be fetched from Kibana for contacts that are checked In already.
Possible restriction reasons with fields to look for more info,
Milestone is not completed
The allowed Milestone completion date is not the same as the previous milestone completion date
Milestone is Invalid
Integration is beta
Description
The allowed milestone has not been reached or completed.
The allowed milestone was already completed earlier.
The allowed milestone doesn't match any of the milestone stages.
Troubleshooting steps:
Check for Completed Milestone Stages in bc-json-logs for the value present for the customer.
Check for milestone_completion_date Stages in bc-json-logs for the value present for the customer.
Check for Milestones property value on Integration Dashboard and confirm with the client.
The Integration Source is not Live and is in the Pre-Launch phase.
Possible Error And Resolution at Support End
{"summary":"Internal Server Error","details":"Unexpected Error: Access Denied"}
OR
{"summary": "Forbidden", "details": "Current user does not have the privileges to perform this operation.", "errorCode": "EBS-901"}
This indicates that the API user which we are using to access the Encompass API for this user does not have sufficient privileges to access the webhook request received for the loan. This generally happens when either one of the steps is missing while granting permission.
You can get more info at Permission Request Process point no. 3