About Mercury API
The Mercury public API will allow integrations to your Person and Opportunity records. There are four types of payloads that can be used.
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, employment
Update contacts, addresses, incomes, expenses, employment
Fetch contacts, addresses, incomes, expenses, employment
Delete contacts, addresses, incomes, expenses, employment
Search opportunities and contacts
Note: There are no endpoints for the Connective products database available.
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.
The Version 1 exposes the following top level entities and their children:
Opportunities:
Assets
Liabilities
Related parties
Contacts:
Contact methods
Incomes
Expenses
Addresses
Employment
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
What if the field I want to use does not have an endpoint?
Not all Person and Opportunity fields currently have endpoints. If you want a new field made available, request this via the Ideas Portal. When updates are made these requests will all be taken into consideration.
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/
To connect to the API you will need to add API token. User with Partner Level access will find their API key and token in the Integrations section of the Admin App.
For each API request, add the following header.
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:
Open up Postman
Create a GET request to the following URL:
https://apis.connective.com.au/mercury-v1/{token}/opportunities?search=true&searchParams=%7B%22lastUpdated%22%3A%222017-03-20%22%7D
The value of the searchParams query param is the URL encoded JSON string {"lastUpdated":"2017-03-20"}Replace the {token} in the URL with the token for your API user
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 file and that will automatically create the endpoints:
Press Import on the top left corner of Postman
Drag and drop the swagger file in the popup window
This will automatically create a collection for all endpoints in the left navigation panel of Postman
For more complex searches refer the swagger documentation: https://swagger.io/docs/
What are the rate limits?
The max request per second is limited to 60
The daily quota of requests is limited to 40000
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, please submit a ticket via the Mercury Helpdesk.