---
title: "Subscribe to a supplier watchlist"
method: POST
path: "/v1/monitor/watchlist"
tags: ["Monitoring (Registry Watch)"]
---

# Subscribe to a supplier watchlist

`POST /v1/monitor/watchlist`

## Request

- Base URL: `https://jp-verify.obolpay.xyz`
- URL: `https://jp-verify.obolpay.xyz/v1/monitor/watchlist`
- Auth: API key in header `X-API-Key`

Subscribe 法人番号 / T-numbers to this caller's watchlist. Body:
``{"corporate_numbers": ["T…", "…", …]}`` (each check-digit validated; a bad number is
refused FREE, listing which). Requires ``X-API-Key`` (1.4.0). Metered like /v1/verify.
Opt-in ``Idempotency-Key`` header: a retry with the same key + body replays the first
response instead of re-metering.

## Headers

- `X-API-Key` string

## Request body

- object: ``POST``/``DELETE /v1/monitor/watchlist`` body.
  - `corporate_numbers` string[], required: 法人番号 / T-numbers to subscribe or unsubscribe (each check-digit validated)

## Response `200`

Successful Response

- unknown

## Other responses

- `400`: Malformed input — refused before metering; nothing was charged.
- `401`: No API key (required on every /v1/monitor/* operation since release 1.4.0 — refused before any body read or metering, nothing was charged), or an unknown, inactive, or expired key.
- `413`: Request body over the size cap — refused before it was buffered or parsed; nothing was charged.
- `422`: Validation Error
- `429`: Quota exceeded for the caller's tier.
- `503`: The register, or an optional feature, is unavailable or not configured on this deployment. A register 503 (since 1.4.1) also carries the mirror's `data_as_of` with the source fields — `source_latest_diff_date` (the newest 差分 the NTA 公表サイト listed when the sync last read it), `source_checked_at`, `source_gap_business_days` and `freshness.rule` (`stale` here) — so a caller can tell a mirror that is behind its source (`data_date` older than `source_latest_diff_date`) from a source that has not published (equal, but `source_checked_at` older than `freshness.source_check_max_hours`); `data_as_of` is null when the mirror is absent. Nothing was charged.

---

[API](https://skmtc.dev/obolpay/apis/jp-verify.md) · [All operations](https://skmtc.dev/obolpay/apis/jp-verify/llms.txt) · [OpenAPI document](https://skmtc.dev/obolpay/apis/jp-verify/revisions/bf8851690df0?raw)