{
  "openapi": "3.0.1",
  "info": {
    "title": "Companies House Scraper — UK Companies, Directors & PSCs",
    "description": "Scrape the UK Companies House register: company profiles, directors, PSCs (beneficial owners), SIC codes, addresses, accounts dates, filing history & charges. Search by keyword, company number, SIC code, location or incorporation date. No API key. Monitoring mode. Export JSON, CSV, Excel.",
    "version": "1.1",
    "x-build-id": "aaLBXpy2C3ZIMprHQ"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapesage~companies-house-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapesage-companies-house-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/scrapesage~companies-house-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapesage-companies-house-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/scrapesage~companies-house-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapesage-companies-house-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "searchQueries": {
            "title": "Search queries",
            "type": "array",
            "description": "Keywords or company names to search the Companies House register, e.g. <code>tesco</code>, <code>green energy ltd</code>. Matches company names and previous names.",
            "items": {
              "type": "string"
            }
          },
          "companyNumbers": {
            "title": "Company numbers",
            "type": "array",
            "description": "Exact Companies House company numbers to scrape directly (8 characters, e.g. <code>00445790</code>, <code>SC123456</code>, <code>NI036672</code>, <code>OC301540</code>). Fastest, most precise input.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Start URLs",
            "type": "array",
            "description": "Direct Companies House URLs: company pages (<code>/company/00445790</code>), keyword search pages (<code>/search/companies?q=...</code>) or advanced-search results (<code>/advanced-search/get-results?...</code>).",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "sicCodes": {
            "title": "SIC codes",
            "type": "array",
            "description": "Filter by SIC (industry) codes via advanced search, e.g. <code>62012</code> (software development), <code>68310</code> (estate agents), <code>56101</code> (restaurants). Combine with the other filters below.",
            "items": {
              "type": "string"
            }
          },
          "location": {
            "title": "Registered office location",
            "type": "string",
            "description": "Filter by text in the registered office address, e.g. a town, county or postcode (<code>Manchester</code>, <code>EC1</code>)."
          },
          "companyNameIncludes": {
            "title": "Company name includes",
            "type": "string",
            "description": "Advanced-search filter: only companies whose name contains this text."
          },
          "companyNameExcludes": {
            "title": "Company name excludes",
            "type": "string",
            "description": "Advanced-search filter: exclude companies whose name contains this text."
          },
          "companyTypes": {
            "title": "Company types",
            "type": "array",
            "description": "Restrict to one or more company types (advanced search).",
            "items": {
              "type": "string",
              "enum": [
                "ltd",
                "plc",
                "llp",
                "private-unlimited",
                "limited-partnership",
                "private-limited-guarant-nsc",
                "private-limited-guarant-nsc-limited-exemption",
                "community-interest-company",
                "charitable-incorporated-organisation",
                "registered-overseas-entity",
                "old-public-company",
                "other"
              ],
              "enumTitles": [
                "Private limited (LTD)",
                "Public limited (PLC)",
                "Limited liability partnership (LLP)",
                "Private unlimited",
                "Limited partnership",
                "Private limited by guarantee (no share capital)",
                "Private limited by guarantee (no share capital, exempt)",
                "Community interest company (CIC)",
                "Charitable incorporated organisation",
                "Registered overseas entity",
                "Old public company",
                "Other"
              ]
            }
          },
          "companyStatus": {
            "title": "Company status",
            "type": "array",
            "description": "Restrict to one or more company statuses (advanced search).",
            "items": {
              "type": "string",
              "enum": [
                "active",
                "dissolved",
                "open",
                "closed",
                "converted-closed",
                "receivership",
                "liquidation",
                "administration",
                "insolvency-proceedings",
                "voluntary-arrangement"
              ],
              "enumTitles": [
                "Active",
                "Dissolved",
                "Open",
                "Closed",
                "Converted / closed",
                "Receivership",
                "Liquidation",
                "Administration",
                "Insolvency proceedings",
                "Voluntary arrangement"
              ]
            }
          },
          "incorporatedFrom": {
            "title": "Incorporated from",
            "type": "string",
            "description": "Only companies incorporated on or after this date (YYYY-MM-DD). Great for catching brand-new businesses."
          },
          "incorporatedTo": {
            "title": "Incorporated to",
            "type": "string",
            "description": "Only companies incorporated on or before this date (YYYY-MM-DD)."
          },
          "dissolvedFrom": {
            "title": "Dissolved from",
            "type": "string",
            "description": "Only companies dissolved on or after this date (YYYY-MM-DD)."
          },
          "dissolvedTo": {
            "title": "Dissolved to",
            "type": "string",
            "description": "Only companies dissolved on or before this date (YYYY-MM-DD)."
          },
          "includeOfficers": {
            "title": "Include officers & directors",
            "type": "boolean",
            "description": "Fetch the full officer list per company: name, role, status, date of birth (month/year), nationality, occupation, country of residence, correspondence address, appointed/resigned dates.",
            "default": true
          },
          "includePSCs": {
            "title": "Include PSCs (beneficial owners)",
            "type": "boolean",
            "description": "Fetch persons with significant control: name, nature & level of control, date of birth, nationality, country of residence, notified date, plus any PSC statements (e.g. exemptions).",
            "default": true
          },
          "includeFilingHistory": {
            "title": "Include filing history",
            "type": "boolean",
            "description": "Fetch the most recent filings (date, type, description, document link). Adds the last-filing date/type to each company — useful for monitoring activity.",
            "default": false
          },
          "includeCharges": {
            "title": "Include charges / mortgages",
            "type": "boolean",
            "description": "Fetch registered charges (mortgages): title, status (outstanding/satisfied), created/delivered dates and persons entitled.",
            "default": false
          },
          "emitOfficerRecords": {
            "title": "Emit one lead record per officer",
            "type": "boolean",
            "description": "In addition to the company records, push one flat record per officer/director (type = \"officer\") — a ready-to-use directors list for CRM import.",
            "default": false
          },
          "maxCompanies": {
            "title": "Max companies",
            "minimum": 1,
            "type": "integer",
            "description": "Maximum number of companies to scrape across all inputs. The default (50) returns a rich result set quickly; raise it for bigger lead lists — large runs stream results as they go and stop gracefully before the run's timeout, so nothing is lost.",
            "default": 50
          },
          "monitoringMode": {
            "title": "Monitoring mode (only new companies)",
            "type": "boolean",
            "description": "Output only companies not seen in previous runs — ideal for scheduled runs that return ONLY new matches (e.g. new incorporations for a SIC code). Works alongside Apify Schedules: the schedule triggers the run, monitoring mode deduplicates results.",
            "default": false
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "How many companies to fetch in parallel. The Companies House site is fast and stable; 12 is a good default. Raise it to go faster on large runs.",
            "default": 12
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Proxy settings. Companies House is a public UK government service that does not block datacenter IPs, so the default Apify Proxy is plenty — no residential proxy needed.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}