KYCCentral (KYC Central v0.9.0)

Copy Markdown View Source

Official Elixir client for the KYC Central API — UK company KYC and AML risk assessment.

client = KYCCentral.new()                       # reads KYCCENTRAL_API_KEY
{:ok, assessment} = KYCCentral.KYC.assess(client, "00445790")

assessment.company_name  #=> "TESCO PLC"
assessment.risk_level    #=> :medium

for flag <- KYCCentral.Assessment.flags_at_or_above(assessment, :high) do
  IO.puts("#{flag.code}: #{flag.description}")
end

Every function returns {:ok, result} or {:error, %KYCCentral.Error{}}.

Authentication

Generate a key in Account settings and set KYCCENTRAL_API_KEY, or pass :api_key to new/1.

A key is not always required: reference and lookup endpoints work anonymously at a lower rate limit. Assessments and the AI endpoints always need one.

The client struct

new/1 builds a plain struct holding configuration — it starts no processes and opens no connections, so there is nothing to supervise or close. Build one and pass it around, or memoise it in your application's config.

Calling from Erlang

Module names are prefixed with Elixir. from Erlang:

Client = 'Elixir.KYCCentral':new([{api_key, <<"...">>}]),
{ok, Assessment} = 'Elixir.KYCCentral.KYC':assess(Client, <<"00445790">>).

Summary

Types

t()

Functions

authenticated?(kyc_central)

Whether an API key was resolved. Anonymous clients hit lower rate limits.

data_source_health(client)

Per-upstream availability: Companies House, FCA, GLEIF, sanctions and the rest.

health(client)

Liveness and dependency status. Unversioned and unauthenticated.

new(opts \\ [])

Build a client.

Types

t()

@type t() :: %KYCCentral{
  api_key: String.t() | nil,
  base_url: String.t(),
  headers: keyword() | map(),
  http: (map() -> {:ok, map()} | {:error, term()}),
  max_retries: non_neg_integer(),
  receive_timeout: pos_integer()
}

Functions

authenticated?(kyc_central)

@spec authenticated?(t()) :: boolean()

Whether an API key was resolved. Anonymous clients hit lower rate limits.

data_source_health(client)

@spec data_source_health(t()) :: {:ok, map()} | {:error, KYCCentral.Error.t()}

Per-upstream availability: Companies House, FCA, GLEIF, sanctions and the rest.

health(client)

@spec health(t()) :: {:ok, map()} | {:error, KYCCentral.Error.t()}

Liveness and dependency status. Unversioned and unauthenticated.

new(opts \\ [])

@spec new(keyword()) :: t()

Build a client.

Options

  • :api_key — your API key. Defaults to the KYCCENTRAL_API_KEY environment variable, or nil for anonymous access.
  • :base_url — API root. Defaults to KYCCENTRAL_BASE_URL, then to production.
  • :receive_timeout — per-request timeout in milliseconds. Defaults to 30000.
  • :max_retries — retries for timeouts, connection failures and retryable statuses (408, 429, 500, 502, 503, 504). Backoff is exponential with jitter and honours Retry-After. Defaults to 2; 0 disables retries.
  • :headers — extra headers on every request.
  • :http — a one-argument function used instead of the default :httpc-backed transport. Receives %{method:, url:, headers:, body:, receive_timeout:} and must return {:ok, %{status:, headers:, body:}} or {:error, reason}. Useful for tests, tracing, or plugging in a different HTTP stack.

Examples

KYCCentral.new()
KYCCentral.new(api_key: "...", max_retries: 5)
KYCCentral.new(base_url: "https://dev-api.kyccentral.co.uk")