CompaniesHouse

Copy Markdown View Source

Test Status Coverage Status Hex Version Hex Docs

An Elixir client for the Companies House API.

Installation

The package can be installed by adding companies_house to your list of dependencies in mix.exs:

def deps do
  [
    {:companies_house, "~> 0.2"}
  ]
end

Usage

Configuration

Add your API key to your application config:

config :companies_house, api_key: "your-api-key"

By default the client targets the sandbox environment. To use the live API:

config :companies_house, environment: :live

Available functions

Company data

  • get_company_profile/2
  • get_registered_office_address/2
  • get_insolvency/2
  • get_exemptions/2

Officers

  • list_company_officers/3
  • get_officer_appointment/3
  • list_officer_appointments/3

Filing history

  • list_filing_history/3
  • get_filing_history/3

Persons with significant control

  • list_persons_with_significant_control/3
  • get_person_with_significant_control/3

Charges

  • list_charges/3
  • get_charge/3

UK establishments

  • list_uk_establishments/3

Search

  • search_companies/3
  • search_officers/3
  • search_disqualified_officers/3

Streaming (auto-pagination)

  • stream_company_officers/3
  • stream_filing_history/3
  • stream_persons_with_significant_control/3

Return values

  • get_* and list_* return {:ok, map()} or {:ok, [map()]} on success. Errors are either {:error, {status_code, body}} for non-2xx HTTP responses or {:error, exception} for network/transport failures (e.g. timeout, connection refused).
  • search_* return the full response envelope (including "total_results" and "start_index"), not just the items array.
  • stream_* return a lazy Enumerable that auto-paginates. Pipe into Enum or Stream functions.

See the HexDocs for full API reference.

Development

Requirements

  • Elixir (see .tool-versions or mix.exs for version)
  • Homebrew (for installing pre-commit hook dependencies)

Setup

bin/setup
mix setup

bin/setup installs the pre-commit hook tools (actionlint, check-jsonschema, lefthook, markdownlint-cli2) and activates the hooks. mix setup fetches Elixir dependencies.

Common commands

mix test          # Run tests
mix credo         # Lint
mix format        # Format code
mix coveralls     # Test coverage

License

CompaniesHouse is released under the MIT license.