Holdings & indications reference notes

This page covers the "what does this field actually mean" questions that come up during integration. The generated API reference is the authoritative shape; this page fills in the semantics the schema doesn't capture.

Yield semantics

All yield fields are APY unless the field name says otherwise. Holding.yield, Subscription.yield, Indication.indicativeYield, and the event yields are all annualised, compounded APY values in the same convention.

The only exception is Holding.mmyA365F, which surfaces the same underlying return in MMYA365F format. Reach for it only when you specifically need that format.

There is no separate fee field. If TreasurySpring's costs change, the yield change reflects that. The maturityValue returned by the API is post-fee.

For early or partial redemption, see the maturity value adjustment (MVA) flow in the lifecycle guide. The MVA is also folded into maturityValue — no separate field.

Holding statuses

The HoldingStatusEnum values are descriptive labels. They mean:

Status	Meaning
Pending	Holding created from an accepted subscription. Cash has not yet moved into the cell. Issuance is the next process.
Issued	Live. Cash is in the cell, earning yield. Maturity action(s) can be changed via PUT /holding/{entity_code}/{holding_uid}/maturity-action.
Processing	Transient — TreasurySpring is acting on the holding (e.g. split, adjust). Refetch shortly to get the stable status.
CutOff	Cut-off has fired. Maturity action is locked. TreasurySpring's maturity process decides redeem / roll / extend / finalize.
PendingWithdrawal	Redemption initiated; cash payout to the entity's bank not yet confirmed.
Redeemed	Holding has completed its lifecycle and cash has been paid out (or rolled).
Cancelled	Holding was unwound before natural maturity — usually because funding never arrived. Emits a CANCELLED event.

See FTF Lifecycle for the transitions between these.

Extendable holdings carry extra term and yield fields — see Reading an extendable's terms, which also covers why nextYield reads null for most of an extension's life.

Maturity action enums — two of them, slightly different

There are two related enums in the schema, and they use different casing and slightly different values:

Enum	Where it's used	Values
MaturityActionEnum	Holding.maturityActions (current state on a live holding)	HOLD, REDEEM, ROLL, SWITCH
SubscriptionMaturityActionEnum	SubscriptionBody.maturityAction (what you send at subscribe time)	Hold, Redeem, Roll (no Switch)

What to know:

• When sending a subscription, please use the title-case values — "Roll" rather than "ROLL".
• When reading a holding's maturityActions, expect the uppercase values.
• SWITCH cannot be requested at subscription time; it is set later on a live holding via the maturity-action endpoint.
• The portal shows friendlier labels for the same four values, and they differ by product type — most notably ROLL appears as Auto-extend on an extendable holding. See Portal labels and API enum values.
• A holding's value can be split across several actions. Send actions rather than action on the maturity-action endpoint — see Splitting a holding's value across actions.
• To find the FTFs a live holding can roll or switch into, call GET/holding/{entity_code}/{holding_uid}/indication. It returns the indications available against that holding; use a returned indication uid when setting the maturity action.
• The default for SubscriptionBody.maturityAction is Roll rather than Redeem. See the callout in the lifecycle guide.

Obligor exposure codes — the bracket reference

obligorExposureCode identifies the credit exposure of a position. The format is the issuer's short code, optionally followed by a square-bracket collateral suffix that distinguishes different exposures to the same issuer.

A few examples of suffixes you may encounter:

Suffix	Meaning
(none)	Unsecured exposure to the issuer.
[GC]	Secured exposure, collateralised by government securities.
[WC]	Secured exposure, collateralised by wide collateral (broader eligible-collateral pool than GC).

Other suffixes exist beyond the ones listed here, and new ones may be introduced over time. For an authoritative list of the codes accessible to your API user, read them off the values returned by GET/holding and GET/indication/{code}.

It's worth treating the full obligorExposureCode as the credit-exposure key, with the bracket suffix kept in place. Bracketed and unbracketed forms represent meaningfully different exposures for limit-monitoring purposes.

Indication metadata: what's there, what isn't

Indications expose the product's commercial terms. To translate an indication into a fuller credit picture, join on obligorExposureCode and read the obligor record:

Want to know...	Field	Source
Issuer sector (bank, sovereign, supra)	sector	Indication or ObligorExposure
Issuer credit research / data sheet URL	creditUrl	ObligorExposure
Indicative yield for this entity	indicativeYield	Indication (entity-specific tier — same UID, different number per entity)
Term (e.g. "3M", "12M")	term	Indication (free-text string; no min_term / max_term)

Not currently exposed via the API:

• Credit ratings — not currently surfaced via the API.
• A structured secured / unsecured flag. The presence of a [...] suffix on obligorExposureCode can be used in its place.
• A structured term range. term is a single string.

Calendar endpoint shape

GET/holiday/{year} returns a flat, concatenated list of dates: TreasurySpring's own scheduled non-business days plus the relevant country holidays for the calendars the entity is exposed to. There is no calendar name field on each entry — the list is the union.

For more granular filtering (for example, "give me only UK bank holidays for next year"), we'd suggest sourcing from your own calendar provider; the TreasurySpring endpoint is the union of what affects TreasurySpring processing.

Rebuilding the holding chain across rolls

There is currently no previousHoldingUid back-link from a rolled holding to its predecessor. To rebuild the chain (predecessor → successor across a roll), use the event stream:

1. Fetch GET/event with entity_code filter and time window.
2. Find the predecessor's REDEEMED event.
3. Find the successor's SUBSCRIBED event with the same entityCode, same productCode family, and timestamp immediately after the predecessor's redemption.
4. Match by holdingUid on both events.

For a Split, the relationship is forward-only in the schema today: the original holding emits a SPLIT event whose payload includes the new child holdingUids. Walking backward requires the reverse join.

Cash holdings

Uninvested cash in a cell appears on GET/holding alongside investment positions. There is exactly one cash UID per currency per cell, identified by type: "Cash". Cash and investments share the same endpoint, but cash positions have no yield (or a zero-yield reference rate, depending on cell) and a constant cost == value == maturityValue.

So type takes three values, not two: Fixed and Extendable for FTF holdings, and Cash. When sweeping for "what investments do I hold?", filter the cash entries out by type.

isOnBalanceSheet is not a substitute. It tests the lifecycle — settled, and not pending, cancelled or redeemed — so it is true for cash as well as for live FTF holdings. Filtering on it keeps every cash position.

Cash carries a sentinel maturity date

maturityDate is required on every holding, so a cash position reports 9999-12-31 rather than nothing. It is a placeholder, not a date.

Anything that averages, buckets or charts by maturity — weighted average maturity, a maturity ladder, "what matures this quarter" — must exclude type: "Cash" first, or a single cash row will dominate the result. The same applies to the min_maturity_date / max_maturity_date filters: cash clears any lower bound you set.

Cash that is tied up in an in-flight transaction (an FX conversion, or a movement between cells) also reports type: "Cash", but with status: "Processing". It settles into the ordinary cash position once the transaction completes.