# The SHAB API: Reading the Swiss Gazette Programmatically

10 Aug 2026 6 min read

This guide is for developers building a SHAB data import. If you need to interpret a gazette entry for sales, start with [Reading SHAB/FOSC](https://prospex.ch/guides/reading-shab-fosc/), which explains what each entry type means commercially.

Here we cover the publication endpoints and XML fields. We also explain four API behaviours that can waste a day when you meet them in production.

## Use the public API for machine access

SHAB's `robots.txt` applies to automated crawling of the website. For machine access, the Amtsblattportal provides a public REST API intended for production use. Use the API endpoints below for published material. They require no login.

| Environment | Base URL |
| --- | --- |
| Production | `https://amtsblattportal.ch/api/v1/` |
| Integration | `https://int.amtsblattportal.ch/api/v1/` |

The login endpoint is for submitting publications. The open endpoints above serve published material.

## List publications, then fetch each record

`GET /api/v1/publications/xml` returns a paginated list of publication metadata and ids. Fetch each publication body with `GET /api/v1/publications/{id}/xml`.

Store the id as the publication key. Check it before fetching the detail document so reruns can skip bodies you already hold.

Both endpoints support `/xml`, `/csv`, `/pdf`, and `/docx` variants.

A typical list request for a day of HR publications:

```
GET https://amtsblattportal.ch/api/v1/publications/xml
    ?publicationStates=PUBLISHED
    &tenant=shab
    &rubrics=HR
    &publicationDate.start=2026-07-09
    &publicationDate.end=2026-07-09
    &pageRequest.page=0
    &pageRequest.size=2000
```

## Parameters for an HR publication list

| Parameter | Value | Note |
| --- | --- | --- |
| `publicationStates` | `PUBLISHED` | Mandatory. Include it to receive records. |
| `tenant` | `shab` | The federal commercial gazette. Cantonal tenants exist. |
| `rubrics` | `HR` | Handelsregister. Use `HR`. The documentation listed `BH` when last checked. |
| `subRubrics` | — | **Ignored by the live API.** See below. |
| `publicationDate.start` / `.end` | ISO date | Inclusive dates at day granularity. |
| `cantons` | `ZH`, `GE`, … | Optional. |
| `pageRequest.page` / `.size` | 0-based / max 2,000 | The only documented hard limit. |
| `pageRequest.sortOrders` | `column:PUBLICATION_DATE\|direction:DESC` |  |

**The subRubrics trap.** In our production test, `subRubrics=HR01` also returned HR02 and HR03 records. Request `rubrics=HR`, then classify each fetched publication from `meta.subRubric`. Otherwise, a new-registration table can quietly include changes and deletions.

Classify each HR publication into one of these sub-rubrics:

- `HR01`: Neueintragungen, new entries. Incorporations and branch creations.
- `HR02`: Mutationen, changes. Seat moves, address changes, name changes, capital increases, mergers.
- `HR03`: Löschungen, deletions.

## Read the structured fields first

An HR detail document contains structured `meta` and `content` blocks. Use those fields for company identity and attributes. They also cover common change types. Keep `publicationText` for acts that lack a dedicated structured field.

| Need | Read from | Detail |
| --- | --- | --- |
| Identity and deduplication | `meta.id` | Publication UUID |
| Publication type | `meta.rubric`, `meta.subRubric` | Classify after fetching the detail document |
| Company identity | `content.company` | Name, seat, UID, legal form, address |
| Change type | `content.transaction` | Flags for seat, address, name, and capital changes |
| Register journal reference | `journalDate`, `journalNumber` | Tagebuch entry and effective date |
| Previous notice | `lastFosc*` | Reference to the publication this one supersedes |

HR02 records expose change flags in `transaction`, including `seatChanged`, `addressChanged`, `nameChanged`, and `capitalChanged`. Name changes include old and new values. To identify a capital increase, compare the old and new nominal figures when `capitalChanged` is set. Keyword detection over the publication text is still useful for mergers and branch creations, which lack a dedicated structured flag.

The schemas are published at `https://amtsblattportal.ch/api/v1/schemas/bulk-export.xsd` and per sub-rubric at `https://amtsblattportal.ch/api/v1/schemas/shab/1.26/HR0x-export.xsd`.

## Validate capital figures

Swiss display text uses an apostrophe as the thousands separator, and the gazette occasionally publishes one where a decimal point belongs. We have seen a capital figure overstated by a factor of a hundred that way. The record rose to the top of a monthly capital-increase report before the anomaly was caught.

Flag an SA below CHF 100,000 nominal capital and a GmbH below CHF 20,000 for review. Also flag a single mutation that changes nominal capital by 100 times or more. These checks identify likely parsing or source-data errors. Send the record to review and preserve the original value.

## Reconcile cancellations in every daily run

A publication can be `PUBLISHED` or `CANCELLED`. Reconcile both states on every run because a cancellation may affect a publication already stored or acted on.

Run the two states as separate passes and dedupe the overlapping ids with `CANCELLED` winning. Reconcile the body against the state you discovered it under. Some bodies omit the field.

The daily reconciliation algorithm:

1. List both `PUBLISHED` and `CANCELLED` records for the previous seven calendar days through today. Keep one row per id, with `CANCELLED` taking precedence if the id appears in both lists.
2. Upsert the state for every listed id, including ids already stored. This is how a previous publication becomes cancelled in your database.
3. Fetch detail documents for ids whose body is missing or whose state change requires another copy. Cap concurrency and retry transient failures with exponential backoff.
4. Parse structured fields first. Use `publicationText` for the remaining acts.

In 305,902 publications measured over the past twelve months, the median interval between a change taking effect and its publication was five days. Of those publications, 38% appeared within three days. We re-list the previous seven calendar days on every daily run to absorb late and corrected records.

For scale: on 9 July 2026 there were about 1,310 HR publications out of roughly 1,813 SHAB publications that day.

## An open-source parser for these publications

The parser behind our own import is published under the MIT licence as [python-shab-parser](https://github.com/prospex-ch/python-shab-parser). It reads an Amtsblattportal XML document into typed dataclasses, then classifies each publication into events: incorporation, seat move, capital increase, deletion. Namespace differences between the sub-rubrics are absorbed, so an HR01, HR02 or HR03 document parses the same way.

Its optional HTTP client covers the discovery and fetch loop described above, rate-limited to one request per second, with exponential backoff on transient failures. The [documentation](https://shab-parser.readthedocs.io/en/latest/) sets out the event types and the full API reference.

## Usage terms and legal status

The operator's terms disclaim completeness and accuracy. The signed PDF is the legally authoritative version of each publication. Review the current API terms before commercial reuse. This guide describes our technical implementation and is not legal advice.

A gazette notice tells you which legal change was published. Deciding whether the company is worth contacting usually requires context from its website and current hiring.

[Where Swiss company data actually lives](https://prospex.ch/guides/swiss-company-data-sources/) explains those sources, and [what each of them is good for](https://prospex.ch/guides/compare-swiss-company-data/) compares them on the questions a daily import has to answer.

## More guides

- [How to Track Swiss Companies That Just Raised Capital](https://prospex.ch/guides/track-capital-increases/)
- [Reading SHAB/FOSC: A Practical Guide for Salespeople](https://prospex.ch/guides/reading-shab-fosc/)
- [Where Swiss Company Data Actually Lives](https://prospex.ch/guides/swiss-company-data-sources/)
- [Swiss Company Changes: What They Tell You and What They Do Not](https://prospex.ch/guides/buying-signals-swiss-market/)
- [Zefix, Moneyhouse or SHAB: Which One to Use](https://prospex.ch/guides/compare-swiss-company-data/)
- [What Happens When a Swiss Company Increases Its Capital](https://prospex.ch/guides/what-capital-increase-means/)
- [Prospecting in Romandie: A Field Guide](https://prospex.ch/guides/prospecting-romandie/)
- [Swiss Trademark Filings as an Early Product-Launch Signal](https://prospex.ch/guides/trademark-filings-signal/)
- [How to Check Out a Swiss Company: Name, UID, and What the Registers Tell You](https://prospex.ch/guides/check-swiss-company/)
- [How to Monitor a Swiss Company for Changes, Free](https://prospex.ch/guides/monitor-swiss-company/)
- [How Big Is That Swiss Company? Sizing a Private Firm from Public Records](https://prospex.ch/guides/size-a-swiss-company/)
- [The Zefix REST API: Endpoints, Credentials and Identifiers](https://prospex.ch/guides/zefix-rest-api/)
- [Swiss Buying Signals in Clay and n8n](https://prospex.ch/guides/swiss-signals-clay-n8n/)
- [Sizing a Swiss Target Market from Public Data](https://prospex.ch/guides/size-a-swiss-target-market/)
- [The 100 Addresses That Host the Most Companies in Switzerland](https://prospex.ch/guides/domiciliation-addresses-switzerland/)
- [Finding Companies Like Your Best Customers in Switzerland](https://prospex.ch/guides/similar-companies-switzerland/)
- [Reactivating Dormant and Closed-Lost Accounts](https://prospex.ch/guides/reactivate-dormant-accounts/)
- [How Big Is the Swiss B2B Market, Really?](https://prospex.ch/guides/swiss-b2b-market-size/)
- [Who Is Entering Switzerland: Foreign Subsidiaries and Branches](https://prospex.ch/guides/foreign-companies-entering-switzerland/)
- [Swiss Directorship Concentration: What a Year of Officer Changes Shows](https://prospex.ch/guides/swiss-directorship-concentration/)
- [Gender Composition of Swiss Company Officers](https://prospex.ch/guides/gender-swiss-company-officers/)

[All guides](https://prospex.ch/guides/)

## The numbers behind this

- [The 25 largest capital increases in Switzerland (last 12 months)](https://prospex.ch/signals/largest-capital-increases/)
- [The 25 largest mergers in Switzerland (last 12 months)](https://prospex.ch/signals/largest-mergers/)

[All rankings](https://prospex.ch/signals/)

Build a market from your own criteria, on this data.

[See an example market](https://prospex.ch/market-builder/)

[Or build your own, free](https://prospex.ch/app/accounts/signup/)