POST /v1/source-facts/expense-documents

Create Expense Document Source Fact

Persist an expense document source fact with receipt evidence or an explicit exception. No accounting finality is performed.

Requires API key Idempotent OpenAPI v1

Authentication

Use a HelvCore API key in the Authorization header. Keys are server-side secrets and must not be exposed to browser JavaScript.

GETHeader

Authorization: Bearer hc_...

Parameters

Idempotency-Keystringrequiredheader

Documented field.

Request body

Send JSON using the documented schema. Unknown or unsafe fields fail with structured validation errors where the endpoint owns validation.

See OpenAPI for the complete schema.

Returns

Returns a documented JSON response on success and the standard HelvCore error envelope on failure.

202Successful response.

defaultStructured error response.

401invalid_auth - missing, expired, or invalid Bearer key

Stable error codes

api_key_disabledDocumented HelvCore error code for this operation.

api_key_expiredDocumented HelvCore error code for this operation.

idempotency_key_conflictDocumented HelvCore error code for this operation.

invalid_authDocumented HelvCore error code for this operation.

invalid_requestDocumented HelvCore error code for this operation.

missing_idempotency_keyDocumented HelvCore error code for this operation.

validation_failedDocumented HelvCore error code for this operation.

curl -X POST https://api.helvcore.ch/v1/source-facts/expense-documents \ -H "Authorization: Bearer $HELVCORE_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "business_date": "2026-03-31", "end_customer_id": "00000000-0000-4000-8000-000000000000", "external_reference": "string", "idempotency_key": "string", "source_hash": "string", "source_payload_hash": "string", "source_system": "string", "evidence_links": [ { "sha256": "string", "type": "source_export", "label": "string", "media_type": "string", "uri": "string" } ], "replay_policy": "idempotent_replay", "fact_type": "expense_document", "payload": { "currency": "CHF", "document_date": "2026-03-31", "gross_amount": { "amount_minor": 123, "currency": "CHF" }, "supplier_external_reference": "string", "missing_receipt_exception": { "reason": "string", "approved_by": "string" }, "receipt_required": true, "supplier": { "name": "string", "supplier_external_reference": "string", "structured_address": {}, "uid_mwst_number": "string" } } }'

{ "business_date": "2026-03-31", "end_customer_id": "00000000-0000-4000-8000-000000000000", "external_reference": "string", "idempotency_key": "string", "source_hash": "string", "source_payload_hash": "string", "source_system": "string", "evidence_links": [ { "sha256": "string", "type": "source_export", "label": "string", "media_type": "string", "uri": "string" } ], "replay_policy": "idempotent_replay", "fact_type": "expense_document", "payload": { "currency": "CHF", "document_date": "2026-03-31", "gross_amount": { "amount_minor": 123, "currency": "CHF" }, "supplier_external_reference": "string", "missing_receipt_exception": { "reason": "string", "approved_by": "string" }, "receipt_required": true, "supplier": { "name": "string", "supplier_external_reference": "string", "structured_address": {}, "uid_mwst_number": "string" } } }