Skip to content

UK Entity API · v1

API Reference

Aggregates UK regulatory data from Companies House into a single normalised JSON response. Designed for AI agents performing due diligence and KYB checks on UK companies.

Base URL

https://api.rotuli.co.uk/v1

Authentication

Authorization: Bearer uk_live_your_key

API key prefixed with uk_live_ or uk_test_. Pass as: Authorization: Bearer uk_live_xxx

Responses follow the API's design guarantees: every field is always present (null or empty rather than omitted), enum values are stable and only ever added to, and an unavailable upstream yields a partial 200 with the failure recorded in sources_failed rather than an error.

get/entity/{company_number}

entity.show

Authentication. Requires a Bearer API key (prefixed uk_live_ for production or uk_test_ for sandbox) in the Authorization header.

Parameters

Path parameters

company_numberstringrequired

Query parameters

sourcesstringoptional
freshstringoptionaldefault: false
include_resignedbooleanoptionaldefault: false

Include resigned officers in officers.items (default false — active officers only). total_results, active_count and resigned_count always reflect the full officer set regardless of this flag.

Example request

curl "https://api.rotuli.co.uk/v1/entity/01234567" \
  -H "Authorization: Bearer uk_live_your_key"

Responses

200Full entity profile with risk signals
Body
company_numberstringrequired
namestring | nullrequired
statusstring | nullrequired
fetched_atstringdate-timerequired
sources_checkedstring[]required

Sources the API attempted to query for this request — the requested set (defaults to all available for your tier, or the ?sources= subset). A source that failed remains listed here and also appears in sources_failed; sources_failed is a subset of sources_checked. Successfully consulted sources = sources_checked minus the keys of sources_failed.

Array items — allowed values

chch_pscinsolvencychargesofficers
sources_failedobjectrequired

Sources that could not be queried, as an object keyed by source name with a human-readable failure reason. Empty object when every attempted source succeeded. Always present. Its keys are always a subset of sources_checked.

Object with dynamic string keys; each value is string.

chobjectrequired

Companies House profile data

namestringoptional
company_numberstringoptional
statusstringoptional
typestring | nulloptional
incorporated_onstring | nulldateoptional
dissolved_onstring | nulldateoptional
sic_codesstring[]optional
registered_office_addressobject | nulloptional
accounts_overduebooleanoptional
confirmation_overduebooleanoptional
has_chargesbooleanoptional
has_insolvency_historybooleanoptional
postcodestring | nulloptional
ch_fetched_atstringdate-timeoptional
ch_pscobjectrequired

Persons with significant control

personsobject[]required

Array items

namestring | nulloptional
nature_of_controlstring[]optional
notified_onstring | nulldateoptional
nationalitystring | nulloptional
country_of_residencestring | nulloptional
insolvencyobjectrequired

Insolvency proceedings

has_active_insolvencybooleanrequired
casesobject[]required
insolvency_fetched_atstringdate-timerequired
chargesobjectrequired

Companies House registered charges (security interests) against company assets. Always present; a tri-state status distinguishes "no charges" from "not requested / fetch failed".

statusstringrequired

"none" = confirmed no charges recorded. "present" = one or more charges exist (satisfied charges are included as borrowing history). "unknown" = not requested, or the fetch failed (then charges also appears in sources_failed). Never "none" for a skipped or failed fetch.

Allowed values

nonepresentunknown
total_countintegerrequired
satisfied_countintegerrequired
part_satisfied_countintegerrequired
outstanding_countintegerrequired

Derived: total_count minus satisfied_count minus part_satisfied_count.

truncatedbooleanrequired

True when upstream pagination could not return every charge — items is shorter than total_count and must not be treated as a complete list.

itemsobject[]required

Array items

charge_numberintegerrequired
statusstringrequired

Allowed values

outstandingsatisfiedfully_satisfiedpart_satisfiedother
created_onstring | nulldaterequired
delivered_onstring | nulldaterequired
satisfied_onstring | nulldaterequired
persons_entitledstring[]required
classificationstring | nullrequired
particularsstring | nullrequired
contains_floating_chargeboolean | nullrequired

From CH structured particulars. Null when Companies House did not supply the flag.

floating_charge_covers_allboolean | nullrequired

True when the floating charge covers the whole undertaking (debenture-style). Null when Companies House did not supply the flag.

assets_ceased_releasedstring | nullrequired
officersobjectrequired

Companies House officers (directors, secretaries, LLP members) for this company. Always present; a tri-state status distinguishes "no officers" from "not requested / fetch failed". Active officers only by default — pass ?include_resigned=true to add resigned officers to items; total_results, active_count and resigned_count are always full counts regardless of include_resigned.

statusstringrequired

"none" = confirmed no officers recorded (only assertable once company existence is proven). "present" = one or more officers exist. "unknown" = not requested, or the fetch failed (then officers also appears in sources_failed). Never "none" for a skipped or failed fetch.

Allowed values

nonepresentunknown
total_resultsintegerrequired

Full officer count Companies House holds, regardless of include_resigned.

active_countintegerrequired
resigned_countintegerrequired
truncatedbooleanrequired

True when the fetched items fell short of total_results (defensive pagination against unreliable upstream paging).

itemsobject[]required

Active officers only by default; resigned officers are included when include_resigned=true.

Array items

officer_idstring | nullrequired

Stable CH officer identifier, parsed from the appointments link. Null when absent or unparseable.

namestring | nullrequired
officer_rolestring | nullrequired

Raw Companies House officer_role value (28 upstream values, e.g. director, corporate-director, nominee-director, corporate-nominee-director, secretary, llp-member). Stored intact — callers should tolerate unknown values.

appointed_onstring | nulldaterequired
appointed_beforestring | nulldaterequired

Set instead of appointed_on for appointments predating Companies House's digital record (pre-1992).

is_pre_1992_appointmentbooleanrequired
resigned_onstring | nulldaterequired

Null means the officer is currently active.

nationalitystring | nullrequired
country_of_residencestring | nullrequired
date_of_birthobject | nullrequired

Month and year only — the day is never returned (data minimisation, same treatment as PSC dates of birth).

monthintegerrequired
yearintegerrequired
former_namesobject[]required

Array items

forenamesstring | nullrequired
surnamestring | nullrequired
identificationobject | nullrequired

Corporate officers only. Null for natural persons.

legal_formstring | nullrequired
place_registeredstring | nullrequired
registration_numberstring | nullrequired
legal_authoritystring | nullrequired
identity_verificationobject | nullrequired

ECCTA identity verification details. Null when the upstream record carries none.

identity_verified_onstring | nulldaterequired
authorised_corporate_service_provider_namestring | nullrequired
anti_money_laundering_supervisory_bodiesstring[]required
appointment_verification_statement_due_onstring | nulldaterequired
appointment_verification_statement_start_onstring | nulldaterequired
appointment_verification_statement_end_onstring | nulldaterequired
preferred_namestring | nullrequired
directorsobject[]required

Array items

officer_idstring | nullrequired
namestring | nullrequired
appointed_onstring | nulldaterequired
resigned_onstring | nulldaterequired
risk_signalsobjectoptional

Risk signals derived from the assembled profile. Paid feature: omitted entirely for free-tier keys (treat absence as "not entitled", not "no risk"), so it is not a required field.

scoreintegerrequired

Points from confirmed (triggered) flags only, 0-100. A floor (lower bound) when score_is_floor is true.

score_is_floorbooleanrequired

When true, a required source was unavailable so score is a lower bound — a low value does not mean low risk.

potential_scoreintegerrequired

Worst-case ceiling: score plus the points of every indeterminate flag, capped at 100. Equals score when indeterminate is empty.

coveragestring[]required

Risk-bearing sources actually consulted for this score. A source absent here was not assessed.

Array items — allowed values

chch_pscinsolvencycharges
flagsobject[]required

Array items

codestringrequired

Allowed values

INSOLVENCY_ACTIVECOMPANY_DISSOLVEDACCOUNTS_OVERDUECONFIRMATION_OVERDUECOMPANY_VERY_NEWNO_PSC_RECORDEDOUTSTANDING_CHARGESALL_ASSETS_CHARGED
severitystringrequired

Allowed values

criticalwarninginfo
descriptionstringrequired
triggered_atstringdate-timerequired
indeterminateobject[]required

Flags that could not be evaluated because a required source was unavailable.

Array items

codestringrequired

Allowed values

INSOLVENCY_ACTIVECOMPANY_DISSOLVEDACCOUNTS_OVERDUECONFIRMATION_OVERDUECOMPANY_VERY_NEWNO_PSC_RECORDEDOUTSTANDING_CHARGESALL_ASSETS_CHARGED
severitystringrequired

Allowed values

criticalwarninginfo
sourcestringrequired

Allowed values

chch_pscinsolvencycharges
reasonstringrequired

Allowed values

source_unavailablenot_requestedfeature_disabled
404
Body
errorstringrequired

Allowed values

company_not_found
messagestringrequired
422Validation error
Body
messagestringrequired

Errors overview.

errorsobjectrequired

A detailed description of each field that failed validation.

Object with dynamic string keys; each value is string[].

429Companies House upstream is at capacity, so the CH core fetch was shed (proactive budget limiter or reactive CH 429). Distinct from rate_limit_exceeded, which is your per-key tier limit — upstream_capacity reflects the shared registry being saturated, not your usage. Retry after the Retry-After interval.
Response headers
Retry-AfterSeconds to wait before retrying.
Body
errorstringrequired

Allowed values

upstream_capacity
messagestringrequired
get/entity/{company_number}/risk

entity.risk

Authentication. Requires a Bearer API key (prefixed uk_live_ for production or uk_test_ for sandbox) in the Authorization header.

Parameters

Path parameters

company_numberstringrequired

Example request

curl "https://api.rotuli.co.uk/v1/entity/01234567/risk" \
  -H "Authorization: Bearer uk_live_your_key"

Responses

200Risk signals for a company
Body
company_numberstringrequired
risk_signalsobjectrequired

Risk signals derived from the assembled profile. Paid feature: omitted entirely for free-tier keys (treat absence as "not entitled", not "no risk"), so it is not a required field.

scoreintegerrequired

Points from confirmed (triggered) flags only, 0-100. A floor (lower bound) when score_is_floor is true.

score_is_floorbooleanrequired

When true, a required source was unavailable so score is a lower bound — a low value does not mean low risk.

potential_scoreintegerrequired

Worst-case ceiling: score plus the points of every indeterminate flag, capped at 100. Equals score when indeterminate is empty.

coveragestring[]required

Risk-bearing sources actually consulted for this score. A source absent here was not assessed.

Array items — allowed values

chch_pscinsolvencycharges
flagsobject[]required

Array items

codestringrequired

Allowed values

INSOLVENCY_ACTIVECOMPANY_DISSOLVEDACCOUNTS_OVERDUECONFIRMATION_OVERDUECOMPANY_VERY_NEWNO_PSC_RECORDEDOUTSTANDING_CHARGESALL_ASSETS_CHARGED
severitystringrequired

Allowed values

criticalwarninginfo
descriptionstringrequired
triggered_atstringdate-timerequired
indeterminateobject[]required

Flags that could not be evaluated because a required source was unavailable.

Array items

codestringrequired

Allowed values

INSOLVENCY_ACTIVECOMPANY_DISSOLVEDACCOUNTS_OVERDUECONFIRMATION_OVERDUECOMPANY_VERY_NEWNO_PSC_RECORDEDOUTSTANDING_CHARGESALL_ASSETS_CHARGED
severitystringrequired

Allowed values

criticalwarninginfo
sourcestringrequired

Allowed values

chch_pscinsolvencycharges
reasonstringrequired

Allowed values

source_unavailablenot_requestedfeature_disabled
fetched_atstringdate-timerequired
404
Body
errorstringrequired

Allowed values

company_not_found
messagestringrequired
422Validation error
Body
messagestringrequired

Errors overview.

errorsobjectrequired

A detailed description of each field that failed validation.

Object with dynamic string keys; each value is string[].

429Companies House upstream is at capacity, so the CH core fetch was shed (proactive budget limiter or reactive CH 429). Distinct from rate_limit_exceeded, which is your per-key tier limit — upstream_capacity reflects the shared registry being saturated, not your usage. Retry after the Retry-After interval.
Response headers
Retry-AfterSeconds to wait before retrying.
Body
errorstringrequired

Allowed values

upstream_capacity
messagestringrequired