POST /v1/opening-balance-sets

Create Opening Balance Set

Create or replay a reviewed-migration opening-balance draft set with provenance and balanced lines.

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.

end_customer_idstringrequiredbody

Documented field.

fiscal_year_idstringrequiredbody

Documented field.

legal_entity_idstringrequiredbody

Documented field.

opening_datestringrequiredbody

Documented field.

currencyenum<CHF | EUR>requiredbody

Documented field.

descriptionstringoptionalbody

Documented field.

migration_notesstringoptionalbody

Documented field.

provenanceobjectrequiredbody

Documented field.

linesarrayrequiredbody

Documented field.

Returns

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

201Successful 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/opening-balance-sets \ -H "Authorization: Bearer $HELVCORE_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "currency": "CHF", "end_customer_id": "00000000-0000-4000-8000-000000000000", "fiscal_year_id": "string", "legal_entity_id": "string", "lines": [ { "account_class": "string", "account_id": "string", "account_mapping_id": "string", "credit_amount": { "amount_minor": 123, "currency": "CHF" }, "debit_amount": { "amount_minor": 123, "currency": "CHF" }, "line_memo": "string", "source_snapshot": {} } ], "opening_date": "2026-03-31", "provenance": { "preparer": {}, "source_closing_date": "2026-03-31", "source_hash": "string", "source_reference": "string", "source_system": "string", "evidence_links": [ {} ], "notes": "string", "reviewer": {} }, "description": "string", "migration_notes": "string" }'

{ "currency": "CHF", "end_customer_id": "00000000-0000-4000-8000-000000000000", "fiscal_year_id": "string", "legal_entity_id": "string", "lines": [ { "account_class": "string", "account_id": "string", "account_mapping_id": "string", "credit_amount": { "amount_minor": 123, "currency": "CHF" }, "debit_amount": { "amount_minor": 123, "currency": "CHF" }, "line_memo": "string", "source_snapshot": {} } ], "opening_date": "2026-03-31", "provenance": { "preparer": {}, "source_closing_date": "2026-03-31", "source_hash": "string", "source_reference": "string", "source_system": "string", "evidence_links": [ {} ], "notes": "string", "reviewer": {} }, "description": "string", "migration_notes": "string" }