Skip to main content

Contract Processes

List the process items contract data starts for sales, billing, legal and other departments, read the process catalogue, and mark an item handled by key.

Contract data starts work in other departments: a price that must be fixed before commissioning, billing that waits for the commissioning protocol, the renewal window as the ERP keeps it, the chain of easements. The platform expresses each such obligation as a process rule and evaluates the rules over every contract. A rule that fires produces a process item for one department, with a phase, a kind, a due date (or none) and the evidence it rests on, each piece of evidence carrying the document it came from.

A rule fires only when the fields it reads were captured or are present in the contract register; a rule whose fields are absent never fires. Rules draw on four sources: captured Spec fields (spec), the ERP contract register (register), a document type (document) and a Money Found finding (money_found). A contract that the fold or the ERP has ended keeps only the rules that apply after the end. A lead time that was missed is due today, never silently in the past.

GET/v1/contracts/processes

Query parameters

departmentstringOnly this department: sales, billing, legal, operations, property, contract_management, procurement or controlling. An unknown value is ignored.
daysintegerHorizon for dated items, 1 to 3650. The configured process horizon (180 by default) when omitted or not an integer; other values are clamped.
contract_idstring (uuid)Only this contract.

Entry fields (data[])

idstring (uuid)The process item id; pass it to POST /v1/contracts/processes/{processId}.
contract_id, contract_key, title, counterpartystringThe contract the item belongs to.
rule_idstringThe rule that produced the item.
departmentstringThe department the item is for.
phasestringsigning, construction, commissioning, supply, notice or end.
kindstringdeadline, event, ingest or backlog.
due_date, days_leftstring (date) | null, integer | nullNull when the data names no date.
evidence[]arrayThe fields the item rests on: field, value, document_id and labels (en and de human labels; the field key is shown when both are absent).

cURL: Billing items due within 60 days

curl "https://api.talonic.com/v1/contracts/processes?department=billing&days=60" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response: A process item with evidence

{
  "data": [
    {
      "id": "c90b3e55-27d1-4a6f-8e4c-5a1d7f0b9c22",
      "contract_id": "6f1c2a9e-1d4b-4a7e-9c33-2b8a5e0d7f11",
      "contract_key": "1043020-WLV",
      "title": "Waermelieferungsvertrag",
      "counterparty": "Stadtwerke Musterstadt GmbH",
      "rule_id": "billing_gate_commissioning",
      "department": "billing",
      "phase": "commissioning",
      "kind": "event",
      "due_date": "2026-07-15",
      "days_left": 40,
      "evidence": [
        {
          "field": "inbetriebnahme_protokoll",
          "value": "ausstehend",
          "document_id": "0b7d3c1e-5f2a-4c68-8a19-7e4d9b2c6a30",
          "labels": { "en": "Commissioning protocol", "de": "Inbetriebnahmeprotokoll" }
        }
      ]
    }
  ]
}

The Process Catalogue

GET /v1/contracts/process-rules returns every process rule in catalogue order with its department, phase, kind, source and the field keys it reads. no is the display order in the catalogue. Read the catalogue to learn which fields a department's items depend on, for example before capturing a field that a rule needs.

GET/v1/contracts/process-rules

Entry fields (data[])

idstringThe rule id.
nointegerDisplay order in the catalogue.
department, phase, kindstringAs on process items.
sourcestringspec, register, document or money_found.
fieldsstring[]The field keys the rule can put into evidence.

Marking an Item Handled

POST /v1/contracts/processes/{processId} records that a process item is handled (handled: true) or open (handled: false) as the calling key. The decision is keyed on contract, rule and due date, so a process whose deadline moves opens again, and a process that is rebuilt with the same due date stays handled. The response is 201 with the item id and its handled state.

POST/v1/contracts/processes/{processId}

Body fields

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

cURL: Mark a process item handled

curl -X POST "https://api.talonic.com/v1/contracts/processes/c90b3e55-27d1-4a6f-8e4c-5a1d7f0b9c22" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handled": true, "note": "Invoice released after protocol of 2026-07-10"}'
The same items appear inside the 360 view of a contract (processes) and as a summary in the register (processes.open, processes.next_due, processes.departments). Use the list route for a department-wide queue and the 360 view for the items of one contract.

Frequently asked questions

Why does a department see no process items for a contract?+
A process rule fires only when the fields it reads are captured or present in the contract register. If the fields are absent the rule never fires, and no register rule fires without a bound contract register. Read GET /v1/contracts/process-rules to see which fields a rule needs.
What happens to a handled item when the deadline moves?+
It opens again. The decision is keyed on contract, rule and due date, so a new due date is a new decision key. An item that is rebuilt with the same due date stays handled.
What horizon applies to dated items?+
The configured process horizon, 180 days by default, when days is omitted or is not an integer. Values outside 1 to 3650 are clamped. Undated items are always listed, after the dated ones.

Related

Contracts Overview
Key Dates
Contract Register and 360 View