Record what happened to the money behind a confirmed finding's invoice (ANALYST+, dashboard user)

PUT

/findings/{findingId}/outcome

curl --request PUT \
  --url https://api.invogi.com/v1/findings/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/outcome \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "kind": "PREVENTED", "note": "Removed from the 14 Oct payment run." }'

Records that the invoice’s payment was permanently stopped (PREVENTED: cancelled, voided, corrected or removed from a payment run — a hold alone is not enough). RECOVERED is refused with 409: recovered money is recorded on a recovery case (POST /recoveries), as cash received or credit applied. A prevented outcome is refused while the invoice is part of a recovery case. Prevented outcomes are part of the benefit totalled in the overview’s impact. One outcome per invoice: recording again, from this or another finding on the same invoice, replaces it. Only a CONFIRMED finding on an invoice can justify one (409 otherwise), and amount may not exceed the invoice’s gross amount (it defaults to it). API keys cannot record outcomes (403): like a review, it must be attributable to a person. See docs/31_FINANCIAL_IMPACT.md.

Authorizations

• bearerAuth

Parameters

Path Parameters

findingId

required

string format: uuid

Request Body^required

Media typeapplication/json

object

kind

required

string

Allowed values: PREVENTED RECOVERED

amount

Decimal string in the invoice’s currency; defaults to its gross amount

string

/^\d{1,18}(\.\d{1,6})?$/

note

required

What happened and how it was verified

string

>= 3 characters <= 2000 characters

Example

{
  "kind": "PREVENTED",
  "note": "Removed from the 14 Oct payment run."
}

Responses

200

The invoice’s outcome

Media typeapplication/json

object

kind

required

string

Allowed values: PREVENTED

amount

required

Decimal string in the invoice’s currency

string

currency

required

string

>= 3 characters <= 3 characters

note

required

string

findingId

required

The confirmed finding that recorded it

string format: uuid

recordedAt

required

string format: date-time

recordedBy

required

object

id

required

string format: uuid

name

required

string

counted

required

False when no finding on its invoice is CONFIRMED any more; kept

boolean

Example

{
  "kind": "PREVENTED"
}

400

Invalid request

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: NOT_FOUND UNAUTHORIZED FORBIDDEN INVALID_REQUEST CONFLICT RATE_LIMITED USAGE_LIMIT_EXCEEDED PROCESSING_FAILED

message

required

string

request_id

required

string

Example

{
  "error": {
    "code": "NOT_FOUND"
  }
}

401

Missing or invalid API key

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: NOT_FOUND UNAUTHORIZED FORBIDDEN INVALID_REQUEST CONFLICT RATE_LIMITED USAGE_LIMIT_EXCEEDED PROCESSING_FAILED

message

required

string

request_id

required

string

Example

{
  "error": {
    "code": "NOT_FOUND"
  }
}

403

API key lacks required scope/role

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: NOT_FOUND UNAUTHORIZED FORBIDDEN INVALID_REQUEST CONFLICT RATE_LIMITED USAGE_LIMIT_EXCEEDED PROCESSING_FAILED

message

required

string

request_id

required

string

Example

{
  "error": {
    "code": "NOT_FOUND"
  }
}

404

Resource not found

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: NOT_FOUND UNAUTHORIZED FORBIDDEN INVALID_REQUEST CONFLICT RATE_LIMITED USAGE_LIMIT_EXCEEDED PROCESSING_FAILED

message

required

string

request_id

required

string

Example

{
  "error": {
    "code": "NOT_FOUND"
  }
}

409

The finding is not confirmed or has no invoice, kind is RECOVERED, or the invoice is under recovery