# Japan NTA Corporate Change Review (`remarkable_whipscorpion/nta-corporate-change-review`) Actor

Review published NTA daily change archives for known Japanese corporate numbers, preserving ordered correction facts and explicit archive coverage for human supplier-master review.

- **URL**: https://apify.com/remarkable_whipscorpion/nta-corporate-change-review.md
- **Developed by:** [Kagerou AP](https://apify.com/remarkable_whipscorpion) (community)
- **Categories:** Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / completed corporate archive review

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?

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

## Japan NTA Corporate Change Review

Give this Actor the Japanese corporate numbers already held in your supplier or customer master. It reviews one to seven published National Tax Agency (NTA) daily change archives and returns matching source facts in order, with explicit coverage for a human master-update queue. It uses the public Unicode CSV archives without an NTA API application ID.

The report covers only the selected archives actually listed by NTA. It does not establish a company's current master state, legal status, tax position, creditworthiness or solvency, and it does not update your ERP.

### Input and API example

The default, console prefill and API example use the same live-source input:

```json
{
  "corporateNumbers": ["1010001030440", "1010001038748"],
  "archiveCount": 1
}
```

Supply one to 1000 known 13-digit numbers as strings. Duplicates are reviewed once. `archiveCount` selects the latest one to seven **listed archives**, not calendar days. The source may publish no archive on holidays or may delay publication.

To choose dates explicitly, supply `archiveDates` with one to seven actual publication dates in `YYYY-MM-DD` form. This replaces `archiveCount` selection. Every date is checked against the current source listing; an unlisted date remains unknown and makes the review incomplete. Do not assume a date is still retained because it appeared in an older sample.

There is no fixed-data demo mode. These sample corporate numbers matched the archive published **2026-10-09**, as observed during source validation. Future default runs inspect the latest source archive and can legitimately return zero matching facts.

### Results and coverage

The default Dataset contains `recordType: "change_fact"` rows, followed by a `recordType: "coverage"` row. The default key-value store's `OUTPUT` record contains the same facts in `report.facts`, the coverage in `report.coverage`, Dataset rows in `results`, and the billing/publication state.

Facts retain the source's sequence, process and correction flags; update and change dates; name and address parts; closure date/cause and successor corporate number; latest and search-exclusion flags; archive publication date; downloaded ZIP SHA-256; and observation time. Rows are ordered by archive publication date, then source sequence. Multiple rows for the same corporation are retained. A correction is not labelled as a newly occurring business event.

`imageFieldsIncomplete` warns that name or address image fields prevent a complete textual representation. Image contents are not downloaded. Source deletion process `99` or a source deletion skeleton can contain blank fields. `sourceDeletionNotice`, `identifyingFieldsRedacted` and `redactionReason` make suppression explicit. `sourceSearchExcluded` is the original `hihyoji` flag and does not mean legal closure. Identifying name/address fields in deletion or withdrawn search-excluded rows are redacted. A later deletion or exclusion also suppresses earlier identifying facts for that corporate number in the same packet.

Coverage includes `availableArchives`, `selectedArchives`, `inspectedArchives`, `failedArchives`, `unlistedDates`, `complete`, `sourceFailure`, `matchedFacts` and `archiveDetails` (archive hash, inspected rows and byte sizes). Status means:

| Status | Meaning |
| --- | --- |
| `complete_selected_archives` | Every selected archive was listed and fully inspected within the limits. Zero matches is useful coverage of those archives only. |
| `partial_unknown` | Some requested coverage is unavailable, failed or capped. Retained facts are partial evidence; missing facts cannot establish no change or closure. |
| `budget_exhausted` | The run cannot fund one useful report. Diagnostics contain no useful matched facts or selected/inspected archive identifiers. |
| `aborted` | The run was stopped before source review. Diagnostics do not establish archive coverage. |

`OUTPUT` includes `chargedUnits`, `chargedUnitsExact`, `completed`, `publication`, `billingState` and `stopReason`. Inspect these fields when processing interrupted or resumed runs. An uncertain prior charge is stopped for review rather than charged blindly again.

### Price and budget

The custom Pay-per-event price is **$0.50 for one complete useful report**, event `corporate_archive_review`. A valid, nonempty watchlist and complete review of all selected listed archives qualifies, including a report with zero matching facts. The fee is per report; there is no additional custom archive or row fee and no default Dataset item charge.

Invalid input, incomplete or unlisted requested dates, missing source, failed archives and capped partial reviews have **zero custom review events**. Partial source-failure facts and honest coverage may be saved under that documented exception. The automatic platform start event is **$0.00005**, separate from the custom event. Zero custom events does not mean the total run is free. Platform usage and plan terms also apply.

Funded report capacity is determined before writing any useful Dataset, key-value store or checkpoint content. A useful complete report is made accessible before the exact custom event is emitted. A run that cannot fund one report saves diagnostics only. Allow for the separate start event when setting a run's maximum charge; one report plus that event is $0.50005. Resume handling prevents a second report fee for the same completed report in the same run. If OUTPUT is lost while prior fees or Dataset rows remain, the Actor stops without producing or charging a second report.

### Source-backed sample

These are selected source fields observed during validation on 2026-10-13 JST in `diff_20261009.csv`, published on 2026-10-09; they are not a promise about a future live run:

| Corporate number | Source process | Source change date | Source update date | Source name |
| --- | --- | --- | --- | --- |
| `1010001030440` | `12` | `2026-09-14` | `2026-10-09` | 三井住友海上エイジェンシー・サービス株式会社 |
| `1010001038748` | `11` | `2026-10-07` | `2026-10-09` | アルソシアＲｅビルド株式会社 |

The downloaded ZIP was 172,050 bytes, SHA-256 `9741042fbc801aa3bca7b2d2a3f3bc55a13f91e84d7a525c2bb0af490388bae3`. Its CSV had 2,750 rows of 30 columns. The hash identifies downloaded bytes; OpenPGP signature verification is not performed. A fully inspected selection with these two facts is one report at the fixed $0.50 custom price, rather than a separate charge for each fact.

### Limits and source failures

Each run is capped at 1000 corporate numbers, seven archives, 2 MB of downloaded ZIP per archive, 15 MB of decoded data per archive, 50,000 rows per archive and 5000 matching facts in total. The HTTP workflow is bounded to 14 source requests, 25 seconds per request and 120 seconds for the run. Hitting a limit makes coverage partial and prevents a custom review fee.

The Actor obtains current form tokens, archive file identifiers and anonymous session cookies from the official source. HTTP 403, 429, a challenge page or incompatible source form stops source processing. There is no browser, login, paid upstream service, proxy or manual-session fallback.

### Source, licence and processing

Source: [National Tax Agency Corporate Number Publication Site — daily change downloads](https://www.houjin-bangou.nta.go.jp/download/sabun/). Field definitions: [NTA download resource specification, version 4](https://www.houjin-bangou.nta.go.jp/documents/k-resource-dl-ver4.pdf).

The source is provided under the [NTA terms and Public Data Licence 1.0](https://www.houjin-bangou.nta.go.jp/riyokiyaku/), subject to the terms and any separately marked exceptions. This Actor selects supplied corporate numbers, normalizes field names, orders published rows, redacts identifying fields in search-excluded rows, and adds coverage, provenance and observation time. The resulting report is processed by this Actor and is not prepared or endorsed by NTA. Source attribution and the processing notice are included in output. Third-party works and government logos are not copied.

### Local development

The implementation uses Node.js and pinned Apify SDK 3.7.2 with bounded HTTP, ZIP and CSV parsing. Install the locked dependencies with `npm ci --ignore-scripts`, then run the package's test command. In a Windows sandbox that blocks Node child spawning, `test/launch.ps1` launches the isolated test process directly. Direct dependencies are pinned to Apify 3.7.2, adm-zip 0.6.1 and csv-parse 7.0.2. Every SDK test must start a child process with a SKU-specific absolute `CRAWLEE_STORAGE_DIR` set **before the first SDK import**, and assert the SDK's resolved storage base. Do not use or drop a shared default storage directory.

Local source validation does not establish Apify cloud access or native publication. Those checks and publication require a separate release decision.

# Actor input Schema

## `corporateNumbers` (type: `array`):

One to 1000 known 13-digit Japanese corporate numbers as strings. Duplicate numbers are reviewed once. The two default numbers had published matching facts in the archive published on 2026-10-09; future latest archives may contain no matches.

## `archiveCount` (type: `integer`):

Inspect the latest one to seven Unicode daily change archives currently listed by NTA. This is a count of published archives, not calendar days. Ignored when archiveDates is supplied.

## `archiveDates` (type: `array`):

One to seven actual YYYY-MM-DD publication dates. When supplied, these dates replace archiveCount selection and must be present in the current official archive listing. Unlisted dates produce partial/unknown coverage with no custom review fee; they never mean no change.

## Actor input object example

```json
{
  "corporateNumbers": [
    "1010001030440",
    "1010001038748"
  ],
  "archiveCount": 1
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `output` (type: `string`):

No description

# 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 = {
    "corporateNumbers": [
        "1010001030440",
        "1010001038748"
    ],
    "archiveCount": 1
};

// Run the Actor and wait for it to finish
const run = await client.actor("remarkable_whipscorpion/nta-corporate-change-review").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 = {
    "corporateNumbers": [
        "1010001030440",
        "1010001038748",
    ],
    "archiveCount": 1,
}

# Run the Actor and wait for it to finish
run = client.actor("remarkable_whipscorpion/nta-corporate-change-review").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 '{
  "corporateNumbers": [
    "1010001030440",
    "1010001038748"
  ],
  "archiveCount": 1
}' |
apify call remarkable_whipscorpion/nta-corporate-change-review --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,remarkable_whipscorpion/nta-corporate-change-review"
        }
    }
}
```

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/cl9HhLcqnbj5MNzfP/builds/oLX7f7reynm43KZcD/openapi.json