This article explains how to manage Opportunities in the Mercury API.
Creating opportunities (with or without its nested entities)
METHOD: POST
Creating an opportunity can be done with or without the nested entities.
There is no need to provide a unique id either for opportunity or its nested entities (asset, liability and relatedParties) as it will be auto-generated by Mercury.
Note: Please refer to the note at the bottom of this article regarding Lead Source.
Sample request
{ "opportunityName": "Test Opportunity", "amount": "350000"}OR
Sample request
{ "opportunityName": "Test Opportunity Nested Entities", "amount": "350000", "assets": [ { "name": "Boat", "type": "standard", "value": 100000 } ], "liabilities": [ { "name": "Maintenance", "type": "standard", "value": 100000, "details": "" } ], "relatedParties": [ { "personID": "e2970b4e-a8bc-11e7-9efd-00155d00a466", "relationship": "Primary Applicant" } ]}After creating the opportunity, it will return a unique id for the opportunity in the response.
Sample response
{ "uniqueId": "55c31db1-142c-11e7-a0a2-00155d009933", "emailId": ""}Fetching opportunity by id
METHOD: GET
To retrieve a specific opportunity, the opportunity unique id needs to be provided in the URL.
Sample response
{ "uniqueId": "55c31db1-142c-11e7-a0a2-00155d009933", "company": "P200052", "isDeleted": false, "createdOn": 1490756658000, "amount": 0, "discount": 0, "existingAmount": 0, "lmi": 0, "settlementDateConfirmed": false, "transactionType": "Loan", "workspaceUsers": "", "tranxType": "", "connectiveLodgeId": 0, "peResidualAmount": 0, "peRepaymentAmount": 0, "peEffectiveRate": 0, "peInterestRate": 0, "peBrokerage": 0, "loanTerm": 0, "partnerName": "COSN Dev Test Company33", "statusLastUpdated": 1490756657000, "securityValue": 0, "aliApplicationId": "", "metlifeApplicationId": "", "lastUpdated": 1490756658000, "originationFee": 0, "opportunityName": "SOAP UI Test Opportunity # 818", "assets": [ { "uniqueId": "4c99eb9d-a8bd-11e7-9efd-00155d00a466", "name": "Boat", "type": "standard", "value": 100000 } ], "liabilities": [ { "uniqueId": "53f74dfa-a8bd-11e7-9efd-00155d00a466", "name": "Maintenance", "type": "standard", "value": 100000, "details": "" } ], "relatedParties": [ { "uniqueId": "0dfeccb8-a8be-11e7-9efd-00155d00a466", "personID": "e2970b4e-a8bc-11e7-9efd-00155d00a466", "relationship": "Primary Applicant" } ]}
Updating an opportunity or its nested entities
METHOD: PUT
Updating an opportunity can be done with or without the nested entities. The opportunity unique id needs to be provided in the URL.
To update any of the nested entities within the following rules will apply:
If the unique id of nested entity is provided, it will update the entity.
if the unique id is absent, it will create a new nested entity
If the "isDeleted" field is set to true in the nested entity, it will delete the nested entity (Refer to the Deleting an opportunity or its nested entities section)
Note: Please refer to the note at the bottom of this article regarding Lead Source.
Sample request
{ "amount": 600000, "lmi": 12000, "loanTerm": 30}OR
Sample request
{ "amount": 600000, "lmi": 12000, "loanTerm": 30, "assets": [ { "uniqueId": "4c99eb9d-a8bd-11e7-9efd-00155d00a466", "value": 200000 } ], "liabilities": [ { "uniqueId": "53f74dfa-a8bd-11e7-9efd-00155d00a466", "value": 200000 } ], "relatedParties": [ { "uniqueId": "0dfeccb8-a8be-11e7-9efd-00155d00a466", "relationship": "Applicant" } ]}Deleting an opportunity or its nested entities
METHOD: PUT
Sample request
{ "isDeleted": true}OR
Sample request
{ "assets": [ { "uniqueId": "4c99eb9d-a8bd-11e7-9efd-00155d00a466", "isDeleted": true } ], "liabilities": [ { "uniqueId": "53f74dfa-a8bd-11e7-9efd-00155d00a466", "isDeleted": true } ], "relatedParties": [ { "uniqueId": "0dfeccb8-a8be-11e7-9efd-00155d00a466", "isDeleted": true } ]}** Special Case For Lead Source **
Here are the rules for assigning "Lead Source" to opportunity:
To assign a specific "Lead Source" to an opportunity using create or update method, "leadSourceId" or "leadSourceDisplay" need to be defined inside the nested "Lead Source" payload.
If "leadSourceDisplay" is defined without "leadSourceId", the system will check if the existence of the "Lead Source".
If "leadSourceDisplay" does exist in the system, the "Lead Source" will be assigned for that opportunity.
If "leadSourceDisplay" does not exist in the system, a new "Lead Source" will be created with the provided "leadSourceDisplay" and the new "Lead Source" will be assigned for that opportunity.
If "leadSourceId" is defined without "leadSourceDisplay", the system will check if the existence of the "Lead Source".
If "leadSourceId" does exist in the system, the "Lead Source" will be assigned for that opportunity.
If "leadSourceId" does not exist in the system, the "Lead Source" will not be assigned for that opportunity.
If both "leadSourceDisplay" and "Lead SourceId" are defined,
and "leadSourceDisplay" and "leadSourceId" match in the system, the "Lead Source" will be assigned for that opportunity.
and "leadSourceDisplay" and "leadSourceId" did not match in the system,
if "leadSourceId" exists, it will update the "leadSourceDisplay" that is being provided. the "Lead Source" will not be assigned for that opportunity.
if "leadSourceId" does not exists but "leadSourceDisplay", a new "Lead Source" will be created with the provided "leadSourceDisplay" and the new "Lead Source" will be assigned for that opportunity.