Skip to main content
Update an alert: edit, confirm, mark as false alarm, skip, move back to review, add to a claim, move to another topic

Authorizations

Authorization
string
header
required

Personal API key sent as a bearer token, together with X-Organization-Id. The key must have at least the access level the endpoint requires (read, write or admin).

Headers

X-Organization-Id
string

The organization to act in. Required for personal API keys; list the organizations you can access with GET /v1/organizations.

Path Parameters

id
string<uuid>
required

Body

application/json
citations
object

Changes to the alert's citations, by source_ref: upsert edits a citation's fields, or points the reference at an existing citation by id or a new one; remove drops references.

title
string
Required string length: 1 - 500
explanation
string | null
Maximum string length: 20000
questions
string[]
Maximum array length: 50
Maximum string length: 2000
impact_amount
string | null

The remaining impact in the invoice currency after assessed credits. Positive means still owed. Pricing edits leave it unchanged; send impact_amount explicitly to change it.

Maximum string length: 100
Pattern: ^-?\d+(?:\.\d+)?$
confidence
object
expected
object
verdict
enum<string>

Whether the finding is right. pending: still to review. accepted: confirmed, the deviation is real (also when it is too small to pursue or already handled). dismissed: a false alarm, Watchdog was wrong; requires dismissal with a category. skipped (shown as Unsure): nobody can or will judge it; it leaves review without teaching anything. Claim membership and credit are not changed. Leaving dismissed takes the dismissal off the alert; it stays in the history.

Available options:
pending,
accepted,
dismissed,
skipped
dismissal
object

Why the alerts are false alarms. Required with verdict dismissed, and only valid with it. Sending a different reason for an already dismissed alert replaces its reason.

suggest_instructions
boolean

Whether the false alarm should start a run that suggests changes to the agreement's instructions, so later checks avoid the mistake. Defaults to true. Send false when the note explains a cleanup rather than a rule for future checks. Only valid with verdict dismissed; it is not stored on the alert.

claim_id
string<uuid> | null

Put the alerts in this pending or in-progress claim of their agreement, or null to take them out of their claim. Verdicts are not changed: send verdict accepted to accept them too. Alerts move out of a cancelled claim; out of another open claim only with move_from_open_claims. Alerts in completed claims cannot be changed. POST /v1/claims/alerts/preview says first which alerts would join and why the others would not.

move_from_open_claims
boolean

Move alerts out of other pending or in-progress claims. Only valid with a claim_id.

topic_id
string<uuid> | null

Move the alerts into this topic of their agreement, out of any other topic, or null to take them out of their topic. Categorization may later place an alert without a topic in one again.

Response

The alert.

id
string<uuid>
required
check_type
enum<string>
required

The type of invoice check the alert belongs to. Alerts of an agreement check have an agreement, alerts of a purchase-order check a purchase order; never both; duplicate alerts neither.

Available options:
agreement,
purchase_order,
duplicate
code
enum<string> | null
required

The named finding of a purchase-order check (unit_price, quantity, received: billed above what was received, vat_rate: a higher VAT rate than the order line states, unordered_charge, unbilled_discount: an order discount the invoices leave out, amount_limit: the order's running total, uncertain) or duplicate check (different_total, different_date: another invoice of the supplier with the same number; other_company: the same number, date and total received by another of the workspace's companies); the explanation says what it found. Null on agreement alerts.

Available options:
unit_price,
quantity,
received,
vat_rate,
unordered_charge,
unbilled_discount,
amount_limit,
uncertain,
different_total,
different_date,
other_company,
null
details
object
required

A purchase-order finding's compared values, one shape per code; price and quantity findings also fill expected and invoiced. A duplicate finding's other invoice_id. Null on agreement alerts, whose explanation names the values, and on a duplicate alert whose other invoice you cannot see.

title
string | null
required
explanation
string | null
required
verdict
enum<string>
required

Whether the finding is right: pending (still to review), accepted (confirmed), dismissed (a false alarm) or skipped (unsure). Independent of claim membership and credit.

Available options:
pending,
accepted,
dismissed,
skipped
credit
object | null
required

Set while a matched credit note fully reverses the invoice; it cannot be set by hand. Independent of the verdict and claim.

correction_type
enum<string>
required
Available options:
modify_item,
modify_invoice,
add_item
confidence
object
required
questions
string[]
required

What Watchdog needs answered to decide the alert, mostly on uncertain alerts. Empty when nothing is open.

impact_amount
string | null
required

The remaining impact in the invoice currency, after credit notes assessed by the check. Expected pricing stays at the agreement terms. Pricing edits preserve impact unless it is explicitly changed.

Pattern: ^-?\d+(?:\.\d+)?$
currency_code
string
required
organization_currency
object
required

The impact converted with the rate stored on the alert.

invalidation
object | null
required

Set when the alert no longer counts. unmatched: its invoice no longer matches the agreement; excluded: a person excluded the invoice from it. Both count again once it matches again. replaced: a re-check of its pair replaced it with new alerts; it stays for reference. It keeps its verdict, credit and claim either way.

invoice
object | null
required
invoice_item
object | null
required
read-only

The current invoice line. Null when no line is linked.

agreement
object | null
required

The agreement the alert was found against. Null when you cannot see it, or when the alert belongs to a check type without an agreement.

purchase_order
object | null
required

The purchase order a purchase-order check found the alert against. Never the agreement that order is linked to.

supplier
object | null
required
recipient
object | null
required
topic
object | null
required
claim
object | null
required

The claim this alert is currently attached to, if any.

dismissal
object | null
required

Why the alert is a false alarm, while its verdict is dismissed, credited or not; dismissed_by is null when no person is recorded. Dismiss it again with a different category or note to change the reason. Any other verdict clears it; the alert activity keeps the history.

provenance
object
required

Who or what created the alert, and from which agreement version and check.

correction_relationships
object[]
required

Links between an added-item alert and the line alerts it replaces.

Maximum array length: 100
correction_relationships_truncated
boolean
required
created_at
string<date-time>
required
updated_at
string<date-time>
required
price_item_ids
string<uuid>[]
required

Agreement prices the alert relies on. Read them with GET /v1/agreements/{id}/price-items?ids=. Empty when you cannot see the agreement.

expected
object
required

The pricing the check's baseline gives for this line: the agreement's, as the check applied it, or the purchase order line's net price and ordered quantity. base_price is the agreed unit price before discount and surcharge; price_explanation says where it comes from. Every field of an agreement alert is null when you cannot see its agreement; a purchase-order alert is visible only with its order.

invoiced
object
required
read-only

Invoiced pricing when the alert was created.

evidence
object
required