Invoices

Create invoice

Changed on Oct 1, 2026

post/invoices

Request

Base URL
https://api.vocal.email/v1
Auth
- API key in header X-API-Key
- or HTTP bearer
TypeScript
https://skmtc.dev/vocal/apis/magic-heidi-invoicing-software-api/docs/invoices/post.ts
A function with typed inputs. Its response is checked against the schema.

Request body

bankIdstring nullable

Id from GET /bank-accounts; null picks one by client and currency. The account must be in the invoice currency, or a CHF IBAN for a EUR invoice; GBP, USD and other currencies need a custom account in that currency.

clientIdstring

Id of one of your clients; stored as clientRef.

clientRefstring

users/{uid}/clients/{clientId}; prefer clientId.

confirmDateboolean

Request-only, never stored: confirms an invoice date outside the current year.

currencystring

Must be an ISO 4217 currency code like CHF, EUR or USD.

datestring

ISO 8601 date or date-time. Invoice date (a date only is fine). Must be in this or last calendar year and at most 92 days ahead; a date outside the current Swiss calendar year also needs confirmDate: true.

descriptionstring

Footer text.

disableRoundingboolean

exchangeRatenumber nullable

CHF -> currency rate: units of currency per 1 CHF (about 1.07 for EUR). Non-CHF invoices only; leave it null: when a foreign-currency invoice is paid (app or API) the rate of its latest payment date is stored. A rate sent here is kept.

generationCountinteger

headerDescriptionstring

Header text.

hideQuotePricingboolean

idstring

isArchivedboolean

isPaidboolean

language'de' | 'en' | 'fr' | 'it'

biYearly = every 6 months, triYearly = every 4 months.

recurringAutoSendboolean

recurringDueDatestring nullable

ISO 8601 date (2026-09-30) or date-time (2026-09-30T08:00:00Z).

sentboolean

type'normal' | 'quote'

vatEnabledboolean

vatMode'additive' | 'inclusive'

versioninteger

Invoice number, unique per (Swiss calendar year of date, type). Omit to get the next one.

Changes

Oct 1, 2026d0319ad57804 Revision changes
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property

Operation history