Skip to main content

Contract Party Management Overview

Keep every party behind your contracts as one entity with its roles, periods and evidence, and resolve the partner and addressee on any day through /v1/parties.

Every endpoint on this page answers 404 in a workspace that has not added the Contract Party Management app (catalog slug parties). Add it from the Apps catalog or with POST /v1/apps and slug parties; GET /v1/apps lists the apps a workspace has added.

The Contract Party Management API exposes the Contract Party Management app, catalog slug parties. The app keeps every party behind the workspace's contracts as one entity: a person, a married couple, a company or an owners' association. Each party carries its details and the roles it holds on each contract, and each role carries its period and the evidence it rests on. A workspace uses these endpoints after adding the app; GET /v1/apps lists a workspace's apps by slug.

A contract is a row of an assembled data product. Parties are not read from a separate document store: they come from the row's mapped fields, from the Field Registry, from the Contracts app's filing and from the contract register. The model reads a contract's documents only on request. The roles a party can hold are partner (the party the contract is signed with), our_party (the workspace's own side), manager (a Verwalter acting for another party), tenant, previous_owner, new_owner, contact and invoice_recipient.

Every source only suggests. A role has a state of suggested, confirmed or rejected; a role a person confirmed or rejected is never overwritten by a later fill, and a rejected role is never suggested again. Any edit through the API is a decision: an edited suggestion becomes confirmed unless the request says otherwise. Evidence is kept per role, and its kinds are document (a verbatim quote, with verified stating whether the quote occurs in the named document), reference (a row of the contract register), capture (a data product field), registry (a Field Registry value), contract (the Contracts app) and person.

From the roles the app computes one answer to "who is this contract with, and to whom does a letter go" on any day. The effective partner is a tenant who enters the contract while the tenant's period covers the day, else the partner. The addressee is the effective partner's Verwalter when it has one, else the effective partner. The owner addressee is the owner, reached through the Verwalter when there is one. Consumers read this one computed view and do not re-derive it.

Reads need the read scope. Writes need the write scope and the key's person must be a member or above in the workspace. Rows and parties follow the Sources visibility rules of the key's minting user: a row is visible when that user may see one of its documents, and a party when it holds a role on a visible row. Decisions made with a key are recorded as api:<key id>.

Worked Example: From Setup to a Confirmed Partner

First check where the workspace stands. GET /v1/parties/status reports whether the app is configured, whether the first fill is under way and how many rows, reads and parties exist. It is safe to call in any workspace: a workspace that has not added the app answers configured: false and the call enrolls nothing.

cURL: 1. Read the status

curl "https://api.talonic.com/v1/parties/status" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Then list the contract partners that need a person, open the computed view of one contract row, and confirm a suggested role. A row is addressed by the data product id and the data product record id, which is text and not necessarily a UUID.

cURL: 2. Find partners that need attention, read a row, confirm a role

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

curl "https://api.talonic.com/v1/parties/rows/$PRODUCT_ID/$ROW_ID?on=2026-06-01" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

curl -X PATCH "https://api.talonic.com/v1/parties/roles/$ROLE_ID" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "confirmed", "note": "Checked against the signed contract"}'

The surface splits into five groups: setup and sync, the register of parties, the roles on a contract row, merging and contacts, and the workspace's own group companies.

Reading the status or the settings never enrolls a workspace: only adding the app does.

Frequently asked questions

What is a contract in Contract Party Management?+
A row of an assembled data product. The app reads every active assembled product of the workspace; nobody chooses which. A row is addressed by the data product id and the data product record id, which is text and not necessarily a UUID.
Does the app call a model to find parties?+
Not by default. Parties are filled from the row's mapped fields, the Field Registry values of its documents, the Contracts app's filing and the contract register, without a model call. The model reads a contract's documents only when POST /v1/parties/rows/{productId}/{rowId}/read is called, and that read costs a model call.
Can a sync overwrite my decisions?+
No. Every source only suggests. A confirmed or rejected role keeps its state and fields, a fill never re-creates a rejected role, and parties are matched by name but never merged on their own.
Which parties appear in the register?+
By default the contract partners: parties holding the partner or our_party role, or no role yet. Every other entity, such as a Verwalter, a tenant, an owner or a contact, appears with scope=all.

Related

Setup and Sync
Party Register
Contract Rows and Roles
Apps Overview
Authentication