Identifiers & keying your records

TreasurySpring uses different identifier strategies for different concepts. Picking the right one as your primary key is one of the more important decisions when reconciling a TreasurySpring position against an internal record. This page walks through each identifier, what guarantees it offers, and where those guarantees stop.

The TL;DR

Concept	What to use as your primary key	Stability
Entity	entityCode	Stable, human-readable, scoped per client organisation
Indication (extendable)	uid	Stable across days
Indication (fixed)	Do not persist uid; overwrite the indication record on each refresh	Re-issued daily
Subscription	uid	Stable from creation
Holding	holdingUid	Stable across issuance, splits, adjustments, extensions, and redemption — recommended primary key

Note: there is no stable primary key for an "FTF product" concept itself. See Product codes are not unique below.

Entities

• The smallest unit of access is an entity (a client organisation).
• entityCode is the identifier to use for an entity; there is no separate numeric entityId field.
• A user may have access to multiple entities — calling GET/entity first will enumerate the codes available to your API user.
• Family-level grouping exists internally but is intentionally not exposed via the API. Entity is the most granular level that partners see.

Product codes are not unique

productCode identifies an FTF product line, not a specific instrument. Many products are re-issued every business day with new economics (yield, maturity date), and all of those daily issuances share the same productCode.

Even within a single day, two offerings can share the same productCode, issueDate, maturityDate, and obligorExposureCode — for example, two issuances of the same product may differ only in their minimum investment amount (and therefore in their yield). For that reason, there is no reliable composite key for an FTF product on its own.

For reconciliation and persistence, we'd suggest keying on the concrete records instead:

• For an offer that hasn't yet been subscribed to: the indication uid (refreshed daily for fixed indications — see Indication UIDs below).
• For a placed request: the subscription uid.
• For an active position: holdingUid — the recommended long-term key, covered in Holding UIDs are the source of truth.

productCode and the associated date / obligor fields remain useful for human-readable display (report headers, audit trails) but they aren't unique enough to act as a primary key on their own.

Indication UIDs — different rules for fixed vs extendable

Indications are presented as one global universe:

• Every entity that calls GET/indication/{code} sees the same uid values for the same underlying indication.
• Visibility is controlled by entity permissions (you only see indications you're allowed to subscribe to).
• The same uid can carry different indicativeYield / minimum / maximum values per entity — this is intentional.

UID stability depends on the indication type:

• Extendable indications — UID is stable across days.
• Fixed indications — re-uploaded daily. The same logical product gets a new uid each day. Storing yesterday's uid and re-using it tomorrow will either fail or fetch a different product.

We'd recommend refreshing indications daily and overwriting the local record. The indication uid is best treated as a short-lived handle rather than a long-term key.

Subscription UIDs and the link to a holding

Submitting POST/subscribe returns a subscription uid immediately. The subscription is the request to invest; the resulting holding is the live position.

Poll GET/subscription until holdingUid is populated, then switch to keying on the holding. The subscription record is retained for workflow history, but the holding is the live source of truth for terms — yield, maturity date, and issuance timing can all differ slightly between the subscription request and the issued holding.

Holding UIDs are the source of truth

holdingUid is assigned at subscription acceptance and is stable for the entire lifecycle of that holding:

• Survives Pending → Issued (issuance does not re-key).
• Survives Adjusted and Extended events.
• Survives Split — both resulting holdings keep the original parent reference via the SPLIT event payload.
• Disappears only at Redeemed or Cancelled.

This is the right primary key for portfolio reconciliation, P&L attribution, and any system-of-record join.

Rolled holdings get a new UID

When a holding's maturity action is ROLL, the next holding is a new record with a new holdingUid. The two are non-overlapping in time; use the SUBSCRIBED event on the successor combined with the predecessor's REDEEMED event to reconstruct the chain. See FTF Lifecycle → Rolls.

Obligor exposure codes

obligorExposureCode identifies the credit exposure of a holding — the institution issuing the underlying, plus its collateralisation profile. The same obligor can appear under multiple exposure codes when collateral differs:

Example	Meaning
BACR	Unsecured exposure to Barclays
BACR[GC]	Secured exposure to Barclays, government-collateral
BACR[WC]	Secured exposure to Barclays, wide-collateral

The square-bracket suffix communicates the collateral bracket. If you're keying on credit exposure (for example, for limit monitoring), it's worth using the full obligorExposureCode value verbatim and keeping the suffix in place.

Call GET/obligor-exposure to retrieve sector, credit details, and any URLs (e.g. credit research links) associated with an exposure code.

Worst-case recovery: rebuilding the chain from events

If you need to reconstruct a position's full history (subscribed → issued → adjusted → split → redeemed → rolled into successor), the event stream is the canonical source. Use GET/event with cursor pagination and join on holdingUid. See FTF Lifecycle for the full event taxonomy.