Upsert external invoices

POST

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

Create or update invoices by immutable external source identity.

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

ExternalInvoiceImportResult

Batch import/upsert execution result.

object

imported_count

Imported Count

integer

0

updated_count

Updated Count

integer

0

skipped_count

Skipped Count

integer

0

conflict_count

Conflict Count

integer

0

errors

Errors

Array<object>

default:

object

key

additional properties

any

invoice_ids

Invoice Ids

Array<string>

default:

conflict_ids

Conflict Ids

Array<string>

default:

Examples

200 response example

{
  "imported_count": 0,
  "updated_count": 0,
  "skipped_count": 0,
  "conflict_count": 0
}

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