company_uk_filings_output

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/eckari-com/json-schema/eckari-com-company-uk-filings-output-schema.json",
  "title": "company_uk_filings_output",
  "description": "Contains public sector information licensed under the Open Government Licence v3.0 (Companies House).",
  "x-generated": "2026-11-06",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/eckari-com-openapi.json#/components/schemas/company_uk_filings_output",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "company_number",
    "query",
    "filing_history_status",
    "is_filing_history_available",
    "items",
    "page"
  ],
  "properties": {
    "company_number": {
      "type": "string"
    },
    "query": {
      "type": "object",
      "description": "The resolved inputs, echoed because page.total depends on the category filter and the item shape depends on detail.",
      "additionalProperties": false,
      "required": [
        "category",
        "detail"
      ],
      "properties": {
        "category": {
          "type": [
            "string",
            "null"
          ],
          "description": "The category filter actually applied (the normalised input value), or null when none was applied."
        },
        "detail": {
          "type": "string",
          "enum": [
            "summary",
            "full"
          ]
        }
      }
    },
    "filing_history_status": {
      "type": [
        "string",
        "null"
      ],
      "description": "The register's own statement about this company's filing history, passed through unchanged (e.g. filing-history-available). It qualifies a short or empty list: without it, 'no filings match this filter' and 'the register holds no filing history for this company' look identical. Null when the register omits it."
    },
    "is_filing_history_available": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Derived; true when filing_history_status is exactly filing-history-available (the only value the register enumerates), false when it reports some other status, and null when it omits the member — the register did not say, which is never reported as 'not available'."
    },
    "items": {
      "type": "array",
      "description": "The register's own filing order, passed through unchanged — reverse chronological (most recent first) in practice. Eckari applies no sort of its own and guarantees no ordering; sort on date yourself if your logic depends on it.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "transaction_id",
          "date",
          "category",
          "type",
          "description",
          "description_source",
          "annotations",
          "has_document",
          "document_url"
        ],
        "properties": {
          "transaction_id": {
            "type": "string",
            "description": "The register's identifier for this filing; it appears in document_url."
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "Date the filing was processed by the register."
          },
          "category": {
            "type": "string"
          },
          "subcategory": {
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "type": "string",
            "description": "Register filing type code (e.g. AA, CS01, AP01, TM01)."
          },
          "description": {
            "type": "string",
            "description": "Human-readable description of the filing, rendered from the Companies House filing_history_descriptions enumeration with the register's own description_values merged in (e.g. \"Confirmation statement made on 2026-06-18 with no updates\"). Never invented: an unrecognised key is rendered as a readable form of the key itself and flagged by description_source. Registrar annotations are NOT merged into this text — read annotations[] as well to see everything the register shows for the filing."
          },
          "description_source": {
            "type": "string",
            "enum": [
              "enumeration",
              "fallback"
            ],
            "description": "\"enumeration\" when the register's description key matched the published Companies House enumeration; \"fallback\" when it did not and the key itself (or the register's own free text) was made readable."
          },
          "description_key": {
            "type": "string",
            "description": "Raw register description key for the filing (e.g. capital-return-purchase-own-shares), stable for machine matching. Returned only when detail=full."
          },
          "description_values": {
            "type": [
              "object",
              "null"
            ],
            "description": "Placeholder values supplied by the register for the description template (dates, officer names, addresses, capital figures). Passed through unmodified; null when the register supplies none. Returned only when detail=full — `description` already carries them merged in."
          },
          "annotations": {
            "type": "array",
            "description": "Registrar annotations attached to this filing, verbatim and in register order; empty when there are none. The register renders them beneath the filing's own description (e.g. \"Purchase of own shares. ANNOTATION Clarification …\"), so a consumer reading description alone is not reading what the register says about the filing. Annotations are the registrar's after-the-fact clarifications and corrections.",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "annotation",
                "date",
                "description"
              ],
              "properties": {
                "annotation": {
                  "type": "string",
                  "description": "The annotation text as published by the register."
                },
                "date": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date",
                  "description": "The date the annotation was added, as a date. The register publishes it as a midnight timestamp; only the date part is a fact, so only the date is returned. Null when the register omits it."
                },
                "description": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The register's own description key for the annotation entry (e.g. annotation). Null when the register omits it."
                }
              }
            }
          },
          "pages": {
            "type": [
              "integer",
              "null"
            ]
          },
          "paper_filed": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "has_document": {
            "type": "boolean",
            "description": "Derived; true when the register exposes document metadata for this filing, meaning a filed image exists on the Companies House document service. document_url is then the address to fetch it from."
          },
          "document_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Derived; the Companies House public register URL for the filed document (https://find-and-update.company-information.service.gov.uk/company/{company_number}/filing-history/{transaction_id}/document?format=pdf). Null exactly when has_document is false. Eckari does not proxy, host or charge for the document itself; fetching it is a separate, free request to Companies House under the same OGL terms."
          }
        }
      }
    },
    "page": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "limit",
        "offset",
        "returned",
        "total",
        "has_more",
        "next_offset"
      ],
      "properties": {
        "limit": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The page size applied (the requested limit, default 5)."
        },
        "offset": {
          "type": "integer",
          "description": "The register index this page started at (the requested offset)."
        },
        "returned": {
          "type": "integer",
          "description": "Number of filings in this response."
        },
        "total": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Register-wide count of filings for the applied category filter — read it together with query.category, which is why the filter is echoed. Never a count of this page."
        },
        "has_more": {
          "type": "boolean",
          "description": "Authoritative end-of-list signal; true when further filings remain beyond this page for the applied filter."
        },
        "next_offset": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The offset to request next. Null exactly when has_more is false."
        }
      }
    }
  }
}