/BizEntity

When to Use

• Updating existing investor entity details, status, or classification
• Modifying party relationships, adding or removing authorized signatories
• Updating compliance information (FATCA/CRS, sophisticated investor status)
• Refreshing contact information, addresses, or payment details
• Performing comprehensive entity updates with complete data replacement

Common Scenarios

• Change Primary Contact: Update entity-level contact person without modifying accounts or payment methods. MUST include all existing accounts, addresses, communications, paymentDetails, and parties arrays to prevent data loss - only modify the specific party's isPrimaryContact flag.
• Add New Address: Entity relocates and needs additional correspondence address. GET current entity → Add new address to addresses array with new properties (omit AddressID) → Include ALL existing addresses → PUT complete structure. Omitting existing addresses permanently deletes them.
• Update Payment Method: Investor changes bank account details for distributions. GET current entity → Locate payment in paymentDetails array → Update BSB/account number (include paymentDetailID to update existing) → Include ALL other payment methods unchanged → PUT complete structure.
• Change Entity Status: Suspend entity due to compliance review. GET current entity → Update bizEntityStatusID to 3 (Suspended) → Include ALL nested arrays exactly as retrieved → PUT complete structure. Status change triggers automatic transaction restrictions and compliance workflows.
• Update Sophisticated Investor Status: Renew certification for wholesale product access. GET current entity → Update sophisticatedInvestorCertificateDate and sophisticatedInvestorEligibility → Include ALL nested arrays → PUT complete structure. Certification must be current (less than 2 years old) for continued access.
• Modify Party Signatory: Grant transaction signing authority to existing party. GET current entity → Locate party in bizEntityParties array → Set isSignatory to true (include bizEntityPartyID to update) → Include ALL other parties → PUT complete structure. Authorization changes affect transaction approval workflows.

Prerequisites

• Valid entity identifier (bizEntityID or externalBizEntityId must exist in system)
• Current entity data retrieved via GET to prevent unintentional data loss
• Access token with entity modification permissions and appropriate scope
• Understanding that nested arrays are completely replaced, not merged
• Backup of critical data relationships before modification
• Validation of all dependent system states (active accounts, pending transactions)

Considerations

• Complete Replacement: All arrays (accounts, addresses, communications, paymentDetails, parties) are replaced entirely - include ALL items you want to keep. Omitting an array or sending partial array deletes unlisted items permanently without recovery.
• Data Integrity: Always GET current entity first, modify specific fields, then PUT complete structure back with ALL unchanged nested items included. Skipping GET step risks permanent data loss.
• Immutable Fields: bizEntityTypeID cannot be changed after creation due to structural dependencies. Must exactly match entity's current type - PUT operations validate immutability and reject type changes.
• Required Arrays: accounts and bizEntityParties arrays are MANDATORY - validation fails if either is empty or omitted. Entity cannot exist without at least one account and one party relationship.
• Same ProductID Rule: All accounts within entity must share same productID or externalProductId. Validation enforces consistency across all account updates - mixed products trigger 400 error.
• Status Change Impact: Changing bizEntityStatusID triggers automatic workflows. Inactive/Suspended entities cannot process transactions, status changes cascade to all accounts, and compliance notifications are sent to regulatory systems.
• External ID Maintenance: externalBizEntityId changes break API integrations and external system linkages. Only modify if intentional re-mapping required - downstream systems depend on ID stability.
• Concurrent Updates: Multiple users updating same entity simultaneously causes data conflicts - last write wins. Implement optimistic locking with version checks or timestamps to prevent unintended overwrites.
• Account Dependencies: Currency changes trigger automatic balance conversions with FX rate calculations. Status changes affect transaction processing capabilities - closed accounts reject new transactions.
• Audit Trail: All changes are logged for compliance with immutable audit records. Modifications trigger notifications to related parties (investors, administrators, compliance officers) and regulatory reporting updates.
• Validation Cascade: Changes propagate through nested objects (accounts → transactions, parties → authorizations) with full business rule validation at each level. Failures at any level roll back entire PUT operation.