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.

Updated over a week ago

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
Searching Opportunities and Contacts
Managing related parties via the Mercury API
Managing assets
Managing Mercury API Webhooks
Mercury API FAQs
Did this answer your question?