The Nexus API v2 is Connective's single REST API for partner integrations, replacing the older Mercury API and Nexus API v1. For complete endpoint details, fields and operations, always refer to the developer portal.
This article is for developers and software providers building integrations with Connective. You should be comfortable with REST APIs, JSON and OAuth 2.0.
Finding the API documentation
Any partner can access the developer portal at developer.connective.com.au. Sign in with your Mercury username and password.
The developer portal holds:
the OpenAPI (Swagger) specification for every operation
the fields each request and response uses
the permissions (scopes) each operation needs
the possible errors
the identity provider addresses, API audience and scope names you need for sign-in
Note: The developer portal is the only source of truth for the API. Don't rely on older articles, saved copies of the specification or third-party descriptions. The portal is updated at any time.
API address and environments
Production: https://apis.connective.com.au/api/v2
Staging (sandbox): A sandbox environment is available for testing your integration safely. Access is on request through the Mercury Helpdesk. Its details will be added to the developer portal later.
Note: Use HTTPS only. Requests over plain HTTP are not supported.
Getting access to the API
All access is arranged through the Mercury Helpdesk. It is the only contact for integration requests, technical questions and registration.
Submit a request to the Mercury Helpdesk to register your integration.
Tell them the exact redirect URI (or URIs) your application will use after sign-in.
The Helpdesk registers your redirect URIs and gives you a client ID.
If you want to test first, ask the Helpdesk for access to the staging environment.
Tip: Create a dedicated Mercury user for your integration, rather than using a person's own login. This keeps the integration's access separate and easy to manage.
How authentication works
The API uses OAuth 2.0 with the Authorization Code flow and PKCE (using the S256 method). Sign-in is handled by Connective's identity provider.
Key points:
Your application is a public client. There is no client secret.
Tokens are issued to a signed-in Mercury user and act with that user's permissions.
Each person or integration user signs in themselves. Your application never handles their Mercury password.
Important: These are not supported: client credentials (machine-to-machine) access, API keys, static API tokens and client secrets. If your system needs unattended access, sign in as your dedicated integration user and keep its refresh token safe (see below).
The sign-in steps
The exact addresses, API audience and scope names are on the developer portal.
Start sign-in. Send the user's browser to the identity provider's authorise address. Include your client ID, your registered redirect URI, your PKCE code challenge (S256), the API audience and the scopes you need. Request all the scopes you need at once. Include the scopes for sign-in (
openid) and for a refresh token (offline_access).User signs in. The user signs in with their Mercury credentials and approves access.
Receive the code. The identity provider redirects back to your redirect URI with a one-time authorisation code.
Exchange the code for tokens. Send the code and your original PKCE code verifier to the token address. You receive an access token and, because you asked for it, a refresh token.
Call the API. Send the access token with every request in the
Authorization: Bearerheader.Refresh when the access token expires. Send the refresh token to the token address to get a new access token. Don't assume how long a token lasts. Use the expiry information returned with the token.
Store the newest refresh token. Refresh tokens rotate. Each time you refresh, you receive a new refresh token, and you must store it and use it next time. The previous one stops working.
If refresh fails, sign in again. If the refresh token is rejected or has expired, send the user through the sign-in steps again.
What your integration can do and see
Permissions (scopes)
Scopes decide what your integration is allowed to do. Each operation on the developer portal lists the scopes it needs. If your access token is missing a required scope, the API returns a 403 (forbidden) response.
Request only the scopes you need. If you later need more, sign the user in again with the extra scopes.
Data access
Your integration can only see the data the signed-in Mercury user can see in Mercury, which depends on their partner and branch. Two integrations signed in as different users can see different data.
A 404 (not found) response can mean either that the record doesn't exist or that it isn't visible to the signed-in user.
Using the API: general conventions
The details of every operation are on the developer portal. These conventions apply across the API.
JSON. Requests and responses use JSON.
Partial updates. Updates that change only some fields use JSON Merge Patch. Send only the fields you want to change.
Creating records. When you create a record, the response tells you the location of the new record.
Safe retries when creating. Where an operation supports it, you can send an idempotency key with a create request. If you have to retry (for example after a timeout), the same key stops the record being created twice.
Lists. Lists are paged and sorted. Use the paging details in each response to fetch the next page.
Searching and filtering. Filtering is done with search requests. See the portal for what each search supports.
Protection against overwriting. Where an operation offers it, use the ETag from a response and send it back in an If-Match header when you update. If someone else changed the record in the meantime, your update is rejected instead of overwriting their change.
Warnings. A successful write may include warnings. Consider showing these to your users.
Handling errors
Errors follow the standard problem-details format (RFC 9457) and include a trace ID. Always log the trace ID (without any tokens) so you can quote it to the Helpdesk.
Managing rate limits and temporary problems
If the API responds with 429 (too many requests) or 503 (service unavailable), wait for the time given in the Retry-After header before you try again. Don't retry immediately or in a tight loop.
Security best practice
Keep access tokens and refresh tokens out of logs, error messages and URLs.
Store refresh tokens securely, for example in an encrypted secrets store. Never store them in client-side code or in source control.
Use HTTPS only.
Request only the scopes you need.
Use a dedicated integration user, and remove its access when the integration is retired.
Keep your PKCE verifier secret and use a new one for each sign-in.
Quick start checklist
Sign in to developer.connective.com.au with your Mercury username and password, and read the specification.
Contact the Mercury Helpdesk to register your integration, give them your exact redirect URI(s), and receive your client ID.
Ask for staging access if you want to test first.
Create a dedicated integration user in Mercury.
Build the Authorization Code flow with PKCE (S256), requesting all the scopes you need, including
openidandoffline_access.Call the API with the
Authorization: Bearerheader.Store the newest refresh token every time you refresh, and sign the user in again if refresh fails.
Handle 403 and 404 responses, and wait for Retry-After on 429 and 503.
Log the trace ID from any error response.
Re-check the developer portal whenever you update your integration.
Need help?
If you need support with your integration or have technical questions, contact your Partnership Manager or email [email protected]. Include the trace ID from any error response, the date and time of the request (with time zone), and the operation you were calling. Never include access tokens, refresh tokens or passwords in your request.