Skip to main content

Nexus Financials Living Expenses Endpoint

There is an API endpoint available for the Living Expenses section of Financials. IT can be used as below for existing Mercury Opportunity records.

The API uses keyed extensions at the opportunity level, not contact-level expenses, to manage living expenses.

Retrieve Living Expenses by Opportunity ID

GET

Token: Your branch API token

Id: The unique ID for your Opportunity record

A successful set of returned data will look like the following,

NOTE: all unique codes have been redacted in this wiki

{

"uniqueId": "ece74c1b-e8XXXXXXXX05056b5e136",

"parentType": "loan",

"parentId": "2f280310-33XXXXXXXXX-b2f975f67ee8",

"key": "livingExpense",

"value": "[{\"uniqueId\":\"29a49080-XXXXXXXX1b-e9f16328a787\",\"amount\":\"1000.00\",\"type\":\"Clothing & Personal Care\",\"frequency\":\"Monthly\",\"splits\":[{\"personId\":\"5aeef758-34XXXXXXX4d3c2c77e247\",\"percent\":60},{\"percent\":40,\"personId\":\"e885520a-XXXXXXXX25-25d36fd0cd93\"}]}]"

}

uniqueId = This is the unique database value for the Living Expenses for the Opportunity

parentId = This is the unique Opportunity Id

value = This is the complete list of Living Expense values on this Opportunity record

personId = This is the unique database value for the Contact(s) linked to the Living Expense line items

Every personId in the splits array must be a related party on the opportunity. Use GET /opportunities/{loanId}/relatedParties to verify related parties.

The Amount, Type, Frequency and Percentage of Ownership is included in the Value sub section.

If there are no Living Expenses loaded in the Financials of the Opportunity record the returned data will look like the following. The Value section is empty.

{

"uniqueId": "ece74c1b-e8XXXXXXXX5056b5e136",

"parentType": "loan",

"parentId": "2f280310-33XXXXXXXXf975f67ee8",

"key": "livingExpense",

"value": "[]"

}

As the returned data was not completely empty. This indicates that the Opportunity does have a uniqueId already which would need to be used when updating the Living Expenses on this Opportunity record.

A second POST to the same key will return a 400 error, so it is critical to check the GET response first.

--------------------------------------------------------------------------------------------------------------------

How to create the Opportunity Living Expenses unique ID

NOTE: If in previous step a unique ID was returned, there is no requirement to run a POST

POST

{

"uniqueId": "b173327e-fbf6-11XXXXXXXX5056b526da",

"parentType": "loan",

"parentId": "29d8919f-ea3a-4XXXXXXXXXX6dce3b1d",

"key": "livingExpense",

"value": "[]"

}

--------------------------------------------------------------------------------------------------------------------

How to add or update the Opportunity Living Expenses

NOTE: The value data sent in will replace all existing entries so it is important to include any existing Living Expenses line items in the PUT payload.

To update living expenses, follow the Read-Modify-Write process: use GET to retrieve the full array of living expenses, merge changes locally, and then use PUT to update the complete set.

PUT

{

"uniqueId":"bb9b45d0-e8XXXXXXXXf6894d1cbfa",

"key":"livingExpense",

"parentId":"2f280310-3372XXXXXXXXf975f67ee8",

"parentType":"loan",

"value":"[{\"uniqueId\":\"1ece8ba0-XXXXXXXX2-9f6894d1cbfc\",\"amount\":\"200\",\"type\":\"Child & Spouse Maintenance\",\"frequency\":\"Monthly\",\"splits\":[]}]"

}

When creating a new Living Expense line item a unique ID needs to be generated and inserted into your payload. Below is a website which can generate unique codes.

ID Generator site

Here is another example with the Ownership of the line item also being edited, it is split 60/40 between two contacts.

{

"uniqueId":"ece74c1b-e85XXXXXXXX056b5e136",

"parentId":"2f280310-3XXXXXXXXb2f975f67ee8",

"parentType":"loan",

"key":"livingExpense",

"value":"[{\"uniqueId\":\"29a49080-e8XXXXXXXX-e9f16328a787\",\"amount\":\"1000.00\",\"type\":\"Clothing & Personal Care\",\"frequency\":\"Monthly\",\"splits\":[{\"personId\":\"5aeef758-34XXXXXXXX4d3c2c77e247\",\"percent\":60},{\"percent\":40,\"personId\":\"e885520a-e149XXXXXXXX25d36fd0cd93\"}]}]"

Troubleshooting Missing Living Expenses

If living expenses or ownership details are not appearing in the Financials tab, consider the following:

  1. Applicant/Guarantor Status:

    • Only individuals marked as applicants or guarantors will have their living expenses displayed.

    • If a person is listed as a director or another role, their data will not appear.

  2. Completion of Relevant Sections:

    • Ensure the individual has completed the necessary sections for their data to display.

}

If you do not include Ownership in the PUT payload it will be automatically allocated evenly across the Contacts.

Did this answer your question?