Party Register

List contract partners with their roles and open problems, create and edit parties, and read one party with its letters, contracts, documents and duplicates.

GET /v1/parties lists the parties the key's minting user may see: a party holding a role on a visible row, or one that user created and that has no role yet. By default the register lists contract partners, meaning parties holding the partner or our_party role, or no role yet. Every other entity (a Verwalter, a tenant, an owner, a contact) appears with scope=all. The list is sorted by display name.

Each entry is a party with three additions: contracts (the contract rows the party holds a non-rejected role on), roles (the role names it holds) and issues (the problems that name the party, plus one when the party has a duplicate candidate). total counts the parties matching the filters before limit, and needs_attention counts the parties in scope, before the other filters, that need a person. attention=true (or 1) keeps only those; any other value applies no filter.

curl "https://api.talonic.com/v1/parties?kind=company&attention=true&limit=50" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

{
  "total": 1,
  "needs_attention": 37,
  "data": [
    {
      "id": "e5a3c7b1-2d94-4f08-b6a2-81c0d9e47f35",
      "kind": "company",
      "display_name": "Stadtwerke Musterstadt GmbH",
      "name_key": "stadtwerke musterstadt gmbh",
      "legal_form": "GmbH",
      "street": "Hauptstrasse 12",
      "postcode": "12345",
      "town": "Musterstadt",
      "status": "active",
      "source": "capture",
      "contracts": 14,
      "roles": ["partner"],
      "issues": 1
    }
  ]
}

Creating and Editing Parties

POST /v1/parties creates a party from the given details. display_name is required; when kind is omitted it is inferred from the name (a legal form makes a company, WEG an owners' association). A party created this way is visible only to its creator until it holds a role on a contract the reader may see. PATCH /v1/parties/{id} changes the given details; every field is optional on an edit.

Changing display_name recomputes name_key, the normalized name used to match documents, the register and duplicates. A party renamed by hand stops matching its old spelling, so the next sync can create a duplicate candidate for the old spelling. Rename deliberately, and merge the duplicate afterwards if one appears.

One Party in Full

GET /v1/parties/{id} returns the party with letters (where its letters go and why), contracts (its rows, each with the party's own roles, the other parties' roles, the computed view and the row's problems), documents (with the quotes that support its roles), members and member_of (contacts), duplicates (merge candidates) and issues. product_id restricts the contracts to one data product.

letters.reason_code explains the address: self (the party is written to directly), manager (through its Verwalter), owner_while_tenant, or is_manager. letters.assumption is weg_via_manager when the platform assumed an owners' association is written to through its Verwalter. A party that was merged into another answers with merged_into and empty lists when the reader may see the survivor.

{
  "party": { "id": "e5a3c7b1-2d94-4f08-b6a2-81c0d9e47f35", "display_name": "Eigentuemergemeinschaft Gartenweg 4", "kind": "owners_association" },
  "letters": {
    "party_id": "e5a3c7b1-2d94-4f08-b6a2-81c0d9e47f35",
    "display_name": "Eigentuemergemeinschaft Gartenweg 4",
    "address_lines": ["Hausverwaltung Nord GmbH", "Marktplatz 1", "12345 Musterstadt"],
    "reason_code": "manager",
    "reason": "Letters go to the Verwalter of the owners' association.",
    "via": "Hausverwaltung Nord GmbH",
    "assumption": "weg_via_manager"
  },
  "duplicates": [],
  "issues": []
}