CORE CONCEPT

IDs & External References

Master the dual ID system providing both database performance and flexible integration with your external systems.

For HTTP/REST users: Use native IDs (BizEntityID) for performance, external IDs (ExternalBizEntityId) for client system integration

For .NET SDK users: Use native IDs for queries, external IDs for creating/updating resources from external systems

Both approaches support the dual ID system - every resource has a native database ID (integer) and an optional external ID (string) for your reference.

Quick Reference

Dual ID System

🔢

Native IDs (Database Primary Keys)

Type: Integer (int, long)

Format: Auto-generated by database

Example: BizEntityID, AccountID, PersonID

Performance: Indexed integers (fastest queries)

Use for: Internal operations, fast lookups, performance-critical queries

🏷️

External IDs (Client-Controlled References)

Type: String (max 50 characters)

Format: Your choice (alphanumeric + hyphens recommended)

Example: ExternalBizEntityId, ExternalAccountId, ExternalPersonId

Performance: String lookups (slower than native IDs)

Use for: Integration with external systems, cross-system references, deduplication

⚠️

Critical: ExternalPersonId Pattern

ExternalPersonId prevents duplicate person records - same ExternalPersonId reuses existing person instead of creating duplicate.

Essential for preventing John Smith from your CRM creating 5 duplicate person records across different entities.

Use native IDs for performance, external IDs for integration - both are supported across all endpoints.

Why This Matters

The dual ID system enables seamless integration with external systems while maintaining database performance through optimized integer indexes. ExternalPersonId deduplication prevents duplicate person records across operations, essential for registry platforms synchronizing data from multiple sources.

💡

The Dual ID Principle

Every resource in the 7G API supports two parallel identification systems: native database IDs (auto-generated integers) and external IDs (client-controlled strings). You can use either or both depending on your integration needs.

How It Works:

Create resource - Optionally provide ExternalBizEntityId (your reference)
API assigns native ID - Database generates BizEntityID (integer primary key)
Response includes both - API returns both BizEntityID and ExternalBizEntityId
Query by either - Use native ID for performance, external ID for integration
Uniqueness enforced - Each external ID is unique per client (case-insensitive)

⚖️

Native IDs vs External IDs

Understanding the dual identification system

Native IDs (Database Primary Keys)

Characteristics:

Auto-generated by database (identity columns)
Integer type (int for most resources, long for high-volume like transactions)
Guaranteed unique globally
Never null for existing records
Database-indexed for optimal performance

Naming Pattern: *ID (uppercase 'ID')

Resource	Native ID Field	Type
BizEntity	`BizEntityID`	int
Account	`AccountID`	int
Person	`PersonID`	int
Organisation	`OrganisationID`	int
Investment	`InvestmentID`	int
BizTransaction	`BizTransactionID`	long
Distribution	`DistributionID`	int

json

# Query by native ID (fastest)
GET /BizEntity?BizEntityID=1001

# Response includes the native ID
{
  "result": true,
  "data": [{
    "bizEntityID": 1001,
    "name": "Smith Super Fund",
    "bizEntityTypeID": 4
  }]
}

External IDs (Client-Controlled References)

Characteristics:

Client-defined strings (your choice of format)
Maximum 50 characters
Case-insensitive matching
Unique per client (not globally)
Optional (can be null)

Naming Pattern: External*Id (titlecase 'd')

Resource	External ID Field	Max Length
BizEntity	`ExternalBizEntityId`	50 chars
Account	`ExternalAccountId`	50 chars
Person	`ExternalPersonId`	50 chars
Organisation	`ExternalOrganisationId`	50 chars
Investment	`ExternalInvestmentId`	50 chars
Product	`ExternalProductId`	50 chars

Format Recommendations:

Alphanumeric with hyphens: CLIENT-001, ACC-7G-12345
Avoid special characters, spaces, or symbols
Consistent naming convention across your integration
Maximum 50 characters

json

# Query by external ID
GET /BizEntity?ExternalBizEntityId=CLIENT-001

# Response includes both IDs
{
  "result": true,
  "data": [{
    "bizEntityID": 1001,
    "externalBizEntityId": "CLIENT-001",
    "name": "Smith Family SMSF"
  }]
}

# Create with external ID
POST /BizEntity
{
  "externalBizEntityId": "CLIENT-001",
  "name": "Smith Family SMSF",
  "bizEntityTypeID": 4
}

📊

Performance Comparison

Choose the right ID type for your use case

Aspect	Native IDs	External IDs
Query Speed	Sub-second (indexed integers)	Slower (string comparison)
Storage	4 bytes (int), 8 bytes (long)	Variable (up to 50 chars)
Uniqueness	Global (database-enforced)	Per-client (case-insensitive)
Use Case	Internal operations, fast lookups	Cross-system integration
Recommended For	Performance-critical queries	External system references

Performance

Recommendation: Use native IDs for performance-critical queries, store both IDs in your local database for fast bidirectional lookups.

🔄

ExternalPersonId Deduplication Pattern

Prevent duplicate person records across operations

⚠️

Critical Feature

When creating or updating resources that reference a Person, the same ExternalPersonId across multiple operations reuses the existing person record instead of creating duplicates.

The Problem Without Deduplication:

Create BizEntity 1 with person "John Smith" (ExternalPersonId: "PERSON-001") → Creates PersonID 501
Create BizEntity 2 with same person (ExternalPersonId: "PERSON-001")
WITHOUT deduplication: Creates PersonID 502 (DUPLICATE!)
WITH deduplication: Reuses PersonID 501 (CORRECT!)

How It Works:

First operation creates person with ExternalPersonId: "PERSON-001" → Assigned PersonID: 501
Second operation references ExternalPersonId: "PERSON-001" → API finds existing PersonID: 501
Second entity links to existing person (no duplicate created)

json

# Entity 1 - Creates new person
POST /BizEntity
{
  "name": "Smith Family SMSF",
  "bizEntityTypeID": 4,
  "person": {
    "firstName": "John",
    "lastName": "Smith",
    "externalPersonId": "PERSON-JohnSmith-001"
  }
}
# API creates PersonID 501

# Entity 2 - Reuses same person (same ExternalPersonId)
POST /BizEntity
{
  "name": "Smith Investment Trust",
  "bizEntityTypeID": 5,
  "person": {
    "firstName": "John",
    "lastName": "Smith",
    "externalPersonId": "PERSON-JohnSmith-001"
  }
}
# API reuses existing PersonID 501 (no duplicate created)

Best Practice: Always provide ExternalPersonId when creating entities with person references to prevent duplicate person records.

BizEntity Advanced Scenarios: For placement rules across nested contexts (bizEntityParties, associatedPersons, contact), advanced multi-role patterns (SMSF, Trust), and validation details, see Person Reuse & Deduplication Logic in the BizEntity reference.

🔍

Filtering by IDs

Query by native IDs, external IDs, or both simultaneously

You can filter by native IDs, external IDs, or both simultaneously.

Filtering by Native ID:

json

# Filter by native ID (exact match)
GET /BizEntity?BizEntityID=1001

# Filter by native ID (using equal operator explicitly)
GET /BizEntity?BizEntityID.equal=1001

# Filter by multiple native IDs (using in operator)
GET /BizEntity?BizEntityID.in=1001,1002,1003

Filtering by External ID:

json

# Filter by external ID (exact match)
GET /BizEntity?ExternalBizEntityId=CLIENT-001

# Filter by external ID prefix (using startsWith operator)
GET /BizEntity?ExternalBizEntityId.startsWith=CLIENT-

# Combine filters (type + external ID prefix)
GET /BizEntity?BizEntityTypeID.equal=4&ExternalBizEntityId.startsWith=SMSF-

See Query & Filtering for all filter operators including startsWith (HTTP) / StartsWith (SDK), contains / Contains, in / In.

✅

Best Practices

Guidelines for effective ID management

Use native IDs for performance-critical queries and relationships
Provide external IDs when creating resources from external systems
Always use ExternalPersonId to prevent duplicate person records
Store both IDs in your local database for bidirectional lookups
Use consistent external ID format across your integration (e.g., CLIENT-{`{id}`})

Avoid

Relying solely on external IDs for high-frequency production queries (performance impact)
Using special characters, spaces, or symbols in external IDs (alphanumeric + hyphens only)
Exceeding the 50-character limit for external IDs
Creating person records without ExternalPersonId (causes duplicates)
Assuming external IDs are case-sensitive (they're matched case-insensitively)