API Overview

With Apex NZ’s onboarding and post-onboarding API’s, you can develop your own investment related applications to securely signup investors, share with them a historical view of their investment data and enable a level of self-management.

Our API’s handle the synchronisation of data between data sources, access to required third party services and all aspects of user management. User management can also be performed by the client application if required.

There are a number of API’s that can be utilised in both the onboarding and the ongoing management of investors and their investments.

Onboarding

Apex NZ's onboarding API takes an automated approach to the registry workflow. Utilising a mixture of proprietary and third party services, developers can integrate into a workflow which:

Validates and verifies AML and residential addresses data in real-time.
Provides a configurable setup to meet a range of client / investment requirements.
Triggers communication checkpoints at different stages of the onboaring process so visibility is at the forefront.
Accepts multi-invesmtent, bank account and direct debit set up data.

NeXus - Investors and Investments

Apex NZ's post onboarding API provides developers the ability to retrieve and update existing investors data. Developers are able to:

Present historical investor data from date of inception to current date. (Updated daily). Please note: This is not a bulk API
Show a view of multiple linked investors and investments.
Update customer details and add transactions.
Provide the ability for a customer to manage their account.
A secure environment for an investor to view their investment data.

Onboarding API Flow

Apex NZ's onboarding flow follows a series of four stages. These stages perform specific onboarding requirements ranging from AML checking to internal peer peviews. These stages can be configured to meet specific client and compliance requirements. The diagram and information below describe each stage and the functions they provides.

Application Review
This stage:
- Checks all required fields have valid data so that applications can be saved to NeXus. e.g. Investment data, tax information etc.
- Enables manual data input
Returns:
- Stage Success or Fail
- List of all missing fields
AML check
This stage:
- Checks that all fields required for AML check are completed
- Passes application data to CloudCheck’s AML API service
- Performs manual AML if required (Apex NZ use only)
Returns:
- Stage Success or Fail (with list of missing fields and specific errors)
- AML report attached to application (PDF)
- Automated email workflow if AML delivers a failed result (including partial passes)

Peer Review
This stage:
- Apex NZ internal stage for reviewing any data manually entered into applications by the Apex NZ team
Returns:
- Approved or Denied
- Automated workflow to correct errors if denied (incl. emails to originally editor)
Completed
This stage:
- Validates all data fields and workflow statuses
- Saves completed applications into NeXus
- Uploads attached documents to cloud storage
Returns:
- Stage Success or Fail
- NeXus Beneficiary ID
- Locks application so it can’t be edited
- Completion email (Release 2)

NeXus Static Data Updates and Transactions

Once investors and investments have been onboarded, certain updates or new transactions can be handled by the API. This API enables a wealth of data to be retrieved and allows a subset of that information to be updated. Our Swagger site contains all the data that can be retrieved via the API.

Field / Type	Via the API		Updated

Fields that can be updated via the NeXus API

The below table highlights what fields / data can be updated via the API and duration when those updates will be visible.

Preferred name	✔	Instant
PIR Rate	✔
Primary Phone Number	✔	Instant
Primary Address	✔	Instant
Transactions - Applications	✔	Overnight
Transactions - Redemptions	✔	Overnight
Transactions - Custom Profile Rebalance	✔	Overnight

Required Fields

Beneficiary and AML

The required fields for AML depend on the type of identification document supplied e.g. Driver's Licence requires Driver's Licence Number and Version

Field	Data type	Required	AML

All Beneficiaries

Beneficiary.LastName	String	✔	✔
Beneficiary.PreferredName	String ¹
Beneficiary.Email	String
Beneficiary.PreferredComm	String	✔
Beneficiary.IRDNo	String	✔
Beneficiary.InvestorType	String ⁴	✔
Beneficiary.Nation	String ²	✔
Beneficiary.ExternalReference	String ³
Beneficiary.PIRRate	Number	✔
Beneficiary.TaxResident	Boolean	✔
Beneficiary.IsUSTaxResident	Boolean
Beneficiary.TINNumber	String
Beneficiary.TINCountry	String ²
Beneficiary.TINNumber2	String
Beneficiary.TINCountry2	String ²
Beneficiary.TINNumber3	String
Beneficiary.TINCountry3	String ²
Beneficiary.Risk	String ⁴
Beneficiary.SouthOfWealth	String ⁴
Beneficiary.UserDefined1	String
to...
Beneficiary.UserDefined10	String

Individual Beneficiaries

Beneficiary.FirstName	String	✔	✔
Beneficiary.MiddleName	String
Beneficiary.DateOfBirth	String	✔	✔
Beneficiary.Gender	String
Beneficiary.Title	String
Beneficiary.PlaceOfBirth	String ²
Beneficiary.IdVerified	Boolean
Beneficiary.NotifiedForeignInvestor	Boolean
Beneficiary.Occupation	String ⁴
Beneficiary.OccupationStatus	String ⁴

Entity Beneficiaries

Beneficiary.GIIN	String
Beneficiary.FATCAType	String ⁴
Beneficiary.CompanyNumber	String

¹ If the Preferred Name is not supplied then NeXus will use FirstName.

² Supplied country value needs to follow ISO Alpha-2 Code. E.g. New Zealand = NZ

³ External references associated with beneficiaries are extremely important as they provide the ability for NeXus to match the correct beneficiary when making static updates or subsequent investments. The external reference can be supplied via the API e.g. to match existing references in CRM’s or one will be created during the onboarding process.

⁴ Refer to the Swagger for a list of accepted values.

Driver’s Licence

ID items are restricted to one per beneficiary. e.g. an investor can only have one driver’s license. If these items require updating please use PUT vs POST. We will return an error if a POST tries to create a duplicate item.

BeneficiaryIdentification.Number	String	✔	✔
BeneficiaryIdentification.Version	String	✔	✔
BeneficiaryIdentification.ExpiryDate	String
BeneficiaryIdentification.Nation	String

Passport

BeneficiaryIdentification.Number	String	✔
BeneficiaryIdentification.Expiry	String	✔
BeneficiaryIdentification.Nation	String

Birth Certificate

BeneficiaryIdentification.Number	String	✔
BeneficiaryIdentification.Nation	String

Beneficiary Address

BeneficiaryAddress.AddressLine1	String	✔	✔
BeneficiaryAddress.City	String	✔	✔
BeneficiaryAddress.Postcode	String	✔	✔
BeneficiaryAddress.Region	String
BeneficiaryAddress.State	String
BeneficiaryAddress.Nation	String ¹	✔	✔
BeneficiaryAddress.AddressType	String ²	✔
BeneficiaryAddress.IsPrimary	Boolean ³	✔

¹ If funds are only open to NZ residents, NZ should be set as a default value for Country of Residency, Citizenship and Address Country if the fields are not to be visible on the front-end application.

² Options are Residential or Postal

³ Please note: Primary is defaulted to True for the first record added. If a subsequent record is set to Primary, then the old Primary record is set to False. If a Primary record is deleted, then the last modified record is set to Primary.

Beneficiary Phone Number

These items will be restricted to one per beneficiary. e.g. an investor can only have one driver’s license. If these items require updating please use PUT vs POST. We will return an error if a POST tries to create a duplicate item.

BeneficiaryPhone.PhoneNumber	String	✔
BeneficiaryPhone.PhoneType	String ¹	✔
BeneficiaryPhones.IsPrimary	Boolean ²	✔

¹ Options are Home, Business or Mobile.

² Please note: Primary is defaulted to True for the first record added. If a subsequent record is set to Primary, then the old Primary record is set to False. If a Primary record is deleted, then the last modified record is set to Primary.

Investment ¹

Investment Strategy data (even if it’s blank data) must be posted at the same time as Investment Funds data for validation via the API to occur.

Investment.Name	String	✔
Investment.InvestmentType	String	✔
Investment.AmountToInvest	Number ¹	✔
Investment.ReinvestPercentage	Number ²	✔
Investment.InvestmentStrategy	String ³
Investment.InvestmentStrategyBand	Int ³
Investment.ExternalReference	String ⁴
Investment.AdvisorCode	String
Investment.AdvisorRate	Decimal
Investment.UserDefined1	String
to...
Investment.UserDefined10	String

¹ AmountToInvest can utilise a value of zero, however you will need to specify the fund percentages of any attached investment funds. These funds must also have zero amounts..

² 0 = Cash out and 100 = Reinvest. Only use if individual funds are not going to have specific distribution percentages.

³ If the customer has the ability to choose a Predefined Strategy OR a Custom Strategy of their own they should use the Investment Funds fields below. Validation upfront must determine that at least either a Predefined Strategy or a Custom Strategy have been selected by the customer.

⁴ External references associated with investments provide the means for NeXus to match additional beneficiaries to an investment or making investment specific static updates. The external reference can be supplied via the API or one will be created during the onboarding process.

Investment Funds¹

None of the following fields are required if the Investment has an Investment Strategy and Amount. However, Funds data (even if it’s blank data) must be posted at the same time as Investment Strategy data for validation via the API to occur.

An error is returned if the fund amounts don’t sum to the investment amount.

InvestmentFund.Name	String
InvestmentFund.Code	String	✔
InvestmentFund.Amount	Number	✔
InvestmentFund.Percentage	Number	✔
InvestmentFund.ReinvestPercentage ³	Number

¹ Amount can utilise a value of zero, however you will need to specify the percentage of the parent investment's funds to be allocated. The parent investment must also use an AmountToInvest of zero.

² 0 = Cash out and 100 = Reinvest. Individual funds can have specific distribution percentages. Only use if the investment level distribution percentage is overriding the parent investment reinvest percentage.

Bank Accounts

This data is only required if the applicant wants to make regular contributions to their investments.

BankAccount.BankCode	Integer	✔
BankAccount.BranchCode	Integer	✔
BankAccount.Account	Integer	✔
BankAccount.Suffix	Integer	✔
BankAccount.BankAccountName	String	✔
BankAccount.BankAccountCurrency	String ¹	✔

¹ This value will generally be 'NZD'.

Direct Debit

This data is only required if the applicant wants to make regular contributions to their investments.

DirectDebit.Amount	Number	✔
DirectDebit.StartDate	String ¹	✔
DirectDebit.EndDate	String
DirectDebit.Frequency	String ²	✔
DirectDebit.IsActive	String ³	✔
DirectDebit.Type	String ⁴	✔

¹ DD start dates must be at least 12 days in the future given legislative requirements to send confirmations at least 10 days in advance of first payment?

² Options are Weekly, Monthly, Fortnightly, Quarterly, Semiannually & Annually

³ This should be set to 'True'.

⁴ This should be set to 'DD'.

Enum types & status codes

Below is a list of common enum types that apply specifically to project requirements. Additional enums can be found on the MMC Swagger.

Type	Value

Investor Types

Individual

Investment Types

Unit_Registry	0
KiwiSaver	1

DD Distribution Methods

Cash	C or 0
Reinvest	R or 100

Phone Types

Home	Home
Business	Business
Mobile	Mobile

Identification Types

Passport	Passport
Drivers Licence	Drivers Licence
Birth Certificate	Birth Certificate

Nation / Country Codes

Supplied country and nation values need to follow ISO Alpha-2 Code. E.g. New Zealand = NZ

For a document listing all of these codes, please click here.

Beneficiary.Nation	NZ
BeneficiaryAddress.Nation	NZ
BeneficiaryIdentification.Nation	NZ
BeneficiaryPhone.Nation	NZ

Relationship Types

This relationship types describe the nature of the relationship between two beneficiaries. Note that valid relationships are restricted based on the investor types of each beneficiary.

For a document listing all valid relationships between specific investor types, please click here.

Trustee
Settlor
Director
Beneficial Owner
Authorised Person
Effective Control
Parent
Guardian

Swagger

All our API calls can be accessed through our Swagger sites. Here you will find all available end points, models and examples.

Please only refer to the Onboarding endpoints within this Swagger site, as there are other end-points that have been replaced and documented in new Swagger references listed below.