Documents and Import

Find contract and invoice documents, list contract documents that have no price model yet, queue them for background extraction, and poll the import queue.

Four routes prepare the ground for a price model. GET /v1/price-baseline/documents is the picker for contracts and invoices: it finds workspace documents by filename. GET /v1/price-baseline/import/candidates lists the documents that look like contract price documents and have no model yet, grouped by contract number. POST /v1/price-baseline/import queues documents for extraction, and GET /v1/price-baseline/import/status reports the queue. Together they are the bulk path from a document store to a set of price models.

Single extraction (POST /v1/price-baseline/models) runs the extraction model inside the request. The import queue does the same work in the background: a scheduler extracts the price models of queued documents, so a workspace can queue hundreds of documents with one call and poll for the outcome. The queue holds one entry per document with a status of pending, running, done or failed.

Candidates are workspace documents that look like contract price documents: a supply, lease, service or maintenance contract, an amendment, a price sheet. Invoices and letters are left out, and up to 2000 documents are considered. Each candidate carries a kind of contract, amendment or price_sheet, and groups form by the contract number the filename carries. Documents without a number form a group with a null contract_key, listed last.

{
  "data": [
    {
      "id": "3f6c1d2e-8a41-4c57-9b0e-2d7a5c1e9f10",
      "filename": "Waermeliefervertrag_4711.pdf",
      "created_at": "2025-03-11T09:14:22.000Z"
    }
  ]
}

curl -X POST "https://api.talonic.com/v1/price-baseline/import" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["3f6c1d2e-8a41-4c57-9b0e-2d7a5c1e9f10", "8d20b6c4-17fe-4a93-b5c8-6e1f0a9d3c72"]}'

{
  "counts": { "pending": 12, "running": 3, "done": 140, "failed": 1 },
  "failed": [
    {
      "document_id": "8d20b6c4-17fe-4a93-b5c8-6e1f0a9d3c72",
      "filename": "Preisblatt_2024.pdf",
      "error": "The extraction model returned no price components.",
      "attempts": 2
    }
  ]
}