Impact API (1.0)

Download OpenAPI specification:Download

Introduction

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.

Getting Started

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.

Authentication

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.

AuthenticatedUser

The AuthenticatedUser authentication is for requests representing a user and requires valid user credentials.

The user credentials are exchanged for an OAuth 2 token with appropriate scopes and is used for all subsequent requests to the API for this session.

The authentication allows the API to be secured at the individual member level and mitigate the risks of data breach of overall fund data.

Security Scheme Type OAuth2
authorizationCode OAuth Flow
Authorization URL: /oauth2/login
Token URL: /oauth2/token
Scopes:
  • https://api.sargon.com/member -

    Member Scope

implicit OAuth Flow
Authorization URL: /oauth2/login
Scopes:
  • https://api.sargon.com/member -

    Member Scope

Integration

The Integration authentication is used for machine-to-machine API usage. Integration level access tokens can only be requested using a backend application and client_credentials OAuth flow and will require special access to be granted due to the increased level of risks involved.

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: /oauth2/token
Scopes:
  • https://api.sargon.com/integration -

    Integration Scope

UnauthenticatedUser

Some endpoints may be accessed without first verifying the user's identity. An example is the Create Member endpoint, typically used in member on-boarding and "sign up" applications. For these endpoints, you can use your application's Client ID credential in the request as header X-Api-Key.

Security Scheme Type API Key
Header parameter name: X-API-Key

API Overview

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

Currency

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 })

Errors

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.

Identifiers

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.

Pagination

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).

Versioning

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.

Security

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.

Multi-Factor Authentication (MFA)

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.

Testing

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.

Environments

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 [email protected] to learn more.

Fund Search Test Scenarios

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.

Tax ID Identity Verification Response
Any In Australia, the taxId is validated using a Check digit checksum algorithm.
123456782 Valid
Customer identity details are validated based on the taxId supplied.
Multiple funds were found upon fund search:
  • Two existing retirement funds
  • One unclaimed fund
  • One defined benefit fund
999999992 Valid
Customer identity details are validated based on the taxId supplied.
A single fund is found upon fund search:
  • One existing retirement fund
999999925 Valid
Customer identity details are validated based on the taxId supplied.
No funds returned.
999999968 Valid
Customer identity details are validated based on the taxId supplied.
Multiple funds were found upon fund search:
  • One existing retirement fund
  • Three unclaimed funds

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.

Tax ID Identity Verification Response
000000000 Invalid Customer identity details cannot be validated based on the taxId supplied.
000000027 Error Identity verification error.
000000043 Valid
Customer identity details are validated based on the taxId supplied.
Identity verification successful, but fund search error.

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.

Fund Type Description Can it be electronically rolled over? (canRollover)
Existing A member's existing fund that is currently managed by another entity. This is the most frequent and common response and the fund can be electronically rolled over. Yes
Unclaimed

Unclaimed funds correspond to a pool of funds that are "unclaimed" and do not belong to a typical individual account. This is typically managed centrally by the regulator and is a consolidation of customer accounts that were inactive.

In Australia, unclaimed funds are held by Australian Tax Office.

The response for these funds is held in the unclaimedFunds array.

Yes

Multiple unclaimed funds may be returned, but only the entirety of unclaimed funds can be rolled over.

Defined Benefit

Defined benefit funds are a form of retirement fund that cannot be electronically rolled over.

We recommend our clients to handle the rollover process via a separate manual process where the defined benefit fund is manually contacted.

The user interface should appropriately convey this to the user.

No

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.

Webhooks

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:

Header Description
x-super-signature The timestamp the message was sent in seconds since epoch.
x-super-timestamp The computed HMAC SHA-256 of signed payload. The signed payload is [x-super-signature].[request body]

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

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:

Attribute Description
id the UUID of the event
type the name of the event type
mode either sandbox or live
created the date the event was created
data Object that contains the data that is specific to the event type

Event Types

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

Event Description
member.created This occurs when a new member is created
rollover.received This occurs when a rollover is received
contribution.received This occurs when a contribution is received

Members

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

Create New Member

No authentication (other than API Key) is required to create a new Member. On creation, a valid access token with member scope will be returned in the response to be used for further API requests on behalf of this member. If externalIdpUserId is supplied, token will not be returned. This member will have to use your own IDP to obtain token to make subsequent calls. New Member requests are created as temporary entities at the API level (not propagated to the underlying fund registry) until the member has provided sufficient details and been verified for their identity. Once a member's identity has been verified, some attributes will no longer be updatable. These attributes are shown with an unverified indicator. If no postal address is supplied it will be defaulted to be the same as the residential address.

Authorizations:
Request Body schema: application/json
id
string <uuid> (UUID)

The Universally Unique Resource Identifier (UUID) for this Resource.

externalIdpUserId
string

The unique primary key / id of the member's identity in the source IdP.

givenName
required
string

The Member's given name. In western countries this is usually the first name.

familyName
required
string

The Member's family name. In western countries this is usually the surname or lastname.

gender
required
string
Enum: "Male" "Female" "Unspecified" "Unknown"

Gender of the person.

birthDate
required
string <date>

The Member's Date of Birth. This value may be obfuscated by the API. In this case an asterisk will replace any masked characters.

memberStatus
string (memberStatus)
Enum: "Active" "Peer Review" "Pending" "Exited" "Voided" "Inactive" "BeingExited"

Membership Status. The specific membership status and meanings utilised may vary on a fund by fund basis.

phoneMobile
required
string

Mobile Phone Number in E.164 international format, e.g. +61412345678.

email
required
string <email>

Email Address

addressResidential
required
object Recursive

Residential Address

addressPostal
required
object

Postal Address

group
string

Member Group. This is typically used to group cohorts of members or to provide attribution on the source of the member.

password
string <password>

Password of the member to login.

taxId
string (taxId)

The Member's Tax Identifier. For Australia, this is the Tax File Number.

This value may be obfuscated by the API. In this case an asterisk will replace any masked characters.

Responses

201

Member Created Resource

400

Bad Request

401

Unauthorized

409

Conflict - The email address has already been used

post /members

Production server

https://api.sargon.com/v1/members

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "2109987f-a750-4ddf-93b3-6d4e46a17e48",
  • "externalIdpUserId": "string",
  • "givenName": "John",
  • "familyName": "Doe",
  • "gender": "Male",
  • "birthDate": "1967-**-**",
  • "memberStatus": "Active",
  • "phoneMobile": "+61412345678",
  • "email": "[email protected]",
  • "addressResidential":
    {
    },
  • "addressPostal":
    {
    },
  • "group": "string",
  • "password": "pa$$word",
  • "taxId": "123456789"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    },
  • "links":