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.

Plan requirement: Both endpoints require the business plan. Free and starter keys receive 402 PLAN_FEATURE_REQUIRED — qualified confirmations are not available on the starter plan.

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

Every key shown above is present on every response. Fields that were not supplied or not returned are null — they are never omitted.

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; all four keys are always present
result	object	Match results and official company data from BZSt; all seven keys are always present
result.valid	boolean	Whether the VAT ID was valid at validation time
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

Errors

Status	error.code	When
401	UNAUTHORIZED	No valid API key supplied
402	PLAN_FEATURE_REQUIRED	Key is on the free or starter plan
404	NOT_FOUND	Receipt unknown or created by a different API key

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Receipt not found",
    "request_id": "req_01HZ9X2Y3Z4A5B6C7D8E9F0G"
  }
}

404 Behavior

A receipt that belongs to a different API key returns 404, not 403. This prevents enumeration of other API keys’ receipt IDs. Access is tied to the API key that created the receipt, not to your account — see API key scoping below.

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 the qualified confirmation receipts created by 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

{
  "items": [
    {
      "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"
    }
  ],
  "next_cursor": null
}

Each element of items is the full receipt object — exactly the same shape as the single receipt endpoint above, including input, result.valid, and source.

Response Fields

Field	Type	Description
items	array of receipt objects	Full receipts created by the authenticated API key, newest first
next_cursor	string | null	Opaque cursor for the next page; null on the last page

Errors

Status	error.code	When
400	INVALID_QUERY	Malformed query parameters (e.g. limit outside 1–100)
401	UNAUTHORIZED	No valid API key supplied
402	PLAN_FEATURE_REQUIRED	Key is on the free or starter plan

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_..."

---

API key scoping and rotation

Receipts are scoped to the API key that created them — not to your account:

• The list endpoint only returns receipts created by the key used for the request.
• The single endpoint only returns a receipt to the key that created it; any other key gets 404.
• If an API key is revoked (for example rotated out during key management), its receipts can no longer be retrieved or listed by any key. Keep this in mind before rotating keys: store the receipts you need for audits, or keep the creating key active.

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).