IDs & External References

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')

# 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')

# 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
}

Many 7G endpoints treat the native ID and its external counterpart as a conditional pair: either identifier is accepted, but at least one must be supplied. This lets native integrators work with database IDs while external integrators reference resources by their own identifiers - without requiring both on every call.

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:

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

# Entity 1 - Creates new person
POST /BizEntity
{
  "name": "Smith Family SMSF",
  "bizEntityTypeID": 3,
  "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)

In nested structures like BizEntityParty, External IDs serve dual purposes. The same ExternalOrganisationId field triggers completely different behaviour depending on whether it's placed at the party level or inside a nested Organisation object.

{
  "bizEntityParties": [{
    "externalOrganisationId": "ORG-001",
    "organisation": null
  }]
}
// ExternalOrganisationId at PARTY level
// → Triggers lookup-only path
// → Finds existing org "ORG-001" and links it
// → Constraint error if "ORG-001" does not exist

Investment resources support a third identifier beyond the standard native/external pair: SecurityCode. It's a business-facing, ticker-style code (e.g. HGF001A, GRW001) that your team already uses to refer to investment classes. Every endpoint that resolves an investment - filters, transaction payloads, event payloads, distribution payloads - accepts any of the three.

Resolution Precedence

When a caller provides more than one identifier, the API's resolver tries each branch in a single OR'd query: native ID first, external ID next, SecurityCode last. If the identifiers don't all point to the same record, results are indeterminate. Supply exactly one identifier per operation to avoid ambiguity.

Where SecurityCode Works - And Where It Doesn't

SecurityCode is accepted as an identifier on most operations that reference an investment, but there are three deliberate exclusions documented below. Consult the relevant endpoint page for the exact parameter name, casing, and example payload.

Exact Error Strings

When a SecurityCode can't be resolved, the API returns a specific message. Match against these exact strings rather than a substring - several variants differ only in phrasing or the presence of the ProductID hint.

# Filter investments by SecurityCode (product-scoped)
GET /investment?SecurityCode=HGF001A&ProductID=100

# Deposit against an investment identified by SecurityCode
POST /BizTransaction/Deposit
{
  "productID": 100,
  "accountID": 5001,
  "securityCode": "HGF001A",
  "amount": 10000.00,
  "paymentMethodID": 1,
  "transactionDate": "2026-04-22"
}

# Conversion uses From/To prefixed variants
POST /BizTransaction/Conversion
{
  "productID": 100,
  "accountID": 5001,
  "fromSecurityCode": "GRA001",
  "toSecurityCode": "GRB001",
  "quantity": 1000,
  "transactionDate": "2026-04-22"
}

# Distribution supports drpSecurityCode for the DRP target
POST /Distribution
{
  "productID": 100,
  "securityCode": "GRW001",
  "drpSecurityCode": "DRP001",
  "accrualDate": "2026-04-01",
  "recordDate": "2026-04-15",
  "paymentDate": "2026-04-30"
}

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

Filtering by Native ID:

# BizEntityID on BizEntityFilter is a plain scalar (exact match only)
GET /BizEntity?BizEntityID=1001

# For operator-rich queries, use a FilterField property like BizEntityTypeID
GET /BizEntity?BizEntityTypeID.equal=3
GET /BizEntity?BizEntityTypeID.in=1,2,3

Filtering by External ID:

# ExternalBizEntityId on BizEntityFilter is a plain string (exact match only)
GET /BizEntity?ExternalBizEntityId=CLIENT-001

# For operator-rich external-ID queries, use a FilterField property such as
# ExternalAccountId (FilterField<string?>) on BizEntityFilter.
GET /BizEntity?ExternalAccountId.beginsWith=CLIENT-

# Combine filters (type + account external-ID prefix)
GET /BizEntity?BizEntityTypeID.equal=3&ExternalAccountId.beginsWith=SMSF-