Skip to main content

Managing Opportunities via the Mercury API

Learn how to create, retrieve, update and delete Opportunities and nested entities using the Mercury API.

This article explains how to manage Opportunities using the Mercury API, including nested entities such as assets, liabilities and related parties.

Create an Opportunity

Endpoint

POST https://apis.connective.com.au/mercury/v1/{token}/opportunities

You can create an Opportunity:

  • With or without nested entities

  • Without supplying unique IDs (Mercury auto-generates them)

Basic Opportunity example

{   "opportunityName": "Test Opportunity",   "amount": "350000" }

Opportunity with nested entities

{   "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"     }   ] }

Sample response

{   "uniqueId": "55c31db1-142c-11e7-a0a2-00155d009933",   "emailId": "" }

The uniqueId is required for future update and retrieval operations.

Fetch an Opportunity by ID

Endpoint

GET https://apis.connective.com.au/mercury/v1/{token}/opportunities/{id}

Replace {id} with the Opportunity uniqueId.

Sample response

{   "uniqueId": "55c31db1-142c-11e7-a0a2-00155d009933",   "company": "P200052",   "isDeleted": false,   "createdOn": 1490756658000,   "amount": 0,   "transactionType": "Loan",   "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"     }   ] }

Update an Opportunity

Endpoint

PUT https://apis.connective.com.au/mercury/v1/{token}/opportunities/{id}

Update Opportunity fields only

{   "amount": 600000,   "lmi": 12000,   "loanTerm": 30 }

Update nested entities

Rules for nested entities:

  • If uniqueId is provided → existing entity is updated

  • If uniqueId is omitted → new entity is created

  • If "isDeleted": true → entity is soft deleted

Example:

{   "amount": 600000,   "assets": [     {       "uniqueId": "4c99eb9d-a8bd-11e7-9efd-00155d00a466",       "value": 200000     }   ],   "relatedParties": [     {       "uniqueId": "0dfeccb8-a8be-11e7-9efd-00155d00a466",       "relationship": "Applicant"     }   ] }

Delete an Opportunity (soft delete)

Endpoint

PUT https://apis.connective.com.au/mercury/v1/{token}/opportunities/{id}

Delete entire Opportunity

{   "isDeleted": true }

Delete nested entities

{   "assets": [     {       "uniqueId": "4c99eb9d-a8bd-11e7-9efd-00155d00a466",       "isDeleted": true     }   ],   "relatedParties": [     {       "uniqueId": "0dfeccb8-a8be-11e7-9efd-00155d00a466",       "isDeleted": true     }   ] }

Special Case: Lead Source assignment

Lead Source must be provided inside a nested leadSource payload.

You can assign Lead Source using:

  • leadSourceId

  • leadSourceDisplay

  • or both

Rules

If only leadSourceDisplay is provided:

  • If it exists → assign it

  • If not → create new Lead Source and assign

If only leadSourceId is provided:

  • If it exists → assign it

  • If not → no assignment

If both are provided:

  • If they match → assign

  • If they do not match:

    • If leadSourceId exists → update display name but do not assign

    • If leadSourceId does not exist but display exists → create new and assign

Important notes

  • Replace {token} with valid authentication token.

  • All nested entity deletions are soft deletes (isDeleted: true).

  • Unique IDs are auto-generated when not supplied.

Need help?

For API integration assistance, contact your Partnership Manager or email [email protected].

Related Articles
Getting Started with Mercury API
Managing related parties via the Mercury API
Managing assets
Managing Mercury API Webhooks
Mercury API FAQs
Did this answer your question?