CompaniesHouse

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.4.0"}
  ]
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

Retries

By default no retries are performed. To retry transient failures — including 429 rate-limit and 503 responses, honouring their Retry-After header — set the :retry option, which is passed straight through to Req:

config :companies_house, retry: :safe_transient

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/4 (pass kind: for corporate-entity, legal-person, beneficial-owner, and super-secure PSCs)

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).
• list_* return only a single page of items and discard pagination metadata — they do not auto-paginate. Use the matching stream_* function to fetch every item across all pages.
• 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.