Definitive ConnectorStarts a loan in Encompass for the workflow's contact, or returns the loan the contact already has.
Add it to a workflow
In a workflow, add an action and choose Create loan in Encompass (under Definitive Connector). Common starting points: a loan application form is submitted, a tag is added, or an opportunity moves to an "Application" stage.
The action needs premium workflow actions turned on for the account; your CRM provider may charge a small fee per run.
Inputs (all optional)
| Input | What it does |
|---|---|
| Loan amount | A number (350000 or $350,000.00) or a custom value such as the contact's loan amount field. Written to the loan amount (field 1109) through your field mapping. If it can't be read as a number, the loan is still created and the amount is reported. |
| Loan purpose | Purchase, Refinance (no cash out), Cash-out refinance, Construction only, Construction to permanent, or Other. Written to the loan purpose (field 19). You can also pick a custom value such as a contact field: the usual wordings ("Refinance", "Cash out refinance", "Rate and term refinance") are read, and anything else is left out and reported. |
| Loan folder | The Encompass loan folder for this workflow's loans. Leave blank to use the folder on the New loans tab. |
Everything else on the loan (the borrower's name, email, phone, address, date of birth, your custom fields) comes from your field mapping.
What happens when it runs
- It checks whether the contact already has a loan.
- If a loan made for this contact is still active, that loan is returned as existing. Running the action twice, or from two workflows at once, never makes a second loan.
- If the contact's loan is finished in Encompass (originated, withdrawn, denied), a new loan is created: a past client coming back gets a new file. The note on the contact names the earlier loan.
- If the contact has no loan here but there's an active Encompass loan with the same borrower email (a processor started it, or it's older than the connector), that loan is linked instead of making a duplicate. You can turn this off on the New loans tab.
- It creates the loan in your folder, with your template, and the mapped values.
- It assigns the loan officer: the Encompass user whose email matches the CRM user the contact is assigned to; otherwise your default loan officer. If neither works out, the loan keeps the API user and the note says why.
- It writes the property state after the loan officer, because Encompass checks the loan officer's license against it. If they aren't licensed there, the note lists the states they are licensed in.
- It reads the loan back and reports any value Encompass didn't keep.
- The contact gets the loan's opportunity in your pipeline, and the tag
encompass. If the contact already has an open opportunity in that pipeline, it's used rather than adding a second one.
A run usually takes about five seconds.
Values Encompass won't take
The loan is created whenever it can be. A value Encompass refuses (a date that isn't a date, a choice a dropdown doesn't offer, a field that doesn't exist on your instance) is left out, and:
- listed in the action's Warnings output;
- added as a note on the contact, so someone can fix it in Encompass. Social Security numbers, tax IDs and account numbers show only their last four characters.
Outputs
Use these in later workflow steps, such as an If/Else on Result or a message with the Loan number.
| Output | Contents |
|---|---|
| Result | created or existing |
| Loan number | the Encompass loan number |
| Loan GUID | Encompass's ID for the loan |
| Loan officer name / email | blank if none was assigned |
| Loan folder | where the new loan was created (blank for an existing loan) |
| Warning count / Warnings | values Encompass didn't take |
| Message | one line, for people |
| Already existed | true when an existing loan was linked |
When it fails
The action fails only when no loan could be created or linked. The workflow's history shows the reason, and the contact gets a note (at most once an hour for the same reason). Running it again is always safe: a loan made by an earlier run is found and returned.
| Reason | What to do |
|---|---|
| Encompass isn't connected | An account admin connects it on the Encompass connection tab. |
| Encompass rejected the login | The API user's password or the client secret changed: enter the new one. |
| The API user isn't allowed to create the loan | Give the API user's persona rights to the loan folder. |
| Encompass didn't accept the loan | The message gives Encompass's reason; often the folder or template. |
| Encompass was busy, unavailable or slow | Run it again shortly. |
| Too many loans at once | The account is already creating several loans; run it again shortly. |
| The contact wasn't found | The contact was deleted or merged. |
| The connector lost access to this account | Reinstall Definitive Connector from the App Marketplace. |
Many contacts at once
Loans are created four at a time per account, about 45 a minute. In a very large batch, a contact that waits more than a minute gets "Too many loans at once": run the action again for those contacts.
New loans settings
On the New loans tab:
- Loan folder: where new loans go (a workflow's Loan folder input overrides it).
- Loan template: an Encompass loan template to apply, shown by its full path. If Encompass can't apply it, the loan is created without it and the note says so.
- Loan officer role: the Encompass role the loan officer is assigned to, usually "Loan Officer".
- Default loan officer: used when the contact's CRM user doesn't match an Encompass user.
- Duplicates: use the borrower's existing active loan (same email) instead of creating another. On by default.
Need help? Email support@definitiveconnector.com. We reply within 24 hours. Please don't send passwords, client secrets or borrower details such as Social Security numbers.