Skip to main content

Key Dates

List the open contract key dates inside a horizon, soonest first, and mark a notice deadline, renewal or escalation handled so the decision survives rebuilds.

A key date is a day on which a contract needs someone. The kinds are expiry, renewal, notice_deadline, escalation, termination and obligation (a dated obligation the contract states). Key dates are rebuilt from the fold whenever the contract is recomputed, so they always reflect the current terms; a date that moves is announced again to the other apps, while a date that did not change keeps its announcement state.

GET /v1/contracts/upcoming lists the open key dates from today to today plus days, soonest first. A date a person marked handled is left out. days defaults to the configured alert horizon (90 days by default) when it is omitted or is not an integer, and values outside 1 to 3650 are clamped. Each entry carries the contract it belongs to, the due date, days_left, and the document and quote the date rests on.

GET/v1/contracts/upcoming

Query parameters

daysintegerHorizon in days, 1 to 3650. The configured alert horizon (90 by default) when omitted or not an integer; other values are clamped.

Entry fields (data[])

idstring (uuid)The key date id; pass it to POST /v1/contracts/key-dates/{keyDateId}.
contract_id, contract_key, title, counterpartystringThe contract the date belongs to.
kindstringexpiry, renewal, notice_deadline, escalation, termination or obligation.
due_datestring (date)The day the date falls on.
labelstringFree text for obligations; empty for the fixed kinds.
document_id, quotestring | nullThe document and the passage the date rests on.
days_leftintegerDays from today to the due date.

cURL: Dates in the next 30 days

curl "https://api.talonic.com/v1/contracts/upcoming?days=30" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response: Open key dates

{
  "data": [
    {
      "id": "a41e7c20-6d3b-4f8a-b5c1-92e07d1a3f48",
      "contract_id": "6f1c2a9e-1d4b-4a7e-9c33-2b8a5e0d7f11",
      "contract_key": "1043020-WLV",
      "title": "Waermelieferungsvertrag",
      "counterparty": "Stadtwerke Musterstadt GmbH",
      "kind": "notice_deadline",
      "due_date": "2026-06-30",
      "label": "",
      "document_id": "0b7d3c1e-5f2a-4c68-8a19-7e4d9b2c6a30",
      "quote": "Die Kuendigungsfrist betraegt sechs Monate zum Vertragsende.",
      "days_left": 25
    }
  ]
}

Marking a Date Handled

POST /v1/contracts/key-dates/{keyDateId} records the decision that a key date was handled (handled: true) or is open again (handled: false). The decision is stored as the calling key and applies to the same kind, day and label, so it survives every rebuild of the contract's key dates. A date whose day moves is a different date and opens again. The response is 201 with the key date id and its handled state.

POST/v1/contracts/key-dates/{keyDateId}

Body fields

handled*booleanTrue marks the date handled; false opens it again.
notestringUp to 2000 characters. Recorded with the decision.

cURL: Mark the notice deadline handled

curl -X POST "https://api.talonic.com/v1/contracts/key-dates/a41e7c20-6d3b-4f8a-b5c1-92e07d1a3f48" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handled": true, "note": "Renewal declined by letter of 2026-05-02"}'
Marking a date handled is not the same as deciding the contract. To record that notice was sent or the renewal was declined, use POST /v1/contracts/{id}/decision: the decision changes how the fold computes the end of the term. A handled mark only removes the date from the open lists.

Frequently asked questions

What horizon does the upcoming list use when I omit days?+
The configured alert horizon, 90 days by default. A days value that is not an integer falls back to the same default, and values outside 1 to 3650 are clamped into that range.
Does a handled key date come back after the contract is recomputed?+
No, as long as its kind, day and label are unchanged. The decision is keyed on those three values, so it survives every rebuild of the key dates. If the day moves, the date is a new date and is open.
How do I reopen a date I marked handled?+
Send the same request with handled set to false. The date returns to the open lists and to the upcoming list when it falls inside the horizon.

Related

Contracts Overview
Contract Register and 360 View
Contract Processes
Corrections and Decisions