🏢 BizEntity Resource

The foundational investor identity in the 7G Registry Platform

BizEntity represents the complete investor identity in the 7G platform - the central hub for accounts, holdings, party relationships, addresses, communications, and payment details. All investment operations flow through a BizEntity. Direct endpoints for Person, Organisation, and other resources exist for specialized scenarios like bulk imports.

8
Endpoints
5
Entity Types
45
Properties
Primary
Resource Type

BizEntity is the primary API resource for investor operations. Most Person, Organisation, Address, Communication, and PaymentDetail management occurs through BizEntity operations. Direct endpoints exist for specialized scenarios like bulk imports or data migration.

Usage Notes

When

  • Create and manage investor entities (Individual, Company, Trust, SMSF, Partnership)
  • Query entities by type, product, account, or party relationships
  • Synchronize entity changes using date-based filtering

Requirements

  • Valid Bearer token with BizEntity permissions

Notes

  • BizEntity is the primary aggregation point for all investor data
  • Every transaction, distribution, and holding connects through a BizEntity
  • Most Person, Organisation, Address, Communication, and PaymentDetail management occurs through BizEntity operations
  • Same externalPersonId appearing multiple times in a request reuses ONE person record (deduplication)

Available Endpoints

Core Operations

GET Get BizEntities Query with filters and cross-resource search
POST Create BizEntity Create investor with nested accounts and parties
PUT Update BizEntity Replace entity structure
DELETE Delete BizEntity Remove with transaction validation

Account Holdings & Portfolio Queries

GET Account Holdings Portfolio positions and valuations

Parent Relationship Management

POST Create Parent Establish parent-child hierarchies
PUT Update Parent Modify hierarchical relationships
DELETE Delete Parent Remove relationship validation

Core Data Transfer Objects

BizEntityDTO POST, PUT, GET responses Complete entity structure (39 main properties + 6 arrays: Accounts, Addresses, Communications, PaymentDetails, BizEntityParties, BizEntityParents)
BizEntityParentDTO Parent relationship endpoints Hierarchical relationships for corporate structures (8 properties)
BizEntityPartyDTO Entity operations (nested) Person/Organisation links with shareholding details (13 properties)
AccountDTO Entity operations (nested) Account structure for investment management (10 properties)

Filter Data Transfer Objects

GET endpoints use filter classes to bind query parameters. These are request-only structures for filtering and pagination.

BizEntityFilter GET /BizEntity 19 properties: 10 direct ID lookups (BizEntityID, ProductID, InvestmentID, PersonID, OrganisationID + externals) + 6 FilterField with dot operators (BizEntityTypeID, AccountID, AccountNumber, ExternalAccountId, CreatedDate, UpdatedDate) + UpdatedDateFull + pagination
AccountHoldingFilter GET /BizEntity/Account/Holdings 10 properties: 2 direct lookups (ProductID + external) + 5 FilterField with dot operators (AccountID, ExternalAccountId, AccountNumber, InvestmentID, ExternalInvestmentId) + Date (DateOnly) + pagination

Dual-Approach Creation Pattern

BizEntity operations support two approaches for managing Person and Organisation records: reference existing by ID (lightweight), or create/update nested objects atomically (complete setup in one call).

Reference Approach

Link to existing Person/Organisation by ID when records already exist:

  • Lightweight payload
  • Reuses existing records
  • Prevents duplication
json
POST /BizEntity
Content-Type: application/json

{
  "name": "Smith Family Trust",
  "bizEntityTypeID": 3,
  "bizEntityStatusID": 1,
  "accounts": [{
    "accountNumber": "TRUST001",
    "productID": 100
  }],
  "bizEntityParties": [{
    "personID": 5001,
    "isPrimaryContact": true
  }]
}

Full Structure Approach

Create or update complete Person/Organisation within BizEntity for atomic operations:

  • Single API call for complete setup
  • Atomic creation/update
  • Full data consistency
json
POST /BizEntity
Content-Type: application/json

{
  "name": "Smith Family Trust",
  "bizEntityTypeID": 3,
  "bizEntityStatusID": 1,
  "accounts": [{
    "accountNumber": "TRUST001",
    "productID": 100
  }],
  "bizEntityParties": [{
    "person": {
      "externalPersonId": "PERSON-001",
      "firstName": "John",
      "lastName": "Smith",
      "addresses": [{
        "addressTypeID": 1,
        "addressLine1": "123 Main St",
        "city": "Sydney",
        "postcode": "2000"
      }],
      "communications": [{
        "communicationTypeID": 1,
        "communicationValue": "john.smith@example.com"
      }]
    },
    "isPrimaryContact": true
  }]
}

Person Reuse & Deduplication Logic

When the same externalPersonId appears multiple times in a single request, the platform automatically deduplicates and reuses the Person record.

New to ExternalPersonId deduplication? See ExternalPersonId Deduplication Pattern for a comprehensive explanation of how and why this pattern prevents duplicate person records across all resources.

⚡ Critical Pattern: ExternalPersonId Reuse

When the same externalPersonId appears multiple times in a single BizEntity request, the 7G platform automatically deduplicates and reuses the Person record. This prevents creation of duplicate persons and maintains referential integrity.

How Person Reuse Works

Scenario: Person serves as both entity contact and company director:

POST /BizEntity
Content-Type: application/json

{
  "bizEntityParties": [
    {
      "person": {
        "externalPersonId": "PERSON-001",
        "firstName": "John",
        "lastName": "Smith"
      },
      "isPrimaryContact": true
    },
    {
      "organisation": {
        "name": "Smith Holdings Pty Ltd",
        "associatedPersons": [{
          "externalPersonId": "PERSON-001",
          "isSignatory": true
        }]
      }
    }
  ]
}
Result: ONE Person record created (PERSON-001), referenced in both contexts

ExternalPersonId Placement Rules

Context Correct Field Location Purpose
BizEntityParty with Person bizEntityParty.person.externalPersonId Entity-level identifier for person creation/reuse
Organisation Associated Person associatedPersons[].externalPersonId Entity-level identifier for person linkage
Reference Only (no creation) bizEntityParty.externalPersonId Linking-level reference to existing person

⚠️ Important: Entity-Level IDs Control Deduplication

The system uses the entity-level externalPersonId (within the Person object) as the primary deduplication key. Linking-level IDs are secondary references. Always populate the entity-level ID when creating or reusing persons within complex structures.

Key Deduplication Rules

  • Request Scope: Deduplication applies only within a single API request
  • First Occurrence Wins: First externalPersonId with full person details creates the record; subsequent occurrences reuse it
  • Minimal Reference: Second+ occurrences only need externalPersonId (other fields ignored)
  • Cross-Context Support: Same person can appear in bizEntityParties[], organisation.associatedPersons[], nested addresses
  • Cross-Request Behavior: Same externalPersonId across separate requests creates distinct person records (different scope)

Advanced Multi-Role Patterns

Complex Scenarios (SMSF, Trusts, Multi-Entity)

SMSF with Individual Trustees

Pattern: Same person serves as both member AND trustee

Implementation: Create person once with full details, reference externalPersonId in second party entry

Result: One person record, two BizEntityParty records (separate member + trustee entries)

Trust with Corporate Trustee

Pattern: Company directors also serve as trust beneficiaries

Implementation: Create persons within organisation.associatedPersons[], reuse externalPersonId in bizEntityParties[] beneficiaries

Result: Each person appears twice: once as company director, once as beneficiary

Cross-Entity Person Sharing

Pattern: Master fund advisor also serves sub-fund entities

Implementation: First request creates person, second request references via externalPersonId (not nested object)

Critical: Cross-entity reuse requires person to exist from prior request (different request scope)

Validation & Error Handling
  • Missing Entity-Level ID: Person object without externalPersonId creates duplicate each time
  • Orphaned Linking ID: Using bizEntityParty.externalPersonId without existing person fails
  • Inconsistent Data: Same externalPersonId with conflicting details may fail validation

Business Rules & Constraints

BizEntity Integration & Ecosystem

  • BizEntity is the foundational resource - all transactions, distributions, and holdings reference a BizEntity
  • Complete entity creation includes nested Accounts, Addresses, Communications, PaymentDetails, and Parties in a single operation
  • BizEntityParty records link to either Person OR Organisation (mutually exclusive)
  • Multiple party relationships per entity support roles like investor, signatory, controller, beneficial owner
  • Parent-child entity hierarchies enable complex corporate and trust structures
  • Account holdings aggregate across all accounts within the entity

Validation & Business Logic

  • Validation Rules: Name is required, BizEntityTypeID/StatusID must be > 0, at least one Account and BizEntityParty required, TaxationCountryCode must be 3 characters, and SAME PRODUCT RULE (all accounts must share ProductID or ExternalProductId)
  • Entity cannot be deleted if active BizTransaction, Distribution, or BizEvent records exist
  • TaxationCountryCode validated as 3-character ISO code

Performance & Advanced Features

  • Native IDs (BizEntityID) provide optimal performance; External IDs for integration flexibility
  • GET operations support 15+ filter parameters with typed filters (FilterOfInt32, StringFilter)
  • Cross-resource filtering by ProductID, InvestmentID, PersonID, OrganisationID for complex queries
  • Account Holdings endpoint provides real-time investment position data
  • Dual ID system: Native IDs for performance, External IDs for third-party system integration
  • Bulk entity operations supported for large-scale onboarding and portfolio management