/BizEntity
When to Use
- New Investor Onboarding: Creating first-time investor entities for individuals, trusts, companies, or SMSFs with complete compliance data capture
- Complex Entity Structures: Establishing entities with multiple party relationships (directors, trustees, beneficiaries, authorized representatives) requiring role-based access control
- Multi-Account Investor Setup: Creating entities managing multiple accounts within the SAME product (e.g., separate accounts for capital growth vs income distribution strategies)
- International Investor Registration: Onboarding foreign residents or dual tax residents requiring CRS/FATCA compliance documentation and international banking details
- Bulk Migration Operations: Migrating investor records from legacy systems using externalBizEntityId and externalPersonId for deduplication and reconciliation
- Entity Consolidation: Creating parent-child entity relationships where one investor entity (e.g., family trust) controls multiple sub-entities
Common Scenarios
- Individual Investor (Simplest Pattern): Create entity with bizEntityTypeID=1 (Individual), one person in bizEntityParties array with isPrimaryContact=true and isIncomeReceiving=true, one account for selected product, one distribution payment detail (Australian EFT), and residential address + email communication
- Joint Investment (Person Reuse Pattern): Create entity with bizEntityTypeID=1, TWO persons in bizEntityParties array (both with isIncomeReceiving=true, one isPrimaryContact=true), shared addresses/communications using externalPersonId deduplication to prevent duplicate person records, joint payment details for combined distribution payments
- Family Trust (Complex Structure): Create entity with bizEntityTypeID=3 (Trust), trustee person/organisation in bizEntityParties with isTrustee=true, additional parties for beneficiaries and authorized signatories, trust-level addresses and banking, accounts for trust investments
- Company Investment (Corporate Entity): Create entity with bizEntityTypeID=2 (Company), directors and company secretary in bizEntityParties with isSignatory flags, organisation details including ACN/ABN/ASIC registration, registered office address, corporate banking details
- SMSF (Regulatory Compliance Focus): Create entity with bizEntityTypeID=4 (SMSF), trustees in bizEntityParties (minimum 2 individual trustees OR 1 corporate trustee), SMSF-specific tax details (TFN, ABN), compliant banking structure, member benefit accounts
- International Investor (CRS/FATCA Compliance): Create entity with non-Australian taxationCountryCode, foreign tax residency details (taxationCountryTIN, CRS participation status), international wire transfer payment details (SWIFT, IBAN), passport identification, foreign address with countryCode
Prerequisites
- Valid entity type classification (bizEntityTypeID must exist in system)
- Required identity verification documents for regulatory compliance
- At least one person or organization ready for party relationship creation
- At least one investment product selected for initial account creation
- Same ProductID Rule: ALL accounts within a BizEntity MUST share the same productID or externalProductId. Multi-product entities are not supported - create separate BizEntity records per product
- Payment method details available for distribution and redemption processing
- Access token with entity creation permissions and appropriate scope
Considerations
- ExternalPersonId Deduplication Pattern: Use Entity-Level person.externalPersonId (within PersonDTO) to control person reuse across complex structures. Same externalPersonId in multiple contexts reuses one person record instead of creating duplicates. Without proper externalPersonId placement, duplicate person records compromise compliance data, beneficial ownership tracking, and audit trails. See worked example above for correct pattern.
- Same ProductID Rule (Validation Enforced): All accounts within a BizEntity must share identical productID or externalProductId. System validates this rule - violation causes 400 Bad Request. Multi-product entities are not supported - create separate BizEntity records per product. Attempting mixed products triggers validation error: "All accounts must have the same ProductID or ExternalProductId."
- Minimum Viable Entity Requirements: Must include (1) At least one account with valid productID, (2) At least one party relationship (person or organisation), (3) Valid bizEntityTypeID and bizEntityStatusID. Missing required arrays triggers 400 validation errors. Empty entity without accounts/parties cannot process transactions.
- Regulatory Compliance by Entity Type: Individual entities (bizEntityTypeID=1) require person identity verification (passport/driver's license). Company entities (bizEntityTypeID=2) require ACN/ABN and ASIC registration. Trust entities (bizEntityTypeID=3) require trustee documentation. SMSF entities (bizEntityTypeID=4) require trustee structure compliance (2+ individual trustees or 1 corporate trustee).
- International Tax Compliance (CRS/FATCA): Non-Australian tax residents must provide taxationCountryCode + either taxationCountryTIN or taxationCountryNoTINReason per jurisdiction. Missing TIN without valid reason causes CRS reporting failures. Dual/triple tax residents require complete details for each jurisdiction (taxationCountryCode2/3, taxationCountryTIN2/3, or NoTINReason2/3).
- Payment Method Strategy: At least one payment detail strongly recommended for automated distribution processing. Australian investors typically provide EFT details (requires BSB + account number). International investors require Wire transfer details (SWIFT code + IBAN/account number + bank address). Each payment detail requires at least one transaction type flag enabled (isForDistribution, isForRedemption, isForDeposit, isForOther).
- Data Validation Cascade: Complex nested structures validate at multiple levels - entity-level validation (required fields, entity type), array-level validation (at least one account/party), nested object validation (person/organisation/address/communication/paymentDetail validators). Single validation failure in deeply nested object causes entire operation to fail with detailed error path reporting.
- External ID Strategy for Integration: Plan systematic external ID schema for cross-system reconciliation. externalBizEntityId enables entity deduplication across operations. externalPersonId prevents duplicate person records (essential for data quality). externalAddressId enables address reuse. externalCommunicationId prevents duplicate email/phone records. externalPaymentDetailId enables banking detail reuse. Without external IDs, repeated submissions create duplicates.
- Immutable Entity Type Decision: bizEntityTypeID cannot be changed after entity creation - determines tax treatment, regulatory obligations, and operational capabilities. Choose carefully: Individual (1) for personal investors, Company (2) for corporate investors, Trust (3) for family/discretionary trusts, SMSF (4) for self-managed super funds. Incorrect entity type requires deletion and recreation with correct type.
- Mutual Exclusivity Patterns: BizEntityParty can link to either person or organisation (not both). Addresses/Communications/PaymentDetails must link to exactly one owner (BizEntity, Person, or Organisation). Provide entity-level externalPersonId or linking-level externalPersonId (not both in same context). Violating mutual exclusivity causes 400 validation errors.
- Performance Considerations: Large nested structures (e.g., trust with 10+ beneficiaries, multiple addresses per person, international wire details with correspondent banking) increase payload size and processing time. Complex validation cascades add latency. Consider batch processing for bulk entity creation. Performance varies based on entity complexity and nested structure depth. Simple individual entities process quickly. Complex structures with extensive party relationships, multiple addresses, and international compliance data require additional processing time.
Description
Creates a comprehensive business entity record with support for complex party relationships, account structures, and regulatory compliance data. The entity serves as the primary container for all investor-related information and account associations.
Entity Creation Process
Creating an investor entity is a process of building an object structure from its parts:
- Core Entity Data: Basic identification and classification
- Party Relationships: Links to persons and organizations via BizEntityParty records
- Account Structure: At least one account record associating with a product
- Supporting Data: Communications, addresses, and payment details
Required Headers
Header | Value | Description |
---|---|---|
Authorization | {accessToken} | Bearer token for API access |
Version | 2.0 | API version identifier |
Content-Type | application/json | Content type for request body |
Request Body
Parameter | Type | Required | Description |
---|---|---|---|
BizEntityID |
integer | Optional |
System-generated identifier assigned automatically upon creation. Leave null for POST requests. |
externalBizEntityId |
string | Your system's reference ID for this entity (max 50 chars). Enables dual-ID linking when you cannot store 7G's native IDs. | |
bizEntityTypeID |
integer | Entity classification determining structural schema and compliance requirements. Lookup values via GET /Common/Lookup (category: BizEntityType). Immutable after creation. | |
advisorNumber |
string | Optional |
Financial advisor identifier for entities under advisory management (max 100 chars). Links entity to advisor reporting and commission structures. |
authorizedNomineePersonID |
integer | References the PersonID authorized to act as nominee for this entity. Used for trust arrangements and power of attorney situations. | |
bizEntityStatusID |
integer | Entity operational status controlling transaction processing capability. Lookup values via GET /Common/Lookup (category: BizEntityStatus). Typically set to Active=1 for new entities. | |
bizEntityTaxOfficeTypeID |
integer | Specifies which tax office jurisdiction applies to this entity. Affects tax reporting format and submission requirements. | |
communicationPreferenceCopyParentBizEntity |
boolean | Optional |
When true, inherits communication preferences from parent entity in group structures. When false, uses entity-specific preferences for reporting and notification delivery. |
communicationPreferenceID |
integer | Optional |
References preferred communication method for statements and notifications. Overrides parent preferences when copyParent is false. |
contactPerson |
string | Optional |
Primary contact name for administrative purposes. Used when entity structure doesn't clearly identify a single contact person. |
controllingPID |
integer | PersonID of the individual who controls this entity. Essential for beneficial ownership reporting and regulatory compliance. | |
corporateRepresentative |
string | Optional |
Name of the corporate representative for company entities. Used when a company officer acts on behalf of the entity. |
customerCategoryID |
integer | Optional |
Classification for pricing and service level determination. Affects fee structures and available investment products. |
customerCode |
string | Your internal customer reference code for cross-system integration and reporting alignment. Enables bidirectional entity matching with external CRM or portfolio management systems. | |
description |
string | Optional |
Free-text description for additional entity context (max 2000 chars). Useful for complex structures or special notes. |
groupedWithBizEntityID |
integer | References parent entity in group structures. Enables consolidated reporting and inherited settings across entity hierarchies. | |
investorTypeID |
integer | Investor classification affecting product eligibility and regulatory treatment. Lookup values via GET /Common/Lookup (category: InvestorType). Controls access to wholesale investment products. | |
isDirectorInterest |
boolean | Optional |
Indicates if entity represents director interests in listed securities. Triggers enhanced reporting and disclosure requirements under director interest disclosure rules. |
isExecutiveInterest |
boolean | Optional |
Indicates if entity represents executive/insider interests. Affects transaction reporting and regulatory disclosure obligations for compliance with executive interest reporting. |
legalName |
string | Official registered legal name as appears on incorporation documents or ASIC registry. Must match government-issued business registration for regulatory reporting. | |
marginLenderOrganisationID |
integer | References the lending organization for entities with margin loan facilities. Links to margin lending arrangements and risk monitoring. | |
name |
string | Display name for the entity used in reports, statements, and user interfaces. Serves as the primary identifier in operational systems and investor-facing communications. | |
powerOfAttorney |
string | Optional |
Details of power of attorney arrangements affecting entity operations. Used for authorization and compliance verification. |
purposeOfInvestmentID |
integer | Optional |
Investment purpose classification for compliance and suitability assessment. Affects product recommendations and risk profiling. |
salesPersonID |
integer | Optional |
References the sales person or relationship manager responsible for this entity. Used for commission allocation and relationship management. |
salutation |
string | Optional |
Preferred salutation for correspondence (Mr, Mrs, Dr, etc). Enhances personalized communication with the entity. |
signatureParty |
integer | PersonID authorized to sign documents on behalf of this entity. Used for transaction authorization and compliance. | |
sophisticatedInvestorCertificateDate |
string (date) | Date of sophisticated investor certification. Unlocks access to wholesale investment products restricted to sophisticated investors. | |
sophisticatedInvestorComment |
string | Optional |
Additional notes regarding sophisticated investor status. Documents basis for certification and compliance verification details. |
sophisticatedInvestorEligibility |
string | Specific test basis for sophisticated investor status (Accountant Certificate, Income Test, Net Assets Test, Professional Investor). Required for product eligibility verification. | |
sourceOfFundsID |
integer | Classification of fund sources for AML/CTF compliance. Lookup values via GET /Common/Lookup (category: SourceOfFunds). Triggers appropriate due diligence workflows for high-risk categories. | |
specialConditions |
string | Optional |
Special terms or conditions applying to this entity (max 2000 chars). Documents restrictions, requirements, or operational notes. |
standingProxy |
string | Optional |
Details of standing proxy arrangements for voting rights. Used for corporate actions and shareholder meetings. |
taxationCountryCode |
string | Primary tax jurisdiction for this entity (ISO 3166-1 alpha-3 country code: AUS, USA, GBR, NZL, etc.). Determines CRS/FATCA reporting obligations and tax treaty applicability. | |
createdDate |
datetime | Optional |
System-assigned timestamp when the entity was created. Read-only field - automatically populated on creation. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ). |
accounts |
>
List<AccountDTO>... |
Optional |
Investment accounts owned by this entity. Each account is linked to a specific product and tracks balances, DRP settings, and status. All accounts within a BizEntity must share the same productID or externalProductId - multi-product entities require separate BizEntity records. |
addresses |
>
List<AddressDTO>... |
Optional |
Physical and postal addresses for this entity. Used for correspondence, compliance verification, and regulatory reporting. |
communications |
>
List<CommunicationDTO>... |
Optional |
Contact methods (email, phone, fax) for this entity. Each communication record belongs to exactly one entity, person, or organisation. |
paymentDetails |
>
List<PaymentDetailDTO>... |
Optional |
Banking instructions and account details for processing investor payments (distributions, redemptions, deposits). Supports multiple payment methods (Australian EFT, international wires, cheque) with method-specific validation rules. Payment details link to exactly one owner (BizEntity, Person, or Organisation). |
bizEntityParties |
>
List<BizEntityPartyDTO>... |
Optional |
Links this entity to associated persons and organizations. Defines roles like primary contact, signatory, and income receiving parties. Every BizEntity requires at least one party relationship to establish who owns/controls the entity. |
Example Requests
curl -X POST 'https://api.7g.com.au/BizEntity' \
-H 'Version: 2.0' \
-H 'Authorization: {accessToken}' \
-H 'Content-Type: application/json' \
-d '{
"bizEntityTypeID": 4,
"name": "John Smith Investment Trust",
"bizEntityStatusID": 1,
"communicationPreferenceCopyParentBizEntity": false,
"isDirectorInterest": false,
"isExecutiveInterest": false,
"externalBizEntityId": "ENT-001",
"advisorNumber": "ADV-12345",
"legalName": "John Smith Investment Trust",
"description": "Individual investment trust for John Smith",
"customerCode": "CUST-001",
"taxationCountryCode": "AUS",
"bizEntityParties": [
{
"personID": null,
"externalPersonId": null,
"isPrimaryContact": true,
"isIncomeReceiving": true,
"isSignatory": true,
"isAuthorisedNominee": false,
"isPowerOfAttorney": false,
"ordinal": 1,
"person": {
"externalPersonId": "PERSON-001",
"firstName": "John",
"lastName": "Smith",
"dateOfBirth": "1980-05-15",
"birthCountryCode": "AUS",
"taxationCountryCode": "AUS",
"taxationFileNumber": "123-456-782",
"crsfatcaParticipationID": 1,
"salutation": "Mr",
"addresses": [
{
"addressTypeID": 101,
"aboveAddressLine": "Unit 5",
"addressLine": "123 Collins Street",
"suburb": "Melbourne",
"postcode": "3000",
"stateCode": "VIC",
"countryCode": "AUS",
"externalAddressId": "ADDR-001"
}
],
"communications": [
{
"communicationTypeID": 1,
"name": "john.smith@email.com",
"externalCommunicationId": "COMM-001"
},
{
"communicationTypeID": 2,
"name": "+61412345678",
"externalCommunicationId": "COMM-002"
}
]
}
}
],
"accounts": [
{
"externalAccountId": "ACC-001",
"productID": 101,
"accountNumber": "INV-123456",
"currencyID": 1,
"drpTypeID": 1,
"accountStatusID": 1,
"balance": 0.00
}
],
"addresses": [
{
"addressTypeID": 102,
"aboveAddressLine": "Suite 10",
"addressLine": "456 Business Street",
"suburb": "Sydney",
"postcode": "2000",
"stateCode": "NSW",
"countryCode": "AUS",
"externalAddressId": "ADDR-002"
}
],
"communications": [
{
"communicationTypeID": 1,
"name": "info@johnsmith-trust.com.au",
"externalCommunicationId": "COMM-003"
}
],
"paymentDetails": [
{
"externalPaymentDetailId": "PAY-001",
"paymentTypeID": 1,
"bsb": "032001",
"accountNumber": "123456789",
"accountName": "John Smith Investment Trust",
"isForDeposit": true,
"isForDistribution": true,
"isForRedemption": true,
"isForOther": false,
"reference": "INV-001"
}
]
}'
Person Reuse & Deduplication
BizEntity operations support automatic person deduplication using externalPersonId
to prevent duplicate person records when individuals appear in multiple entity contexts.
When the same externalPersonId
appears multiple times within a single request,
the system reuses one person record instead of creating duplicates.
{
"bizEntityParties": [
{
"person": {
"externalPersonId": "PERSON-001",
"firstName": "John",
"lastName": "Smith"
}
},
{
"organisation": {
"associatedPersons": [{
"person": {
"externalPersonId": "PERSON-001" // Reuses same person
}
}]
}
}
]
}
For comprehensive deduplication documentation including validation logic, dual-level placement rules, error handling, and advanced scenarios:
📖 Complete Person Reuse & Deduplication GuideResponse Examples
{
"result": true,
"message": null,
"recordCount": 1,
"data": [
{
"bizEntityID": 12345,
"externalBizEntityId": "ENT-001",
"bizEntityTypeID": 4,
"advisorNumber": "ADV-12345",
"authorizedNomineePersonID": null,
"bizEntityStatusID": 1,
"bizEntityTaxOfficeTypeID": null,
"communicationPreferenceCopyParentBizEntity": false,
"communicationPreferenceID": null,
"contactPerson": null,
"controllingPID": null,
"corporateRepresentative": null,
"customerCategoryID": null,
"customerCode": "CUST-001",
"description": "Individual investment trust for John Smith",
"groupedWithBizEntityID": null,
"investorTypeID": null,
"isDirectorInterest": false,
"isExecutiveInterest": false,
"legalName": "John Smith Investment Trust",
"marginLenderOrganisationID": null,
"name": "John Smith Investment Trust",
"powerOfAttorney": null,
"purposeOfInvestmentID": null,
"salesPersonID": null,
"salutation": null,
"signatureParty": null,
"sophisticatedInvestorCertificateDate": null,
"sophisticatedInvestorComment": null,
"sophisticatedInvestorEligibility": null,
"sourceOfFundsID": null,
"specialConditions": null,
"standingProxy": null,
"taxationCountryCode": "AUS",
"createdDate": "2024-01-15T08:30:00Z",
"bizEntityParties": [
{
"bizEntityPartyID": 1001,
"organisationID": null,
"externalOrganisationId": null,
"personID": 5001,
"externalPersonId": "PERSON-001",
"isPrimaryContact": true,
"isIncomeReceiving": true,
"isSignatory": true,
"isAuthorisedNominee": false,
"isPowerOfAttorney": false,
"ordinal": 1,
"person": {
"personID": 5001,
"externalPersonId": "PERSON-001",
"firstName": "John",
"middleName": null,
"lastName": "Smith",
"fullName": "John Smith",
"description": null,
"abn": null,
"birthCountryCode": "AUS",
"crsfatcaParticipationID": 1,
"customerCode": null,
"dateOfBirth": "1980-05-15",
"driversLicenseIssueCountryCode": null,
"driversLicenseNumber": null,
"gender": null,
"identificationTypeID": null,
"identificationValue": null,
"isDirectorOfCorporateTrustee": null,
"isPEP": null,
"isSophisticatedInvestor": null,
"isTrustee": null,
"pepDescription": null,
"legalGuardianTitleID": null,
"legalGuardianFirstName": null,
"legalGuardianMiddleName": null,
"legalGuardianLastName": null,
"passportIssueCountryCode": null,
"passportNumber": null,
"salutation": "Mr",
"sharePercentage": null,
"sophisticatedInvestorCertificateDate": null,
"taxationCountryCode": "AUS",
"taxationCountryCode2": null,
"taxationCountryCode3": null,
"taxationCountryTIN": null,
"taxationCountryTIN2": null,
"taxationCountryTIN3": null,
"taxationCountryNoTINReason": null,
"taxationCountryNoTINReason2": null,
"taxationCountryNoTINReason3": null,
"taxationFileNumber": "123-456-782",
"tradingName": null,
"taxOfficeTypeID": null,
"tin": null,
"titleID": null,
"addresses": [
{
"addressID": 2001,
"addressTypeID": 101,
"aboveAddressLine": "Unit 5",
"addressLine": "123 Collins Street",
"suburb": "Melbourne",
"postcode": "3000",
"stateCode": "VIC",
"countryCode": "AUS",
"externalAddressId": "ADDR-001",
"externalBizEntityId": null,
"externalPersonId": "PERSON-001",
"externalOrganisationId": null,
"personID": 5001,
"bizEntityID": null,
"organisationID": null
}
],
"communications": [
{
"communicationID": 3001,
"externalCommunicationId": "COMM-001",
"communicationTypeID": 1,
"name": "john.smith@email.com",
"bizEntityID": null,
"externalBizEntityId": null,
"personID": 5001,
"externalPersonId": "PERSON-001",
"organisationID": null,
"externalOrganisationId": null
},
{
"communicationID": 3002,
"externalCommunicationId": "COMM-002",
"communicationTypeID": 3,
"name": "+61412345678",
"bizEntityID": null,
"externalBizEntityId": null,
"personID": 5001,
"externalPersonId": "PERSON-001",
"organisationID": null,
"externalOrganisationId": null
}
]
},
"organisation": null
}
],
"accounts": [
{
"accountID": 7001,
"externalAccountId": "ACC-001",
"productID": 101,
"externalProductId": null,
"accountNumber": "INV-123456",
"currencyID": 1,
"drpTypeID": 1,
"drpValue": null,
"accountStatusID": 1,
"balance": 0.00
}
],
"addresses": [
{
"addressID": 2002,
"addressTypeID": 102,
"aboveAddressLine": "Suite 10",
"addressLine": "456 Business Street",
"suburb": "Sydney",
"postcode": "2000",
"stateCode": "NSW",
"countryCode": "AUS",
"externalAddressId": "ADDR-002",
"externalBizEntityId": "ENT-001",
"externalPersonId": null,
"externalOrganisationId": null,
"personID": null,
"bizEntityID": 12345,
"organisationID": null
}
],
"communications": [],
"paymentDetails": [
{
"paymentDetailID": 4001,
"externalPaymentDetailId": "PAY-001",
"paymentTypeID": 1,
"bizEntityID": 12345,
"externalBizEntityId": "ENT-001",
"bsb": "032001",
"accountNumber": "123456789",
"accountName": "John Smith Investment Trust",
"address": null,
"comments": null,
"currencyID": null,
"iban": null,
"intermediaryBankAccountName": null,
"intermediaryBankAccountNumber": null,
"intermediaryBankAddress": null,
"intermediaryBankName": null,
"intermediaryBankSWIFT": null,
"isForDeposit": true,
"isForDistribution": true,
"isForOther": false,
"isForRedemption": true,
"message": null,
"personalName": null,
"reference": "INV-001",
"swift": null
}
]
}
]
}