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 helpdesk@sargon.com 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": "john@test.com",
  • "addressResidential":
    {
    },
  • "addressPostal":
    {
    },
  • "group": "string",
  • "password": "pa$$word",
  • "taxId": "123456789"
}

Response samples

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

Get Member

Return the full representation of the requested member by member UUID.

When accessed using member scope, the result is limited to the currently authenticated member.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Responses

200

Member Resource

401

Unauthorized

403

Forbidden

404

Not Found

get /members/{member}

Production server

https://api.sargon.com/v1/members/{member}

Response samples

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

Update Member

Update or perform an operation on a Member resource.

Once a member has been identity verified, some attributes will become readOnly.

For an identity verified member, only these properties are updatable: addressPostal, addressResidential.

To change important communication details such as email and phoneMobile, you should first verify the member's details using Verifications endpoints.

In the case where the API detects no changes between the update request and current member details, the API will return a HTTP 200 status.

A valid OTP session is required to perform this operation.

When accessed using member scope, this operation is limited to the currently authenticated member.

otp-scope: write
Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Request Body schema: application/json
givenName
string

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

familyName
string

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

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

Gender of the person.

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

phoneMobile
string

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

email
string <email>

Email Address

addressResidential
object

Residential Address

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

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.

externalIdpUserId
string

Responses

200

Member Resource

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

put /members/{member}

Production server

https://api.sargon.com/v1/members/{member}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "givenName": "John",
  • "familyName": "Doe",
  • "gender": "Male",
  • "birthDate": "1967-**-**",
  • "phoneMobile": "+61412345678",
  • "email": "john@test.com",
  • "addressResidential":
    {
    },
  • "addressPostal":
    {
    },
  • "group": "string",
  • "taxId": "123456789",
  • "externalIdpUserId": "string"
}

Response samples

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

Balance

Balance Resources represent account balances associated with the Member.

Get Member Account Balance

Returns an account balance summary of a member.

Note that when the member is first created, the response will be 404 - Not Found until the member has a transaction on their account.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Responses

200

Member Balance Resource

400

Bad Request

401

Unauthorized

404

Not Found

get /members/{member}/balance

Production server

https://api.sargon.com/v1/members/{member}/balance

Response samples

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

List Member Balances Over Time

List member's account balance over time.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

query Parameters
frequency
string <string>
Enum: "daily" "weekly" "monthly" "yearly"

Filter by frequency, daily, weekly, monthly, or yearly.

page.size
integer [ 5 .. 100 ]
Default: 100

Pagination Page Size (number of entries per page)

page.offset
integer
Default: 0

Pagination Starting Offset

Responses

200

Member Balance Collection Response

400

Bad Request

401

Unauthorized

404

Not Found

get /members/{member}/balance-over-time

Production server

https://api.sargon.com/v1/members/{member}/balance-over-time

Response samples

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

Beneficiaries

Beneficiary Resources represents the nominated beneficiaries associated with a Member.

List Beneficiaries

List all beneficiaries for the member specified by memberId. Note: Due to a technical limitation, we are currently unable to return the beneficiaries' addresses.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Responses

200

Beneficiary response

400

Bad Request

401

Unauthorized

404

Not Found

get /members/{member}/beneficiaries

Production server

https://api.sargon.com/v1/members/{member}/beneficiaries

Response samples

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

Create Beneficiary Intent

Submit beneficiary intent for the Member. HTTP Status 400 (Bad Request) will be returned by the API if the Update call is made on a Binding Beneficiary

otp-scope: write
Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Request Body schema: application/json

Beneficiary intent request

beneficiaries
Array of objects (BeneficiaryBase)

Responses

201

Beneficiary intent response

400

Bad Request

401

Unauthorized

404

Not Found

post /members/{member}/beneficiaries/intents

Production server

https://api.sargon.com/v1/members/{member}/beneficiaries/intents

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "beneficiaries":
    [
    ]
}

Response samples

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

Retrieve Latest Beneficiary Intent

Retrieve the latest beneficiary intent for the member specified by memberId.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Responses

200

Beneficiary intent response

400

Bad Request

401

Unauthorized

404

Not Found

get /members/{member}/beneficiaries/intents/latest

Production server

https://api.sargon.com/v1/members/{member}/beneficiaries/intents/latest

Response samples

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

Retrieve a Beneficiary Intent

Retrieve the beneficiary intent with the given ID.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

beneficiaryIntentId
required
string <uuid>

Unique UUID of the Beneficiary Intent.

Responses

200

Beneficiary intent response

400

Bad Request

401

Unauthorized

404

Not Found

get /members/{member}/beneficiaries/intents/{beneficiaryIntentId}

Production server

https://api.sargon.com/v1/members/{member}/beneficiaries/intents/{beneficiaryIntentId}

Response samples

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

Contributions

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.

List Contribution Intents

List all contribution intents for the member specified by memberId.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

query Parameters
page.size
integer [ 5 .. 100 ]
Default: 100

Pagination Page Size (number of entries per page)

page.offset
integer
Default: 0

Pagination Starting Offset

Responses

200

Contribution intent collection response

400

Bad Request

401

Unauthorized

404

Not Found

get /members/{member}/contributions/intents

Production server

https://api.sargon.com/v1/members/{member}/contributions/intents

Response samples

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

Create Contribution Intent

Submit a contribution intent for the Member. In some scenarios it is useful for customer service officers to have knowledge of the members intended contribution, for example, when manual reconciliation is required.

otp-scope: write
Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Request Body schema: application/json

Contribution intent request

id
string <uuid>
amount
required
object (Money)

A money object with a specific currency in ISO 4217 format, an amount, and a precision.

referenceNumber
required
string

Responses

201

Contribution intent response

400

Bad Request

401

Unauthorized

404

Not Found

post /members/{member}/contributions/intents

Production server

https://api.sargon.com/v1/members/{member}/contributions/intents

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "amount":
    {
    },
  • "referenceNumber": "string"
}

Response samples

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

Retrieve a Contribution Intent

Retrieve the contribution intent with the given ID.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

contributionIntentId
required
string <uuid>

Unique UUID of the Contribution Intent.

Responses

200

Contribution intent response

400

Bad Request

401

Unauthorized

404

Not Found

get /members/{member}/contributions/intents/{contributionIntentId}

Production server

https://api.sargon.com/v1/members/{member}/contributions/intents/{contributionIntentId}

Response samples

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

Retrieve a Contribution Payment Details

Retrieve the contribution payment details. The member should use these payment details when completing their payment, for example, via their internet banking portal.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Responses

200

Contribution payment details response

400

Bad Request

401

Unauthorized

404

Not Found

get /members/{member}/contributions/payment-details

Production server

https://api.sargon.com/v1/members/{member}/contributions/payment-details

Response samples

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

Investments

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

List Investments

Returns a collection of investments available.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)

Responses

200

Investment Options Collection Response

400

Bad Request

401

Unauthorized

404

Not Found

get /investments

Production server

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

Response samples

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

Get Historical Investment Performance

Returns unit price and investment performance data points for the specified investment option.

The unit price can be used to calculate the historical investment performance of the fund. A unit price is the price of one unit of an investment option. When a member invests in their chosen investment option, the money is placed in an investment pool made up of the investments of all members who have chosen that investment option. The investment pool for each option is broken up into units. Every unit the member owns in the investment pool represents their share of the investment option, and has a value. This value is the unit price.

Both the buy_price and sell_price can be returned. For example:

  • The sell_price can be used to calculate member balances and investment performance over time.
  • The buy_price can be used to calculate the number of units that a member can obtain upon a contribution.

Further, the frequency of the unit price calculation may also be returned depending on your fund's unit pricing arrangement. For example:

  • weekly data points represent the prices as at each Friday.
  • monthly data points represent the prices as at the last day of the calendar month.

Prices are represented in whole numbers with precision of 6. This means the the price value can be divided by 10 ^ 6 to determine the floating point value. Caution: take care with floating point arithmetic in Javascript. Consider using a library such as Dinero to parse the money objects returned by this endpoint. For more details, refer to the Currency section.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
investment
required
string <uuid>

Unique UUID of the Investment

query Parameters
page.size
integer [ 5 .. 100 ]
Default: 100

Pagination Page Size (number of entries per page)

page.offset
integer
Default: 0

Pagination Starting Offset

sort
string
Default: "desc"
Enum: "desc" "asc"

Sort by date in ascending/oldest first (asc) or descending/newest first (desc) order.

Responses

200

Investment Performance Response

400

Bad Request

401

Unauthorized

404

Not Found

get /investments/{investment}/performance

Production server

https://api.sargon.com/v1/investments/{investment}/performance

Response samples

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

List Investments Balance

List the balance information for the specified member's investment allocations.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Responses

200

Investment Balance Collection Response

401

Unauthorized

403

Forbidden

get /members/{member}/investments/balance

Production server

https://api.sargon.com/v1/members/{member}/investments/balance

Response samples

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

Request Investment Rebalance / Transfer

Change the investment allocation for the specified member.

The API accepts either:

  • Percentage based rebalance
  • Amount based transfer

Either percent OR transferAmount field must be present in the request.

For percentage based rebalance, a representation of all allocations must be included in the request. The sum of all percentages specified MUST equal 100.

For amount based transfer, the "source" and "destination" investments must be specified in the request. Negative amount should be used for "source" investment. The sum of all amounts specified MUST equal 0.

A valid OTP session is required to perform this operation.

API will respond with HTTP 202 Accepted status and schedule the update request with the underlying fund registry.

Example

// Percent based
[
  {
    "id": "investment option UUID",
    "percent": 60
  },
  {
    "id": "investment option UUID",
    "percent": 40
  }
]

// Amount based
[
  {
    "id": "source investment option UUID"
    "transferAmount": {
      "amount": -10000,
      "currency": "AUD"
    }
  },
  {
    "id": "destination investment option UUID"
    "transferAmount": {
      "amount": 10000,
      "currency": "AUD"
    }
  }
]
otp-scope: write
Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

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

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

percent
number <float>

Percentage to allocate

transferAmount
object (Money)

A money object with a specific currency in ISO 4217 format, an amount, and a precision.

Responses

202

Request Accepted

400

Bad Request

401

Unauthorized

404

Not Found

put /members/{member}/investments/balance

Production server

https://api.sargon.com/v1/members/{member}/investments/balance

Request samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Response samples

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

List Future Cash Allocations

Get the current investment allocation for the specified member. The investment allocation will be applied upon the next cash transaction contributed or rolled over to the member account.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Responses

200

Investment Cash Allocation Collection Response

400

Bad Request

401

Unauthorized

404

Not Found

get /members/{member}/investments/futurecash

Production server

https://api.sargon.com/v1/members/{member}/investments/futurecash

Response samples

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

Update Future Cash Allocations

Update member's investment future cash allocations.

This Resource accepts a JSON array of InvestmentAllocation Resources which each contain a pointer to an Investment Resource and percentage attribute.

A representation of all allocations must be included in the request. The sum of all percentages specified MUST equal 100.

A valid OTP session is required to perform this operation.

A successful request will return a 200 OK status and include the updated future cash allocations.

If the update cannot be performed immediately the API will respond with a HTTP 202 Accepted status and schedule the update request with the investment administrator.

otp-scope: write
Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Request Body schema: application/json
Array
id
required
string <uuid>

Investment option UUID

percent
required
number <float>

Percentage allocated to this investment

Responses

200

Investment Cash Allocation Collection Response

202

Request Accepted

400

Bad Request

401

Unauthorized

403

Forbidden

put /members/{member}/investments/futurecash

Production server

https://api.sargon.com/v1/members/{member}/investments/futurecash

Request samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Response samples

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

Insurance

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.

List Available Insurance Policies

Returns a collection of insurance policies that can be attached to or activated for this member.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Responses

200

Insurance Policy Collection Response

400

Bad Request

401

Unauthorized

get /members/{member}/insurance/policies

Production server

https://api.sargon.com/v1/members/{member}/insurance/policies

Response samples

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

Get Available Insurance Policy

Returns a specified insurance policy by ID, that can be attached to or activated for this member. It also returns a JSON Schema definition for the fields required to create a policy from this policy. You SHOULD ensure that the payload used when creating a new policy from this policy validates against this schema. "JSON Schema" is a well supported standard for annotating and validating JSON data. See http://json-schema.org/

Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

policy
required
string <uuid>

Unique UUID of the Insurance Policy.

Responses

200

Insurance Policy Response

400

Bad Request

401

Unauthorized

get /members/{member}/insurance/policies/{policy}

Production server

https://api.sargon.com/v1/members/{member}/insurance/policies/{policy}

Response samples

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

List Member Insurance Covers

Returns a collection of Insurance Covers applicable to the specified member.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Responses

200

Insurance Covers Collection Response

400

Bad Request

401

Unauthorized

404

Not Found

get /members/{member}/insurance/covers

Production server

https://api.sargon.com/v1/members/{member}/insurance/covers

Response samples

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

Apply for Insurance Cover

Create an application for a new Insurance Cover for this member, using the specified Insurance Policy. Additional dynamic properties are supported in the request payload depending on the policy being created. Refer to Get Available Insurance Policy for retrieving the JSON Schema for a specific policy. Use status OPT_OUT, if member wants to opt out from a specific insurance policy.

otp-scope: write
Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Request Body schema: application/json

Insurance Cover Details

Array
policyId
required
string <uuid>
application
object

JSON object conforming to the Insurance Policy schema

status
string
Value: "OPT_OUT"
terms
Array of strings

Responses

201

Insurance Covers Response

400

Bad Request

401

Unauthorized

404

Not Found

post /members/{member}/insurance/covers

Production server

https://api.sargon.com/v1/members/{member}/insurance/covers

Request samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Response samples

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

Get Insurance Cover Details

Retrieve the full details of the specified Insurance Cover.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

cover
required
string <uuid>

Unique UUID of the Insurance Cover.

Responses

200

Insurance Cover Response

400

Bad Request

401

Unauthorized

404

Not Found

get /members/{member}/insurance/covers/{cover}

Production server

https://api.sargon.com/v1/members/{member}/insurance/covers/{cover}

Response samples

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

Update Insurance Cover Details

Update details of the specified Insurance Cover.

otp-scope: write
production-only: true
Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

cover
required
string <uuid>

Unique UUID of the Insurance Cover.

Request Body schema: application/json

Insurance Cover Beneficiary Details to Update

application
object

JSON object conforming to the Insurance Policy schema

terms
Array of strings

Responses

200

Insurance Cover Response

400

Bad Request

401

Unauthorized

404

Not Found

put /members/{member}/insurance/covers/{cover}

Production server

https://api.sargon.com/v1/members/{member}/insurance/covers/{cover}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "application":
    {
    },
  • "terms":
    [
    ]
}

Response samples

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

Request Insurance Cover Cancellation

Request cancellation an existing (active) Insurance Cover.

otp-scope: write
production-only: true
Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

cover
required
string <uuid>

Unique UUID of the Insurance Cover.

Responses

204

Empty Body

400

Bad Request

401

Unauthorized

404

Not Found

delete /members/{member}/insurance/covers/{cover}

Production server

https://api.sargon.com/v1/members/{member}/insurance/covers/{cover}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "errors":
    [
    ]
}

Transactions

Transaction Resources represent individual transactions for a Member. All Transaction details are returned as a read-only collection.

List Transactions

Returns a collection of Transactions. The collection defaults to transactions belonging to the currently authenticated member when accessed with member scope.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
query Parameters
type
string <string>
Enum: "Contribution" "Adjustment" "ContributionsTax" "BenefitPayment" "TaxRebate" "Commission" "Surcharge" "MiscIncome" "OtherTaxes" "TfrToReserve" "Payment" "TaxGST" "RITC" "PAYG Taxes" "TaxRemittance"

Show only Transactions of the specified type.

date
string

Return results for the specified date (or date range). Date must be provided in ISO 8601 date format (YYYY-MM-DD) with optional times.

A Range can be specified separated by a comma in the form of date=start_date,end_date

If only one date is specified the API will return results for only the specified date. If start date is empty the API will search for all dates up to and including the end date. If end date is empty the API will search for all dates including and after the start date. If the specified dates do not include a time the API will default the start dates time to 00:00 and the end dates time to 23:59:59

Examples:

  • 2016-01-01 - Single day date range covering the date 2016-01-01 only
  • 2016-01-01, - All dates from 2016-01-01, including 2016-01-01
  • ,2016-01-01 - All dates up to and including 2016-01-01
  • 2016-01-01,2016-02-28 - All dates from 2016-01-01 to 2016-02-28 inclusive
  • ,today - All dates up to and including todays date
  • today, - All dates from and including todays date
page.size
integer [ 5 .. 100 ]
Default: 100

Pagination Page Size (number of entries per page)

page.offset
integer
Default: 0

Pagination Starting Offset

sort
string
Default: "desc"
Enum: "desc" "asc"

Sort by date in ascending/oldest first (asc) or descending/newest first (desc) order.

Responses

200

Transaction Collection

400

Bad Request

401

Unauthorized

404

Not Found

get /transactions

Production server

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

Response samples

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

Fund Search & Rollover

Fund search & rollover provides the ability to find and consolidate funds from other fund providers.

Fund Search Resources represent the results from a fund search performed by or on behalf of a member. The results can be consented to, for rollover and transfer into the member's account.

A full or partial transfer can be conducted, including:

  • Create Rollover Request from Fund Search: Consent to rollover ALL of the funds from the results returned.
  • Create Rollover Request: Consent to rollover specific funds and/or transferAmount.

Note that if multiple unclaimedMoneys are found, the consent must be made for the ALL unclaimed monies using rolloverUnclaimedMoneys.

Perform Fund Search

Perform a new Fund Search request for the current member. The request is asychronous and you will be required to retrieve the results after the request is made.

HTTP Status 403 (Forbidden) will be returned by the API if the Fund Search call is made before member's identity has been verified.

otp-scope: write
Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Responses

202

Fund Search Operation

401

Unauthorized

403

Forbidden

post /members/{member}/fundsearch

Production server

https://api.sargon.com/v1/members/{member}/fundsearch

Response samples

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

Get Latest Fund Search Results

Returns the most recent fund search results.

The results contains detailed data of the member's existing accounts from third party funds (funds) and any unclaimed monies (unclaimedMoneys). The results can be consented to for rollover and transfer into the member's account, either partially or fully.

We note that:

  • Some funds cannot be consented to rollover via the API. See canRollover attribute for more details.
  • The entirety of unclaimed monies must be consented for rollover.

Please see our Testing Guidelines to learn more.

Status 204 will be returned if fund search results are not available yet.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Responses

200

Fund Search Result

204

Empty Body

401

Unauthorized

404

Not Found

get /members/{member}/fundsearch/latest

Production server

https://api.sargon.com/v1/members/{member}/fundsearch/latest

Response samples

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

List Fund Search Results

Returns the results of a Fund Search for the specified ID.

Status 204 will be returned if fund search results are not available yet.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

fundsearchid
required
string <uuid>

Unique UUID of the Fund Search

Responses

200

Fund Search Result

204

Empty Body

401

Unauthorized

404

Not Found

get /members/{member}/fundsearch/{fundsearchid}

Production server

https://api.sargon.com/v1/members/{member}/fundsearch/{fundsearchid}

Response samples

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

Create Rollover Request from Fund Search

Creating a Rollover Request from Fund Search provides a convenient way to quickly Create Rollover Request for the specified member based on the specified Fund Search Result ID. For special circumstances, the consents may be placed onHold to allow your fund operations to review and perform the request on a batch and upon discretion.

otp-scope: write
Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

fundsearchid
required
string <uuid>

Unique UUID of the Fund Search

query Parameters
onHold
boolean
Default: false

When true, all consents created will be set to "on hold"

Responses

200

Rollover Request Confirmation Response

400

Bad Request

401

Unauthorized

404

Not Found

post /members/{member}/fundsearch/{fundsearchid}/consent

Production server

https://api.sargon.com/v1/members/{member}/fundsearch/{fundsearchid}/consent

Response samples

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

List Rollover Requests

Returns a collection of Rollover Requests consented by the specified member, including those created with a Consent to Fund Search Rollover.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Responses

200

Rollover Collection Response

400

Bad Request

401

Unauthorized

get /members/{member}/rollovers

Production server

https://api.sargon.com/v1/members/{member}/rollovers

Response samples

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

Create Rollover Request

Creates a Rollover Request for the specified member which provides consent for funds to be transferred to the member's account. The following consents are possible:

  • Specific fund(s), and/or;
  • Entire balances or a specifically nominated transferAmount per fund, and/or;
  • All unclaimed monies using the rolloverUnclaimedMoneys attribute

Detailed data for applicable funds and unclaimedMoneys can be retrieved from the results of a fund search.

For special circumstances, the consents may be placed onHold to allow your fund operations to review and perform the request on a batch and upon discretion.

otp-scope: write
Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

query Parameters
onHold
boolean
Default: false

When true, all consents created will be set to "on hold"

Request Body schema: application/json
funds
Array of objects (RolloverStatusDetail)

List of Funds to be consented to rollover.

rolloverUnclaimedMoneys
boolean

If true, create rollover consent for all unclaimed moneys.

Responses

201

Rollover Request Confirmation Response

400

Bad Request

401

Unauthorized

post /members/{member}/rollovers

Production server

https://api.sargon.com/v1/members/{member}/rollovers

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "funds":
    [
    ],
  • "rolloverUnclaimedMoneys": true
}

Response samples

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

Documents

Document Resources represent key documents associated to a Member such as welcome pack, employer contribution form and annual statements.

List Member Documents

List all documents for a member

Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Responses

200

Document Collection Response

401

Unauthorized

403

Forbidden

get /members/{member}/documents

Production server

https://api.sargon.com/v1/members/{member}/documents

Response samples

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

Get Member Document

Get the details for a member document including download link.

The returned download link is a short-lived url with expiry of 30 seconds (expiry populated in urlExpiry property). If you wish to download the document file it is expected that you will call this endpoint and then immediately request or redirect to the download url.

By default the download url will return with a content-disposition header of attachment which will trigger a download in most browsers. If you'd prefer the document to open instead of download you can control this by setting the display query parameter to inline.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member) Integration (https://api.sargon.com/integration)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

document
required
string <uuid>

Unique UUID of the Document.

query Parameters
display
string
Default: "attachment"
Enum: "attachment" "inline"

Response display option for requested document - e.g. inline vs attachment. This controls the content-disposition header in the response when the document url is fetched. Defaults to attachment.

Responses

200

Document Response

401

Unauthorized

403

Forbidden

404

Not Found

get /members/{member}/documents/{document}

Production server

https://api.sargon.com/v1/members/{member}/documents/{document}

Response samples

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

OTP

One Time Password (OTP) related operations. OTP restrictions can be configured and the default configuration is designed to meet security and compliance requirements associated with the member scope.

Request Member OTP

Request a One Time Password (OTP) to be sent to the Member. After requesting an OTP you have 10 minutes to verify it before it expires.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

query Parameters
scope
string
Deprecated
Enum: "read" "write"

OTP Scope will be default to write scope and is no longer required.

Responses

200

OTP Resource

400

Bad Request

401

Unauthorized

post /members/{member}/otp

Production server

https://api.sargon.com/v1/members/{member}/otp

Response samples

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

Verify Member OTP

To verify a One Time Password (OTP), you will need to first Request a One Time Password (OTP). Then, specify the retrieved OTP code in your verify request as part of the X-Super-OTP request header. If successful, the current member will be granted access for the OTP scope requested when creating the OTP. Learn more on Multi-Factor Authentication.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

header Parameters
X-Super-OTP
string

Responses

200

OTP Verify Resource

401

Unauthorized

post /members/{member}/otp/verify

Production server

https://api.sargon.com/v1/members/{member}/otp/verify

Response samples

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

Verifications

Verififications allow you to verify the member's ownership of their email address or phone number. Separate to the One Time Password (OTP) which is used for security of certain operations, Verifications be used when changing important communication details for the member, in addition to Update Member.

Send Verification Code

Send a verification code to member using specified verification channel. This can be either email or sms. After requesting a verification code, you will have 10 minutes to check (Check Verification Code endpoint) before it expires.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

Request Body schema: application/json
channel
required
string (VerificationChannel)
Enum: "email" "sms"

Verification Type.

to
required
string

The mobile number or email being verified.

Responses

200

Send verification response

400

Bad Request

401

Unauthorized

post /members/{member}/verifications

Production server

https://api.sargon.com/v1/members/{member}/verifications

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "channel": "sms",
  • "to": "+6141234567"
}

Response samples

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

Check Verification Code

Check verification code. After 5 failed attempts, you will have to request a new code.

Authorizations:
AuthenticatedUser (https://api.sargon.com/member)
path Parameters
member
required
string <uuid>

Unique UUID of the Member.

A value of "me" can be provided instead of a literal UUID. "me" will be expanded to represent the currently authenticated member, if any.

verificationId
required
string <uuid>

Unique UUID of the Verification.

Request Body schema: application/json
code
required
string

The code being verified.

Responses

200

Check verification response

400

Bad Request

401

Unauthorized

404

Not Found

429

Rate Limited

post /members/{member}/verifications/{verificationId}/check

Production server

https://api.sargon.com/v1/members/{member}/verifications/{verificationId}/check

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "code": "23456"
}

Response samples

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

Events

Event Resources represent important things that occur in your fund. We create an Event object for each occurrence in your fund that is worth notifying you about, such as when a rollover or contribution transaction is made. Each event contains data explaining what happened.

List Recent Events

Returns a list of events that have occurred in the past 15 days.

Authorizations:
Integration (https://api.sargon.com/integration)

Responses

200

Event collection response

401

Unauthorized

403

Forbidden

get /events

Production server

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

Response samples

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

Get Supported Event Types

Retrieves all supported and available event types for webhooks.

Authorizations:
Integration (https://api.sargon.com/integration)

Responses

200

Event type collection response

401

Unauthorized

403

Forbidden

get /events/types

Production server

https://api.sargon.com/v1/events/types

Response samples

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

Webhooks

Webhooks allows notifications to be sent to your applications on key Events, such as when a rollover or contribution transaction is made. We provide the ability to manage webhooks via the API.

List Webhooks

Returns a list of all your webhooks.

Authorizations:
Integration (https://api.sargon.com/integration)

Responses

200

Webhook Collection Resource

401

Unauthorized

403

Forbidden

get /webhooks

Production server

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

Response samples

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

Create Webhook

A webhook must have a url and a list of events.

Authorizations:
Integration (https://api.sargon.com/integration)
Request Body schema: application/json
url
required
string

The URL of the webhook.

events
required
Array of strings

The list of events to enable for this webhook.

enabled
string

The status whether webhook is enabled or disabled.

Responses

201

Webhook Resource

401

Unauthorized

403

Forbidden

post /webhooks

Production server

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

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "url": "string",
  • "events":
    [
    ],
  • "enabled": "string"
}

Response samples

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

Get Webhook

Retrieves the webhook with the given ID.

Authorizations:
Integration (https://api.sargon.com/integration)
path Parameters
webhookId
required
string <uuid>

Unique UUID of the Webhook.

Responses

200

Webhook Resource

401

Unauthorized

403

Forbidden

404

Not Found

get /webhooks/{webhookId}

Production server

https://api.sargon.com/v1/webhooks/{webhookId}

Response samples

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

Update Webhook

Update the webhook with the given ID. You may edit the url, the list of events, and the enabled status.

Authorizations:
Integration (https://api.sargon.com/integration)
path Parameters
webhookId
required
string <uuid>

Unique UUID of the Webhook.

Request Body schema: application/json
url
required
string

The URL of the webhook.

events
required
Array of strings

The list of events to enable for this webhook.

enabled
required
string

The status whether webhook is enabled or disabled.

Responses

200

Webhook Resource

401

Unauthorized

403

Forbidden

404

Not Found

put /webhooks/{webhookId}

Production server

https://api.sargon.com/v1/webhooks/{webhookId}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "url": "string",
  • "events":
    [
    ],
  • "enabled": "string"
}

Response samples

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

Delete Webhook

Deletes the webhook with the given ID.

Authorizations:
Integration (https://api.sargon.com/integration)
path Parameters
webhookId
required
string <uuid>

Unique UUID of the Webhook.

Responses

204

Empty Body

401

Unauthorized

403

Forbidden

404

Not Found

delete /webhooks/{webhookId}

Production server

https://api.sargon.com/v1/webhooks/{webhookId}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "errors":
    [
    ]
}

List Webhook Attempts

Returns a list of webhooks attempts for a specified webhook.

Authorizations:
Integration (https://api.sargon.com/integration)
path Parameters
webhookId
required
string <uuid>

Unique UUID of the Webhook.

Responses

200

Webhook Attempts Collection Resource

401

Unauthorized

403

Forbidden

get /webhooks/{webhookId}/attempts

Production server

https://api.sargon.com/v1/webhooks/{webhookId}/attempts

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ]
}

Get Webhook Secret

Returns webhook details including the signing secret.

Authorizations:
Integration (https://api.sargon.com/integration)
path Parameters
webhookId
required
string <uuid>

Unique UUID of the Webhook.

Responses

200

Webhook Resource

401

Unauthorized

403

Forbidden

404

Not Found

get /webhooks/{webhookId}/secret

Production server

https://api.sargon.com/v1/webhooks/{webhookId}/secret

Response samples

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

Regenerate Webhook Secret

Regenerates the webhook signing secret.

Once regenerated the new signing secret will be used immediately for signing any new webhook notifications.

The existing active signing secret can be expired immediately or delayed for up to 24 hours to allow graceful updates to downstream systems. During this delay period signatures for both secrets will be included in all webhook notifications.

Authorizations:
Integration (https://api.sargon.com/integration)
path Parameters
webhookId
required
string <uuid>

Unique UUID of the Webhook.

Request Body schema: application/json
expiryHours
required
integer [ 0 .. 24 ]

How long the current signing secret should remain valid for (0-24 hours)

Responses

200

Webhook Resource

401

Unauthorized

403

Forbidden

404

Not Found

post /webhooks/{webhookId}/secret

Production server

https://api.sargon.com/v1/webhooks/{webhookId}/secret

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "expiryHours": 0
}

Response samples

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

Send Test Webhook Event

Send a test event to a webhook endpoint.

Authorizations:
Integration (https://api.sargon.com/integration)
path Parameters
webhookId
required
string <uuid>

Unique UUID of the Webhook.

eventType
required
string

Event type.

Responses

200

Webhook Attempt Response

401

Unauthorized

403

Forbidden

404

Not Found

post /webhooks/{webhookId}/test/{eventType}

Production server

https://api.sargon.com/v1/webhooks/{webhookId}/test/{eventType}

Response samples

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