# HojinCheck — Japanese Corporate Verification API (hojin = 法人 / corporate entity)

API documentation ・ Status as of: 2026-07-14 ・ [日本語版はこちら](https://hojincheck.com/docs/ja) ・ [llms.txt](https://hojincheck.com/llms.txt)

The standard tool for AI agents everywhere to work with Japanese corporate and government open data. HojinCheck is a remote MCP server and REST API for verifying Japanese companies against Japanese **government open data only**. It provides six tools: corporate-number resolution and verification, qualified invoice issuer registration checks, corporate profiles, Japanese address normalization, and business-day calculations. Every successful response embeds its data source(s), the retrieval timestamp, and the notices required by each data source's terms.

- Base URL: `https://hojincheck.com`
- MCP endpoint (Streamable HTTP): `https://hojincheck.com/mcp`
- REST endpoint: `POST https://hojincheck.com/v1/{tool_name}`

## Tool availability (read this first)

| Tool | Status |
|---|---|
| `resolve_company` | Implementation complete; awaiting issuance of the government API application ID (applied 2026-07-13, expected late July to late August 2026). Until connected, this tool returns UPSTREAM_UNAVAILABLE (HTTP 503) in production. |
| `verify_company` | Implementation complete; awaiting issuance of the government API application ID (applied 2026-07-13, expected late July to late August 2026). Until connected, this tool returns UPSTREAM_UNAVAILABLE (HTTP 503) in production. |
| `verify_invoice_number` | Implementation complete; the NTA Invoice Publication Web-API requires an approval-based review (applied 2026-07-12, expected mid to late August 2026). Until approved, this tool returns UPSTREAM_UNAVAILABLE (HTTP 503) in production. |
| `get_company_profile` | Live (connected to gBizINFO REST API v2). |
| `normalize_address` | Live (driven by bundled government master data; unaffected by government API outages). |
| `jp_calendar` | Live (driven by bundled government master data; unaffected by government API outages). |

We deliberately list pending states instead of overclaiming. This table is updated as government credentials are issued.

## Authentication

All tool calls (MCP and REST) require an API key. Pass it as either header:

```
Authorization: Bearer hjc_live_...
X-Api-Key: hjc_live_...
```

- Free tier: **100 requests/day** (resets at midnight JST) and **60 requests/minute** burst. Exceeding either returns `RATE_LIMITED` (HTTP 429) with a `Retry-After` header. The `X-RateLimit-Remaining-Day` response header reports the remaining daily quota.
- Keys are issued via the self-signup page at [https://hojincheck.com/signup](https://hojincheck.com/signup). The key is shown **exactly once** at issuance and cannot be recovered. If signup is temporarily closed, contact drogerdluffy@gmail.com.
- `GET /v1/tools` (tool catalog) and `GET /health` require no authentication.

## Pricing

Published tier plan (v0.2). USD amounts are **reference values** converted at ¥150/US$; the billing currency (JPY or USD) will be finalized at billing launch. **Paid plans are not purchasable yet** — only the free tier is issued today; paid-tier availability will be announced on this page.

| Plan | Price | Included usage | Notes |
|---|---|---|---|
| Free | US$0 (¥0) | 100 requests/day (JST) + 60/min burst | Self-signup |
| Starter | ~US$20/mo (¥2,980/mo) | 10,000 requests/month |  |
| Pro | ~US$65/mo (¥9,800/mo) | 100,000 requests/month | Priority rate limits |
| Business | ~US$199/mo (¥29,800/mo) | 500,000 requests/month | Priority rate limits, self-serve |
| Enterprise | Custom quote | Custom | For SLA / custom contract requirements only — contact drogerdluffy@gmail.com |

**Overage never hard-stops your integration.** When a plan exceeds its included usage, requests are not cut off: rate limiting tightens, and responses use the standard error envelope — HTTP 429 `RATE_LIMITED` (and HTTP 402 once billing launches) — with guidance toward the next tier.

## Connecting via MCP

The MCP endpoint is stateless Streamable HTTP at `https://hojincheck.com/mcp`. Example configuration (Claude Code):

```
claude mcp add --transport http hojincheck https://hojincheck.com/mcp --header "Authorization: Bearer hjc_live_YOUR_KEY"
```

Generic MCP client configuration:

```json
{
  "mcpServers": {
    "hojincheck": {
      "type": "http",
      "url": "https://hojincheck.com/mcp",
      "headers": { "Authorization": "Bearer hjc_live_YOUR_KEY" }
    }
  }
}
```

All six tools are exposed with the same names, input schemas and response envelope as the REST API (the tool result is the JSON envelope serialized as text).

## Calling via REST

`POST https://hojincheck.com/v1/{tool_name}` with a JSON body matching the tool's input schema. Example:

```
curl -X POST https://hojincheck.com/v1/jp_calendar \
  -H "Authorization: Bearer hjc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"is_business_day","date":"2026-07-14"}'
```

## Response envelope

Every response uses a common envelope. Success:

```json
{
  "ok": true,
  "result": { "...tool-specific..." },
  "sources": [
    {
      "name": "国税庁法人番号システムWeb-API",
      "url": "https://www.houjin-bangou.nta.go.jp/webapi/",
      "retrieved_at": "2026-07-12T04:10:00Z",
      "cache": { "hit": true, "stored_at": "2026-07-12T01:00:00Z", "stale": false }
    }
  ],
  "notices": ["...notices required by the data source's terms..."]
}
```

- `sources[].retrieved_at` is the moment the data was actually fetched from the upstream source — it is preserved even when the response is served from cache (freshness metadata).
- `notices` carries the attribution / non-endorsement statements required by each government data source. **Keep these notices visible when you display or pass on the data.**

Error:

```json
{ "ok": false, "error": { "code": "RATE_LIMITED", "message": "...", "retryable": true }, "sources": [] }
```

| Code | HTTP | Meaning |
|---|---|---|
| `INVALID_ARGUMENT` | 400 | Input failed validation (details in `message`) |
| `UNAUTHORIZED` | 401 | Missing, malformed or disabled API key |
| `NOT_FOUND` | 404 | Unknown tool or path |
| `RATE_LIMITED` | 429 | Your key exceeded its daily or burst limit (`Retry-After` set) |
| `UPSTREAM_UNAVAILABLE` | 503 | Government API unreachable / not yet connected, and no cache available |
| `UPSTREAM_RATE_LIMITED` | 503 | Upstream throttling; retry later |
| `INTERNAL` | 500 | Unexpected server error |

Note: "not found" **as data** (e.g. a corporate number with no registration) is not an error — tools return `ok: true` with `exists: false` / `found: false` / `registered: false`.

MCP note: errors are returned inside the tool result (same JSON envelope, `isError: true`), not as protocol errors.

## Caching and freshness

Responses are cached per data source (corporate-number lookups: 6–24h; invoice data: until the next 6:00 JST publication; gBizINFO: 7 days). When an upstream government API is down, a stale cached response may be served with `cache.stale: true` and the original `retrieved_at`, so you always know how fresh the data is. `normalize_address` and `jp_calendar` run on locally bundled master data and are unaffected by government API outages. **Exception: responses that contain individual (sole-proprietor) invoice data are never cached** (see below).

## Tools

### resolve_company — Resolve a company name to corporate number candidates

Status: Implementation complete; awaiting issuance of the government API application ID (applied 2026-07-13, expected late July to late August 2026). Until connected, this tool returns UPSTREAM_UNAVAILABLE (HTTP 503) in production.

Finds corporate-number candidates from a Japanese company name, tolerant of notation variants (abbreviations like 「(株)」, full/half width, kana readings, old-style kanji). Returns candidates with a confidence score (0–1) and match-basis labels.

Input:

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string (1–100) | yes | Company name; notation variants accepted |
| `address` | string | no | Prefecture filter: 2-digit JIS X 0401 prefecture code, or 5 digits (prefecture + municipality code) |
| `include_closed` | boolean | no | Include closed corporations (default `true`) |
| `limit` | integer 1–50 | no | Max candidates returned (default 10) |

Result: `query` (normalized form, search name, detected legal form), `total_count`, `returned`, `truncated`, and `candidates[]` — each with `corporate_number`, `name`, `furigana`, `kind` (code + label), `address`, `status` (`active`/`closed`), `confidence` and `match` details.

Data source: NTA Corporate Number System Web-API.

### verify_company — Verify a corporate number

Status: Implementation complete; awaiting issuance of the government API application ID (applied 2026-07-13, expected late July to late August 2026). Until connected, this tool returns UPSTREAM_UNAVAILABLE (HTTP 503) in production.

Validates a 13-digit corporate number (check-digit verified; invalid numbers are rejected as `INVALID_ARGUMENT`) and returns existence, registered name, head-office address, corporation kind, and closure status. `include_history: true` adds the change history (trade-name changes, relocations, closure).

Input:

| Field | Type | Required | Description |
|---|---|---|---|
| `corporate_number` | string | yes | 13-digit corporate number (full-width digits, hyphens, spaces tolerated) |
| `include_history` | boolean | no | Include change history (default `false`) |

Result: `corporate_number`, `exists`, `company` (record as above, or `null`), optional `history[]`. A number with no registration returns `ok: true` with `exists: false`.

Data source: NTA Corporate Number System Web-API.

### verify_invoice_number — Verify a qualified invoice issuer registration number

Status: Implementation complete; the NTA Invoice Publication Web-API requires an approval-based review (applied 2026-07-12, expected mid to late August 2026). Until approved, this tool returns UPSTREAM_UNAVAILABLE (HTTP 503) in production.

Checks a qualified invoice issuer registration number (T + 13 digits) against the NTA publication system: registration existence, registration date, and revocation/expiration. `on_date` returns whether the registration was effective on that date (`as_of`). `include_history: true` adds the publication history.

Input:

| Field | Type | Required | Description |
|---|---|---|---|
| `registration_number` | string | yes | T + 13 digits (bare 13 digits, full-width, hyphens/spaces tolerated) |
| `on_date` | string `YYYY-MM-DD` | no | Reference date for effectiveness check |
| `include_history` | boolean | no | Include publication history (default `false`) |

Result: `registered`, `status` (`active` / `revoked` / `expired` / `null`), `kind`, `name`, `trade_name`, `address`, `corporate_number` (for corporations), registration/update/disposal/expire dates, optional `as_of` and `history[]`.

**Privacy design (individuals)**: input is a registration number only — **there is no name search and no reverse lookup**. Published information of individual (sole-proprietor) issuers is returned solely as the response to a number check and is **never cached or stored**. Do not use this tool to compile lists of individuals; that is prohibited by the Terms of Service.

Data source: NTA Qualified Invoice Issuer Publication System Web-API.

### get_company_profile — Corporate profile from gBizINFO

Status: Live (connected to gBizINFO REST API v2).

Returns the gBizINFO profile for a corporate number (check-digit verified): location, representative, capital, employee counts and other attributes — together with **per-field provenance metadata** (`source`, last acquisition date, etc.) passed through from gBizINFO v2, and an attribution string (with date of use) as required by the gBizINFO terms.

Input:

| Field | Type | Required | Description |
|---|---|---|---|
| `corporate_number` | string | yes | 13-digit corporate number (full-width digits, hyphens, spaces tolerated) |

Result: `found` (a company not listed in gBizINFO returns `ok: true` with `found: false`), `profile`, `metadata` (per-field provenance), `attribution`.

Data source: gBizINFO REST API v2 (METI).

### normalize_address — Normalize and decompose a Japanese address

Status: Live (driven by bundled government master data; unaffected by government API outages).

Normalizes a Japanese address string, decomposes it into prefecture / municipality / town-aza (chō-aza: ōaza, town name and chōme), resolves the official town-aza ID from the Address Base Registry, and cross-checks the postal code (mismatches are reported as mismatches, never silently corrected).

**v1 granularity and limits (read carefully)**: decomposition goes down to town/aza level (chōme included). **Block numbers (gaiku), lot/house numbers (banchi, jūkyo bangō), koaza, and Kyoto street names are NOT parsed** — the unparsed remainder is returned verbatim in `residual` (and `skipped` for segments between municipality and town). There is **no speculative completion**.

Input:

| Field | Type | Required | Description |
|---|---|---|---|
| `address` | string (1–200) | yes | Japanese address (postal code may be embedded; notation variants tolerated) |
| `postal_code` | string `NNN-NNNN` | no | Postal code passed separately (takes precedence over one embedded in `address`) |

Result: `normalized`, `resolved` (`prefecture` / `city` / `town` with codes and the ABR town-aza ID), `residual`, `skipped`, optional `ambiguous_cities`, `postal` (match check), `confidence`, `match`, and `master_versions` (data dates of the ABR and postal masters).

Data sources: Address Base Registry town-aza master (Digital Agency) + Japan Post postal code data (locally synchronized masters).

### jp_calendar — Japanese holidays and business-day calculations

Status: Live (driven by bundled government master data; unaffected by government API outages).

Holiday determination and business-day arithmetic based on the Cabinet Office "National Holidays" CSV. Business day = not a weekend and not a national holiday; set `year_end_as_holiday: true` to also treat Dec 29 – Jan 3 as non-business days (government/bank custom).

Input:

| Field | Type | Required | Description |
|---|---|---|---|
| `op` | enum | yes | `is_business_day` / `next_business_day` / `prev_business_day` / `add_business_days` / `list_holidays` |
| `date` | `YYYY-MM-DD` | for date ops | Reference date |
| `days` | integer −1000…1000 | for `add_business_days` | Business days to add (negative = backwards) |
| `from`, `to` | `YYYY-MM-DD` | for `list_holidays` | Period |
| `year_end_as_holiday` | boolean | no | Treat Dec 29 – Jan 3 as non-business (default `false`) |

Holiday data coverage: **1955-01-01 to 2027-12-31** (the Cabinet Office adds the next year's data around each February; the bundled snapshot is refreshed monthly). Dates outside the coverage return `INVALID_ARGUMENT` with the coverage range.

Data source: Cabinet Office "National Holidays" CSV.

## Data sources and attribution

| Source | Publisher |
|---|---|
| Corporate Number System Web-API | National Tax Agency (NTA) |
| Qualified Invoice Issuer Publication System Web-API | National Tax Agency (NTA) |
| gBizINFO REST API v2 | Ministry of Economy, Trade and Industry (METI) |
| Address Base Registry (town-aza master) | Digital Agency |
| Postal code data | Japan Post |
| "National Holidays" CSV | Cabinet Office |

The service edits and processes these sources; **its content is not endorsed or guaranteed by the NTA or any other agency**. Each response's `notices` array carries the exact statements required by the respective source's terms — retain them when redisplaying the data.

## Legal

- [Terms of Service](https://hojincheck.com/legal/terms) ・ [Privacy Policy](https://hojincheck.com/legal/privacy) ・ [Commercial Transactions Act notice](https://hojincheck.com/legal/tokusho) (all in Japanese)
- Not for credit decisions: HojinCheck returns public-registry facts with provenance; it does not provide creditworthiness judgments.
- Contact: drogerdluffy@gmail.com