---
title: "New company check"
method: GET
path: "/company/{number}/new-company-check"
tags: ["New Companies"]
---

# New company check

`GET /company/{number}/new-company-check`

## Request

- Base URL: `https://api.companystack.co.uk`
- URL: `https://api.companystack.co.uk/company/{number}/new-company-check`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Who is behind a new company and what to check before dealing with it, from the register: age, directors and each director's other appointments (by Companies House officer id, with dissolved and insolvent companies; same-name matches against PSC records only as "possible"), PSCs or the no-PSC statement, the first shareholders at incorporation, the shared-address count with its rule, sanctions screening of officers and owners, and the first accounts and confirmation statement due dates. The new company check covers new companies: incorporated less than 24 months ago and no accounts filed yet. Other companies get eligible: false with the reason.

Plans: API Free gets the summary (age, shared address, PSC or no-PSC, the three largest first shareholders with the number of shareholders and the share the three hold, first accounts due, the number of directors' other appointments) for 25 companies a UTC day (the same company again that day is not counted; X-New-Company-Checks-Remaining says how many are left; then 429 daily_check_limit); Starter and above get the full check.

Cached until the register shows a change to the company (profile, PSCs, filings held, share register, sanctions list versions) and for 24 hours at most. When nothing is cached a check asks Companies House for the officer list (1 request), PSCs and PSC statements (2) and each current director's appointments (1 per 50 appointments).

Fair use: a check not held yet is worked out when asked for, and each caller has a share of them: 20 in any five minutes for an account on Starter and above, 8 in any five minutes and 100 a day on web-app Free, 8 in any five minutes on API Free (within its 25 companies a day), 4 in any five minutes and 30 a day for each visitor to the website signed out. A check already held (or being worked out for someone else) is not counted. Past the share a copy held is returned only while the register is unchanged since it was made (it has expired; cache.computed_at says when it was made), never one made before a change; otherwise 429 fair_use_limit with Retry-After. A visitor to the website who is not signed in gets, past its share, the check worked out from the records CompanyStack holds, without asking Companies House (cache.complete is false where a section could not be read).

## Path parameters

- `number` string, required

## Response `200`

The check (level full or summary), or eligible: false with the reason

- object: The full check (level "full": API Starter and above).
  - `level` 'full'
  - `eligible` boolean
  - `company_number` string
  - `company_name` string
  - `company_status` string, nullable
  - `company_type` string, nullable
  - `incorporation_date` string, date, nullable
  - `age` object
    - `days` integer, nullable
    - `months` integer, nullable
    - `text` string, nullable
  - `eligibility` object
    - `eligible` boolean
    - `reason` string
    - `rule` string
  - `shared_address` object
    - `postcode` string, nullable
    - `companies` integer, nullable: Companies on the register with this registered office postcode, this one included, counted up to 1,000
    - `capped` boolean: true when the count stopped at 1,000: the postcode holds at least that many
    - `shared` boolean: true at 100 or more companies
    - `threshold` integer
    - `statement` string
    - `rule` string
  - `directors` object
    - `status` string
    - `reason` string, nullable
    - `count` integer
    - `with_other_companies` integer, nullable
    - `other_appointments` integer, nullable
    - `rule` string
    - `items` object[]
      - `name` string
      - `role` string, nullable
      - `appointed_on` string, date, nullable
      - `officer_id` string, nullable
      - `born` string, nullable: Month and year of birth, as Companies House publishes it
      - `nationality` string, nullable
      - `history` object: The officer's appointments read from Companies House by officer id (match.confidence confirmed)
        - `status` 'ok' | 'unavailable' | 'not_read'
        - `reason` string, nullable
        - `match` object, nullable
          - `basis` 'officer_id'
          - `confidence` 'confirmed'
        - `total_appointments` integer, nullable
        - `other_appointments` integer, nullable
        - `other_companies` integer, nullable
        - `other_current_appointments` integer, nullable
        - `dissolved_companies` integer, nullable
        - `insolvency_companies` integer, nullable: In liquidation, administration or receivership, or dissolved after a company insolvency notice (Gazette 24xx)
        - `struck_off_overdue_companies` integer, nullable
        - `truncated` boolean
        - `summary` string, nullable
        - `fetched_at` string, nullable
        - `companies` object[]
          - `company_number` string
          - `company_name` string, nullable
          - `company_status` string, nullable
          - `officer_role` string, nullable
          - `appointed_on` string, nullable
          - `resigned_on` string, nullable
          - `outcome` 'active' | 'insolvency' | 'struck_off_overdue' | 'dissolved' | 'other'
      - `possible_psc_matches` object, nullable: People with significant control of other companies with the same name and month and year of birth. Possible matches only: it may be a different person.
        - `basis` 'name_and_birth'
        - `confidence` 'possible'
        - `companies` integer
        - `examples` object[]
  - `ownership` object
    - `status` string
    - `summary` string
    - `pscs` object[]
    - `statements` object[]
    - `source` 'companies_house' | 'register_copy'
  - `first_shareholders` object: The subscribers on the incorporation filing, labelled "at incorporation". status pending: being read from the incorporation filing. Paid plans (API Starter, Business and Enterprise) get every shareholder (shown: all); API Free gets the three largest (shown: top_three), with holder_count and top_three_percentage (the share of all shares the three hold together).
    - `status` 'ok' | 'pending' | 'withheld' | 'not_available'
    - `message` string, nullable
    - `as_at` string, nullable
    - `source_form` string, nullable
    - `label` string
    - `holders` object[]
      - `name` string
      - `kind` 'individual' | 'corporate'
      - `share_class` string
      - `shares` number
      - `percentage` number, nullable
    - `total_shares` number, nullable
    - `flagged_reasons` string[]
    - `shown` 'all' | 'top_three'
    - `holder_count` integer, nullable
    - `top_three_percentage` number, nullable
    - `holders_not_shown` integer
  - `sanctions` object
    - `status` string
    - `verdict` string, nullable
    - `verdict_label` string, nullable
    - `summary` string, nullable
    - `subjects_screened` integer
    - `matches` object[]
    - `lists_screened` string[]
    - `screened_at` string, nullable
    - `disclaimer` string
  - `filing_deadlines` object
    - `first_accounts_due` string, nullable
    - `accounts_overdue` boolean
    - `accounts_filed` boolean
    - `confirmation_statement_due` string, nullable
    - `confirmation_statement_overdue` boolean
  - `registration_cluster` object
    - `status` string: `ok` when clusters were looked for; `unavailable` while no registration cluster has been worked out yet (then `in_cluster` is false and says nothing about the company: read `reason`)
    - `in_cluster` boolean
    - `size` integer, nullable
    - `formed_within_window` integer, nullable
    - `rule` string
    - `computed_at` string, date-time, nullable
    - `reason` string, nullable
  - `method` string[]
  - `register_checked_at` string, date-time
  - `plan` object
  - `cache` object
    - `cached` boolean
    - `computed_at` string
    - `complete` boolean

## Other responses

- `401`: API key missing, malformed or revoked
- `403`: The key's plan does not include this endpoint (`code: plan_upgrade_required`, with `upgrade_url`), the key may not call it, or the key is beyond the plan's key limit after a downgrade (`code: key_limit_exceeded`: the newest keys are paused until keys are deleted or the plan upgraded)
- `404`: Not on the register held, or the check is not switched on (code not_enabled)
- `429`: API Free: today's 25 companies are used (code daily_check_limit); or the caller's share of checks not held yet is used and no copy matching the register is held (code fair_use_limit)

---

[API](https://skmtc.dev/companystack/apis/companystack-api.md) · [All operations](https://skmtc.dev/companystack/apis/companystack-api/llms.txt) · [OpenAPI document](https://skmtc.dev/companystack/apis/companystack-api/revisions/8f3234237d2d?raw)