🏢 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

Organisation & Person — Party Linking Patterns

When linking an Organisation or Person to a BizEntityParty, the API supports three distinct patterns. The behaviour depends on where you place the External ID — at the party level or inside a nested object.

Reference Link to an existing record
How
Set ExternalOrganisationId or PersonID at the party level
Result
Lookup only — links existing record. Constraint error if not found.
Create Create a new record atomically
How
Null party-level IDs, nested object with new ExternalId
Result
Creates organisation/person from nested data, then links it.
Update Update an existing record atomically
How
Null party-level IDs, nested object with existing ExternalId
Result
Updates existing record with nested data, then links it.

View code examples showing the Reference approach (link by ID) and Full Structure approach (nested objects with create/update).

Reference Approach

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

json
POST /BizEntity
Content-Type: application/json

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

Full Structure Approach

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

json
POST /BizEntity
Content-Type: application/json

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

Common mistake: Setting ExternalOrganisationId at the party level for an org that doesn't exist yet triggers lookup-only — the nested object is never reached. Set party-level IDs to null and use the nested object instead.

Detailed pattern examples: PUT endpoint patterns | POST endpoint patterns | Conceptual explanation

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.

Tip: Only the first occurrence of an externalPersonId needs full person details. Subsequent occurrences in the same request only need the externalPersonId — all other fields are ignored.

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",
          "relationshipTypeID": 1,
          "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[] and organisation.associatedPersons[]
  • Cross-Request Behavior: Across separate requests, if the externalPersonId already exists in the database, the existing person is updated rather than duplicated

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: If the same externalPersonId appears with conflicting details, the first occurrence's details are used; subsequent occurrences reuse the existing record

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-character ISO code, and SAME PRODUCT RULE (all accounts must share ProductID or ExternalProductId)
  • Entity cannot be deleted if active BizTransaction, Distribution, or BizEvent records exist

Performance & Advanced Features

  • Dual ID system: Native IDs (BizEntityID) for optimal query performance, External IDs (ExternalBizEntityId) for third-party system integration
  • GET operations support 15+ filter parameters with typed filters (FilterField<int>, FilterField<string>)
  • Cross-resource filtering by ProductID, InvestmentID, PersonID, OrganisationID for complex queries
  • Account Holdings endpoint provides real-time investment position data