Skip to main content
Alerts are stored findings. Reading or editing an alert does not start a new check.

​
Find the alerts you need

All retained alerts are included by default. The list, metrics, groups, export, and bulk commands share one set of filters, so what you count is what you act on:
  • Resources: invoice_ids, agreement_ids, supplier_ids, recipient_ids, tag_ids, topic_ids, claim_ids, each with an excluded_…_ids counterpart where exclusion is useful. topic_ids=null selects uncategorized alerts and claim_ids=null alerts in no claim; combine them, as in topic_ids=TOPIC_ID,null.
  • Values: statuses, claim_statuses, confidence_levels (high, mid, low, null), correction_types, currency_codes, freshness.
  • Ranges: impact_min/impact_max on the organization-currency impact, issued_from/issued_through for the invoice date, and created_from/created_through as calendar dates in your organization’s timezone.
  • search matches alert, invoice, line, supplier, agreement, and topic text.
Sort alerts by created_at (default), impact_amount (organization currency), issued_date, invoice_number, supplier, or status. Each alert carries its confidence, the impact in its own currency and in your organization’s currency, the invoice with its dates and total, the invoice line, the agreement and its current version, the topic and whether it is locked, the current claim, and links to the alerts it replaces or is replaced by. Groups return the same totals per agreement, invoice, topic, claim, status, or freshness, sorted by impact, count, or title. Each group’s key is the value to put in that dimension’s filter, so a group expands into its alerts or into subgroups with one more request. GET /v1/alert-topics includes empty topics. GET /v1/alerts/export?format=csv or format=xlsx downloads the matching alerts; XLSX adds a Topics sheet. GET /v1/compliance-checks/{id}/transcript shows the tool calls and final summary of the check behind an alert (provenance.retained_check). Write null as the string null, in query strings and in JSON selection bodies alike. New alerts join topics when the agreement’s alert_topic_reconciliation workflow run completes. A compliance check requests one for each agreement whose check completed; if that request fails, the check is unaffected and the next one requests again. POST /v1/agreements/{id}/alert-topics/reconcile requests one explicitly and returns its workflow_run_id: 202 when a run starts, 200 when one is already queued or running. Responses use data and next_cursor. Keep the same filters and sort when requesting the next page. Amounts are decimal strings. Individual unknown impacts remain null. Aggregate totals treat null impacts as zero and include a missing amount count. Invoice fingerprints start tracking on the first evidence edit. A null current invoice fingerprint does not invalidate an existing check; missing assessment provenance remains unknown.

​
Edit an alert

Fetch GET /v1/alerts/{id}, then send the returned ETag in If-Match:
Send only changed fields. Omitted fields stay unchanged. Prices and quantities use decimal strings; rates use fractions. Derived amounts are recalculated. A 412 response means the alert changed: fetch it again and review the changes before retrying. Narrative and citation changes save together. GET and PATCH use the same expected object for proposed line details, pricing inputs, and explanations. Supplying one nested field preserves the others. expected.net_price and expected.total are calculated and read-only. GET also includes read-only invoiced pricing captured at alert creation and an invoice_item with the linked line’s ID, product code, description, and unit. These line details reflect the current invoice; invoice_item is null when no accessible line is linked. Use POST /v1/alerts/{id}/dismiss with {} or a category and note to dismiss an alert while keeping its claim attachment. Use POST /v1/alerts/{id}/credit without a body to record that the supplier has credited the finding. Use POST /v1/alerts/{id}/reopen without a body to set an alert back to pending. A member of an active claim stays attached; a member of a cancelled claim is released. Repeated commands are no-ops. Alerts in completed claims cannot be changed. A dismissal with a category or note may teach Watchdog something about the agreement. It starts an agreement_context_suggestions workflow run that can propose edits to the agreement’s instructions; review them with agreement context suggestions. The dismissal does not wait for the run.

​
Act on many alerts

POST /v1/alerts/dismiss, /credit, and /reopen apply the same commands to a selection. Send either alert_ids or a filter that uses the alert list filters as JSON lists and booleans, with optional excluded_alert_ids:
Each command is one transaction, changes at most 5000 alerts, and returns changed_count and skipped_count. With alert_ids, an unknown alert returns 404 and an alert in a completed claim returns 409. With a filter, such alerts are left alone and counted in skipped_count. A filter also never dismisses or reopens a credited alert; select it with alert_ids instead. The filter must name agreement_ids, invoice_ids, or topic_ids or claim_ids without null. Count a selection with the metrics endpoint first: a dismissal of pending and claimed alerts leaves members of completed claims unchanged, and statuses=pending,claimed&claim_statuses=completed counts those. Alerts already in the requested state are left alone, so a retry is safe. The claim membership commands and POST /v1/alert-topics/{id}/alerts take the same selection.

​
Edit topics

PATCH /v1/alert-topics/{id} edits title, description (Markdown), and key_questions. POST /v1/alert-topics/{id}/lock protects a topic from automatic categorization and edits; /unlock reverses it. POST /v1/alert-topics/{id}/alerts moves the selected alerts into the topic. POST /v1/alert-topics/{id}/recheck checks the topic’s invoices again; see recheck a topic. GET /v1/alert-topics/{id} includes the topic’s sources under evidence, by the numbers its inline markers such as [1] use. To merge or split topics, request a proposal, review it, then apply it:
The proposal is prepared by a workflow run; its completed item result holds proposal_id. GET /v1/alert-topic-proposals/{id} shows the proposed topics and which alert groups go where. POST /v1/alert-topic-proposals/{id}/apply with {} applies it as proposed; you can also edit the proposed titles, descriptions and questions and, for a split, move groups between the new topics. Applying creates the new topics and deletes the selected ones in one step. It works once, and only if the agreement’s topics have not changed since the proposal was prepared; otherwise it returns 409 and you request a new proposal. Locked topics cannot be merged or split. A proposal run that cannot produce a proposal fails its item with a code such as topic_locked (a selected topic, or one holding alerts replaced together with the selection, is locked), not_splittable (the selection has fewer than two alert groups), stale_input (the selected topics changed or were removed first) or proposal_failed, besides the workflow codes dispatch_failed, admission_expired and execution_incomplete.

​
Change supporting citations

Use explicit upsert and remove operations in the alert PATCH. Existing citations accept partial field changes. Those changes update the shared citation in every linked alert and topic. A new reference needs a citation selector:
Citations also support web URLs, agreement item IDs, and supplied context. To reuse an existing citation without editing it, supply "citation": { "id": "CITATION_UUID" }, using citation_id from a read. A selector cannot be combined with outer field edits. Supplying a new citation changes only this alert’s link; changing fields without a selector edits the shared row everywhere. Citation and document IDs must belong to your organization, and items must belong to the alert’s agreement. Shared edits fail if any linked use is protected by a claim or locked topic. Verification is server-owned. Document edits are re-verified against stored text; unmatched or unavailable evidence remains visible and unverified. Saving does not fetch external material, extract documents, invoke models, or run compliance checks. Assessment freshness stays unchanged. Omitted citations and fields stay unchanged. When removing references, update all affected inline markers in the same request. Duplicate or missing references fail without saving any changes. GET /v1/alerts/{id} returns every citation under evidence. Excerpts are bounded to 10,000 characters, and truncated indicates a shortened excerpt. Send only the fields you deliberately changed; never replace citations from a shortened read. The response ETag can be used for PATCH.

​
Read invoice coverage

Every invoice list item and invoice detail includes alert_summary:
The invoice is fully checked only when every matched, nondeleted agreement has a completed check against current inputs. Status distinguishes not_checkable, checking, not_checked, completed, and incomplete. Reasons preserve missing, failed, cancelled, outdated, and unknown checks; invoice_changed accompanies outdated when the invoice itself changed after a completed check. Zero alerts alone does not establish that checking completed. Use alert_checked, alert_checkable, and has_open_alerts to filter invoices. Invoice metrics provide matching checked/checkable counts and amounts by currency. Dismissed alerts remain in counts. has_credit_note_match records a relationship independently of full credit. is_fully_credited requires one completed, nondeleted credit note uniquely linked to the invoice, with a total including VAT within ±1 currency unit of the invoice total in the same currency. Partial notes are not summed, and a note linked to another invoice does not qualify. Any linked completed, nondeleted credit note makes an invoice uncheckable with reason credit_note_matched. Only qualifying full credit automatically marks findings Credited and enables credited success messaging. Retained links to deleted, unfinished, or reclassified documents do not block checks. financially_valid remains a separate arithmetic result. The generated endpoint references describe all fields, filters, permissions, and error responses.

​
My records and teams

Use mine=true or explicit team_ids to filter by shared team rules. See My records and teams for matching rules, empty results, errors, and pagination.