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 exceptions are the fields ending in MmyA365F and MmyA360F, which surface the return as a money-market yield in MMYA365F and MMYA360F format:

• mmyA365F / mmyA360F on a holding are the money-market equivalent of Holding.yield, except that on a fixed holding they are derived from cost and maturityValue and so also reflect any maturity value adjustment, which yield does not. On an extension (GET /holding/{entity_code}/{holding_uid}/extension) they carry the return accrued from the extension's date to its maturity. On a holding event they are the holding's figures at the time of the event, and null on events recorded before they were added.
• indicativeMmyA365F / indicativeMmyA360F on an indication convert indicativeYield over the term from issueDate to maturityDate, so subscribing on a later date gives a slightly different figure.
• indicativeFinalMmyA365F / indicativeFinalMmyA360F on an indication, and finalMmyA365F / finalMmyA360F on a holding, convert the final period yield over finalDays (extendables only).

The converted figures are given to 3 decimal places, as the portal shows them. Reach for any of these only when you specifically need those formats.

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 only if the holding had been issued; a pending holding cancelled for lack of funding emits no 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, but the subscription links them. Every ROLL or SWITCH maturity action records the uid of the subscription for the next holding. That subscription is created when the action is set, or, for an automatic roll, when TreasurySpring picks the roll target before cut-off. To rebuild the chain (predecessor → successor across a roll or switch):

1. On the predecessor, read maturityActions[].subscriptionUid for each ROLL or SWITCH action from GET/holding/{entity_code}/{holding_uid}.
2. Find the SUBSCRIBED event with that subscriptionUid in GET/event (use the entity_code filter to narrow it down). Its holdingUid is the successor, whose own subscriptionUid is the same value. A successor issued before 22 April 2026 may have no SUBSCRIBED event (see Holdings that predate the stream); match the subscriptionUid on the holdings from GET/holding instead.

The successor's SUBSCRIBED event comes before the predecessor's REDEEMED event in the stream, because the roll is processed at cut-off and the redemption on the maturity date.

One exception: when several of an entity's ROLL or SWITCH actions go into the same product on the same date at the same yield — whether they sit on different holdings or on one — TreasurySpring combines them into one new holding under a new subscription, so none of those actions' subscriptionUid values match. That subscription's source text, on GET/subscription, names the previous holdings' uids.

For a Split, the relationship is forward-only in the schema today: the original holding emits one SPLIT event per new holding, with the new holding's uid as splitHoldingUid. The new holding has no SUBSCRIBED or ISSUED event of its own and carries the original holding's subscriptionUid, so fetch it from GET/holding. 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.

Zero balances

A cash position is never deleted and keeps its uid, but GET/holding leaves it out of the list while its balance is zero. Pass include_zero_cash=true to list it at cost: 0 instead, so a balance that falls to zero shows as zero rather than disappearing. GET/holding/{entity_code}/{holding_uid} returns it whatever its balance.

include_zero_cash does not apply to status: "Processing" cash: that position exists only while its transaction is in flight, and is removed once the transaction completes.