Skip to main content

Assumptions

Make, list, replace and withdraw assumptions that stand in for missing values; every price built on one is marked assumed and never counts as independent.

An assumption stands in for a value where no source exists. It is the explicit alternative to leaving a price open: a person states what number to use, why, and for what scope, and the system marks everything built on it. Every price or plan amount that rests on an assumption is marked as assumed, never counts as independent, and has the gap tier assumed. An assumption is used only where no real value exists, so a real value arriving replaces it with no action.

An assumption has a target_kind and a target. series stands in for an index series (target is the series key), variable for a contract value (target is the variable name), quantity for a price's billing quantity (target is the component key), and profile for how annual energy spreads over the months (target energy). The rule says how: value uses the given number, carry_forward uses the last real value before the period, proxy uses another series' value times params.factor. Scope is a single contract (contract_key) or the whole workspace (null).

GET/v1/price-baseline/assumptions

Query parameters

contract_keystringWithout it, every active assumption is returned. With a key, the assumptions of that contract and the workspace-wide ones are returned. With an empty string, only the workspace-wide ones are returned.

Response fields

data[].iduuidAssumption id.
data[].contract_keystring | nullThe contract it applies to; null for the whole workspace.
data[].target_kind / targetstringWhat it stands in for.
data[].period_from / period_tostring | nullPeriod bounds: YYYY, YYYY-MM, YYYY-Qn or YYYY-Hn.
data[].rule / value / unit / paramsmixedThe rule and its inputs.
data[].note / created_bystring | nullWhy it was made, and who made it; api:<key id> for an API key.
POST/v1/price-baseline/assumptions

Body fields

target_kind*stringseries, variable, quantity, or profile.
target*stringSeries key, variable name or component key, up to 120 characters. * is a workspace default for every series.
rule*stringvalue, carry_forward, or proxy.
contract_keystring | nullThe contract it applies to, up to 64 characters; null or absent applies to every contract of the workspace.
period_from / period_tostring | nullPeriod bounds: YYYY, YYYY-MM, YYYY-Qn or YYYY-Hn.
valuenumber | nullThe number for rule value.
unitstring | nullUnit, up to 40 characters.
paramsobjectseries (the series a proxy or profile is derived from) and factor.
notestring | nullWhy the assumption is made, up to 2000 characters.

cURL: Carry the last real index value forward for one contract

curl -X POST "https://api.talonic.com/v1/price-baseline/assumptions" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contract_key": "4711",
    "target_kind": "series",
    "target": "destatis.erdgas.boerse",
    "rule": "carry_forward",
    "period_from": "2025-04",
    "period_to": "2025-06",
    "note": "March value not yet published; carry the February value."
  }'

The combination rules are enforced with a 422. A value rule needs value, except for target kind profile. carry_forward applies to target kind series only. A proxy rule, and target kind profile, need params.series. The target *, a default for every series, is allowed only as target kind series with rule carry_forward. The response is the stored record with status 201.

PUT/v1/price-baseline/assumptions/{id}

Path parameters

id*uuidAssumption id.
DELETE/v1/price-baseline/assumptions/{id}

Path parameters

id*uuidAssumption id.

Response fields (200)

iduuidThe withdrawn assumption.
activebooleanAlways false.

cURL: Withdraw an assumption

curl -X DELETE "https://api.talonic.com/v1/price-baseline/assumptions/2a7c4e19-b0d3-46f8-8a51-3e9f7c1d0b64" \
  -H "Authorization: Bearer $TALONIC_API_KEY"
Within a scope, a contract-scoped assumption is read before a workspace-wide one, and a named target before *. An assumption is read only where no real value exists, so entering a sourced value, through POST /indices/manual or a synced series, makes the assumption inert without deleting it.

Frequently asked questions

Does an assumption ever override a real value?+
No. An assumption is used only where no real value exists. A real value arriving, a synced index value or an entered value with its quote, replaces the assumption with no action, and the price is no longer marked as assumed.
What does withdrawing an assumption do?+
It deactivates the assumption. The gap it filled shows as open again, and the record is kept with active false and is no longer listed. The prices that rested on it are recomputed without it.
Why was my assumption rejected with a 422?+
A combination rule was violated: rule value needs a value except for target kind profile, carry_forward applies to target kind series only, proxy and target kind profile need params.series, and the target * is allowed only as a series assumption with rule carry_forward.
How are assumptions scoped?+
An assumption applies to one contract when contract_key is set and to the whole workspace when it is null or absent. Listing with a contract_key returns that contract's assumptions plus the workspace-wide ones; listing with an empty contract_key returns only the workspace-wide ones.

Related

Index Values
Open Inputs and Enrichment
Invoice Checks
Contract Pricing Overview