Qualified Confirmations Endpoints

Giltiq persists every qualified confirmation as an immutable receipt row and exposes two retrieval endpoints. These are the backbone of the §18e UStG audit trail — you can retrieve a confirmation years after the original call.

Authentication: API key required (X-Api-Key header) for both endpoints. Anonymous access is not supported.

See also: Qualified Confirmation Guide

---

GET /v1/qualified-confirmations/{receipt_id}

Retrieves a single stored receipt by its Giltiq-issued receipt ID.

Path Parameters

Parameter	Type	Required	Description
receipt_id	string	Yes	The Giltiq-issued receipt ID, e.g. GQ-QC-20260410-A7K2M9P4R3

Authentication

X-Api-Key: gq_live_...

Response — 200 OK

{
  "receipt_id": "GQ-QC-20260410-A7K2M9P4R3",
  "target_vat_id": "DE811575812",
  "requester_vat_id": "DE123456789",
  "input": {
    "company_name": "Bundeszentralamt für Steuern",
    "company_street": "An der Küppe 1",
    "company_zip": "53225",
    "company_city": "Bonn"
  },
  "result": {
    "valid": true,
    "name_match": "match",
    "street_match": "match",
    "zip_match": "match",
    "city_match": "match",
    "official_name": "Bundeszentralamt für Steuern",
    "official_address": "An der Küppe 1, 53225 Bonn"
  },
  "bzst_request_id": "BZST-2026-0410-XYZ123",
  "issued_at": "2026-04-10T12:34:56.000Z",
  "source": "giltiq-issued"
}

Response Fields

Field	Type	Description
receipt_id	string	Giltiq-issued audit receipt ID
target_vat_id	string	The VAT ID that was validated
requester_vat_id	string | null	Your own VAT ID as requester, if supplied
input	object	The company data you supplied at validation time
result	object	Match results and official company data from BZSt
bzst_request_id	string | null	BZSt’s internal request ID, useful in audit disputes
issued_at	string	ISO 8601 timestamp of when Giltiq persisted the receipt
source	string	Always "giltiq-issued" — see note below

Match values

Each *_match field in result is one of:

Value	Meaning
match	Supplied value matched the BZSt registry
mismatch	Supplied value did not match
not_queried	Field was not supplied in the request
not_provided	BZSt did not return a value for this field

404 Behavior

A receipt that belongs to a different API key returns 404, not 403. This prevents enumeration of other accounts’ receipt IDs.

Example

curl "https://api.giltiq.de/v1/qualified-confirmations/GQ-QC-20260410-A7K2M9P4R3" \
  -H "X-Api-Key: gq_live_..."

---

GET /v1/qualified-confirmations

Returns a paginated list of all qualified confirmation receipts for the authenticated API key, newest first.

Query Parameters

Parameter	Type	Required	Description
target_vat_id	string	No	Filter to receipts for a specific VAT ID
limit	integer	No	Page size (1–100, default 20)
cursor	string	No	Pagination cursor from the previous response’s next_cursor

Authentication

X-Api-Key: gq_live_...

Response — 200 OK

{
  "data": [
    {
      "receipt_id": "GQ-QC-20260410-A7K2M9P4R3",
      "target_vat_id": "DE811575812",
      "name_match": "match",
      "street_match": "match",
      "zip_match": "match",
      "city_match": "match",
      "issued_at": "2026-04-10T12:34:56.000Z"
    }
  ],
  "next_cursor": null
}

Pagination

The list uses opaque cursor pagination:

• If next_cursor is a string, pass it as the cursor query parameter to fetch the next page.
• If next_cursor is null, you have reached the last page.
• Do not attempt to construct or decode cursors manually — the format may change.

Example — List all receipts

curl "https://api.giltiq.de/v1/qualified-confirmations?limit=20" \
  -H "X-Api-Key: gq_live_..."

Example — Filter by VAT ID

curl "https://api.giltiq.de/v1/qualified-confirmations?target_vat_id=DE811575812" \
  -H "X-Api-Key: gq_live_..."

Example — Paginate

# Page 1
curl "https://api.giltiq.de/v1/qualified-confirmations?limit=10" \
  -H "X-Api-Key: gq_live_..."

# Page 2 (use next_cursor from previous response)
curl "https://api.giltiq.de/v1/qualified-confirmations?limit=10&cursor=<next_cursor>" \
  -H "X-Api-Key: gq_live_..."

---

Note on source: "giltiq-issued"

Every receipt has "source": "giltiq-issued". This is important:

• The receipt is issued and stored by Giltiq, not by the German tax authority (BZSt).
• It is not an official BZSt Drucksache (the old XML-RPC print receipt from the deactivated BZSt XML-RPC API, discontinued 2025-11-30).
• It is a contemporaneous audit record: Giltiq captures the exact inputs you supplied, the BZSt response, and the match results at the moment of the API call.
• German tax auditors (§ 18e UStG) require you to document that you conducted a due-diligence check at invoicing time. This receipt provides that documentation.

Giltiq retains receipts for the lifetime of your account, with a minimum of 10 years to cover German tax audit windows (§§ 147 AO, 14b UStG).