Link Borrower Contacts to a Loan

You can create a link between a loan and an existing borrower or business contact. Borrower and business contacts can be linked to a loan when the loan is created POST /loans or after the loan is created PATCH /loans/{loanId}.

About Linking Contacts to a Loan

Because Contacts and Loans can be created and modified separately, they can largely be viewed as independent of one another. However, because many of the contacts in your system represent the borrowers and business partners with whom you are transacting business, a logical
connection exists between the two sets of data.

Encompass provides a mechanism for formalizing the relationships between your contacts and your loans. By tying individual contacts to their respective loans, you gain the ability to look at historical data, search out contacts based on loan attributes and avoid duplication of work.

Encompass allows for a many-to-many mapping between the contacts in your system and the loans. Each mapping is made more precise by requiring you to specify the relationship that the contact fulfills within the loan, such as "Appraiser" or "Borrower." A single contact may generally fulfill multiple relationships within a loan (e.g. "title company" and "notary") while each relationship may only be mapped to a single contact.

More precisely, a loan breaks its relationships down into two categories: Borrower Relationships and Business Relationships. A borrower relationship exists for each borrower and co-borrower within the loan file. For example, a loan that has two "borrower pairs" will have four borrower relationships that can be assigned. Each borrower relationship can be assigned to a different Borrower Contact - a contact cannot fulfill multiple borrower relationships on the same loan.

The business relationships within a loan are a fixed set, but a single business contact can be assigned to multiple business relationships. However, a given relationship, such as "Appraiser," can only be assigned to a single business contact. Assigning a new contact to that relationship will
remove any prior contact that was assigned.

Linking and unlinking a borrower contact to a loan is done through the Loan.borrower and Loan.coborrower objects. Contacts are described by the entityRef contract in the respective objects.

Entity Ref Attributes

ATTRIBUTE	DESCRIPTION
entityId string	References the entity ID of the contact. This is the unique identifier that is associated to the business/ borrower contact.
entityType string	Indicates the type of contact. Possible values are Business and Borrower.
entityUri string	The location of the contact in Encompass. Example: /v1/borrowerContacts/78135c8c-0dfa-496f-9b7a-ab0fa8ef229f

{
  "Applications": [
    {
      "Borrower": {
        "AuthorizedCreditReportIndicator": false,
        "BirthDate": null,
        "CommentOfCreditReport": "",
        "CreditReportAuthorizationMethod": "",
        "DateAuthorizedCreditReport": null,
        "EmailAddressText": "",
        "EquifaxScore": "",
        "ExperianCreditScore": "",
        "FirstName": "Test",
        "HomePhoneNumber": "",
        "LastName": "New",
        "MaritalStatusType": "",
        "MiddleName": "",
        "MobilePhone": "",
        "SuffixToName": "",
        "TaxIdentificationIdentifier": "",
        "TransUnionScore": "",
        "WorkEmailAddress": "",
        "HmdaRefusalIndicator": false,
        "HmdaEthnicityType": "",
        "HmdaAmericanIndianIndicator": false,
        "HmdaAsianIndicator": false,
        "HmdaAfricanAmericanIndicator": false,
        "HmdaPacificIslanderIndicator": false,
        "HmdaWhiteIndicator": false,
        "HmdaNotProvidedIndicator": false,
        "HmdaNotApplicableIndicator": false,
        "HmdaGenderType": "",
        "contact": {
          "entityId": "0af604bf-c188-4020-a512-240b1917f8ea",
          "entityType": "Borrower"
        }
      },
      "Coborrower": {
        "AuthorizedCreditReportIndicator": false,
        "BirthDate": null,
        "CreditReportAuthorizationMethod": "",
        "DateAuthorizedCreditReport": null,
        "EmailAddressText": "",
        "EquifaxScore": "",
        "ExperianCreditScore": "",
        "FirstName": "Test",
        "HomePhoneNumber": "",
        "LastName": "CoB",
        "MaritalStatusType": "",
        "MiddleName": "",
        "MobilePhone": "",
        "SuffixToName": "",
        "TaxIdentificationIdentifier": "",
        "TransUnionScore": "",
        "WorkEmailAddress": "",
        "HmdaRefusalIndicator": false,
        "HmdaEthnicityType": "",
        "HmdaAmericanIndianIndicator": false,
        "HmdaAsianIndicator": false,
        "HmdaAfricanAmericanIndicator": false,
        "HmdaPacificIslanderIndicator": false,
        "HmdaWhiteIndicator": false,
        "HmdaNotProvidedIndicator": false,
        "HmdaNotApplicableIndicator": false,
        "HmdaGenderType": "",
        "contact": {
          "entityId": "78135c8c-0dfa-496f-9b7a-ab0fa8ef229f",
          "entityType": "Borrower"
        }
      }
    }
  ]
}