New to NAR1? Start with its purpose, official form and samples. →
A business name marked N/A, an empty email field and an unprovided directors page are different situations. Preserve raw text, field status and source page so reviewers can trace each value.
N/A, blank fields and missing pages
| Source condition | Field status | Handling |
|---|---|---|
| Value supplied | present | Preserve the value and source page. |
| N/A | not_applicable | Preserve N/A; do not convert it to zero. |
| Blank | blank | Record the blank; do not infer a value. |
| Relevant page not supplied | not_in_excerpt | Identify the gap in source coverage. |
| Unclear text or checkbox | needs_review | Flag for review rather than guessing. |
Legacy company number and dates
The sample prints legacy company number 1063959 in the top-right corner. Preserve it as a string rather than relabelling it BRN. The return date 2022-08-02 describes the filing, not the search or extraction date.
Represent share capital as an array
Each row contains share class, currency, issued shares, total amount and paid-up amount. Keep an array even for one row. Store printed totals separately so they are not added again as detail rows. Do not directly combine different currencies.
Free JSON Schema and integration example
The public repository includes field notes, a validatable JSON Schema and a clearly labelled fictional example. This is a separate illustrative integration contract, requiring mapping from the website sample format. It is not an official Companies Registry specification.
Open the field guide and Schema →
Coverage
This guide covers company details and share capital illustrated in a two-page NAR1 excerpt, not complete directors, members or continuation pages. Schema validation checks format, not factual accuracy or current company status.
View the sample, source and coverage · Companies Registry electronic search FAQ
Read the source before choosing field names
Keep the two-page sample beside you as you read. For each item, note the label on the form, the value you can see and what you understand it to mean. These pages do not show director or member details. If you need another page or document to answer a question, leave yourself a note to obtain it rather than filling the gap from memory.
For example, page 1 supports the return date of this filing, not the latest search date. The capital figures on page 2 describe the filing, not the company’s financial position today. Keeping these notes makes it easier for a colleague to see what the document says and what still needs checking.
A blank result can mean several different things
Suppose a colleague asks you to complete the sample’s business name, email and director names. Do not mark all three as extraction failures. The business name is explicitly N/A; the email field is blank, so another extraction cannot supply an address; director details require pages absent from the excerpt.
Scroll sideways to see all columns; focus the table and use arrow keys on a keyboard.
| Sample item | What can be completed | If more information is needed |
|---|---|---|
| Business name: N/A | Retain the source text and not_applicable state | Clarify the new requirement; do not guess a name |
| Email: source field blank | Record blank; transcription of this source is complete | Identify any separately obtained contact source |
| Directors: details outside excerpt | Record the scope gap without a negative finding | Request the relevant pages from the provider |
Check capital headings and units together
The public sample has three values of 10,000 in one row: issued share count, total amount and paid-up amount. Equal values do not make them duplicate fields. The count is shares, while amounts must be read with their currency. Read headings as well as numbers.
The table also contains totals. Compare detail with totals, but do not add them together. With another document, check its actual row count and units rather than assuming the sample’s single row.
Can a colleague find the same answer?
Ask a colleague to locate the company number, date and capital row using only your notes. If they must guess the page, date type or row, improve the references. If they can find it but cannot interpret an empty value, improve the state description. This tests usefulness more directly than adding fields.
If using the public Schema as an integration reference, compare its fields with the actual website sample. Similar names do not guarantee identical meanings, and validation does not replace source reading. Confirm the reading and handover conventions before discussing technical mappings.
Frequently asked questions
Does JSON Schema validation prove accuracy?
No. A schema checks structure. You still need to review the original, its relevant date and page scope; validation does not establish a company’s current situation.
Use your existing fields and format
Share your target format to confirm a sample and quotation first.
Before reading the fields, identify the document
Distinguish a blank form, a completed filing and a teaching excerpt, then check company, dates and page scope. The same form name does not imply the same period or completeness.
This guide explains the sample fields, reasons for blank values and how to read the share-capital table. For an enquiry, tell us which information you need and the format you use. We can agree the field names together afterwards.
- NAR1, NNC1 or a Company Particulars Report?
- NAR1 dates: distinguish the return, filing and download dates
- Before requesting company document extraction: a practical checklist
- Can a Hong Kong company search API download NAR1 filings?
- Hong Kong company registration number vs BRN: how to check both
- What is NAR1? Annual return forms, downloads and samples