Skip to main content

Contract Register and 360 View

List the contract register with status, dates, annual value and direction, then open the 360 view of one contract with every term, document and its source quote.

GET /v1/contracts returns every contract of the workspace, filtered by q, status and key. Each entry carries the status, the dates that matter (effective date, expiry, notice deadline, termination), the annual value, the document count, the next open key date, a summary of the open process items and the links to Price Baseline and Money Found. The response is { "data": [...] } and is not paginated; it is ordered by counterparty, then contract key.

direction states whether the workspace sells under the contract, buys under it or the contract is internal. It is derived on read from the parties the documents name, compared with the workspace's own company names, so changing the own company names needs no backfill. direction_source is read when a document states it and rule when the platform estimated it from the contract type; both are null when the documents name no company of the workspace, and direction_why then gives the reason.

GET/v1/contracts

Query parameters

qstringCase-insensitive substring over contract key, title and counterparty.
statusstringExact status: draft, active, expired, terminated or unknown.
keystringExact contract key.

Entry fields (data[])

idstring (uuid)The contract id used in every path below.
contract_keystringThe key that identifies the contract and joins it to other apps.
cost_unitsstring[]Cost units from the workspace contract register.
statusstringdraft, active, expired, terminated or unknown, as of the day the contract was last folded.
effective_date, expiry_date, notice_deadline, terminated_onstring (date) | nullThe dates in force. expiry_date is the end in force: the printed end rolled forward by auto-renewal, or the termination date when earlier.
auto_renewalboolean | nullWhether the contract renews by itself.
family, title, counterpartystring | nullContract family, title and the other party as the documents state them.
annual_value, currencynumber | null, string | nullAnnual value and its currency.
direction, direction_source, direction_whystring | nullsell, buy or internal; read or rule; and why it holds or why it is null (no_own_party, no_parties, unknown).
documentsintegerNumber of documents folded into the contract.
next_dateobject | nullThe next open key date: id, kind, due_date, label, days_left.
processesobjectopen (count), next_due (date or null) and departments (the departments with an open item).
linksobjectprice_baseline (models, confirmed, model_id) and money_found (direct, estimated, exposure, rows, currency); each is null when the other app reports nothing for the contract.

cURL: Terminated contracts of one counterparty

curl "https://api.talonic.com/v1/contracts?status=terminated&q=musterstadt" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

The 360 View

GET /v1/contracts/{id} returns everything the platform knows about one contract. contract is the folded record; its terms object maps each canonical field name to a value with document_id and quote. not_maintained marks a field that is deliberately empty, and computed marks a value the fold derived from another term (the cited document then states that other term, not this one). documents lists the contract's documents in fold order, each with its role, whether it is excluded, the key a person gave it, and the terms read from it.

Around the contract the view carries its working surface: issues (open problems with the documents concerned), document_history (the edit history per document, newest first, at most 20 entries each), related_documents (letters, e-mails and protocols that are not read for terms), captured (what the workspace's active data products captured from the contract's documents; a value held for review is returned as status only), key_dates, processes, links, the current decision, the decision history (newest first, at most 50 entries) and term_fields, the term vocabulary with each field's value type.

GET/v1/contracts/{id}

Path parameters

id*string (uuid)The contract id from the register.

Response fields

contractobjectThe folded contract: id, contract_key, key_source, title, counterparty, status, dates, terms, obligations, fingerprint, computed_on.
documents[]arrayDocuments in fold order: id (the rowId of the document routes), document_id, filename, role, excluded, key_override, extracted, extract.
issues[]arrayOpen issues: code, detail, document_ids.
document_historyobjectEdit history per document id; documents without history are absent.
related_documents[]arrayDocuments not read for terms, with how they were linked: via record or number.
captured[]arrayPer active data product: columns and the values captured per document, each with status and confidence.
key_dates[], processes[]arrayThe contract's key dates and process items, each with its handled state.
linksobjectThe Price Baseline and Money Found summary plus items[] with the app, reference, label, status, amount and exposure.
decision, historyobject | null, arrayThe person's current decision and the decision history.
term_fieldsobjectTerm vocabulary: field name to string, number, date or boolean.

Response: A term with its source (excerpt)

{
  "contract": {
    "id": "6f1c2a9e-1d4b-4a7e-9c33-2b8a5e0d7f11",
    "contract_key": "1043020-WLV",
    "key_source": "filename",
    "status": "active",
    "expiry_date": "2026-12-31",
    "printed_expiry": "2025-12-31",
    "terms": {
      "notice_months": {
        "value": 6,
        "document_id": "0b7d3c1e-5f2a-4c68-8a19-7e4d9b2c6a30",
        "quote": "Die Kuendigungsfrist betraegt sechs Monate zum Vertragsende."
      },
      "governing_law": { "value": null, "not_maintained": true }
    },
    "computed_on": "2026-05-06"
  },
  "documents": [
    { "id": "d2a8e1f4-9b3c-4d57-a6e0-1c5f8b7a2d93", "document_id": "0b7d3c1e-5f2a-4c68-8a19-7e4d9b2c6a30", "filename": "1043020-WLV_Vertrag.pdf", "role": "master", "excluded": false, "extracted": true }
  ],
  "issues": [],
  "decision": null
}
The term vocabulary is fixed: title, counterparty, our_party, our_side, family, site, signed_date, effective_date, service_start, expiry_date, initial_term_months, auto_renewal, renewal_term_months, notice_days, notice_months, terminated_on, annual_value, currency, escalation_pct, escalation_date, min_commitment, cap_amount, payment_terms_days, governing_law and is_draft.

printed_expiry appears when auto-renewal moved the end in force past the printed end. The fold rolls an auto-renewing contract forward to the first term whose notice deadline is still ahead: a missed deadline counts as a renewal, not as a date to meet. A termination contributes its end, never a new start.

Frequently asked questions

Is the contract register paginated?+
No. GET /v1/contracts returns every matching contract in one response, ordered by counterparty and then contract key. Use q, status or key to narrow it.
What does direction null mean?+
The documents name no company of the workspace, so the platform cannot say whether the workspace sells or buys under the contract. direction_why gives the reason: no_own_party, no_parties or unknown. The cleaning worklist lists such contracts under the no_own_party issue.
Why is expiry_date later than the date printed in the contract?+
expiry_date is the end in force. For an auto-renewing contract the printed end is rolled forward to the first term whose notice deadline is still ahead, and printed_expiry then holds the original printed end. A termination can make the end in force earlier than the printed end.
What does a null value with not_maintained true mean?+
A person answered not maintained for that field: it is deliberately empty in the contract and in the ERP. No live document states it. It is not an extraction failure.

Related

Contracts Overview
Key Dates
Corrections and Decisions
Cleaning and Key Rules