Our API is organised around REST.

It has resource-oriented URLs, and uses HTTP response codes to indicate API errors.

We support Cross-Origin Resource Sharing (CORS), allowing you to interact securely with our API from a client-side web application using the X-Api-Key request header. Note that the API has varying access and authorization scopes and you should never expose your secret API key in any public website's client-side code.

JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

To make the API as explorable as possible, we provide a sandbox environment. Requests made with sandbox credentials are for prototyping only and do not hit our production systems.

First, you will need some API keys for your application. You can create and manage your API keys in our Developer Portal.

Depending on the type of application you create, you will need:

• Client ID: Useful for input to the X-Api-Key request header which allows access to some endpoints with unathenticated access, and/or;

• Client Secret: Useful for back-end applications. This credential carry many privileges, so be sure to keep them secure. Do not share your secret keys in publicly accessible areas such as GitHub, client-side code, and so forth.

You can create multiple sets of credentials to represent each of your applications.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. In most cases, API requests without the appropriate authentication will also fail, with the exception of some endpoints as outlined in Unauthenticated Access below.

Node.js API Client Library

Once you have your credentials, you have the option of using our Node.js client library to easily get started.

npm install @sargon/api-client

Hitting Our Endpoints Directly

You can also hit our endpoints directly on api.sargon.com. We recommend using tools such as Postman or cURL to test the endpoints.

The API can be accessed with various access levels:

• Unauthenticated Access (UnauthenticatedUser): Some endpoints may be accessed without first verifying the user's identity. An example is Create Member that is used for onboarding new members. For these endpoints, you can use your application's Client ID credential in the request as header X-Api-Key.

• User Access (AuthenticatedUser): User access is for requests representing a user, for example a fund member.

• Integration Access (Integration): Integration access is for access to fund-level data and machine-to-machine API usage.

Upon access, the API uses OAuth authorisation scopes to ensure secure access for the appropriate user and integration.

Available scopes:

• Member Scope: https://api.sargon.com/member provides 'member level' information and typically used for member-facing online experiences. For security, the API scope is restricted to access an individual member.

• Integration Scope: https://api.sargon.com/integration provides 'fund level' information and facilitates flexible integrations to analytics and operational software. This only be requested using a backend client and Client Credentials grant.

Further details on the appropriate access can be found below.

This section aims to outline some of the key characteristics and behaviours of the API.

Our API returns dollar values as 'money objects'. In the usual case, a dollar value is represented as the number of whole cents, in currency 'AU'.

For example, the below money object represents AUD $100.10

{
  "amount": 10010,
  "currency": "AUD",
  "precision": 2
}

In the case of the Get Historical Investment Performance endpoint, the buy price and sell price values are represented like this:

{
  "amount": 1234567,
  "currency": "AUD",
  "precision": 6
}

The above example represents a dollar value of $1.234567 (precision is to 6 decimal places).

A popular javascript library such as Dinero will accept the above money objects, e.g:

const price = Dinero({ "amount": 1234567, "currency": "AUD", "precision": 6 })

We use conventional HTTP response codes to indicate the success or failure of an API request.

In general:

• Codes in the 2xx range indicate success.

• Codes in the 4xx range indicate an error that failed given the information provided (e.g. required and/or insufficient parameters)

• Codes in the 5xx range indicate an error with our servers (these are rare).

Errors that could be handled programmatically include an error code that briefly explains the error reported.

Generally, the API uses UUID as the primary unique identifier for most Resources.

That being said, the API consists of a number of identifiers for a Member. The use of the appropriate identifier depends on your specific use cases. These are:

• memberId (Member UUID): A unique UUID generated instantly and is returned synchronously upon Create New Member.

• impactId (Impact ID or Friendly Member Id): A sequential number generated upon Create New Member by Impact. It is unique and more 'human friendly' than memberId (Member UUID). While this number is useful in some use cases, we recommend transitioning away from the use of impactId when communicating to members in favour of a more familiar and intuitive identifier such as email.

• registryId (Registry Identifier): An identifier allocated by your applicable fund registry. It has the following characteristics:

  • The registryId is typically not generated instantly and cannot be returned synchronously upon the creation of a new member. It is typically allocated after the memberId (Member UUID) and impactId (Member Number) have been assigned.

  • The registryId may be communicated to members in their official statements and communications produced by the underlying fund registry. You can retrieve the registryId after a new Member has been created via a webhook.

Some top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list members and transactions.

These list API methods share a common structure, taking at least these two parameters: page.size (page size), and page.offset (and the starting offset).

We generally avoid making backwards-incompatible changes to the API. By default, all API calls will be made to the latest version of our API.

The API has been designed from the ground up with security in mind including access control, API security best practices including industry and widely accepted standards for authentication.

The security implementation within the API is part of a larger security environment and is enhanced by additional security measures at the network infrastructure level and back-office operational controls.

For production applications integrating with our platform, an additional integration security assessment and monitoring adds an additional layer of security.

Some API operations require additional authorisation through the use of a One Time Password (OTP) from the member.

In these cases the API will return a HTTP Status 401 (Unauthorised) and provide additional information in the X-Super-OTP response header. While MFA is important in mitigating security risks, OTP restrictions may be relaxed upon request of specific circumstances where other security controls are applicable.

The format of the X-Super-OTP response header is:

X-Super-OTP`: [status]

Status values:

• required - A One-time password is required for this operation. Please retry the operation including X-Super-OTP header.
• valid - A previous challenge is still valid and a challenge is not required for this operation.

When an OTP is required the client can request one using the Request Member OTP endpoint.

This will return details of the generated code, including the type so that the client can prompt the user accordingly.

Supported OTP types:

• sms - A text message with the One Time Password has been sent to the member's registered mobile phone.

Verifying OTP codes:

Once the user has provided the code there are 2 options for verification:

• Explicitly verify the code by calling the Verify Member OTP endpoint. This will return details of the OTP session.
• Send the desired request and specify the code in the X-Super-OTP request header. The OTP code will be verified and the request performed as normal.

OTP scopes (deprecated):

Note that OTP will now default to write scope, if not specified. OTP read scope is no longer required.

• read - provides limited access and once verified will be valid for the duration of the current member session.
• write - provides full access but will expire 10 minutes after verification.

It is important to thoroughly test your application when integrating to the API. This section aims to outline key testing considerations when using the API.

Our API has two environments to facilitate testing and prototyping. Accessing different environments will require separate API keys. These environments are:

• Sandbox: Sandbox environment for user acceptance testing.
• Live: Production-grade environment ready for end-customers.

Each environment will connect to a separate database. In special circumstances, custom configurations and data migrations may be required. Please contact helpdesk@sargon.com to learn more.

The Fund Search functionality can be tested with different scenarios. To do this, avoid using taxId in the sandbox environment. Instead, use any of the following test taxId to create a successful fund search response.

Testing for specific responses and errors

Thoroughly test your integration for specific errors using our available test information. Use any of the following taxId to generate a specific error response.

Fund types and ability to rollover

The Fund Search may return varying fund types. Funds that can be electronically rolled over are indicated by the canRollover response. A typical API implementation will display the fund search results to the user and allow the user to roll over: all funds, individually, or none. See relevant API Reference.

Nominating a custom amount to rollover

In a typical implementation, the user can also nominate a custom amount to roll over for individual funds with the Existing fund type. Note that the account balances returned in the response may not be an up-to-date balance. A typical API implementation will disclose to the user that this is the case.

We use webhooks to notify your application when key events happen on your fund. When there is an important event worth notifying about, an Event object is created every time with data detailing what happens. This includes transactional events such as rollover and contribution transaction notifications.

A webhook endpoint is like a phone number that we can call when events happen in your account. You will need to specify an endpoint for each webhook created. Your endpoint must be protected by SSL and the SSL certificate must be valid. Each webhook has a signing secret that we use to create a signature which we include in the webhook payload. This allows you to verify that the webhook payload can be trusted.

You can configure a webhook that defines an HTTPS endpoint on your server that will receive event related information in near real-time.

We POST a payload to your endpoint and include the following important HTTP headers:

For example, your server code can verify the message by concatenating x-super-signature, a full stop, and the request body; then computing the HMAC; then asserting that the computed HMAC matches the signature (x-super-signature).

Note: when the signing secret is regenerated it is possible to delay the expiry of the current secret to allow time to update your server endpoints. In this case, the will be multiple signatures in x-super-signature.

If your server endpoint returns an error, the webhook will retry a maximum of 20 times.

We advise that your server endpoint be designed to return a 200 response as soon as possible. If your endpoint performs potentially long running operations (e.g. connecting to other systems, sending email, etc) then these should ideally be executed asynchronously. Webhooks will wait no longer than 20 seconds for a response - at which point we will assume a failure and schedule a retry attempt.

Events represent important things that occur in your fund. When an important event occurs we record the facts in an Event object. Some examples are when a member is created, or when a rollover is completed.

An event represents the state of the resource at the point in time that the event occurred.

You can use the list recent events endpoint to retrieve a list of recent events that have occurred within your fund. More event related endpoints will be added over time.

You can also setup event 'listeners' to receive information about events in near real-time. This is via Webhooks. A Webhook allows you to receive event data directly on an endpoint on your server.

The Event object attributes:

Event Types

This is a list of the currently supported types of events. More will be added in the short term.

Member Resources represent the Members or the investors of a fund. Members are the cornerstone of the API and other resources are related to a Member. The API allows funds to efficiently and programmatically manage their Members:

• At an individual Member level secured using the member scope, and;
• At an overall fund level using the integration scope

Balance Resources represent account balances associated with the Member.

Beneficiary Resources represents the nominated beneficiaries associated with a Member.

Contribution Resources represents voluntary or personal contributions associated with the Member. Compulsory super contributions is processed outside of this API via the ATO SuperStream system and can be retrieved from List Transactions.

Investment Resources represent investment choices and allocations made by the Member.

Insurance Resources represent the Insurance Policies associated with the Member.

For the purpose of this section, the following terms are defined:

• Insurance Policy - A policy that may be added to a Member
• Insurance Cover - An insurance policy attached to a Member

Applying for an Insurance Cover may require additional questions to be answered by the Member. As such, a JSON Schema will need to be configured per Insurance Policy available for the fund. The schema can be retrieved via the API, which will contain the full details of additional attributes and questions will that will need to be supplied when applying for the cover.