Skip to main content
POST

​
Overview

Create an invoice by submitting the invoice data as structured JSON, without uploading a PDF document. Use this endpoint when you have no invoice file and want to pass all fields manually. Unlike the PDF upload endpoint, no OCR runs on this path, so the created invoice is marked with data_extraction_status: "manual". The invoice amounts automatically update the claim’s total_claim_amount via database triggers.
Need to attach an actual PDF invoice (with OCR extraction)? Use POST /openapi/claims//invoices (multipart/form-data) instead.

​
Request Format

  • Content-Type: application/json
  • All fields are optional unless your partner agreement requires them (see Partner intake rules in the API description: default_date, creditor_reminder_dates, contract_date, subject). Amounts must be non-negative and dates must be valid ISO 8601 (YYYY-MM-DD); invalid values return a 400.
  • default_date, creditor_reminder_dates, default_basis and contract_date state how and when the debtor fell into default. default_basis: "bgb_286_3" (default 30 days after the due date and receipt of the invoice, § 286 (3) BGB) needs no reminder dates; against a consumer it applies only if the invoice pointed this out.
  • If your agreement prohibits health data, subject, invoice_issuer and invoice_recipient are checked; a match returns 400 PROHIBITED_DATA naming the field.

​
Authentication

Requires API Token authentication via Bearer token.

​
Path Parameters

​
string
required
UUID of the claim you are attaching an invoice to

​
Request Body (JSON)

​
string
Invoice number/reference
​
string
Name of the invoice issuer (creditor)
​
string
Name of the invoice recipient (debtor)
​
string
Invoice subject/description
​
number
Net invoice amount (before tax). Must be ≥ 0.
​
number
Gross amount on the invoice. Must be ≥ 0. Feeds claims.total_claim_amount (minus amount_paid).
​
string
Invoice issue date in ISO 8601 format (YYYY-MM-DD)
​
string
Invoice due date in ISO 8601 format (YYYY-MM-DD)
​
number
Reminder fees already incurred by creditor and still unpaid. Must be ≥ 0. Feeds claims.total_claim_amount.
​
number
Amount the debtor already paid you on this invoice before you handed it over. Requires invoice_amount_gross in the same request and must be less than it (a fully paid invoice is not handed over). We collect only the open rest; interest and our collection fees are calculated on it, and the collection letter shows “invoice amount – paid – open”. It is not recorded as a payment and sends no payment notification.
​
string
Date of the (last) payment counted in amount_paid, ISO 8601 (YYYY-MM-DD), not in the future. Requires amount_paid. Shown on the letter when given.

​
Examples

cURL
JavaScript
Python

​
Responses

​
Notes

  • This endpoint only accepts JSON; it does not handle file uploads.
  • No OCR runs; the invoice is stored with data_extraction_status: "manual".
  • invoice_amount_gross (minus amount_paid) and creditor_reminder_fees_incurred automatically update the claim’s total_claim_amount via database triggers.
  • Partly paid before handover: send the invoice amount in invoice_amount_gross and the paid part in amount_paid, e.g. "invoice_amount_gross": 59.56, "amount_paid": 43.57, "last_payment_date": "2024-11-05". The response then shows invoice_amount_gross: 59.56, amount_paid: 43.57, amount_open: 15.99. Do not report such a payment through /payments — that endpoint records money paid during collection. Reminder fees the debtor has paid are sent only for the part still open.

Authorizations

​
Authorization
string
header
required

An API key (ico_live_…), sent as Authorization: Bearer <key>. Not a JWT.

Path Parameters

​
claim_id
string<uuid>
required

Body

application/json
​
invoice_number
string
​
invoice_issuer
string

The creditor's name on the invoice

​
invoice_recipient
string

The debtor's name on the invoice

​
subject
string
​
invoice_amount_net
number
Required range: x >= 0
​
invoice_amount_gross
number

Adds to the claim's total_claim_amount

Required range: x >= 0
​
invoice_issue_date
string<date>
​
invoice_due_date
string<date>
​
creditor_reminder_fees_incurred
number

Reminder fees the creditor already charged and that are still unpaid

Required range: x >= 0
​
amount_paid
number

Amount the debtor already paid you on this invoice before you handed it over to us. Requires invoice_amount_gross in the same request and must be less than it. We collect only the rest (amount_open); interest and our collection fees are calculated on it, and the letter shows "invoice amount – paid – open". It is not recorded as a payment.

Required range: x >= 0.01
​
last_payment_date
string<date>

Date of the (last) payment counted in amount_paid; not in the future. Requires amount_paid

​
default_date
string<date>

The date the debtor fell into default (Verzug)

​
creditor_reminder_dates
string<date>[]

The dates of your own reminders before you handed the invoice over. Not needed when default_basis is bgb_286_3.

Minimum array length: 1
​
default_basis
enum<string>

How the default arose. reminder (the default when not sent): by a reminder after the due date (§ 286 (1) BGB). bgb_286_3: 30 days after the due date and receipt of the invoice without a reminder (§ 286 (3) BGB) — against a consumer only when the invoice pointed out this consequence.

Available options:
reminder,
bgb_286_3
​
contract_date
string<date>

The date of the contract the invoice is based on

Response

Invoice created

​
success
boolean
Example:

true

​
data
object