Analyze confirmed, normalized historical invoice rows (ANALYST+)

POST

/scans

const url = 'https://api.invogi.com/v1/scans';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"companyId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","rows":[{"supplierName":"example","supplierTaxId":"example","invoiceNumber":"example","issueDate":"2026-04-15","currency":"GBP","grossAmount":"example","purchaseOrderRef":"example","bankIban":"example","bankSortCode":"60-16-13","bankAccountNumber":"31926819","externalId":"example","sourceRowNumber":1}],"payments":[{"supplierName":"example","supplierTaxId":"example","supplierExternalId":"example","invoiceExternalId":"example","invoiceNumber":"example","amount":"example","currency":"GBP","paidAt":"2026-04-15","paymentReference":"example","method":"example","direction":"PAYMENT","sourceRowNumber":1}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.invogi.com/v1/scans \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "companyId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "rows": [ { "supplierName": "example", "supplierTaxId": "example", "invoiceNumber": "example", "issueDate": "2026-04-15", "currency": "GBP", "grossAmount": "example", "purchaseOrderRef": "example", "bankIban": "example", "bankSortCode": "60-16-13", "bankAccountNumber": "31926819", "externalId": "example", "sourceRowNumber": 1 } ], "payments": [ { "supplierName": "example", "supplierTaxId": "example", "supplierExternalId": "example", "invoiceExternalId": "example", "invoiceNumber": "example", "amount": "example", "currency": "GBP", "paidAt": "2026-04-15", "paymentReference": "example", "method": "example", "direction": "PAYMENT", "sourceRowNumber": 1 } ] }'

Authorizations

bearerAuth

Request Body^required

application/json

object

companyId

Defaults to the default company

string format: uuid

rows

required

Array<object>

>= 1 items <= 5000 items

object

supplierName

required

string

supplierTaxId

string

invoiceNumber

required

string

issueDate

required

string format: date

currency

Optional. Rows without a currency are analysed in the organization’s base currency (a ledger export is in one functional currency).

string

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

grossAmount

required

string

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

purchaseOrderRef

string

bankIban

string

bankSortCode

UK sort code; used only together with bankAccountNumber

string

Example

60-16-13

bankAccountNumber

UK account number (6-8 digits); used only together with bankSortCode

string

Example

31926819

externalId

string

sourceRowNumber

required

integer

payments

Optional payment history for the same period. Imported after the invoices, in the same all-or-nothing transaction, so a payment can link to an invoice by invoiceExternalId or invoiceNumber; then checked for duplicate payments. Payees that match no known supplier are kept as provisional payees and checked against each other at lower confidence; no supplier is created from payment data.

Array<object>

<= 5000 items

object

supplierName

Payee name as exported

string

supplierTaxId

string

supplierExternalId

The payee’s ID in the customer’s system; kept as evidence

string

<= 200 characters

invoiceExternalId

Matches an invoice’s externalId

string

invoiceNumber

Matches an invoice by number when there is no invoice ID

string

<= 200 characters

amount

required

A positive payment amount; at most 18 integer and 6 decimal digits

string

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

currency

Optional; defaults to the organization’s base currency

string

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

paidAt

required

string format: date

paymentReference

string

method

string

direction

REFUND is money the supplier sent back (in an export, a row of the opposite sign to the payments). It is kept as a supplier refund that can be suggested on a matching recovery case, never checked as a payment. The amount stays positive. A refund already imported (same payee, currency, amount, date and reference) is not added again.

string

default: PAYMENT

Allowed values: PAYMENT REFUND

sourceRowNumber

required

integer

Responses

202

Scan created

application/json

object

required

string format: uuid

status

required

string

Allowed values: COMPLETE

invoicesAnalyzed

required

integer

>= 1

rowsSkipped

required

Rows not analyzed because their externalId was already imported or repeated in the file

integer

skippedRows

required

Array<object>

object

sourceRowNumber

required

integer

externalId

Present for ALREADY_IMPORTED and DUPLICATE_EXTERNAL_ID_IN_FILE

string

reason

required

ALREADY_SYNCED_FROM_ERP means an ERP sync already imported an invoice for the same company with the same supplier, invoice number, currency and gross amount

string

Allowed values: ALREADY_IMPORTED DUPLICATE_EXTERNAL_ID_IN_FILE ALREADY_SYNCED_FROM_ERP

matchedInvoiceId

The ERP-synced invoice this row matched (ALREADY_SYNCED_FROM_ERP only)

string format: uuid

analyzedValue

required

Total gross value of the analysed invoices in the organization’s base currency (analyzedValueCurrency). Invoices with no exchange rate are left out; see unconvertedInvoices.

string

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

analyzedValueCurrency

required

string

>= 3 characters <= 3 characters

unconvertedInvoices

required

Analysed invoices not included in analyzedValue because no exchange rate was available

integer

decisionCounts

required

object

key

additional properties

integer

findingCounts

required

object

key

additional properties

integer

payments

One of:

null
object

null

Example

{
  "status": "COMPLETE",
  "skippedRows": [
    {
      "reason": "ALREADY_IMPORTED"
    }
  ]
}

400

Invalid request

application/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

application/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

application/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

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

429

Request-rate or customer-usage limit exceeded; inspect the stable error code

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

Analyze confirmed, normalized historical invoice rows (ANALYST+)

Authorizations

Request Bodyrequired

Example

Example

Responses

202

Example

400

Example

401

Example

403

Example

409

Example

429

Example

Request Body^required