Setup and Sync

Check read progress, choose the data products and the party field map, get field suggestions with samples, and start a background sync through /v1/parties.

Setup tells the app which data products hold the contracts and which of their fields describe parties. The app reads every active assembled data product of the workspace; the settings hold that list and the field map, which names, per data product, the meaning of each party field: a role (partner, our_party, manager, tenant, previous_owner, new_owner, contact or invoice_recipient) and an attribute (name, first_name, last_name, company_name, salutation, street, postcode, town, postcode_town, address, email, phone or kind: a customer-type field such as Privatkunde / Firmenkunde / WEG that sets whether the party is a person, a company or an association of owners).

Status

GET /v1/parties/status reports whether the workspace has data products to read, whether the first fill is still under way, row and read counts, party counts and the products whose party fields could not be read. A workspace that has not added the app answers configured: false when it has no stored settings, and the call enrolls nothing, which makes it a safe probe.

{
  "configured": true,
  "first_fill": false,
  "syncing": false,
  "finding_fields": false,
  "setup_errors": [],
  "products": [{ "id": "3b9e5a14-7c20-4d6f-8a31-0f2d9c7e4b58", "name": "Contract Dataset", "rows": 1000 }],
  "rows": 1000,
  "rows_read": 1000,
  "reads": { "pending": 0, "running": 0, "done": 12, "failed": 0 },
  "parties": 842,
  "needs_attention": 37,
  "synced_at": "2026-06-01T06:15:00.000Z"
}

Settings

GET /v1/parties/settings returns the assembled data products whose rows are the contracts and which of their fields hold party details: data_product_ids, field_map, products, field_errors (per product, why its party fields could not be found), synced_at and ready_at (when the first fill finished). configured is true once the workspace has a data product that assembles contracts.

PUT /v1/parties/settings stores the data products and starts a sync in the background. With field_map the map is stored as given: unknown roles, attributes and fields are dropped, and a product named with no fields means "no party fields". Without field_map the platform finds the party fields itself and the products keep the map they had. Products no longer listed lose their rows and the suggestions on them; a person's decisions stay. The workspace must have added the app first.

curl -X PUT "https://api.talonic.com/v1/parties/settings" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data_product_ids": ["3b9e5a14-7c20-4d6f-8a31-0f2d9c7e4b58"],
    "field_map": {
      "3b9e5a14-7c20-4d6f-8a31-0f2d9c7e4b58": {
        "vertragspartner": { "role": "partner", "attribute": "name" },
        "verwalter": { "role": "manager", "attribute": "name" }
      }
    }
  }'

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "error": "Not Found",
  "message": "This workspace has not added the app 'parties'. Add it in Apps, Add app, or with POST /v1/apps and slug \"parties\".",
  "retryable": false,
  "timestamp": "2026-06-01T08:00:00.000Z",
  "path": "/v1/parties/settings"
}

Field Suggestions

GET /v1/parties/settings/suggest?product_ids= returns, per product, every field with a few sample values and the meaning the saved map or the field name suggests. The samples respect the Sources visibility rules of the key's minting user. A saved map wins over suggestions, and a field name needs a role word (such as vertragspartner, kunde, verwalter, mieter, eigentuemer) to be suggested; a field without one has suggestion: null. Use it to build the field_map for the settings route.

Sync

POST /v1/parties/sync starts a sync in the background and returns 201 with started: true at once; GET /v1/parties/status reports progress. The sync registers every row, fills each from its mapped fields, the Field Registry and the Contracts app, with no model call, and queues reads when background reads are enabled. One sync runs per workspace at a time, and a request made while one runs does nothing further. row_ids (up to 5000 data product record ids) limits the sync to those rows.