Working with Collections
The EPC Partner Loan Model (PLM) supports two general types of collection valued entities (arrays). This section illustrates how to interface with the EPC transaction response resource, and update loan data represented by both collection types in an Encompass application.
Fixed Size Collections
Fixed Sized collections defined in the PLM, such as $.fees (Loan Processing/Closing Fees) or $.contacts (Loan File Contacts), have a fixed length with a pre-defined number of items. Updating these collections requires specifying the index number of the target item in the collection, the name of the item's attribute, and the value of the attribute. The items contained in fixed sized collections can never be removed/deleted. They can only be emptied (i.e. all non-ID fields set to null, empty, or 0). Items also cannot be re-ordered within the collection.
Variable Sized Collections
Variable Sized collections do not have a pre-defined length. These collections grow or contract as items are appended or deleted. Examples of such collection valued entities in the Partner Loan Model are $.applications[*].vods (Verification of Deposits/Assets) and $.applications[*].borrower.employment (Borrower Employment History).
EPC allows Partner integrations to create and modify entries in Variable Sized collections as follows:
- Partner integrations are required to send a unique
recordIdproperty for each new item, and are expected to maintain the relationship between the actual record and itsrecordIdwhen updating the collection. - Partner integrations are required to send the full set of collection items each time they create or modify entries (with the
recordIdincluded, of-course). - Partner integrations are limited to only modifying (updating/deleting) the items they've previously created.
When EPC processes a Partner integration's response to a transaction, if the response contains Variable Sized collection items in the manner described above, EPC interprets the collection response as follows:
- If EPC encounters an item with a
recordIdnot currently present in the subject loan, it appends the the item with the newrecordIdto the collection. - If EPC finds a
recordIdfrom the new transaction response inside the current loan data, and is able to confirm that it was created by the same Partner, it updates the item's attributes with the newly received values. - If EPC detects an item in the current loan data with a
recordIdpreviously sent by the same Partner but not included in the current transaction response, it interprets that as a request from the integration to delete that particular item from the collection in the subject loan.
TLDR - Variable Sized Collection Update Mechanism
Each time a Variable Sized collection is updated by a Partner integration via a transaction response, EPC performs a full overwrite of the collections items delivered by the Partner, deleting any previously delivered items for the same loan that are not represented in the new response. This means that each time Partners send a transaction response that modifies a Variable Sized collection, Partners are expected to send the full set off collection items they intend to deliver to the loan.
Example Workflow:
Let's assume the Loan Processor has just initiated a Verification of Deposit's (VOD) request for a pair of borrowers on an application. The borrowers are yet to link their accounts and generate a report, so no transaction response has been delivered by the VOD Partner integration. The current state of the VOD's collection in the loan looks like this:
{
"applications": [
{
"id": "85c37a19-4b25-45f3-8773-d2d7fe3b6419",
"vods": [
// previously existing VOD's, not owned/delivered by the Partner
{
...
},
{
...
},
{
...
}
]
}
]
}
Step 1: Initial Response
The borrowers finally link their accounts, and the integration is able to generate a VOD report and respond to the initial transaction request. Since this is the first response by the VOD integration for the subject loan, EPC will not find any existing VOD objects with a recordId matching what is sent by the VOD Partner. EPC will append all of the received items in the loan's $.applications[?(@.id == '85c37a19-4b25-45f3-8773-d2d7fe3b6419')].vods collection.
==> Response for Verification of Deposits - Initial Transaction:
{
"status": "completed",
"partnerStatus": "VOD's Verified",
"referenceNumber": "CXV90345",
"loanFormat": "application/vnd.plm-2.0.0+json",
"loan": {
"applications": [
{
"id": "85c37a19-4b25-45f3-8773-d2d7fe3b6419",
"vods": [
{
"recordId": "dd26115b-cf57-4516-a53c-c4b30f40eedd",
"title": "Bank of America",
"holderAddressCity": "Palo Bajo",
"items": [
{
"itemNumber": 1,
"type": "CheckingAccount",
"accountIdentifier": "123456",
"cashOrMarketValueAmount": 12000,
"depositoryAccountName": "Ken N Customer JR"
},
{
"itemNumber": 2,
"type": "MoneyMarketFund",
"accountIdentifier": "22212",
"cashOrMarketValueAmount": 30000,
"depositoryAccountName": "Ken N Customer JR"
}
]
},
{
"recordId": "1d7cd7ec-c59b-40f7-9c75-b508d69daca3",
"title": "Wells Fargo",
"holderAddressCity": "Palo Bajo",
"items": [
{
"itemNumber": 1,
"type": "SavingsAccount",
"accountIdentifier": "21211",
"cashOrMarketValueAmount": 12000,
"depositoryAccountName": "Ken N Customer JR"
},
{
"itemNumber": 2,
"type": "CheckingAccount",
"accountIdentifier": "15612",
"cashOrMarketValueAmount": 22000,
"depositoryAccountName": "Ken N Customer JR"
}
]
},
{
"recordId": "a978c0bc-59a2-4d50-80d5-d9bf0398b369",
"title": "Fidelity",
"holderAddressCity": "Palo Bajo",
"items": [
{
"itemNumber": 1,
"type": "CheckingAccount",
"accountIdentifier": "31212",
"cashOrMarketValueAmount": 12000,
"depositoryAccountName": "Ken N Customer JR"
},
{
"itemNumber": 2,
"type": "SavingsAccount",
"accountIdentifier": "21212",
"cashOrMarketValueAmount": 22000,
"depositoryAccountName": "Ken N Customer JR"
},
{
"itemNumber": 3,
"type": "MutualFunds",
"accountIdentifier": "21212",
"cashOrMarketValueAmount": 32000,
"depositoryAccountName": "Ken N Customer JR"
}
]
}
]
}
]
}
}
As a result of the above operation on the $.applications[0].vods collection by the Partner, the Encompass loan now has items with the following recordId's appended to the VOD list:
dd26115b-cf57-4516-a53c-c4b30f40eedfor a Bank of America account asset1d7cd7ec-c59b-40f7-9c75-b508d69daca3for a Wells Fargo account asseta978c0bc-59a2-4d50-80d5-d9bf0398b369for a Fidelity account asset
==> Loan Updated State - Subsequent Transaction Response:
{
"applications": [
{
"id": "85c37a19-4b25-45f3-8773-d2d7fe3b6419",
"vods": [
// previously existing VOD's, not owned/delivered by the Partner
{
...
},
{
...
},
{
...
},
// Partner appended VOD's - from initial PATCH /response operation
{
"recordId": "dd26115b-cf57-4516-a53c-c4b30f40eedd",
"title": "Bank of America",
"holderAddressCity": "Palo Bajo",
"items": [
{
"itemNumber": 1,
"type": "CheckingAccount",
"accountIdentifier": "123456",
"cashOrMarketValueAmount": 12000,
"depositoryAccountName": "Ken N Customer JR"
},
{
"itemNumber": 2,
"type": "MoneyMarketFund",
"accountIdentifier": "22212",
"cashOrMarketValueAmount": 30000,
"depositoryAccountName": "Ken N Customer JR"
}
]
},
{
"recordId": "1d7cd7ec-c59b-40f7-9c75-b508d69daca3",
"title": "Wells Fargo",
"holderAddressCity": "Palo Bajo",
"items": [
{
"itemNumber": 1,
"type": "SavingsAccount",
"accountIdentifier": "21211",
"cashOrMarketValueAmount": 12000,
"depositoryAccountName": "Ken N Customer JR"
},
{
"itemNumber": 2,
"type": "CheckingAccount",
"accountIdentifier": "15612",
"cashOrMarketValueAmount": 22000,
"depositoryAccountName": "Ken N Customer JR"
}
]
},
{
"recordId": "a978c0bc-59a2-4d50-80d5-d9bf0398b369",
"title": "Fidelity",
"holderAddressCity": "Palo Bajo",
"items": [
{
"itemNumber": 1,
"type": "CheckingAccount",
"accountIdentifier": "31212",
"cashOrMarketValueAmount": 12000,
"depositoryAccountName": "Ken N Customer JR"
},
{
"itemNumber": 2,
"type": "SavingsAccount",
"accountIdentifier": "21212",
"cashOrMarketValueAmount": 22000,
"depositoryAccountName": "Ken N Customer JR"
},
{
"itemNumber": 3,
"type": "MutualFunds",
"accountIdentifier": "21212",
"cashOrMarketValueAmount": 32000,
"depositoryAccountName": "Ken N Customer JR"
}
]
}
]
}
]
}
Step 2: Subsequent Update:
Let's assume the borrowers in the subject loan re-freshed their deposit verification, and decided to make some changes to the deposits reported. The Partner integration will send the following in an updated response to the new VOD report re-fresh transaction request:
- Updated deposit record values for Bank of America and Fidelity (update)
- Not include (remove) the previously sent deposit record object for Wells Fargo (delete)
- New deposit records object from the borrower's E*TRADE account (append)
==> Response for Verification of Deposits - subsequent transaction:
{
"status": "completed",
"partnerStatus": "VOD's Verified",
"referenceNumber": "CXV90345",
"loanFormat": "application/vnd.plm-2.0.0+json",
"loan": {
"applications": [
{
"id": "85c37a19-4b25-45f3-8773-d2d7fe3b6419",
"vods": [
{
"recordId": "dd26115b-cf57-4516-a53c-c4b30f40eedd",
"title": "Bank of America",
"holderAddressCity": "Palo Bajo",
"items": [
{
"itemNumber": 1,
"type": "CheckingAccount",
"accountIdentifier": "123456",
"cashOrMarketValueAmount": 15000,
"depositoryAccountName": "Ken N Customer JR"
},
{
"itemNumber": 2,
"type": "MoneyMarketFund",
"accountIdentifier": "22212",
"cashOrMarketValueAmount": 31000,
"depositoryAccountName": "Ken N Customer JR"
}
]
},
{
"recordId": "a978c0bc-59a2-4d50-80d5-d9bf0398b369",
"title": "Fidelity",
"holderAddressCity": "Palo Bajo",
"items": [
{
"itemNumber": 1,
"type": "CheckingAccount",
"accountIdentifier": "31212",
"cashOrMarketValueAmount": 10000,
"depositoryAccountName": "Ken N Customer JR"
},
{
"itemNumber": 2,
"type": "SavingsAccount",
"accountIdentifier": "21212",
"cashOrMarketValueAmount": 20000,
"depositoryAccountName": "Ken N Customer JR"
},
{
"itemNumber": 3,
"type": "MutualFunds",
"accountIdentifier": "21212",
"cashOrMarketValueAmount": 30000,
"depositoryAccountName": "Ken N Customer JR"
}
]
},
{
"recordId": "37f5bf3e-fcf4-4cda-8c22-a874f33b66f6",
"title": "E*TRADE",
"holderAddressCity": "Palo Bajo",
"items": [
{
"itemNumber": 1,
"type": "MutualFunds",
"accountIdentifier": "21212",
"cashOrMarketValueAmount": 100000,
"depositoryAccountName": "Ken N Customer JR"
}
]
}
]
}
]
}
}
EPC will update the $.applications[?(@.id == '85c37a19-4b25-45f3-8773-d2d7fe3b6419')].vods collection by replacing the original VOD collection data created by the Partner's initial transaction response, with assets received for Bank of America, Fidelity, and E*TRADE. The updated collection inside the loan object will only have items with the following recordId's:
dd26115b-cf57-4516-a53c-c4b30f40eedd(existing - Bank of America record)a978c0bc-59a2-4d50-80d5-d9bf0398b369(existing - Fidelity record)37f5bf3e-fcf4-4cda-8c22-a874f33b66f6(new - E*TRADE record)
==> Loan Updated State - Subsequent Transaction Response:
{
"applications": [
{
"id": "85c37a19-4b25-45f3-8773-d2d7fe3b6419",
"vods": [
// previously existing VOD's, not owned/delivered by the Partner
{
...
},
{
...
},
{
...
},
// Partner's updated VOD's - from subsequent PATCH /response operation
{
"recordId": "dd26115b-cf57-4516-a53c-c4b30f40eedd",
"title": "Bank of America",
"holderAddressCity": "Palo Bajo",
"items": [
{
"itemNumber": 1,
"type": "CheckingAccount",
"accountIdentifier": "123456",
"cashOrMarketValueAmount": 15000,
"depositoryAccountName": "Ken N Customer JR"
},
{
"itemNumber": 2,
"type": "MoneyMarketFund",
"accountIdentifier": "22212",
"cashOrMarketValueAmount": 31000,
"depositoryAccountName": "Ken N Customer JR"
}
]
},
{
"recordId": "a978c0bc-59a2-4d50-80d5-d9bf0398b369",
"title": "Fidelity",
"holderAddressCity": "Palo Bajo",
"items": [
{
"itemNumber": 1,
"type": "CheckingAccount",
"accountIdentifier": "31212",
"cashOrMarketValueAmount": 10000,
"depositoryAccountName": "Ken N Customer JR"
},
{
"itemNumber": 2,
"type": "SavingsAccount",
"accountIdentifier": "21212",
"cashOrMarketValueAmount": 20000,
"depositoryAccountName": "Ken N Customer JR"
},
{
"itemNumber": 3,
"type": "MutualFunds",
"accountIdentifier": "21212",
"cashOrMarketValueAmount": 30000,
"depositoryAccountName": "Ken N Customer JR"
}
]
},
{
"recordId": "37f5bf3e-fcf4-4cda-8c22-a874f33b66f6",
"title": "E*TRADE",
"holderAddressCity": "Palo Bajo",
"items": [
{
"itemNumber": 1,
"type": "MutualFunds",
"accountIdentifier": "21212",
"cashOrMarketValueAmount": 100000,
"depositoryAccountName": "Ken N Customer JR"
}
]
}
]
}
]
}
That's how easy it is for Partners integrating with the EPC platform to append, update, and delete collection valued loan entities!
Updated over 4 years ago