Preview external invoice import

POST

/api/v1/tenants/{tenant_id}/workspaces/{workspace_id}/invoices/import/preview

Preview numbering, IRN validation, and conflicts without persistence.

Authorizations

• HTTPBearer
• HTTPBearer

Parameters

Header Parameters

X-Workspace-ID

Any of:

string

string

null

null

X-API-Key

Any of:

string

string

null

null

X-Tenant-ID

Any of:

string

string

null

null

Request Body ^required

ExternalInvoiceImportRequest

Batch external invoice import request.

object

invoices

required

Invoices

Array<object>

>= 1 items <= 200 items

ExternalInvoicePayload

Single external invoice payload for import/upsert.

object

source_system

required

Source System

string

>= 1 characters <= 50 characters

source_invoice_id

required

Source Invoice Id

string

>= 1 characters <= 200 characters

source_document_version

Any of:

string

string

<= 100 characters

null

null

invoice_number

Any of:

string

string

<= 200 characters

null

null

irn

Any of:

string

string

<= 200 characters

null

null

issue_date

required

Issue Date

string format: date

due_date

Any of:

string

string format: date

null

null

document_currency_code

Document Currency Code

string

default: NGN <= 3 characters

supplier_id

Any of:

string

string format: uuid

null

null

customer_id

Any of:

string

string format: uuid

null

null

supplier_name

Any of:

string

string

<= 500 characters

null

null

supplier_tin

Any of:

string

string

<= 100 characters

null

null

customer_name

Any of:

string

string

<= 500 characters

null

null

customer_tin

Any of:

string

string

<= 100 characters

null

null

direction

InvoiceDirection

Invoice direction - sent or received.

string

default: outbound

Allowed values: outbound inbound

invoice_type_code

Invoice Type Code

string

default: 380 <= 10 characters

line_extension_amount

required

Any of:

number

number

string

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

tax_amount_total

Any of:

number

number

string

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

payable_amount

required

Any of:

number

number

string

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

note

Any of:

string

string

null

null

metadata

Any of:

object

object

key

additional properties

any

null

null

import_policy

ExternalInvoiceImportPolicy

Conflict behavior for external invoice numbering.

string

default: preserve_if_unique_else_fallback

Allowed values: preserve_if_unique_else_fallback always_preserve_and_reject_on_conflict always_local_numbering

numbering_policy_id

Any of:

string

string format: uuid

null

null

Examples

Request payload example

{
  "invoices": [
    {
      "source_system": "string",
      "source_invoice_id": "string",
      "source_document_version": "string",
      "invoice_number": "string",
      "irn": "string",
      "issue_date": "2026-02-11",
      "due_date": "2026-02-11",
      "line_extension_amount": 0,
      "payable_amount": 0
    }
  ],
  "import_policy": "preserve_if_unique_else_fallback",
  "numbering_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Responses

200

Successful Response

ExternalInvoiceImportPreviewResponse

Batch import preview response.

object

import_policy

required

ExternalInvoiceImportPolicy

Conflict behavior for external invoice numbering.

string

Allowed values: preserve_if_unique_else_fallback always_preserve_and_reject_on_conflict always_local_numbering

items

required

Items

Array<object>

ExternalInvoicePreviewItem

Preview result for one external invoice payload.

object

source_system

required

Source System

string

source_invoice_id

required

Source Invoice Id

string

requested_invoice_number

Any of:

string

string

null

null

canonical_invoice_number

Any of:

string

string

null

null

will_use_fallback_numbering

Will Use Fallback Numbering

boolean

has_conflict

Has Conflict

boolean

conflict_reason

Any of:

string

string

null

null

normalized_irn

Any of:

string

string

null

null

irn_error

Any of:

string

string

null

null

existing_invoice_id

Any of:

string

string format: uuid

null

null

Examples

200 response example

{
  "import_policy": "preserve_if_unique_else_fallback",
  "items": [
    {
      "source_system": "string",
      "source_invoice_id": "string",
      "requested_invoice_number": "string",
      "canonical_invoice_number": "string",
      "will_use_fallback_numbering": false,
      "has_conflict": false
    }
  ]
}

422

Validation Error

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

Examples

422 response example

{
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string"
    }
  ]
}