What this feature does

Built for Swiss invoicing, not generic form validation

Swiss QR-Bills have strict address rules. HelvAddress turns those rules into a production-ready API your teams can trust.

Auto-detects mode S or K

Send structured fields or two free-form lines. The API infers whether the address should be validated in structured mode (S) or combined mode (K).

Validates every field

Checks maximum lengths, required fields, allowed characters, and Swiss QR-Bill formatting constraints before document generation.

Checks real Swiss postal codes

Postal codes are not only checked for format. They are verified against the official Swiss postal locality directory.

Returns structured violations

Always returns HTTP 200 with valid true/false and a clean list of violations by field, code, and message — perfect for forms and business workflows.

Compliance-ready by design

Explicitly aligned with SIX Swiss Payments Standard v2.3

This is the validation layer Swiss invoicing teams need before printing, exporting, or sending a QR-Bill.

HelvAddress exposes a dedicated endpoint for QR-Bill address validation so you do not have to re-implement SIX rules inside your ERP, e-commerce platform, or invoicing stack.

The result is simpler compliance, fewer billing exceptions, and a faster path to production for Swiss payment workflows.

What the endpoint guarantees

The contract is intentionally easy to integrate into forms, APIs, and document-generation pipelines.

Swiss addresses only (`countryCode = CH`)
Valid responses always use HTTP 200 with a structured body
When valid, the `formatted` object is ready to use immediately
Address modes

Supports both Swiss QR-Bill address styles

Whether your system stores fully structured addresses or legacy free-form lines, the validation flow adapts to your data model.

MODE S streetName · buildingNumber · postalCode · town
Mode S — structured addresses

Use separate fields when your system already stores street, building number, postal code, and town independently.

  • Ideal for ERPs, CRMs, billing engines, and master-data platforms
  • Validates streetName, buildingNumber, postalCode, and town field by field
  • Best when you want precise validation feedback inside structured forms
MODE K addressLine1 · addressLine2
Mode K — combined address lines

Use two free-form lines when the upstream system still stores addresses in the classic combined Swiss payment format.

  • Works well with legacy accounting systems and imported address data
  • Validates `addressLine1` and `addressLine2` against QR-Bill constraints
  • Lets you add compliance controls without redesigning your data model first
Automatic mode detection If `addressLine1` or `addressLine2` is present, the API validates the request as mode K. Otherwise it uses mode S automatically.
What is checked

The key controls happen in one request

The validation endpoint is designed to answer the real question: can this address appear on a Swiss QR-Bill right now?

1
Field lengths

Enforces SIX maximum lengths such as 70 characters for names and streets, 16 for postal code/building number, and 35 for town.

2
Allowed character set

Rejects disallowed characters and control characters so the address remains compatible with Swiss QR-Bill generation constraints.

3
Swiss postal code rules

Checks that Swiss postal codes use the expected 4-digit format where applicable and align with the requested country.

4
Official postal directory match

Confirms that the postal code exists in the official Swiss postal locality data set instead of relying on format checks alone.

5
Ready-to-use formatting

When the address is valid, the API returns a cleaned `formatted` object ready for QR-Bill output.

Response design

Easy to plug into forms, workflows, and billing systems

No exception-heavy flow, no guessing. Your application gets an explicit result every time.

Request example
POST /api/addresses/validate/qrbill
Authorization: Bearer {access_token}
Content-Type: application/json
X-HelvAddress-API-Version: 1.0.0

{
  "name": "Max Muster AG",
  "streetName": "Bahnhofstrasse",
  "buildingNumber": "1",
  "postalCode": "8001",
  "town": "Zürich",
  "countryCode": "CH"
}
Valid response
{
  "valid": true,
  "mode": "S",
  "violations": [],
  "formatted": {
    "mode": "S",
    "name": "Max Muster AG",
    "streetName": "Bahnhofstrasse",
    "buildingNumber": "1",
    "postalCode": "8001",
    "town": "Zürich",
    "countryCode": "CH"
  }
}
Invalid response
{
  "valid": false,
  "mode": "S",
  "violations": [
    {
      "field": "postalCode",
      "code": "INVALID_POSTAL_CODE",
      "message": "postalCode must be a valid Swiss postal code"
    },
    {
      "field": "town",
      "code": "FIELD_REQUIRED",
      "message": "town is required"
    }
  ]
}
This makes HelvAddress especially useful for inline form validation: the frontend can highlight the exact field and message without handling multiple HTTP error branches.
Business value

A better way to secure Swiss payment workflows

Any Swiss business that issues invoices or manages payments needs reliable address compliance before a QR-Bill is generated.

Invoicing and ERP teams

Validate creditor and debtor addresses before PDF generation, batch invoice export, or print operations.

Billing software vendors

Embed Swiss QR-Bill compliance directly into your product without maintaining your own rule engine or postal code reference data.

E-commerce and portals

Catch payment-blocking address issues earlier in checkout or account flows, before the invoice is ever created.

Need Swiss QR-Bill compliance without building it yourself?

Use HelvAddress to validate addresses before billing, printing, and payment operations — on Swiss-hosted infrastructure and with a developer-friendly contract.

Read the API docs Contact us Explore normalization