# Japan Supplier & KYB Change Monitor (`japan_signal_lab/japan-signal-lab`) Actor

Detect official Japanese supplier and KYB changes from the NTA daily difference file—closures, mergers, name changes, and address changes—with source provenance in every result.

- **URL**: https://apify.com/japan\_signal\_lab/japan-signal-lab.md
- **Developed by:** [Japan Signal Lab](https://apify.com/japan_signal_lab) (community)
- **Categories:** Automation, Developer tools, Agents
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.20 / 1,000 monitored corporate numbers

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Japan Supplier & KYB Change Monitor

**Monitor a fixed Japanese corporate-number watchlist against the National Tax Agency's daily difference file.** Each matching event keeps the official process code, source page, file number, publication date, archive name, and retrieval time needed for an auditable supplier, KYB, or CRM review.

This is a **change-monitoring** Actor, not a static company database and not a legal registry. It is designed for teams that already know the 13-digit corporate numbers they need to watch and want a clean, daily signal for relevant registry changes.

### Who it is for

- **Supplier and procurement teams** checking whether Japanese vendors were closed, merged, renamed, or moved.
- **KYB and compliance operations** keeping an existing Japanese entity watchlist current.
- **CRM and master-data teams** identifying official name or address changes before records drift.
- **Investors, lenders, and M\&A researchers** monitoring a known portfolio, counterparty, or target list.

It does not resolve names to corporate numbers, enrich firmographics, issue legal opinions, send email itself, or retain comparison state. Schedule the Actor in Apify and connect the Dataset to your normal workflow or webhook destination if you need recurring delivery.

### Why this instead of a company-data lookup

Many tools return a current Japanese company profile. This Actor reads one official daily change file once, performs an exact lookup against up to 10,000 supplied corporate numbers, and returns **only newly published matching events**. A zero-row result is therefore useful: no watched corporation appeared in the selected daily difference file.

The result preserves `sequenceNumber`; a daily source file can contain more than one history row for a corporation. It never guesses a change type from a name or address comparison.

### Official source, attribution, and limits

The source of truth is the [National Tax Agency Corporate Number Publication Site daily difference download](https://www.houjin-bangou.nta.go.jp/download/sabun/index.html). The site publishes ZIP-compressed Unicode XML files on business days, normally around 16:00 JST, and keeps a rolling set of files. Corporate numbers are public identifiers; each output row includes this source attribution:

> Created by Japan Signal Lab based on the National Tax Agency Corporate Number Publication Site (https://www.houjin-bangou.nta.go.jp/download/sabun/index.html).

The NTA content is governed by its [Terms of Use](https://www.houjin-bangou.nta.go.jp/en/riyokiyaku/), including the requirement to cite the source and to state that content has been processed. This Actor does both in its output. It uses the download endpoint rather than the NTA Web API, so it does not require an NTA application ID.

The NTA publishes an OpenPGP signature beside its archives. This Actor does **not** verify that signature yet, and does not claim cryptographic verification. Treat outputs as operational monitoring signals and confirm material decisions against the official registry or other appropriate evidence.

### Events

`processCode` is the unmodified official NTA process code. `eventType` is only a stable English projection:

| Code | `eventType` | Official meaning |
| --- | --- | --- |
| 01 | `new` | Corporate number newly assigned |
| 11 | `name_changed` | Name changed |
| 12 | `domestic_address_changed` | Domestic address changed |
| 13 | `foreign_address_changed` | Foreign address changed |
| 21 | `closed` | Registry record closed, including liquidation or merger dissolution |
| 22 | `restored` | Registry record restored |
| 71 | `absorption_merger` | Surviving corporation completed an absorption merger |
| 72 | `absorption_merger_invalidated` | Absorption merger invalidated |
| 81 | `trade_name_registration_deleted` | Trade-name registration deleted |
| 99 | `deleted` | Corporate-number designation/publication deleted |

Unknown future NTA process codes remain visible as `eventType: "unknown"`; they are never silently recategorized.

### Input

```json
{
  "companyNumbers": ["0110005003755", "1300005008220"],
  "sourceDate": ""
}
```

- `companyNumbers` — required; one 13-digit Japanese corporate number per entry, with 1 to 10,000 unique values. Hyphens and spaces are accepted. Matching is exact after only that display normalization; company names are never fuzzy-matched.
- `sourceDate` — optional `YYYY-MM-DD`; selects a date among the files currently retained by the NTA. Omit it to use the newest available XML difference file.

For daily monitoring, leave `sourceDate` empty and create an Apify schedule after the NTA's normal publication time. To replay or audit a retained day, specify that file date explicitly.

### Output

Each Dataset item is a matching official change event. Important fields include:

```json
{
  "companyNumber": "0110005003755",
  "sequenceNumber": 12,
  "name": "Example Co., Ltd.",
  "eventType": "name_changed",
  "processCode": "11",
  "processLabel": "Name changed",
  "changeDate": "2026-08-25",
  "address": "東京都千代田区...",
  "source": {
    "provider": "National Tax Agency Corporate Number Publication Site",
    "sourcePageUrl": "https://www.houjin-bangou.nta.go.jp/download/sabun/index.html",
    "attribution": "Created by Japan Signal Lab based on the National Tax Agency Corporate Number Publication Site (https://www.houjin-bangou.nta.go.jp/download/sabun/index.html).",
    "publishedDate": "2026-08-25",
    "fileNo": 27873,
    "archiveName": "diff_20260825.zip",
    "retrievedAt": "2026-08-26T00:00:00.000Z"
  }
}
```

The `SUMMARY` record in the default key-value store reports the requested and processed unique-watchlist sizes, source provenance, source-row count, matching-row count, PPE charge counts/limit flags, and run duration. If a user sets a maximum run cost below the full request, `processedWatchlistSize` makes the partial result explicit. No result rows means no processed watched corporate number occurred in that file; it does not prove that no real-world change has happened.

### Common workflows

#### Supplier closure and merger watch

Schedule a daily run after 16:00 JST with your supplier corporate-number list. Route Dataset rows with `eventType` `closed`, `absorption_merger`, or `deleted` to an internal review. Preserve the included process code and source fields with the case record.

#### KYB refresh

Run a counterparty watchlist daily or weekly. Use `name_changed`, `domestic_address_changed`, `foreign_address_changed`, and `restored` rows to queue your ordinary-KYB refresh process. This Actor reports the public-source event; it does not determine risk level or pass/fail status.

#### CRM master-data hygiene

Run your current customer or vendor corporate-number list on a schedule, then update only records represented by returned events. The exact 13-digit number remains the primary key even when the displayed name or address changes.

### Store listing copy

**Title**\
Japan Supplier & KYB Change Monitor

**Short description**\
Detect official Japanese supplier and KYB changes from the NTA daily difference file—closures, mergers, name changes, and address changes—with source provenance in every result.

**Search keywords**\
Japan corporate number, Japanese company monitoring, supplier monitoring, vendor risk, KYB, KYC, compliance operations, CRM data hygiene, merger detection, company closure, corporate registry, due diligence.

**Positioning**\
For a known Japanese entity list, this is a daily, audit-ready change signal—not a general-purpose company database or a name search tool.

### Pay per event pricing

Pricing is active in the Apify Store. The Actor verifies this event contract at runtime and stops before processing if the Console configuration differs, preventing an unconfigured or duplicate event from being billed.

| Event | What is billed | Price |
| --- | --- | ---: |
| `apify-actor-start` | One Actor run (Apify synthetic event; charged automatically) | $0.005/run |
| `monitored-corporate-number` | Each corporate number actually processed from the supplied watchlist | $0.00020/company |
| `nta-registry-change-event` | Each matching official NTA change event written to the Dataset | $0.010/event |

The Store price uses the three events above; `apify-default-dataset-item` is deliberately not configured because it would duplicate the per-change charge. The Actor uses the SDK's custom event name when writing a change result, and checks the user's maximum run cost before every billable unit. A deliberately low maximum produces a successful, transparently partial result rather than an over-limit charge.

For 22 scheduled runs per month, the price before matching events is about $0.55 for 100 companies, $4.51 for 1,000, and $44.11 for 10,000. Matching change events add $0.01 each. The Store currently includes platform usage in the PPE price. The Actor fixes memory at 256 MB to keep runtime bounded.

### Live verification record

Verified on 2026-08-26 JST against the official difference file published for **2026-08-25** (NTA file number `27873`, archive `diff_20260825.zip`). The archive downloaded, unzipped, and parsed into **2,222** source rows. Corporate number `1010001008916` produced one Dataset record for `旭化成パックス株式会社`, official process `21`, projected event `closed`.

The same input was also run in Apify Cloud successfully: one Dataset record, about 4 seconds elapsed, and a displayed run cost of `$0.000`. That display is rounded and is not evidence that production usage is free. Review real usage and Payouts data before making a future price change.

| Unique monitored companies | Source rows | Matching rows | Local match + normalize time |
| ---: | ---: | ---: | ---: |
| 1 | 2,222 | 1 | 3.027 ms |
| 100 | 2,222 | 1 | 2.085 ms |
| 1,000 | 2,222 | 1 | 2.054 ms |
| 10,000 | 2,222 | 1 | 4.752 ms |

These are prototype measurements, not a cloud capacity guarantee. The source archive is read once per run and limited to 32 MiB before ZIP processing; the selected XML member is limited to 64 MiB before it is parsed.

After adding the archive-size guard and output provenance field, the official `2026-08-25` file was rechecked on 2026-08-26 JST: file `27873` (`diff_20260825.zip`) downloaded, unzipped, and parsed to 2,222 rows in 511 ms; the one-row `1010001008916` closure match remained unchanged.

### Development

```bash
npm ci
npm test
npm run build
npm audit --json
```

The production container builds TypeScript in a first stage, installs only production dependencies in the final stage, and runs `dist/main.js`. No API token, cookie, payment setting, or account identifier belongs in this repository.

# Actor input Schema

## `companyNumbers` (type: `array`):

One known 13-digit Japanese corporate number per item. Hyphens and spaces are accepted and removed before exact matching. Company names are never fuzzy-matched.

## `sourceDate` (type: `string`):

Use YYYY-MM-DD to select one NTA file that is still retained by the source. Leave empty for the newest XML file. For recurring monitoring, leave it empty and schedule the Actor after the normal NTA publication time.

## Actor input object example

```json
{
  "companyNumbers": [
    "0110005003755"
  ]
}
```

# Actor output Schema

## `changeEvents` (type: `string`):

Only events whose 13-digit corporate number exactly matches the supplied watchlist. Every row includes official source provenance.

## `summary` (type: `string`):

Requested and processed watchlist sizes, selected official source file, source-row count, matching-row count, PPE charge counts/limit flags, and duration.

# 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 = {
    "companyNumbers": [
        "0110005003755"
    ],
    "sourceDate": ""
};

// Run the Actor and wait for it to finish
const run = await client.actor("japan_signal_lab/japan-signal-lab").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 = {
    "companyNumbers": ["0110005003755"],
    "sourceDate": "",
}

# Run the Actor and wait for it to finish
run = client.actor("japan_signal_lab/japan-signal-lab").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 '{
  "companyNumbers": [
    "0110005003755"
  ],
  "sourceDate": ""
}' |
apify call japan_signal_lab/japan-signal-lab --silent --output-dataset

```

## MCP server setup

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

```

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/0NQVu328uYLMIEeJ3/builds/insAqgKe6EPvERCU2/openapi.json