All APIsexpand_more
Shareholder benefits of one company
/stable/shareholder-benefits1 tokens per callNewReturns the shareholder benefit programs of one company, split into programs in effect and scheduled changes or new programs. Each has record months, tiers by shares held and holding period, items with the amounts and annual values stated by the company, choice rules, the source document and the review date. hasBenefits is true (has benefits), false (confirmed to have none) or null (not yet confirmed, or only a scheduled program); null does not mean there are no benefits. Only company-stated amounts are returned; estimated amounts are null.
What you can do with this API
- check_circleCheck the benefits and required shares of stocks you hold or are considering
- check_circleSee how benefits increase with long-term holding
- check_circleLearn about announced changes or new programs in advance
Example URL
https://api.zenithcode.net/stable/shareholder-benefits?symbol=3983&asOf=2026-10-19Shown without percent-encoding for readability. Non-ASCII values are encoded automatically when sent.
Parameters
| Parameter | Required | Description | Example |
|---|---|---|---|
symbolstring | Required | Securities code (4 characters, e.g. 3983) | 3983 |
asOfstring | Optional | Publication date (YYYY-MM-DD, Japan time). Defaults to today. This is not a record-date eligibility check | 2026-10-19 |
Try it
Run it with your own parameters and check the response as a table, JSON or CSV. Sign-in required; each run uses 1 tokens.
travel_exploreTry in the API ViewerResponse example (real data)
Response fields
symbol | string | |
asOfPublication date the response is evaluated at (JST) | string | Publication date the response is evaluated at (JST) |
hasBenefitstrue = a current benefit program exists, false = confirmed that the company has no program (valid within the year it was confirmed), null = unknown or only a scheduled program. null does NOT mean "no benefits" | boolean | true = a current benefit program exists, false = confirmed that the company has no program (valid within the year it was confirmed), null = unknown or only a scheduled program. null does NOT mean "no benefits" |
coverageHow completely this company has been reviewed | object | How completely this company has been reviewed |
lastReviewedAtLatest review date among the returned programs | string | Latest review date among the returned programs |
programsPrograms currently in effect | array | Programs currently in effect |
scheduledAnnounced changes or new programs not yet in effect | array | Announced changes or new programs not yet in effect |
Related APIs
FAQ
Does hasBenefits = null mean the company has no benefits?expand_more
No. It means the company has not been confirmed yet, or only has a scheduled program. Companies confirmed to have no benefits return false.
How is the annual value calculated?expand_more
If the company states an annual amount, that amount is used; otherwise the stated per-occasion amount is multiplied by the number of times per year that can be determined from the source or the record months. Alternatives in a choice are not added together.
How many tokens does one call use?expand_more
1 tokens per call, regardless of how many rows come back. Your monthly allowance depends on your plan.
Do I need an account to try it?expand_more
Use the API Viewer to run it with your own parameters. Sign up for free and sign in (no credit card). Each run uses this API's tokens.
Can I get CSV instead of JSON?expand_more
Add format=csv to the URL to get CSV, ready for spreadsheets or pandas.
Can I get labels in English?expand_more
With neither lang nor Accept-Language, labels such as sector names are returned in English; add lang=ja or send Accept-Language: ja for Japanese. Company and sector names are always returned in both languages as nameJa / nameEn and sectorJa / sectorEn. Field names are the same in both languages.