API
Search the registers over HTTP
Search all three UK charity registers by name or registration number. JSON out, highest income first, with tidied names and addresses and a logo for each charity.
Keys and limits
You can try the API without a key: each IP address gets 60 requests a minute. For more, ask us for a key and send it with every request:
curl -H 'Authorization: Bearer clk_…' '/v1/charities?q=oxfam'
A key allows 600 requests a minute. X-API-Key: clk_… works too. Keep keys on your server: anyone who can see one can use it. Over the limit you'll get 429 with a Retry-After header.
Logos have their own limit of 300 a minute, and only count when we have to fetch one: logos served from our cache are never limited. Logo URLs work without a key; a server fetching them can add ?key= to use its key's limit.
Responses allow any origin (CORS), so you can call the API from a browser without a key.
Search
GET /v1/charities
curl '/v1/charities?q=macmillan®ister=ew&limit=5'
| Param | Meaning |
|---|---|
q | Required. Part of the charity's name or one of its other names, at least 3 characters, or the start of its registration number. |
register | ew (England & Wales), sc (Scotland), ni (Northern Ireland) or all (default). |
limit | How many results, from 1 to 50. Default 15. |
Matching ignores case and accents, so cafe finds CAFÉ. There's no paging: if you get limit results back, ask for more of the name. Removed charities aren't included.
Returns {"data": [ … ]}, each item a charity.
One charity
GET /v1/charities/{register}/{regno}
curl '/v1/charities/ew/202918'
Returns {"data": { … }}, or 404 if that register has no such number.
Fields
{
"register": "ew",
"regno": "202918",
"name": "OXFAM",
"known_as": ["OXFAM GB"],
"company_number": "00612172",
"income": 339366903,
"website": "https://www.oxfam.org.uk/",
"logo": "https://charities.superlawyer.io/v1/charities/ew/202918/logo",
"address": {
"lines": ["2600 John Smith Drive", "Oxford Business Park South", "Oxford"],
"postcode": "OX4 2JY"
},
"display": {
"name": "Oxfam",
"address": {
"lines": ["2600 John Smith Drive", "Oxford Business Park South", "Oxford"],
"postcode": "OX4 2JY"
}
}
}
| Field | Notes |
|---|---|
register | ew, sc or ni. |
regno | Registration number, always a string. Scottish numbers start SC. |
name | Registered name, exactly as the register has it (often in capitals). |
known_as | Other names the charity uses. Always an array, possibly empty. Searches match these too. |
company_number | Companies House number if the charity is also a company, otherwise null. Always null for Scotland. |
income | Latest reported income in pounds, or null. Results are ordered by it. |
website | The register's website as a full URL, or null. |
logo | URL of the site's icon, ready for an <img> (no key needed). null if the charity has no website. It can still 404 when the site has no icon, so handle the image's error event. |
address | As the register has it: lines without blanks, a first line that repeats the name, or the postcode; postcode or null. |
display | The name and address tidied for showing to people: title case, with ordinals (3rd Floor), postcodes and abbreviations such as UK and LTD kept right. |
Errors
Errors are JSON with a status code: {"error": {"code": "query_too_short", "message": "…"}}.
| Status | Codes |
|---|---|
400 | missing_query, query_too_short, invalid_register, invalid_limit |
401 | invalid_api_key: a key was sent but isn't valid. |
404 | not_found |
429 | rate_limited: wait for Retry-After seconds. |
Health
GET /health
When the dataset was built and how many charities each register has, with the date of each register's extract. Live right now:
Loading…
Legacy endpoint
GET /charities/search
The old Laravel service's API, kept byte for byte so existing callers don't need to change. New integrations should use /v1/charities. Returns up to 15 charities, highest income first.
curl '/charities/search?term=oxfam&jurisdiction=all&lower=1'
Parameters
| Param | Meaning |
|---|---|
term | Name contains term, or registration number starts with it. Overrides name and reg_no. |
name | Name contains name. |
reg_no | Registration number starts with reg_no. Combined with name using AND. |
jurisdiction | eng (default), scot (or sco), ni or all. Anything else returns []. |
lower | 1 to title-case names and addresses (OXFAM becomes Oxfam). |
key | Your API key, if you have one (or send it as a header, as for /v1). An unrecognised key isn't an error: the request just counts as anonymous. |
Matching ignores case and accents, so cafe finds CAFÉ. Charities that have been removed from a register aren't included.
Response
A JSON array. Here's ?term=oxfam&jurisdiction=eng&lower=1:
[
{
"regno": 202918,
"name": "Oxfam",
"add1": "Oxfam",
"add2": "2600 John Smith Drive",
"add3": "Oxford Business Park South",
"add4": "Oxford",
"add5": "",
"postcode": "OX4 2JY",
"web": "www.oxfam.org.uk",
"full_address": "Oxfam, 2600 John Smith Drive, Oxford Business Park South, Oxford, OX4 2JY",
"known_as": [
"OXFAM GB"
],
"company_number": "00612172",
"logo_url": "https:\/\/charities.example.com\/charities\/202918\/logo"
}
]
| Field | Notes |
|---|---|
regno | Registration number. A number when jurisdiction=eng, a string otherwise (Scottish numbers start SC). |
name | Registered name. |
add1–add5 | Address lines, without the postcode. Unused lines are "". |
postcode | Can be "". |
web | Website as the register has it, often without https://. null if there isn't one. |
full_address | The address lines and postcode, joined with ", ". |
known_as | Other names the charity uses. Always an array, possibly empty. |
company_number | Companies House number if the charity is also a company, otherwise null. Always null for Scotland (OSCR doesn't publish it). Northern Ireland numbers are as CCNI has them, without the NI prefix or leading zeros. |
logo_url | Public URL of the charity's site icon, ready to drop into an <img>. null if the charity has no website. A URL doesn't promise an icon: it 404s when the site hasn't got one, so handle the image's error event. |