Getting Started with Mercury API

About Mercury API

Version 1 of the Mercury API will allow integrations to:

• Create opportunities, assets, liabilities, related parties
• Update opportunities, assets, liabilities, related parties
• Fetch opportunities, assets, liabilities, related parties
• Delete opportunities, assets, liabilities, related parties
  
  
• Create contacts, addresses, incomes, expenses
• Update contacts, addresses, incomes, expenses
• Fetch contacts, addresses, incomes, expenses
• Delete contacts, addresses, incomes, expenses
  
  
• Search opportunities and contacts 

The Mercury API handles only JSON requests over HTTPS using three standard HTTP verbs GET, PUT, POST.

The DELETE VERB is not supported yet. To do a delete you need to make a PUT request, with the isDeleted property set to true in the JSON payload

The API exposes the mercury data model with a separate endpoint for each entity.

The API uses Unix Date Format. To convert a human readable date into Unix, use the following site.

https://www.epochconverter.com/

The Version 1 exposes the following top level entities and their children:

Opportunities:

• Assets
• Liabilities
• Related parties

Contacts:

• Contact methods
• Incomes
• Expenses
• Addresses

The Mercury API endpoints are laid out in a similar fashion which reflect the parent-child relationship. For example: 

GET a contact by id:

/contacts/{id}

To get all expenses for a contact do a GET as follows:

/contacts/{id}/incomes

How do you get started?

The API endpoints are structured as follows:

https://host/apiName/version/{token}/entityName 

Host: apis.connective.com.au or io.connective.com.au

apiName: mercury

version: v1

{token}: security token unique to each user accessing the API

EntityName: the name of the entity you are working with. Eg. Contacts or opportunities

Production URL: https://apis.connective.com.au/mercury/v1/

Note: The sandbox URL follows a slightly different scheme:

https://host/apiName-version/{token}/entityName

Sandbox URL: https://sandbox.connective.com.au/mercury-v1/

To connect to the API you will need two things:

1. An API User account: This is essentially a Mercury account, with a long-life security token, which will go into the {token} path param of the every endpoint. This token is unique to each user. This will make it easy to audit and track and separate out the activity done via the API vs a human user. One security token has already been sent to you as part of the Welcome email. 
   Note: If you require additional tokens, please contact the Connective Helpdesk. 
2. API Key

For each API request, add the following header. This is the API key provided to you in the API welcome email, which uniquely identifies your broker group. This key is the same for both v1 and sandbox

x-api-key:keyvalue

For example, assuming you are using Postman, and want to search for opportunities in your sandbox account, which were updated after 20th March 2017 you will need to do this:

1. Open up Postman 
2. Create a GET request to the following URL:
   https://sandbox.connective.com.au/mercury-v1/{token}/opportunities?search=true&searchParams=%7B%22lastUpdated%22%3A%222017-03-20%22%7D
   The value of the searhParams query param is the URL encoded JSON string {"lastUpdated":"2017-03-20"}
3. Replace the {token} in the URL with the token for your API user
4. Next in the Headers tab, add the following header x-api-key:keyvalue
   The request should look like this in Postman

     5. Press send you should get a response with a HTTP status code 200, and if there are any opportunities created after 20th March 2017, they will be present in the response body

TIP: If using Postman, you can also simply just import the Swagger.yml and that will automatically create the endpoints:

1. Press Import on the top left corner of Postman
   
   
2. And just drag and drop the swagger in the popup that come up:
   
3. This will automatically create a collection for all endpoints in the left navigation panel of postman
   

For more complex searches refer the swagger documentation: swagger.yml

What are the rate limits?

The max request per second is limited to 60

The daily quota of requests is limited to 20000

Note: If you have specific needs for which you need additional quota, please contact us via the standard help desk process.

Getting help

If you require support during the API Pilot Program, please submit a ticket via the Mercury Helpdesk and be sure to mention that you are participating in the API Pilot Program.