There is an API endpoint available for the Other Income section of Financials. It can be used as below for existing Mercury Opportunity records.
NOTE: all unique codes have been redacted in this wiki
Retrieve Other Income by Opportunity ID
Type: 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,
{
"uniqueId": "ece74c1b-e8XXXXXXXX05056b5e136",
"parentType": "loan",
"parentId": "2f280310-33XXXXXXXXX-b2f975f67ee8",
"key": "otherIncome",
"value": "[{\"uniqueId\":\"29a49080-XXXXXXXX1b-e9f16328a787\",\"amount\":\"1000.00\",\"type\":\"Maintenance\",\"frequency\":\"Monthly\",\"splits\":[{\"personId\":\"5aeef758-34XXXXXXX4d3c2c77e247\",\"percent\":60},{\"percent\":40,\"personId\":\"e885520a-XXXXXXXX25-25d36fd0cd93\"}]}]"
}
Definitions
uniqueId = This is the unique database value for the Other Income for the Opportunity
parentId = This is the unique Opportunity Id
value = This is the complete list of Other Income values on this Opportunity record
personId = This is the unique database value for the Contact(s) linked to the Other Income line items
The Amount, Type, Frequency and Percentage of Ownership is included in the Value sub section.
If there are no Other Income 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": "otherIncome",
"value": "[]"
}
Note: 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 Other Income on this Opportunity record.
How to create the Opportunity Other Income unique ID
Note: If in previous step a unique ID was returned, there is no requirement to run a POST
Type: POST
{
"uniqueId": "b173327e-fbf6-11XXXXXXXX5056b526da",
"parentType": "loan",
"parentId": "29d8919f-ea3a-4XXXXXXXXXX6dce3b1d",
"key": "otherIncome",
"value": "[]"
}
How to add or update the Opportunity Other Income
Note: The value data sent in will replace all existing entries so it is important to include any existing Other Income line items in the PUT payload.
Type: PUT
{
"uniqueId":"bb9b45d0-e8XXXXXXXXf6894d1cbfa",
"key":"otherIncome",
"parentId":"2f280310-3372XXXXXXXXf975f67ee8",
"parentType":"loan",
"value":"[{\"uniqueId\":\"1ece8ba0-XXXXXXXX2-9f6894d1cbfc\",\"amount\":\"200\",\"type\":\"Maintenance\",\"frequency\":\"Monthly\",\"splits\":[]}]"
}
When creating a new Other Income 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":"otherIncome",
"value":"[{\"uniqueId\":\"29a49080-e8XXXXXXXX-e9f16328a787\",\"amount\":\"1000.00\",\"type\":\"Maintenance\",\"frequency\":\"Monthly\",\"splits\":[{\"personId\":\"5aeef758-34XXXXXXXX4d3c2c77e247\",\"percent\":60},{\"percent\":40,\"personId\":\"e885520a-e149XXXXXXXX25d36fd0cd93\"}]}]"
}
Note: If you do not include Ownership in the PUT payload it will be automatically allocated evenly across the Contacts.