Skip to main content
Create an alert

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.

Idempotency-Key
string

Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request.

Required string length: 1 - 200
Pattern: ^[\x21-\x7e]+$

Body

application/json
invoice_id
string<uuid>
required
agreement_id
string<uuid>
required

The agreement the finding is about. The invoice must be matched to it.

title
string
required
Required string length: 1 - 500
invoice_item_id
string<uuid> | null

The invoice line the finding is about. Required for modify_item, and only then.

correction_type
enum<string>

modify_item: a billed line is wrong. add_item: a line is missing. modify_invoice: the finding concerns the whole invoice. Defaults to modify_item with an invoice_item_id and modify_invoice without.

Available options:
modify_item,
modify_invoice,
add_item
explanation
string | null
Maximum string length: 20000
impact_amount
string | null

The amount the invoice is wrong by, in the invoice currency: positive when it charges more than agreed. Omit it on a line or missing-line alert to calculate it from expected pricing; an invoice-level alert has no line to compare with, so send it there.

Maximum string length: 100
Pattern: ^-?\d+(?:\.\d+)?$
confidence
object
questions
string[]
Maximum array length: 50
Maximum string length: 2000
expected
object
citations
object[]

Sources for the finding, numbered by source_ref. Inline markers such as [1] in the text refer to them. Each citation is a new source or an existing citation id.

Maximum array length: 100
topic_id
string<uuid> | null

A topic of the same agreement to put the alert in. Without one, the agreement's topics are reconciled so the alert gets grouped.

Response

The alert.

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

The decision on the finding, independent of claim membership and credit.

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

Supplier credit, independent of the verdict and claim.

correction_type
enum<string>
required
Available options:
modify_item,
modify_invoice,
add_item
confidence
object
required
impact_amount
string | null
required
Pattern: ^-?\d+(?:\.\d+)?$
currency_code
string
required
organization_currency
object
required

The impact converted with the rate stored on the alert.

freshness
enum<string>
required
Available options:
current,
outdated,
unknown
invalidation
object | null
required

Set when the alert no longer counts, for example because its invoice no longer matches the agreement. It keeps its verdict, credit and claim, and counts again if the invoice matches again.

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
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 was dismissed, while its verdict is dismissed, credited or not. Dismiss it again with a different category or note to change the reason. Reopening or accepting clears it; the alert activity keeps the history.

provenance
object
required
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
questions
string[]
required
price_item_ids
string<uuid>[]
required

Agreement prices the alert relies on. Read them with GET /v1/agreements/{id}/price-items?ids=.

expected
object
required
invoiced
object
required
read-only

Invoiced pricing when the alert was created.

evidence
object
required