Create a single individual beneficiary investment

chevron-down-icon chevron-up-icon

Follow the below steps to create an investment for one individual beneficiary.

1. Create the application

Call either the POST /onboarding/applications/applicationType/Individual OR /onboarding/applications/externalReference/{externalReference}/applicationType/Individual endpoints.

  • Individual is an applicationType for people as opposed to entities.
  • externalReference is an application identifier you can use if you wish to set an additional identity on the application.

This will return the ApplicationId and the PrimaryBeneficiaryId which you will need going forward.

2. Populate the primary beneficiary details

Call the PUT /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId} endpoint with the correct details within the body of the request and using the above ApplicationId and BeneficiaryId provided above.

  • See the PostBeneficiary/PutBeneficiary documentation for a breakdown of all the beneficiary fields.

This will return the ApplicationId and the PrimaryBeneficiaryId which you will need going forward.

3. Add beneficiary address details

Call the POST /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId}/addresses endpoint.

  • AddressType can be set to "Residential" or "Postal".
  • Nation is specified via ISO 3166-1 Alpha-2 format. i.e. "NZ", "AU", "US, "UK", "IN" etc.
  • IsPrimary determines if this is to be used as the primary contact address. At least one address should be set to primary.

4. Add beneficiary phone details

Call the POST /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId}/phones endpoint.

  • PhoneType can be set to "Home", "Business" or "Mobile".
  • Nation is specified via ISO 3166-1 Alpha-2 format. i.e. "NZ", "AU", "US, "UK", "IN" etc.
  • IsPrimary determines if this is to be used as the primary contact phone number. At least one phone number should be set to primary.

5. Add beneficiary identification details

Call the POST /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId}/identifications endpoint.

  • IdentificationType can be set to "Passport", "DriversLicence", "BirthCertificate" or "CertifiedDocs".
  • Nation is specified via ISO 3166-1 Alpha-2 format. i.e. "NZ", "AU", "US, "UK", "IN" etc.
  • IsPrimary determines if this is to be used as the primary identification. At least one identification should be set to primary.
  • Version is only used when supplying Drivers Licence details.

6. Add the investment

Call the POST /onboarding/applications/{applicationId}/investments endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • InvestmentType can be set to "Unit_Registry" or "Kiwisaver".
  • InvestmentFunds can either be included within this call or processed separately via the below investment funds endpoint.
  • If a strategy is to be used, instead of funds, then specify this within the InvestmentStrategy field. You will also need to specify a value for the InvestmentStrategyBand field.
  • ExternalReference can be used to set a unique identifier on an investment. If none is provided, the onboarding process will generate one upon saving to Nexus.
  • ReinvestPercentage will apply to any funds that do not have their own reinvestment percentage values set.
  • AmountToInvest can be left as zero if all funds provided also use zero amounts.

7. Add investment funds

Call the POST /onboarding/applications/{applicationId}/investments/{investmentId}/investmentFunds/ endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • InvestmentId needs to be set to the parent Investment that this fund will be attached to.
  • FundCode needs to be set to the correct portfolio code.
  • FundName is not required to be populated, as this will auto populate, based on the FundCode, when the investment is created in Nexus, if left null.
  • Amount can be left as zero if the investment itself has an AmountToInvest set to zero. Otherwise the total of all funds will need to sum to the investment’s AmountToInvest. This will be used to calculate the investment fund percentages if they do not add to 100.
  • Percentage is the percent of the total investment that will be allocated to the given fund.
  • ReinvestmentPercentage is used to specify a reinvestment value for the fund. Defaults to the parent investment’s reinvest percentage if left as null.

8. Add bank accounts

Call the POST /onboarding/applications/{applicationId}/bankaccounts endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • BankCode, BranchCode, Account and Suffix are all integers, leading zeroes can be ignored.
  • IsVerified is only set to true if the beneficiaries bank account has been directly verified by supporting documentation.
  • BankAccountCurrency should be set to "NZD".
  • BankAccountName should match the name of the bank account as it appears on documentation. e.g. "Mr K Wilson" or "Mrs Edith McDougal" etc.

9. Add direct debits

Call the POST /onboarding/applications/{applicationId}/investments/{investmentId}/bankaccounts/{bankaccountId}/directDebits endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • BankAccountId specifies which bank account this direct debit is attached to.
  • InvestmentId specifies which investment this direct debit is pointing to.
  • Amount specifies the amount to be deducted each period.
  • Frequency denotes what period the direct debit is. Valid values include:
    • "Weekly"
    • "Fortnightly"
    • "Monthly"
    • "Quarterly"
    • "SemiAnnually"
    • "Annually"
    • "OneOff"
  • Type is set to "DD".
  • StartDate and EndDate specify the active time period. Note that the start date will dictate the day of the period the direct debit will be generated. For example, if you specify a weekly or fortnightly period, the start date will specify what day of the week. One should also provide a buffer between when the application is submitted and the start date to allow for any issues/delays that may arise in processing the application.

10. Submit the application

Call the POST /onboarding/applications/{applicationId}/submit endpoint. This will validate all of the information provided, and assuming there are no issues the application will be passed to Apex NZ to complete.

  • Any issues will be returned in a list of errors. These are generally fairly clear to understand, however you can consult the list of common validation error messages here for additional information.

Create a joint individual beneficiary investment

chevron-down-icon chevron-up-icon

Follow the below steps to create an investment for joint beneficiaries.

1. Create the application

Call either the POST /onboarding/applications/applicationType/Individual OR /onboarding/applications/externalReference/{externalReference}/applicationType/Individual endpoints.

  • Individual is an applicationType for people as opposed to entities.
  • externalReference is an application identifier you can use if you wish to set an additional identity on the application.

This will return the ApplicationId and the PrimaryBeneficiaryId which you will need going forward.

2. Populate the primary beneficiary details

Call the PUT /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId} endpoint with the correct details within the body of the request and using the above ApplicationId and BeneficiaryId provided above.

  • See the PostBeneficiary/PutBeneficiary documentation for a breakdown of all the beneficiary fields.

3. Add any additional beneficiaries.

Call the POST /onboarding/applications/{applicationId}/beneficiaries endpoint for each additional beneficiary.

4. Add beneficiary address details for each beneficiary

Call the POST /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId}/addresses endpoint.

  • BeneficiaryId specifies which beneficiary the address is attached to.
  • AddressType can be set to "Residential" or "Postal".
  • Nation is specified via ISO 3166-1 Alpha-2 format. i.e. "NZ", "AU", "US, "UK", "IN" etc.
  • IsPrimary determines if this is to be used as the primary contact address. At least one address should be set to primary.

5. Add beneficiary phone details for each beneficiary

Call the POST /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId}/phones endpoint.

  • BeneficiaryId specifies which beneficiary the phone number is attached to.
  • PhoneType can be set to "Home", "Business" or "Mobile".
  • Nation is specified via ISO 3166-1 Alpha-2 format. i.e. "NZ", "AU", "US, "UK", "IN" etc.
  • IsPrimary determines if this is to be used as the primary contact phone number. At least one phone number should be set to primary.

6. Add beneficiary identification details for each beneficiary

Call the POST /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId}/identifications endpoint.

  • BeneficiaryId specifies which beneficiary the identfiication is attached to.
  • IdentificationType can be set to "Passport", "DriversLicence", "BirthCertificate" or "CertifiedDocs".
  • Nation is specified via ISO 3166-1 Alpha-2 format. i.e. "NZ", "AU", "US, "UK", "IN" etc.
  • IsPrimary determines if this is to be used as the primary identification. At least one identification should be set to primary.
  • Version is only used when supplying Drivers Licence details.

7. Add the investment

Call the POST /onboarding/applications/{applicationId}/investments endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • InvestmentType can be set to "Unit_Registry" or "Kiwisaver".
  • InvestmentFunds can either be included within this call or processed separately via the below investment funds endpoint.
  • If a strategy is to be used, instead of funds, then specify this within the InvestmentStrategy field. You will also need to specify a value for the InvestmentStrategyBand field.
  • ExternalReference can be used to set a unique identifier on an investment. If none is provided, the onboarding process will generate one upon saving to Nexus.
  • ReinvestPercentage will apply to any funds that do not have their own reinvestment percentage values set.
  • AmountToInvest can be left as zero if all funds provided also use zero amounts.

8. Add investment funds

Call the POST /onboarding/applications/{applicationId}/investments/{investmentId}/investmentFunds/ endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • InvestmentId needs to be set to the parent Investment that this fund will be attached to.
  • FundCode needs to be set to the correct portfolio code.
  • FundName is not required to be populated, as this will auto populate, based on the FundCode, when the investment is created in Nexus, if left null.
  • Amount can be left as zero if the investment itself has an AmountToInvest set to zero. Otherwise the total of all funds will need to sum to the investment’s AmountToInvest. This will be used to calculate the investment fund percentages if they do not add to 100.
  • Percentage is the percent of the total investment that will be allocated to the given fund.
  • ReinvestmentPercentage is used to specify a reinvestment value for the fund. Defaults to the parent investment’s reinvest percentage if left as null.

9. Add bank accounts

Call the POST /onboarding/applications/{applicationId}/bankaccounts endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • BankCode, BranchCode, Account and Suffix are all integers, leading zeroes can be ignored.
  • IsVerified is only set to true if the beneficiaries bank account has been directly verified by supporting documentation.
  • BankAccountCurrency should be set to "NZD".
  • BankAccountName should match the name of the bank account as it appears on documentation. e.g. "Mr K Wilson" or "Mrs Edith McDougal" etc.

10. Add direct debits

Call the POST /onboarding/applications/{applicationId}/investments/{investmentId}/bankaccounts/{bankaccountId}/directDebits endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • BankAccountId specifies which bank account this direct debit is attached to.
  • InvestmentId specifies which investment this direct debit is pointing to.
  • Amount specifies the amount to be deducted each period.
  • Frequency denotes what period the direct debit is. Valid values include:
    • "Weekly"
    • "Fortnightly"
    • "Monthly"
    • "Quarterly"
    • "SemiAnnually"
    • "Annually"
    • "OneOff"
  • Type is set to "DD".
  • StartDate and EndDate specify the active time period. Note that the start date will dictate the day of the period the direct debit will be generated. For example, if you specify a weekly or fortnightly period, the start date will specify what day of the week. One should also provide a buffer between when the application is submitted and the start date to allow for any issues/delays that may arise in processing the application.

11. Submit the application

Call the POST /onboarding/applications/{applicationId}/submit endpoint. This will validate all of the information provided, and assuming there are no issues the application will be passed to Apex NZ to complete.

  • Any issues will be returned in a list of errors. These are generally fairly clear to understand, however you can consult the list of common validation error messages here for additional information.

Create a minor individual beneficiary investment

chevron-down-icon chevron-up-icon

Follow the below steps to create an investment for a minor, under 18 years of age, beneficiary.

1. Create the application

Call either the POST /onboarding/applications/applicationType/Individual OR /onboarding/applications/externalReference/{externalReference}/applicationType/Individual endpoints.

  • Individual is an applicationType for people as opposed to entities.
  • externalReference is an application identifier you can use if you wish to set an additional identity on the application.

This will return the ApplicationId and the PrimaryBeneficiaryId which you will need going forward.

2. Populate the primary beneficiary details

Call the PUT /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId} endpoint with the correct details within the body of the request and using the above ApplicationId and BeneficiaryId provided above.

  • See the PostBeneficiary/PutBeneficiary documentation for a breakdown of all the beneficiary fields.
  • The primary beneficiary must be under 18 years old.

3. Add any additional beneficiaries.

Call the POST /onboarding/applications/{applicationId}/beneficiaries endpoint for each additional beneficiary.

  • If the minor is under 16, you will need to attach two additional beneficiary who are over 18 years old.
  • If the minor is over 16, but under 18, they require only one additional beneficiary who is over 18 years old.
  • You can provide an IRD number of ‘000000000’ for anyone that is not directly linked to an investment, i.e. guardian, parent etc.

4. Add beneficiary address details for each beneficiary

Call the POST /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId}/addresses endpoint.

  • BeneficiaryId specifies which beneficiary the address is attached to.
  • AddressType can be set to "Residential" or "Postal".
  • Nation is specified via ISO 3166-1 Alpha-2 format. i.e. "NZ", "AU", "US, "UK", "IN" etc.
  • IsPrimary determines if this is to be used as the primary contact address. At least one address should be set to primary.

5. Add beneficiary phone details for each beneficiary

Call the POST /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId}/phones endpoint.

  • BeneficiaryId specifies which beneficiary the phone number is attached to.
  • PhoneType can be set to "Home", "Business" or "Mobile".
  • Nation is specified via ISO 3166-1 Alpha-2 format. i.e. "NZ", "AU", "US, "UK", "IN" etc.
  • IsPrimary determines if this is to be used as the primary contact phone number. At least one phone number should be set to primary.

6. Add beneficiary identification details for each beneficiary

Call the POST /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId}/identifications endpoint.

  • BeneficiaryId specifies which beneficiary the identfiication is attached to.
  • IdentificationType can be set to "Passport", "DriversLicence", "BirthCertificate" or "CertifiedDocs".
  • Nation is specified via ISO 3166-1 Alpha-2 format. i.e. "NZ", "AU", "US, "UK", "IN" etc.
  • IsPrimary determines if this is to be used as the primary identification. At least one identification should be set to primary.
  • Version is only used when supplying Drivers Licence details.

7. Add the investment

Call the POST /onboarding/applications/{applicationId}/investments endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • InvestmentType can be set to "Unit_Registry" or "Kiwisaver".
  • InvestmentFunds can either be included within this call or processed separately via the below investment funds endpoint.
  • If a strategy is to be used, instead of funds, then specify this within the InvestmentStrategy field. You will also need to specify a value for the InvestmentStrategyBand field.
  • ExternalReference can be used to set a unique identifier on an investment. If none is provided, the onboarding process will generate one upon saving to Nexus.
  • ReinvestPercentage will apply to any funds that do not have their own reinvestment percentage values set.
  • AmountToInvest can be left as zero if all funds provided also use zero amounts.

8. Add investment funds

Call the POST /onboarding/applications/{applicationId}/investments/{investmentId}/investmentFunds/ endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • InvestmentId needs to be set to the parent Investment that this fund will be attached to.
  • FundCode needs to be set to the correct portfolio code.
  • FundName is not required to be populated, as this will auto populate, based on the FundCode, when the investment is created in Nexus, if left null.
  • Amount can be left as zero if the investment itself has an AmountToInvest set to zero. Otherwise the total of all funds will need to sum to the investment’s AmountToInvest. This will be used to calculate the investment fund percentages if they do not add to 100.
  • Percentage is the percent of the total investment that will be allocated to the given fund.
  • ReinvestmentPercentage is used to specify a reinvestment value for the fund. Defaults to the parent investment’s reinvest percentage if left as null.

9. Add bank accounts

Call the POST /onboarding/applications/{applicationId}/bankaccounts endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • BankCode, BranchCode, Account and Suffix are all integers, leading zeroes can be ignored.
  • IsVerified is only set to true if the beneficiaries bank account has been directly verified by supporting documentation.
  • BankAccountCurrency should be set to "NZD".
  • BankAccountName should match the name of the bank account as it appears on documentation. e.g. "Mr K Wilson" or "Mrs Edith McDougal" etc.

10. Add direct debits

Call the POST /onboarding/applications/{applicationId}/investments/{investmentId}/bankaccounts/{bankaccountId}/directDebits endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • BankAccountId specifies which bank account this direct debit is attached to.
  • InvestmentId specifies which investment this direct debit is pointing to.
  • Amount specifies the amount to be deducted each period.
  • Frequency denotes what period the direct debit is. Valid values include:
    • "Weekly"
    • "Fortnightly"
    • "Monthly"
    • "Quarterly"
    • "SemiAnnually"
    • "Annually"
    • "OneOff"
  • Type is set to "DD".
  • StartDate and EndDate specify the active time period. Note that the start date will dictate the day of the period the direct debit will be generated. For example, if you specify a weekly or fortnightly period, the start date will specify what day of the week. One should also provide a buffer between when the application is submitted and the start date to allow for any issues/delays that may arise in processing the application.

11. Add beneficiary relationships

For each parent or guardian, you will need to create a BeneficiaryRelationship by calling the POST /onboarding/applications/{applicationId}/beneficiaryrelationship/ endpoint.

  • Each relationship has a ‘Parent’ beneficiary, specified by the BeneficiaryId, and a ‘Child’ beneficiary, specified by the SecondaryBeneficiaryId. Note that this applies to all relationships, not just parent and guardian relationships.
  • BeneficiaryId must be set to the parent or guardian's BeneficiaryId.
  • SecondaryBeneficiaryId must be set to the minor, in this case the PrimaryBeneficiaryId
  • RelationshipType will need to be set to either "Parent" or "Guardian".

12. Submit the application

Call the POST /onboarding/applications/{applicationId}/submit endpoint. This will validate all of the information provided, and assuming there are no issues the application will be passed to Apex NZ to complete.

  • Any issues will be returned in a list of errors. These are generally fairly clear to understand, however you can consult the list of common validation error messages here for additional information.

Create a single individual beneficiary investment with an authorised person

chevron-down-icon chevron-up-icon

Follow the below steps to create an investment for a single beneficiary, with additional beneficiaries attached as authorised persons.

1. Create the application

Call either the POST /onboarding/applications/applicationType/Individual OR /onboarding/applications/externalReference/{externalReference}/applicationType/Individual endpoints.

  • Individual is an applicationType for people as opposed to entities.
  • externalReference is an application identifier you can use if you wish to set an additional identity on the application.

This will return the ApplicationId and the PrimaryBeneficiaryId which you will need going forward.

2. Populate the primary beneficiary details

Call the PUT /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId} endpoint with the correct details within the body of the request and using the above ApplicationId and BeneficiaryId provided above.

  • See the PostBeneficiary/PutBeneficiary documentation for a breakdown of all the beneficiary fields.

This will return the ApplicationId and the PrimaryBeneficiaryId which you will need going forward.

3. Add any additional beneficiaries.

Call the POST /onboarding/applications/{applicationId}/beneficiaries endpoint for each additional beneficiary.

  • An authorised person, like any beneficiary not linked directly to the investment, can use a blank ‘000000000’ IRD number.

4. Add beneficiary address details for each beneficiary

Call the POST /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId}/addresses endpoint.

  • BeneficiaryId specifies which beneficiary the address is attached to.
  • AddressType can be set to "Residential" or "Postal".
  • Nation is specified via ISO 3166-1 Alpha-2 format. i.e. "NZ", "AU", "US, "UK", "IN" etc.
  • IsPrimary determines if this is to be used as the primary contact address. At least one address should be set to primary.

5. Add beneficiary phone details for each beneficiary

Call the POST /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId}/phones endpoint.

  • BeneficiaryId specifies which beneficiary the phone number is attached to.
  • PhoneType can be set to "Home", "Business" or "Mobile".
  • Nation is specified via ISO 3166-1 Alpha-2 format. i.e. "NZ", "AU", "US, "UK", "IN" etc.
  • IsPrimary determines if this is to be used as the primary contact phone number. At least one phone number should be set to primary.

6. Add beneficiary identification details for each beneficiary

Call the POST /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId}/identifications endpoint.

  • BeneficiaryId specifies which beneficiary the identfiication is attached to.
  • IdentificationType can be set to "Passport", "DriversLicence", "BirthCertificate" or "CertifiedDocs".
  • Nation is specified via ISO 3166-1 Alpha-2 format. i.e. "NZ", "AU", "US, "UK", "IN" etc.
  • IsPrimary determines if this is to be used as the primary identification. At least one identification should be set to primary.
  • Version is only used when supplying Drivers Licence details.

7. Add the investment

Call the POST /onboarding/applications/{applicationId}/investments endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • InvestmentType can be set to "Unit_Registry" or "Kiwisaver".
  • InvestmentFunds can either be included within this call or processed separately via the below investment funds endpoint.
  • If a strategy is to be used, instead of funds, then specify this within the InvestmentStrategy field. You will also need to specify a value for the InvestmentStrategyBand field.
  • ExternalReference can be used to set a unique identifier on an investment. If none is provided, the onboarding process will generate one upon saving to Nexus.
  • ReinvestPercentage will apply to any funds that do not have their own reinvestment percentage values set.
  • AmountToInvest can be left as zero if all funds provided also use zero amounts.

8. Add investment funds

Call the POST /onboarding/applications/{applicationId}/investments/{investmentId}/investmentFunds/ endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • InvestmentId needs to be set to the parent Investment that this fund will be attached to.
  • FundCode needs to be set to the correct portfolio code.
  • FundName is not required to be populated, as this will auto populate, based on the FundCode, when the investment is created in Nexus, if left null.
  • Amount can be left as zero if the investment itself has an AmountToInvest set to zero. Otherwise the total of all funds will need to sum to the investment’s AmountToInvest. This will be used to calculate the investment fund percentages if they do not add to 100.
  • Percentage is the percent of the total investment that will be allocated to the given fund.
  • ReinvestmentPercentage is used to specify a reinvestment value for the fund. Defaults to the parent investment’s reinvest percentage if left as null.

9. Add bank accounts

Call the POST /onboarding/applications/{applicationId}/bankaccounts endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • BankCode, BranchCode, Account and Suffix are all integers, leading zeroes can be ignored.
  • IsVerified is only set to true if the beneficiaries bank account has been directly verified by supporting documentation.
  • BankAccountCurrency should be set to "NZD".
  • BankAccountName should match the name of the bank account as it appears on documentation. e.g. "Mr K Wilson" or "Mrs Edith McDougal" etc.

10. Add direct debits

Call the POST /onboarding/applications/{applicationId}/investments/{investmentId}/bankaccounts/{bankaccountId}/directDebits endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • BankAccountId specifies which bank account this direct debit is attached to.
  • InvestmentId specifies which investment this direct debit is pointing to.
  • Amount specifies the amount to be deducted each period.
  • Frequency denotes what period the direct debit is. Valid values include:
    • "Weekly"
    • "Fortnightly"
    • "Monthly"
    • "Quarterly"
    • "SemiAnnually"
    • "Annually"
    • "OneOff"
  • Type is set to "DD".
  • StartDate and EndDate specify the active time period. Note that the start date will dictate the day of the period the direct debit will be generated. For example, if you specify a weekly or fortnightly period, the start date will specify what day of the week. One should also provide a buffer between when the application is submitted and the start date to allow for any issues/delays that may arise in processing the application.

11. Add beneficiary relationships

For each authorised person, you will need to create a BeneficiaryRelationship by calling the POST /onboarding/applications/{applicationId}/beneficiaryrelationship/ endpoint.

  • Each relationship has a ‘Parent’ beneficiary, specified by the BeneficiaryId, and a ‘Child’ beneficiary, specified by the SecondaryBeneficiaryId.
  • BeneficiaryId must be set to the authorised person's BeneficiaryId.
  • SecondaryBeneficiaryId must be set to the beneficary the person is an authorised person for.
  • RelationshipType will need to be set to "Authorised_Person".
  • If this relationship is not set, the additional beneficiary will automatically be linked to the investment by default.

12. Submit the application

Call the POST /onboarding/applications/{applicationId}/submit endpoint. This will validate all of the information provided, and assuming there are no issues the application will be passed to Apex NZ to complete.

  • Any issues will be returned in a list of errors. These are generally fairly clear to understand, however you can consult the list of common validation error messages here for additional information.

Create an entity beneficiary investment, with linked individual beneficiaries

chevron-down-icon chevron-up-icon

Follow the below steps to create an investment for an entity, with linked individual beneficiaries.

1. Create the application

Call either the POST /onboarding/applications/applicationType/Entity OR /onboarding/applications/externalReference/{externalReference}/applicationType/Entity endpoints.

  • Entity is an applicationType for entities as opposed to people.
  • externalReference is an application identifier you can use if you wish to set an additional identity on the application.
  • An entity investment has different validation rules compared to an individual investment.

This will return the ApplicationId and the PrimaryBeneficiaryId which you will need going forward.

2. Populate the primary beneficiary details

Call the PUT /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId} endpoint with the correct details within the body of the request and using the above ApplicationId and BeneficiaryId provided above.

  • The primary beneficiary must have an entity type InvestorTyps, which are as follows:
    • "Company"
    • "Estate"
    • "Partnership"
    • "Trust"
    • "Charity"
  • The choice of TnvestorType restricts the possible relationships that can be created between the entity and individuals that will be connected to it. See the full list here.
  • See the PostBeneficiary/PutBeneficiary documentation for a breakdown of all the beneficiary fields.

This will return the ApplicationId and the PrimaryBeneficiaryId which you will need going forward.

3. Add any additional beneficiaries.

Call the POST /onboarding/applications/{applicationId}/beneficiaries endpoint for each additional beneficiary.

  • Ensure the correct InvestorType is specified when creating the beneficiary, as changing this later may cause validation issues. This can be "Individual" for normal beneficiaries.

4. Add beneficiary address details for each beneficiary

Call the POST /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId}/addresses endpoint.

  • BeneficiaryId specifies which beneficiary the address is attached to.
  • AddressType can be set to "Residential" or "Postal".
  • Nation is specified via ISO 3166-1 Alpha-2 format. i.e. "NZ", "AU", "US, "UK", "IN" etc.
  • IsPrimary determines if this is to be used as the primary contact address. At least one address should be set to primary.

5. Add beneficiary phone details for each beneficiary

Call the POST /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId}/phones endpoint.

  • BeneficiaryId specifies which beneficiary the phone number is attached to.
  • PhoneType can be set to "Home", "Business" or "Mobile".
  • Nation is specified via ISO 3166-1 Alpha-2 format. i.e. "NZ", "AU", "US, "UK", "IN" etc.
  • IsPrimary determines if this is to be used as the primary contact phone number. At least one phone number should be set to primary.

6. Add beneficiary identification details for each beneficiary

Call the POST /onboarding/applications/{applicationId}/beneficiaries/{beneficiaryId}/identifications endpoint.

  • BeneficiaryId specifies which beneficiary the identfiication is attached to.
  • IdentificationType can be set to "Passport", "DriversLicence", "BirthCertificate" or "CertifiedDocs".
  • Nation is specified via ISO 3166-1 Alpha-2 format. i.e. "NZ", "AU", "US, "UK", "IN" etc.
  • IsPrimary determines if this is to be used as the primary identification. At least one identification should be set to primary.
  • Version is only used when supplying Drivers Licence details.

7. Add the investment

Call the POST /onboarding/applications/{applicationId}/investments endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • InvestmentType can be set to "Unit_Registry" or "Kiwisaver".
  • InvestmentFunds can either be included within this call or processed separately via the below investment funds endpoint.
  • If a strategy is to be used, instead of funds, then specify this within the InvestmentStrategy field. You will also need to specify a value for the InvestmentStrategyBand field.
  • ExternalReference can be used to set a unique identifier on an investment. If none is provided, the onboarding process will generate one upon saving to Nexus.
  • ReinvestPercentage will apply to any funds that do not have their own reinvestment percentage values set.
  • AmountToInvest can be left as zero if all funds provided also use zero amounts.

8. Add investment funds

Call the POST /onboarding/applications/{applicationId}/investments/{investmentId}/investmentFunds/ endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • InvestmentId needs to be set to the parent Investment that this fund will be attached to.
  • FundCode needs to be set to the correct portfolio code.
  • FundName is not required to be populated, as this will auto populate, based on the FundCode, when the investment is created in Nexus, if left null.
  • Amount can be left as zero if the investment itself has an AmountToInvest set to zero. Otherwise the total of all funds will need to sum to the investment’s AmountToInvest. This will be used to calculate the investment fund percentages if they do not add to 100.
  • Percentage is the percent of the total investment that will be allocated to the given fund.
  • ReinvestmentPercentage is used to specify a reinvestment value for the fund. Defaults to the parent investment’s reinvest percentage if left as null.

9. Add bank accounts

Call the POST /onboarding/applications/{applicationId}/bankaccounts endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • BankCode, BranchCode, Account and Suffix are all integers, leading zeroes can be ignored.
  • IsVerified is only set to true if the beneficiaries bank account has been directly verified by supporting documentation.
  • BankAccountCurrency should be set to "NZD".
  • BankAccountName should match the name of the bank account as it appears on documentation. e.g. "Mr K Wilson" or "Mrs Edith McDougal" etc.

10. Add direct debits

Call the POST /onboarding/applications/{applicationId}/investments/{investmentId}/bankaccounts/{bankaccountId}/directDebits endpoint.

  • BeneficiaryId must be set to the PrimaryBeneficiaryId of the application.
  • BankAccountId specifies which bank account this direct debit is attached to.
  • InvestmentId specifies which investment this direct debit is pointing to.
  • Amount specifies the amount to be deducted each period.
  • Frequency denotes what period the direct debit is. Valid values include:
    • "Weekly"
    • "Fortnightly"
    • "Monthly"
    • "Quarterly"
    • "SemiAnnually"
    • "Annually"
    • "OneOff"
  • Type is set to "DD".
  • StartDate and EndDate specify the active time period. Note that the start date will dictate the day of the period the direct debit will be generated. For example, if you specify a weekly or fortnightly period, the start date will specify what day of the week. One should also provide a buffer between when the application is submitted and the start date to allow for any issues/delays that may arise in processing the application.

11. Add beneficiary relationships

You will need to ensure that all beneficiaries link either directly or indirectly back to the primary beneficiary by calling the POST /onboarding/applications/{applicationId}/beneficiaryrelationship/ endpoint.

  • Each relationship has a ‘Parent’ beneficiary, specified by the BeneficiaryId, and a ‘Child’ beneficiary, specified by the SecondaryBeneficiaryId.
  • BeneficiaryId must be set to the BeneficiaryId of the 'Parent' end of the relationship.
  • SecondaryBeneficiaryId must be set to the BeneficiaryId of the 'Child' end of the relationship.
  • Valid RelationshipType's are dependent on the InvestorTypes of both the ‘Parent’ and ‘Child’ nodes of the relationship. These valid relationships can be viewed here.
  • Only the primary beneficiary is linked directly to the investment itself. Therefore all other beneficiaries must have a relationship set.
  • You can have multiple tiers of entities and individuals. However, all entities should have individuals as their parents. For example, you may have a trust, which has a company as a parent trustee, and then an individual must be a parent director of that company
  • A single beneficiary can link to multiple other beneficiaries. For example, you may have a individual who is a director of a company, and also a trustee of a trust. You would only create a single beneficiary for that individual, but two relationships which they are the parent on.
  • Only one relationship can exist between two beneficiaries. A beneficiary can not have a director relationship and an authorised person relationship to the same company beneficiary.
  • When submitting the application, validation will be performed to ensure that all beneficiaries are linked via relationships. You will be alerted to any orphaned beneficiaries or invalid relationships via an error list.

12. Submit the application

Call the POST /onboarding/applications/{applicationId}/submit endpoint. This will validate all of the information provided, and assuming there are no issues the application will be passed to Apex NZ to complete.

  • Any issues will be returned in a list of errors. These are generally fairly clear to understand, however you can consult the list of common validation error messages here for additional information.

Common validation error messages

chevron-down-icon chevron-up-icon

Beneficiary Validation on POST/PUT

"Invalid date of birth."

  • Date of birth must be before or equal to today’s date, or and not greater than 150 years ago.

"Invalid Gender. Valid values are:"

  • Gender needs to be entered as a single character (M, F or O) or left as null.

"Invalid InvestorType. Valid values are:"

  • InvestorType value must be one of the valid types listed.

"Entities may not exist on non-entity applications."

  • The InvestorType has been set to an entity type on a non-entity application. Entities may only exist on entity applciations, check that you have specified the correct ApplicationType when creating the application.

"The primary beneficiary on an entity application cannot be an Individual InvestorType."

  • An entity application can not have an "Individual" InvestorType as the primary beneficiary. The beneficiary linked directly to the investment must be an entity type. If you want to create an investment for an Individual, you will need to specify the Individual application type on creation.

"Invalid FATCAType. Valid values are:"

  • Check to ensure that the specified FATCAType is valid.

"PlaceOfBirth is invalid, it must be a two character country code. (ISO 3166 Alpha-2)."
"Nation is invalid, it must be a two character country code. (ISO 3166 Alpha-2)."
"TINCountry is invalid, it must be a two character country code. (ISO 3166 Alpha-2)."

  • Check Appendix B for a list of valid ISO codes for nation fields. If more than two characters are entered, it will also produce this error to avoid "New Zealand" becoming "NE" due to trimming.

"Invalid GroupScheme. Valid values are:"

  • Check to ensure that the specified GroupScheme is valid, if this field is utilised by the client.

"Invalid SourceOfWealth. Valid values are:"

  • Check to ensure that the specified SourceOfWealth is valid, if this field is utilised by the client.

"Invalid Risk. Valid values are:"

  • Check to ensure that the specified Risk is valid, if this field is utilised by the client.

"Invalid PIRRate. Valid values are:"

  • Check to ensure that the specified PIRRate is valid. Note that any beneficiary attached to an investment must have a PIRRate, and this may be defaulted to 28% if left null. Individual’s may not have a 0% PIRRate.

BeneficiaryAddress Validation on POST/PUT

"Invalid AddressType. Valid values are: "
"AddressType is required. Valid values are: "

  • AddressType must be set to either “Residential” or “Postal”. It cannot be left blank and will not default to a value.

"Nation is invalid, it must be a two character country code. (ISO 3166 Alpha-2)."

  • Check here for a list of valid ISO codes for nation fields. If more than two characters are entered, it will also produce this error to avoid “New Zealand” becoming “NE” due to trimming.

"IsPrimary is required."

  • The IsPrimary field must be set to true or false. If no IsPrimary true address exists, the current address will default to true. If IsPrimary is set to true, any other address with IsPrimary true will be set to false.

BeneficiaryIdentification Validation on POST/PUT

"Invalid IdentificationType. Valid values are: "
"IdentificationType is required. Valid values are: "

  • IdentificationType must be set to one of: “DriversLicence”, “Passport”, “BirthCertificate” or “CertifiedDocs” for general documents. It cannot be left blank and will not default to a value.

"IsPrimary is required."

  • The IsPrimary field must be set to true or false. If no IsPrimary true identification exists, the current identification will default to true. If IsPrimary is set to true, any other identification with IsPrimary true will be set to false.

BeneficiaryPhone Validation on POST/PUT

"Invalid PhoneType. Valid values are: "
"PhoneType is required. Valid values are: "

  • PhoneType must be set to one of: “Home”, “Business” or “Mobile”. It cannot be left blank and will not default to a value.

"IsPrimary is required."

  • The IsPrimary field must be set to true or false. If no IsPrimary true phone exists, the current phone will default to true. If IsPrimary is set to true, any other phone with IsPrimary true will be set to false.

BeneficiaryRelationship Validation on POST/PUT

"Invalid RelationshipType. Valid values are: "
"RelationshipType is required. Valid values are: "

  • Refer to here for valid RelationshipTypes. Note this error is just checking that it is an existing type, not whether it is valid type between the two beneficiaries.

BankAccount Validation on POST/PUT

"BeneficiaryId is not for the Primary Beneficiary. Value = "

  • The BeneficiaryId specified must match the application’s PrimaryBeneficiaryId.

Investment Validation on POST/PUT

"InvestmentType is missing. Valid values are: "
"Invalid InvestmentType. Valid values are: "

  • InvestmentType needs to be set to either “Unit_Registry” or “Kiwisaver”. It cannot be left blank and will not default to a value.

"Invalid AdvisorRate value. Value must be between 0.0000 and 1.0000"

  • AdvisorRate must be a decimal value between 0, which represents 0%, and 1, which represents 100%.

"Invalid AdditionalEmailType. Valid values are: "

  • AdditionalEmailType must be set to “Personal”, “Work” or “Other”. If providing an investment email addres, it cannot be left blank and will not default to a value.

"Invalid BeneficiaryId: x, this must be the PrimaryBeneficiaryId: "

  • The BeneficiaryId specified must match the application’s PrimaryBeneficiaryId.

InvestmentFund Validation on POST/PUT

"Percentage must be between 0 and 100."

  • The Percentage value must be a decimal value between 0 and 100.

"Invalid BeneficiaryId: x, this must be the PrimaryBeneficiaryId: "

  • The BeneficiaryId specified must match the application’s PrimaryBeneficiaryId.

DirectDebit Validation on POST/PUT

"Frequency is required. Valid values are: "
"Invalid frequency. Valid values are: "

  • The Frequency value must be a set to one of the following:
    • “Weekly”
    • “Fortnightly”
    • “Monthly”
    • “Quarterly”
    • “SemiAnnually”
    • “Annually”
    • “OneOff”.
    It cannot be left blank and will not default to a value.

"Invalid BeneficiaryId: x, this must be the PrimaryBeneficiaryId: "

  • The BeneficiaryId specified must match the application’s PrimaryBeneficiaryId.

Document Validation on POST/PUT

"DocumentType is required. Valid values are: "
"Invalid DocumentType. Valid values are: "

  • The DocumentType value must be a set to one of the following:
    • “Application”
    • “Identification”
    • “CloudCheck”
    • “SingleGuardianConsent”
    • “Other”
    It cannot be left blank and will not default to a value.

Application validation on submission / completion

"<objectname>: <fieldname> is required."

  • A required field is missing from an object, such as an address, beneficiary or investment. Some of these fields are always required, but others may be configured to be required based on the client’s requirements.

"<objectname> is required on PrimaryBeneficiaryId: "

  • A required object has not been provided for the application’s primary beneficiary. These include non-beneficiary specific records such as an Investment, InvestmentFund, BankAccount or DirectDebit if these records have been set as required for the client.

"<objectname> is required on BeneficiaryId: "

  • A required object has not been provided for the specified beneficiary. These include beneficiary specific records such as an Address, Phone or Identification if these records have been set as required for the client.

"Investment x cannot have both a strategy and custom funds."

  • When setting up an investment, the investment may either have a custom configuration of attached InvestmentFunds or an InvestmentStrategy value which sets a preassigned distribution across the client’s funds when saved to Nexus.

"Investment x: Amount to invest is invalid."

  • The AmountToInvest on an investment must be set to 0 or greater. Generally, a zero amount should be set to avoid any recalculation of InvestmentFund percentages. This also requires the attached investment funds also use zero amounts.

"Investment re-investment percentage must be between 0 and 100."
"Fund x: Reinvest percentage must be between 0 and 100."

  • The ReinvestmentPercentage on an investment or InvestmentFund should be set to a value between 0, meaning earnings will be paid out as direct credits, and 100, where all earnings are all re-invested. Kiwisaver accounts require a reinvestment percentage of 100. If this field is left null, it will default to 100 on an Investment, and to the parent’s ReinvestPercentage on an InvestmentFund.

"Investment x: Fund percentages do not add up to 100."
"Investment x: Fund percentages must add to 100 when investment amount is zero."

  • The total of an Investments attached InvestmentFund’s allocation percentages must add up to 100. If they do not, and the Investment and InvestmentFunds have amounts set, the onboarding API will attempt to calculate these percentages itself. Note that this may require rounding to be performed on your percentages, for example three funds of 33.33 will fail, so instead set the final percentage to 33.34.

"Fund x: Fund code is invalid."

  • The FundCode provided does not match a known fund code for the client. This code is a six digit number passed as a string.

"Fund x: Amount and percentage are missing."

  • An InvestmentFund must have a percentage value or an amount, along with it’s parent investment having an amount, so that the percentage can be calculated.

"BeneficiaryId: x is not connected to the Primary Beneficiary via Relationships, either directly or indirectly."

  • If the application is for an entity or a minor application, all beneficiaries must link to the primary beneficiary either directly to it, or through a relationship to someone that is linked to the primary beneficiary. This can be via as many tiers as required, but no beneficiary can be orphaned.

"Minors must be assigned to the primary beneficiary id."

  • A minor beneficiary must be set as the primary beneficiary on an application. A minor is determined by the beneficiaries’ date of birth being under 18 years old.

"An application can not have more than one minor attached."

  • If the primary beneficiary is a minor, being under 18, then no other beneficiary can be attached who is also under 18 years old.

"Unable to load ApplicationType settings for this application."

  • We may not currently have a minor application configuration set up for the given client. Please contact us so that we can create this with the desired minor application settings.

"Minors under 16 years of age require two or more guardian beneficiaries, or a SingleGuardianConsent document must be attached."

  • You will need to ensure that two parent / guardian beneficiaries over the age of 18 are attached to the application. If there is a documented reason as to why only one guardian can be added, then this will need to be attached as document type “SingleGuardianConsent”.

"Minors between 16 and 18 years of age require one or more guardian beneficiaries."

  • You will need to attach a parent or guardian beneficiary to the minor's application.

"Guardian beneficiaries cannot be created on minor applications for this Masterclient."

  • The client’s minor application configuration does not require guardians to be loaded into Nexus for minor applicants.

"Minor's must have a valid IRD Number."

  • Applicants that are directly linked to investments must have a valid IRD number.

"Each guardian must have a relationship set to the minor beneficiary."

  • This error is displayed if a guardian beneficiary has not been linked to the minor via a BeneficiaryRelationship. Ensure that the BeneficiaryRelationship has been created correctly for each guardian.

"Each guardian can only have a single relationship set."
"Guardian's relationship SecondaryBeneficiaryId must match the minor beneficiary's."

  • On a minor application the guardian beneficiaries can only be linked to the minor applicant, whose BeneficiaryId must be set to the SecondaryBeneficiaryId of that relationship.

"A Kiwisaver investment may not be attached to an entity application."

  • Entity applications may only use InvestmentType “Unit_Registry”, ensure that this has been set correctly on the investment.

"A Kiwisaver investment may only have a single beneficiary attached."

  • Kiwisaver investments can not be linked to multiple beneficiaries, you may need to either set the InvestmentType correctly or check that you have set all BeneficiaryRelationships on the application correctly.

"One-Off direct debit has an invalid StartDate."
"One-Off direct debit does not have EndDate set to StartDate."

  • The current StartDate of the one off direct is set to today or earlier, or the date is set to a Saturday or Sunday. A one off direct debit also requires the EndDate to be set to the same date as the StartDate to ensure only a single payment is processed.