Skip to main content
Update an invoice, or send, approve, hold, close or mark it paid

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]+$

Path Parameters

id
string<uuid>
required

Body

application/json

At most 2 MiB, including all lines.

supplier
object
recipient
object
category
enum<string>
Available options:
invoice,
credit_note,
self_billed_invoice
invoice_number
string | null
Required string length: 1 - 255
title
string | null
Maximum string length: 2000
issued_date
string | null
Pattern: ^\d{4}-\d{2}-\d{2}$
due_date
string | null
Pattern: ^\d{4}-\d{2}-\d{2}$
amounts
object
payment
object
delivery
object | null
references
object
review
object

Set confirmed to true when a person has checked the extracted data, or false to clear it.

line_item_changes
object
matched_invoice_ids
string<uuid>[]
Maximum array length: 50
expected_updated_at
string<date-time>

Only on a reminder or collection notice, with letter, party, reference, date and payment corrections; a request with totals, lines, category, delivery or matched invoices does not accept it (400). Its updated_at as you reviewed it: when it changed since, nothing is saved (409). Required to replace claims, charges or payments. Approving uses approval.expected_updated_at instead.

letter
object

Corrections to what a reminder or collection notice prints.

send_for_approval
enum<boolean>

Send the invoice from Inbox to Approval and ask its approvers: refused (409) unless lifecycle.status is ready_for_approval (see lifecycle.blockers), and nothing once sent. Watchdog sends a clean arrival itself, so this is for one a person worked on, one with review_issues, or one without approvers, which admins then decide. The AP team and admins send; applied after any correction in the same request.

Available options:
true
approval
object | null

Approve an invoice sent for approval (409 otherwise), also one on hold, ending the hold; approving one already approved changes nothing. null reopens it: an approved or closed invoice, or one in Approval (the AP team and admins only), returns to Inbox as a draft with its approvals cleared. Its approvers approve, admins also one without approvers; its approvers, the AP team and admins reopen. A member who added themselves cannot approve while an approval rule also chose approvers (403); admins can. Approving goes ahead while checks run or failed: read check_progress first. It does not send the invoice to the accounting system: transferInvoice does.

send_back
object

Send an invoice in Approval back to Inbox for the AP team to fix, as one of its approvers: its approvals are cleared, it reads sent_back with the reason, and its approvers are asked again once it is sent again. The AP team and admins pull it back with approval: null instead.

close
object

Close an undecided invoice in Inbox or Approval without payment (lifecycle.status closed); a reopen undoes it. The AP team and admins close; approvers send back instead. Repeating it changes nothing.

hold
object | null

Put an undecided invoice in Approval on hold, or null to take it off; it then awaits its approvers again. Its approvers, the AP team and admins can. Repeating it changes nothing.

paid_mark
object | null

Mark the invoice paid while its accounting system cannot read it (payment.can_mark_paid), or null to take that back. It counts until the system reads the invoice again; while it can, setting one is refused (409). The AP team, admins and its approvers can.

Response

The updated invoice, and what else the change updated.

company_id
string<uuid> | null
required

The invoice's company, its recipient's. Null while no rule placed it: nothing works on it until someone chooses one (setInvoiceCompany).

suggested_company_id
string<uuid> | null
required

For an invoice without a company: the company its printed buyer likely names, for a person to accept with setInvoiceCompany. Never applied by itself; null otherwise.

id
string<uuid>
required
url
string<uri>
required

The invoice in the Watchdog app.

invoice_number
string | null
required
title
string | null
required
category
enum<string>
required
Available options:
invoice,
credit_note,
self_billed_invoice,
reminder,
collection_notice
issued_date
string<date> | null
required
due_date
string<date> | null
required
created_at
string<date-time>
required
updated_at
string<date-time>
required
deleted_at
string<date-time> | null
required
supplier
object
required
recipient
object
required
amounts
object
required
review
object
required
read-only
stage
enum<string> | null
required

Superseded by lifecycle, the invoice's one status; removed once the app no longer reads it. Watchdog's approval flow, from Watchdog's facts only: rejected (closed) or approved as decided, on_hold, needs_approval while it has approvers, else inbox. Null outside the flow (see the invoice's outside_flow).

Available options:
inbox,
needs_approval,
on_hold,
approved,
rejected,
null
outside_flow
enum<string> | null
required

Superseded by lifecycle; removed once the app no longer reads it. Why stage is null: cancelled_in_source (its accounting system cancelled it), or accounting_history (marked as history on arrival; new arrivals qualify through posted rows or a settled source balance, not source approval).

Available options:
cancelled_in_source,
accounting_history,
null
lifecycle
object
required

The invoice's lifecycle, the one status every screen shows. Filter with phase, lifecycle_statuses and actionable; count with GET /v1/invoices/lifecycle-counts.

accounting
object
required

The accounting system's own state of the invoice, apart from Watchdog's approval. Payment is under payment.

overdue
boolean
required

True when it still waits on Watchdog past its due date (Oslo date): its lifecycle.status is in Inbox or Approval, or it is approved and not yet sent (not_ready_to_send, ready_to_send, send_failed). Once it is in the accounting system or done, it is not overdue.

approvers
object[]
required

The people asked to approve the invoice, in the order they were added.

approver_teams
object[]
required

The teams asked to approve the invoice, in the order they were added. Each counts as one approver toward required_approvals.

required_approvals
integer
required

How many approvers must approve the invoice: the organization's approval policy setting, however many approval steps it has. With fewer approvers than this, add more before it can be approved.

Required range: x >= 1
assigning_approvers
boolean
required

Approvers come once it is read, matched to its orders and coded: its orders' invoice approvers, else rules.

policy_approval
enum<string> | null
required

The approval policy decides instead of people: waiting (not evaluated yet, no approvers) or decided. Null when people decide.

Available options:
waiting,
decided,
null
background_runs
object[]
required

The latest run of each background area the invoice has had. Poll check_progress until it is no longer running, then read alerts and checks.

alerts
object
required
checks
object[]
required

One entry per check type, limited to the same scope as alerts.

check_progress
enum<string>
required

Whether the invoice's checks have settled. running: a background run (also one waiting for its sync or batch) or a check is in progress; failed: a background run or a check failed and waits for its automatic retry or a person; settled: neither. Poll it after a change, then read alerts and checks. Approving one invoice is allowed either way and its activity records this; bulk approval skips unsettled invoices.

Available options:
running,
failed,
settled
relationships
object
required
current_step
integer | null
required

The approval step whose turn it is (WD-2901): the first step nobody in it has approved. Approvers of later steps wait their turn. Null once every step has an approval, when any approver who has not approved may, once the invoice is decided, and while it has no approvers.

Required range: x >= 1
letter
object | null
required
payment_handoff
object | null
required

How the newest letter chasing the invoice says to pay it. Null when no letter chases it, and once it is paid: what remains is the letters' own charges, decided on each letter.

amount_owed
object | null
required

Detail only, on an invoice letters chase: what we owe on it and its letters.

suggested_approvers
object[]
required

Detail only. Invoice approvers of its purchase orders who are not on it and could approve it now, as when an order was linked after it got its approvers. Nothing adds them by itself; add them with updateInvoiceApprovers. Empty once it is decided and while it waits for its approvers.

note
string | null
required

The invoice-wide note in its original wording. Null means unavailable; empty text stays empty.

payment
object
required
delivery
object
required
references
object
required
additional_properties
object[] | null
required

Other named details found in the source, with where they were found. Null when not available; empty when none were found.

approval
object | null
required

The decision; null until it is approved or closed, and again once reopened.

sent_back
object | null
required

Set while the invoice is sent back to Inbox (lifecycle.status sent_back): who sent it back, when and why. Null once it is sent for approval again.

progress
object[]
required

The lifecycle: received, approved, booked, paid, each with its own state.

hold
object | null
required

Set while the invoice is on hold; null otherwise.

locked
boolean
required

Sent for approval: a record until it is reopened, and every correction (updateInvoice, line items, documents, classification) returns 409 until then; actions says what the caller may still do. False while it is a draft in Inbox, and for an invoice that never went through approval in Watchdog.

intake
object
required

Processing (matching, checks, coding and approvers) starts once the invoice has a company and a supplier; a recipient is optional. missing says which a person must choose. Complete means that processing ended, not that every check passed.

actions
object
required

What the caller may do now, by the rules the writes apply. code: updateInvoiceCoding; pull_back: from Approval to Inbox, approvals cleared; hold: put on hold or take off. send_for_approval is still refused while lifecycle.blockers lists anything.

voucher
object | null
required

The voucher the accounting system booked it on, with names from its chart of accounts. Null when none (Tripletex only).

transfer
object | null
required

For an invoice or credit note Watchdog received (Peppol, email, upload) and approved under accounts payable: whether it was registered in the organization's accounting system as a supplier invoice, with its coding and payment details (Tripletex: as the person signed in on the connection, in Ikke bokførte bilag, its payment waiting for approval there or set to pay later), and booked if the integration books what it sends. Approving does not send it: transferInvoice does, and sending again retries a failed attempt. Only invoices in NOK are written so far; others fail as currency_unsupported. A written invoice stays shown after the approval is reopened. Credit notes are registered as credit notes. Null when there is nothing to send (one not approved under accounts payable, or no connection takes invoices), and while an attempt is still writing.

origin
object
required
sources
object[]
required

Every arrival of this invoice, in the order received: an accounting system, a Peppol message, an email attachment, an upload or an API import. The first created the invoice; later ones are linked.

approval_evaluation
object | null
required

The approval policy's evaluation, made once the invoice settled; null until then.

effects
object
required