Create and analyze a canonical invoice

POST

/invoices

curl --request POST \
  --url https://api.invogi.com/v1/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "supplier": { "name": "example", "tax_id": "example", "bank_account": { "iban": "example", "sort_code": "60-16-13", "account_number": "31926819" } }, "invoice_number": "example", "issue_date": "2026-04-15", "due_date": "2026-04-15", "currency": "GBP", "net_amount": "example", "tax_amount": "example", "gross_amount": "example", "purchase_order_ref": "example", "buyer": { "name": "example", "tax_id": "example" }, "company_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

Authorizations

• bearerAuth

Parameters

Header Parameters

Idempotency-Key

string

Request Body^required

Media typeapplication/json

object

supplier

required

object

name

required

string

tax_id

string

bank_account

IBAN, or a UK domestic account as sort_code plus account_number (both required together). A GB IBAN and its sort code + account number are treated as the same account.

object

iban

string

sort_code

Six-digit UK sort code; “-” and spaces are ignored

string

Example

60-16-13

account_number

Six- to eight-digit UK account number

string

Example

31926819

invoice_number

required

string

issue_date

required

string format: date

due_date

string format: date

currency

required

ISO 4217 alphabetic currency code, case-insensitive and stored upper-case. A code that is not a currency suppliers invoice in (including XXX, funds and precious-metal codes) is rejected with INVALID_REQUEST. Invoices whose currency cannot be read from an uploaded document are stored with the ISO placeholder XXX and raise a CURRENCY_UNKNOWN finding.

string

/^[A-Za-z]{3}$/

Example

GBP

net_amount

string

/^-?[0-9]+(\.[0-9]{1,6})?$/

tax_amount

string

/^-?[0-9]+(\.[0-9]{1,6})?$/

gross_amount

required

string

/^-?[0-9]+(\.[0-9]{1,6})?$/

purchase_order_ref

string

buyer

Invoice recipient (EN 16931 BG-7). tax_id routes the invoice to the company with that VAT ID when company_id is omitted.

object

name

string

tax_id

string

company_id

One of the organization’s companies (GET /companies); defaults to the default company

string format: uuid

Responses

202

Accepted

Media typeapplication/json

object

id

required

string

status

required

string

Allowed value: ANALYZING

decision

required

string

Allowed values: PASS REVIEW BLOCK

risk_score

required

integer

<= 100

findings

required

Array<object>

object

type

required

string

severity

required

string

Allowed values: INFO LOW MEDIUM HIGH CRITICAL

summary

required

string

recommendedAction

string | null

confidence

number

<= 1

evidence

required

object

key

additional properties

any

versions

required

object

riskEngine

required

string

policy

required

string

compliance

string

Example

{
  "status": "ANALYZING",
  "decision": "PASS",
  "findings": [
    {
      "severity": "INFO"
    }
  ]
}

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"
  }
}

409

Conflicting idempotency key or resource processing state

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"
  }
}