# Swiss Official Gazette Scraper (SHAB / FOSC / Handelsregister) (`actor-x/shab-actor`) Actor

Extract real-time Swiss corporate data. Monitor the commercial register (Handelsregister / Registre du commerce) and bankruptcies (Konkurse / Faillites).

- **URL**: https://apify.com/actor-x/shab-actor.md
- **Developed by:** [Remo](https://apify.com/actor-x) (community)
- **Categories:** Developer tools, Automation, News
- **Features:** Limited permissions
- **Stats:** 4 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.0175 / result

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 🇨🇭 SHAB Scraper — Swiss Official Gazette of Commerce Extractor

**The industry-standard, enterprise-grade extraction tool for the Swiss Official Gazette of Commerce (Schweizerisches Handelsamtsblatt - SHAB / Feuille officielle suisse du commerce - FOSC / Foglio ufficiale svizzero di commercio - FUSC).**

Stop wrestling with complex, deeply nested APIs. The SHAB Scraper transforms raw Swiss commercial registry and bankruptcy data into **clean, flattened, fully enriched, and AI-ready JSON records**. Whether you are building compliance monitors, conducting due diligence, or training financial LLMs, this is the most robust and reliable way to access Swiss corporate data.

Extract highly structured data from the **Commercial Register (Handelsregister / Registre du commerce)**, **Bankruptcy notices (Konkurse / Faillites)**, **Debt Enforcement (Schuldbetreibungen / Poursuites)**, and official cantonal gazettes (Amtsblatt / Feuille d'avis).

***

### 🏆 Why this is the definitive SHAB integration

- **Enterprise-Grade Data Flattening**: We've done the heavy lifting. Complex, nested debtor data and legal texts are automatically flattened into easy-to-digest fields (`debtorName`, `debtorUid`, `legalRemedy`), saving you hours of data engineering.
- **AI & Agent Ready**: Fully documented dataset and output schemas make this Actor plug-and-play for AI Agents, LLMs, and Apify's MCP (Model Context Protocol).
- **Unmatched Reliability (Auto-Chunking)**: The SHAB API strictly limits queries to 3,000 results. Our built-in auto-chunking engine automatically detects massive queries (like multi-year historical backfills) and recursively splits them into safe sub-windows, ensuring you never drop a single record.
- **Comprehensive Coverage**: Native support for **all 16 federal rubrics** and **15 hosted cantonal gazettes** (including Zürich, Bern, Basel, Ticino).
- **Human-Readable Enrichment**: Arcane API codes (e.g., `HR01`, `KK02`) are instantly enriched with human-readable, translated names (`Neueintragung`, `Konkurspublikation`), paired with full municipality lookups.

***

### 🚀 Strategic Use Cases

- **Due Diligence & KYC**: Set up daily monitors on new commercial register entries (HR01 / Neueintragung), mutations (HR02 / Mutation), or deletions (HR03 / Löschung) for automated risk profiling.
- **Credit Risk & Bankruptcy Intelligence**: Feed real-time bankruptcy (KK / Faillites) and debt enforcement (SB) publications directly into your CRM or risk models.
- **Legal & Regulatory Research**: Execute full-text extraction of court rulings (UV), inheritance proceedings (ES / Erbschaft), or debt restructuring (NA / Nachlassverfahren).
- **B2B Lead Generation**: Automatically extract fresh company UIDs (`CHE-XXX.XXX.XXX`), legal forms, registered addresses, and executive board changes.

***

### ⚙️ Input Parameters

Configure your extraction with granular precision:

| Parameter | Type | Default | Description |
|---|---|---|---|
| `rubrics` | array | `[]` (all) | Target specific categories (e.g., `["HR", "KK"]`). Leave empty for all 16. |
| `subRubrics` | array | `[]` | Laser-target sub-categories (e.g. `["HR01", "HR02"]`). |
| `publicationStates` | array | `["PUBLISHED"]` | Fetch `PUBLISHED` and/or `CANCELLED` notices. |
| `language` | string | `""` (all) | Filter strictly by language: `de`, `fr`, `it`, `en`. |
| `tenants` | array | `["shab"]` | Target the federal gazette (`shab`) or cantonal gazettes (e.g., `kabzh`). |
| `searchPeriod` | string | `LAST7DAYS` | Quick filters: `TODAY`, `LAST7DAYS`, `LAST30DAYS`, or `CUSTOM`. |
| `startDate` | string | — | Required if using `CUSTOM`. Format: `YYYY-MM-DD`. |
| `endDate` | string | — | Required if using `CUSTOM`. Format: `YYYY-MM-DD`. |
| `includeContent` | boolean | `true` | Extract the full, structured payload (highly recommended). |
| `enrichLookups` | boolean | `true` | Embed human-readable names and translated rubrics directly into the data. |
| `autoChunkOnLargeResults`| boolean | `true` | Automatically bypass the 3,000-item API limit by date-chunking huge queries. |
| `maxItems` | integer | `0` (unlimit) | Set a hard cap on results (ideal for testing and schema validation). |
| `pageSize` | integer | `100` | Items per API request. Max 100. |

***

### 📊 The Gold-Standard Output Dataset

Each publication is delivered as a single, perfectly flattened JSON object designed for immediate downstream processing.

#### Core Fields

| Field | Type | Description |
|---|---|---|
| `id` | string | Unique SHAB identifier. |
| `publicationNumber` | string | The official publication sequence (e.g., `HR02-1006640827`). |
| `publicationDate` | string | ISO 8601 publication timestamp. |
| `title` | string | Publication title in the extracted language. |
| `language` | string | The language of the publication (`de`, `fr`, `it`). |
| `rubric` / `subRubric` | string | Human-readable category and sub-category (e.g., "Bankruptcies"). |
| `tenant` | string | The publishing gazette name. |
| `cantons` | array | Applicable Swiss canton codes (e.g., `["ZH", "ZG"]`). |
| `debtorName` | string | **\[Enriched]** Automatically resolved name of the target person or company. |
| `debtorAddress` | string | **\[Enriched]** Formatted primary address of the debtor. |
| `debtorType` | string | `PERSON` or `COMPANY`. |
| `debtorUid` | string | The official Swiss UID (`CHE-XXX.XXX.XXX`), if applicable. |
| `debtorPlaceOfOrigin`| string | The person's place of origin, if applicable. |
| `registrationOffice`| string | Responsible office (e.g., "Konkursamt Zürich"). |
| `registrationOfficeAddress` | string | Formatted address of the registration office. |
| `legalRemedy` | string | Cleaned legal basis text (HTML breaks converted to safe newlines). |
| `claimDeadline` | string | Deadline for creditors to file claims, if applicable. |
| `url` | string | Direct permalink to the official SHAB / FOSC publication. |

#### Pristine JSON Example

```json
{
  "id": "00f4fc49-2b3d-4def-8bf3-271e5d50bde2",
  "publicationNumber": "KK04-0000054869",
  "publicationDate": "2026-01-30T00:00:00.000Z",
  "title": "Kollokationsplan und Inventar Klara Hinterberger, ausgeschlagene Erbschaft",
  "language": "de",
  "rubric": "Konkurse",
  "subRubric": "Kollokationsplan und Inventar",
  "tenant": "Schweizerisches Handelsamtsblatt",
  "cantons": ["SG"],
  "debtorName": "Klara Hinterberger, ausgeschlagene Erbschaft",
  "debtorAddress": "Langgasse 120 9008 St.Gallen",
  "debtorType": "PERSON",
  "debtorPlaceOfOrigin": "Altstätten SG",
  "registrationOffice": "Konkursamt St.Gallen",
  "registrationOfficeAddress": "Davidstrasse 27 9000 St. Gallen",
  "legalRemedy": "Ein Gläubiger, der den Kollokationsplan anfechten will...",
  "claimDeadline": "2026-02-19T00:00:00.000Z",
  "url": "https://www.shab.ch/shab/publication-detail/00f4fc49-2b3d-4def-8bf3-271e5d50bde2?lang=de"
}
```

***

### 📈 Key-Value Store: Run Summary

For programmatic workflow control, the Actor generates a real-time analytics payload at the end of every successful run. Found in the default Key-Value Store under `RUN-SUMMARY`:

```json
{
  "publicationsPushed": 14205,
  "dateWindows": 8
}
```

*(Note: `dateWindows` indicates how many sub-queries the auto-chunker generated to safely bypass the SHAB 3,000-item limits).*

***

### 🗂️ Reference: Rubrics & Data Scope

To optimize your searches, use the following codes for the `rubrics` and `subRubrics` arrays.

| Code | German Name | English Equivalent |
|---|---|---|
| `HR` | Handelsregistereintragungen | Commercial Register Entries |
| `KK` | Konkurse | Bankruptcies |
| `SB` | Schuldbetreibungen | Debt Enforcement |
| `ES` | Erbschaft | Inheritance |
| `FM` | Finanzmarkt | Financial Market |
| `AB` | Arbeit | Employment |
| `AW` | Abhandengekommene Wertpapiere | Lost Securities |
| `AZ` | Anzeigen | Notices |
| `BB` | Weitere Register und Bekanntmachungen Bund | Federal Register Announcements |
| `BH` | Bekanntmachungen nach HR-Verordnung | Commercial Register Ordinance Notices |
| `EK` | Edelmetallkontrolle | Precious Metals Control |
| `LS` | Liquidationsschuldenrufe | Liquidation Calls to Creditors |
| `NA` | Nachlassverfahren | Debt Restructuring Proceedings |
| `SR` | Weitere gesellschaftsrechtliche Schuldenrufe | Other Corporate Law Calls |
| `UP` | Mitteilungen an Gesellschafter | Company Member Notifications |
| `UV` | Gerichtliche Entscheide und Vorladungen | Court Rulings and Summons |

#### Common Sub-Rubric Codes (Targeted Scraping)

| Code | Description (DE / EN / FR) |
|---|---|
| `HR01` | Neueintrag / New commercial register entry / Nouvelle inscription |
| `HR02` | Mutation / Change or amendment / Mutation |
| `HR03` | Löschung / Deletion / Radiation |
| `KK01` | Vorläufige Konkursanzeige / Preliminary bankruptcy notice |
| `KK02` | Konkurspublikation (Schuldenruf) / Bankruptcy publication |
| `KK06` | Schluss des Konkursverfahrens / Close of bankruptcy |
| `SB01` | Betreibungsamtliche Grundstücksteigerung / Property auction |
| `SB02` | Zahlungsbefehl / Payment order / Commandement de payer |
| `ES02` | Erbenaufruf / Call to heirs / Appel aux héritiers |
| `AW01` | Abhandengekommene Wertpapiere / Lost securities notice |

***

### 🏛 Supported Tenants (Gazettes)

Filter by specific cantonal official gazettes using the `tenants` input parameter.

| ID | Gazette / Amtsblatt | Canton |
|---|---|---|
| `shab` | SHAB / FOSC / FUSC (Federal) | — |
| `kabbe` | Amtsblatt des Kantons Bern | BE |
| `kabzh` | Amtsblatt des Kantons Zürich | ZH |
| `kabbs` | Kantonsblatt Basel-Stadt | BS |
| `kabbl` | Amtsblatt des Kantons Basel-Landschaft | BL |
| `kabti` | Foglio ufficiale del Canton Ticino | TI |
| `kabso` | Amtsblatt des Kantons Solothurn | SO |
| `kabzg` | Amtsblatt des Kantons Zug | ZG |
| `kabvs` | Amtsblatt des Kantons Wallis / Bulletin officiel | VS |
| `kabsh` | Amtsblatt des Kantons Schaffhausen | SH |
| `kabsz` | Amtsblatt des Kantons Schwyz | SZ |
| `kabar` | Amtsblatt des Kantons Appenzell Ausserrhoden | AR |
| `kabnw` | Amtsblatt des Kantons Nidwalden | NW |
| `kabow` | Amtsblatt des Kantons Obwalden | OW |

> **Note on external cantons:** Cantons running proprietary, non-federated portals (e.g., AG, GE, VD) are structurally isolated from the unified SHAB API and are currently not supported pending the planned 2027 national platform integration.

***

### 💡 Tips & Known Limits

- **3,000-Item API Ceiling**: Any single date-windowed query to the official API is capped at 3,000 results. Ensure `autoChunkOnLargeResults` is enabled so the Actor can automatically split large custom date ranges into safe sub-windows.
- **Language Filter Narrows Results**: Adding `language="de"` typically reduces the result set by ~30% compared to fetching all languages, as publications are usually filed in the primary language of the canton.
- **Cancelled Publications**: Over 90% of `CANCELLED` SHAB publications belong to `AW01` (lost securities revocations). Searching for cancelled bankruptcies (`KK`) returns very few records.
- **Custom Date Ranges**: When `searchPeriod` is set to `CUSTOM`, both `startDate` and `endDate` MUST be provided in `YYYY-MM-DD` format.

***

### 💰 Pricing Model

This Actor utilizes a strict **Pay-per-event** pricing model. You are charged a base fee for starting the Actor, plus a small fee for each publication successfully extracted and saved to the dataset. Empty runs only cost the Actor Start fee.

**Base Pricing:**

- **Actor Start:** $0.10 per run
- **Result (Dataset Item):** $0.025 per extracted publication

**Volume Discounts:**
Apify automatically applies volume discounts based on your subscription tier:

| Subscription Tier | Actor Start Fee | Price Per Result |
|---|---|---|
| **No discount** | $0.10 | $0.0250 |
| **Bronze** | $0.09 | $0.0225 |
| **Silver** | $0.08 | $0.0200 |
| **Gold** | $0.07 | $0.0175 |

#### Example Calculation (No Discount Tier)

If you start the Actor on a daily schedule to fetch the latest publications, and it extracts **100** new items:

- Actor Start: `$0.10`
- Results (100 \* $0.025): `$2.50`
- **Total Cost:** `$2.60`

# Actor input Schema

## `rubrics` (type: `array`):

One or more SHAB publication categories. Leave empty to fetch all 16 rubrics.

## `subRubrics` (type: `array`):

Restrict to specific sub-rubric codes. Examples: HR01 = Neueintrag (new entry), HR02 = Mutation (change), HR03 = Löschung (deletion); KK01 = Vorläufige Konkursanzeige, KK02 = Konkurspublikation/Schuldenruf; SB01 = Grundstücksteigerung, SB02 = Zahlungsbefehl. Leave empty for all sub-rubrics of the selected rubrics.

## `publicationStates` (type: `array`):

PUBLISHED covers all active notices. Add CANCELLED to also include withdrawn or annulled entries (dominated by AW – lost securities revocations).

## `language` (type: `string`):

Filter by publication language. German (de) covers roughly 70% of SHAB publications. Leave empty for all languages.

## `tenants` (type: `array`):

Which official gazettes to include. The central SHAB (shab) is selected by default. 13 external cantonal gazettes (AG, AI, FR, GE, GL, GR, JU, LU, NE, SG, TG, UR, VD) are not accessible via this API.

## `searchPeriod` (type: `string`):

Predefined date window. Use 'Custom range' together with Start date and End date for precise control.

## `startDate` (type: `string`):

Inclusive lower bound for the publication date. Required when Search period is 'Custom range'. Format: YYYY-MM-DD.

## `endDate` (type: `string`):

Inclusive upper bound for the publication date. Required when Search period is 'Custom range'. Format: YYYY-MM-DD.

## `includeContent` (type: `boolean`):

When enabled, each record includes the full structured content payload (company details, legal text, etc.). Disable to return metadata-only records, which are smaller and faster.

## `enrichLookups` (type: `boolean`):

Fetches rubric, tenant, and municipality reference data once at startup and adds slim \_rubric, \_subRubric, \_tenant, and \_municipality fields to each record (code + multilingual name).

## `proxyConfiguration` (type: `object`):

Optional Apify proxy settings. The SHAB API has no documented rate limits or geo-restrictions; proxy adds resilience for very large runs.

## `maxItems` (type: `integer`):

Hard cap on the number of publications pushed to the dataset. Useful for testing. Set to 0 for no limit.

## `autoChunkOnLargeResults` (type: `boolean`):

When enabled and the query total exceeds 3,000 (the API export ceiling), the actor automatically splits the date range into smaller windows recursively until each fits. Only applies to Custom range queries.

## `pageSize` (type: `integer`):

Number of publications fetched per API request. The SHAB search endpoint caps this at 100. Reduce only for debugging.

## Actor input object example

```json
{
  "rubrics": [
    "HR",
    "KK",
    "SB"
  ],
  "publicationStates": [
    "PUBLISHED"
  ],
  "language": "",
  "tenants": [
    "shab"
  ],
  "searchPeriod": "LAST7DAYS",
  "startDate": "2026-01-01",
  "endDate": "2026-01-31",
  "includeContent": true,
  "enrichLookups": true,
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "maxItems": 0,
  "autoChunkOnLargeResults": true,
  "pageSize": 100
}
```

# Actor output Schema

## `publications` (type: `string`):

The scraped SHAB publications in a flattened, user-friendly JSON format.

## `runSummary` (type: `string`):

A summary of the actor run, including the total number of publications pushed.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "startDate": "2026-01-01",
    "endDate": "2026-01-31",
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("actor-x/shab-actor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "startDate": "2026-01-01",
    "endDate": "2026-01-31",
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("actor-x/shab-actor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startDate": "2026-01-01",
  "endDate": "2026-01-31",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call actor-x/shab-actor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,actor-x/shab-actor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/u0FfZDkaRFR4A5VhV/builds/0Z36W2NZfFgDzfxI2/openapi.json