CORE CONCEPT

IDs & External References

Master the dual ID system that provides both performance and flexibility for entity management

Why This Matters

The 7G API's dual identifier system balances performance with flexibility, enabling seamless integration while maintaining optimal query performance.

🏗️

System Integration

Connect existing systems while maintaining data integrity and performance.

⚡

Performance Optimization

Native IDs for database queries, external IDs for flexible referencing.

🔄

Migration Support

Maintain existing identifiers during migration without disrupting operations.

💡

The Dual ID System

Key Principle

Use native IDs for performance-critical operations, external IDs for integration and human-readable references.

🔢

Native IDs

System-generated performance identifiers

Native IDs are integer-based identifiers automatically generated by the 7G platform, following a consistent {EntityName}ID naming convention.

Characteristics

  • Auto-generated: System assigns unique integers automatically
  • Optimized: Designed for maximum database query performance
  • Consistent: Follow predictable naming patterns across all entities
  • Required: Every entity has a native ID upon creation
  • Immutable: Never change once assigned

Naming Pattern

{EntityName}ID
bizEntityID personID accountID investmentID

Usage Examples

json
// Get business entity by native ID
GET /BizEntity?bizEntityID=12345

// Response includes the native ID
{
  "result": true,
  "data": [{
    "bizEntityID": 12345,
    "name": "Smith Super Fund",
    "bizEntityTypeID": 4
  }]
}
🏷️

External IDs

Client-provided integration identifiers

External IDs are optional client-provided string identifiers that enable seamless integration with your existing systems using your own naming conventions.

Characteristics

  • Optional: Not required but highly recommended for integration
  • Client-controlled: You define the values and format
  • String-based: Up to 50 characters in length
  • Unique per client: Must be unique within your organization
  • Searchable: Support dot operators for advanced filtering

Naming Patterns

Parameters (PascalCase)
External{EntityName}Id ExternalBizEntityId
JSON Properties (camelCase)
external{EntityName}Id externalBizEntityId

Usage Examples

json
// Create entity with your external identifier
POST /BizEntity
{
  "externalBizEntityId": "SMSF-SMITH-001",
  "name": "Smith Super Fund",
  "bizEntityTypeID": 4,
  "accounts": [{
    "externalAccountId": "ACC-SMITH-001",
    "accountNumber": "SMITH001",
    "productID": 100
  }]
}
📈

Performance Considerations

Understanding the trade-offs between ID types

Aspect Native IDs External IDs
Query Speed Fastest Good
Database Index Optimal Larger
Memory Usage Minimal Higher
Best Use Cases High-frequency lookups, large datasets, performance-critical operations System integration, human-readable references, data migration
⚡

Performance Strategy

Use native IDs as your primary reference method for optimal performance. Include external IDs during entity creation for integration, but prefer native IDs for all subsequent API operations.

🔄

Implementation Patterns

Three proven strategies for effective dual ID usage

1

Integration Pattern

Use external IDs to maintain references to your existing system identifiers during entity creation.

json
// Step 1: Create with your external ID
POST /BizEntity
{
  "externalBizEntityId": "CRM-CLIENT-789",
  "name": "ABC Corporation Trust",
  "bizEntityTypeID": 2
}

// Response provides native ID
{
  "result": true,
  "data": {
    "bizEntityID": 15678,
    "externalBizEntityId": "CRM-CLIENT-789"
  }
}
2

Performance Pattern

Store native IDs locally after creation for maximum performance in subsequent API calls.

json
// Step 1: Create entity and store native ID locally
const createResponse = await api.post('/BizEntity', {
  externalBizEntityId: 'CLIENT-123',
  name: 'Smith Trust'
});

// Store BOTH IDs in your database
const nativeId = createResponse.data.bizEntityID;
const externalId = createResponse.data.externalBizEntityId;

await db.clients.update(clientId, {
  sevenGNativeId: nativeId,
  sevenGExternalId: externalId
});
3

Migration Pattern

Gradually transition from external to native IDs as your integration matures and stabilizes.

json
// Phase 1: Create with external IDs for migration
POST /BizEntity
{
  "externalBizEntityId": "LEGACY-12345",
  "name": "Migrated Entity"
}

// Store the response
{
  "bizEntityID": 98765,
  "externalBizEntityId": "LEGACY-12345"
}
✅

Best Practices

Guidelines for effective ID management

Recommended

  • External IDs are not required, but are provided as an alternative for integration
  • Use native IDs for performance-critical queries and relationships
  • Follow consistent external ID naming conventions across your system
  • Store both ID types in your local database for flexibility
  • Validate external ID uniqueness in your application logic

Avoid

  • Relying solely on external IDs for production queries
  • Using special characters or spaces in external IDs
  • Assuming external IDs are case-sensitive (API performs case-insensitive matching)
  • Assuming external ID lookups distinguish between "CLIENT-001" and "client-001" (they match the same record)
  • Reusing external IDs across different entity types
  • Exceeding the 50-character limit for external IDs
  • Modifying external IDs after entity creation

Quick Reference

ID Format Rules & Constraints

Aspect Native IDs External IDs
Parameter Format PascalCase: BizEntityID PascalCase: ExternalBizEntityId
JSON Format camelCase: bizEntityID camelCase: externalBizEntityId
Data Type int32, int64 string
Max Length System-generated 50 characters
Required Always present Optional (streamlined alternative to handle integration)
Uniqueness Globally unique Unique per client
Performance Optimized indexes Secondary indexes

ID Filter Capabilities

Both native and external IDs support advanced filtering with dot operators:

Native ID Filters (FilterOfInt32/FilterOfInt64)

  • BizEntityID.Equal=12345
  • BizEntityID.NotEqual=0
  • BizEntityID.In=100,101,102
  • AccountID.GreaterThan=1000

External ID Filters (StringFilter)

  • ExternalBizEntityId.Equal=SMSF-001
  • ExternalAccountId.BeginsWith=ACC-
  • ExternalPersonId.Contains=TRUSTEE
  • ExternalInvestmentId.EndsWith=-2024

Important Business Rules

⚠️

Relationship Constraints

  • Address, Communication, and PaymentDetail belong to ONE entity exclusively—either BizEntity, Person, OR Organisation (not multiple)
  • Exclusive ownership model: Cannot reference multiple entities or multiple entity types simultaneously
  • External IDs must be unique across your organization for each entity type
  • One-to-one mapping between native IDs and external IDs is enforced