Building a Charity Lookup Tool with the Charity Commission API

A real charity integration where the prototype changed the quote

Appycodes worked on a scoping engagement for a UK registered charity ahead of an invitation to tender. The work included a technical specification, a vendor-evaluation tool and a CRM recommendation. Instead of estimating the integration from sales documentation, the team built a working CRM-to-website prototype and exercised the flow end to end.

The prototype exposed three constraints that would have materially affected a fixed-price commitment: trial accounts did not provide API keys, payments used a connected-account model that could not be tested without live credentials, and the vendor offered a sandbox only on its highest plan. The hard decision was to spend delivery effort before bidding so the estimate described what could actually be proved, rather than assuming every vendor surface behaved like a conventional test API.

That project did not use the Charity Commission API, and we do not imply that it did. It provides the implementation lesson behind this guide: a public-register lookup is one bounded component in a charity product. It does not remove the need to prototype the CRM, payment, consent, eligibility and operational paths that sit around it. The verified, anonymised project summary is published in the Appycodes case-study register.

What the Charity Commission API can—and cannot—prove

The Charity Commission for England and Wales says its beta API exposes the latest information shown on its Register of Charities and requires a developer-hub subscription and API key. It supports searches by name, registration date, registered number and removal date, plus detail operations for charity records, classifications, trustees, areas of operation and financial information. Charity Commission: API documentation · Charity Commission: current operations

The biggest data-model trap is assuming the public-facing registered number is always unique to one record. The Commission’s current data definition says organisation_number is unique to a single charity, while reg_charity_number can be shared by multiple charities; group_subsid_suffix distinguishes the main record from a linked or subsidiary record. It also defines R as registered and RM as removed, and warns that the removal date is not necessarily when the charity ceased to exist or operate. Charity Commission: API data definitions

Coverage is another hard boundary. GOV.UK states that the England and Wales register does not include some charities below £5,000 income, excepted charities or exempt charities, and points users to separate registers for Scotland and Northern Ireland. GOV.UK: search the charity register OSCR publishes a daily Scottish register download and a separate beta API; Northern Ireland maintains its own searchable register. OSCR: Scottish Charity Register APIs · CCNI: Northern Ireland charity search

The Appycodes Registry Fit Gate

Score five gates from 0 to 3: 0 unknown or absent, 1 user-asserted, 2 matched with unresolved ambiguity, 3 confirmed with retained evidence. The maximum is 15. Jurisdiction and Identifier are hard gates: if either scores zero, the product cannot describe the result as a confirmed register match.

The gate is a product-control model, not a legal or statistical risk score. Its purpose is to stop a clean API response from being promoted into a claim the source does not support.

Store a confirmed snapshot, not a mutable copy of the register

Keep registry discovery, user confirmation and the business decision as separate records. A useful minimum model is:

Refresh status at the point of consequence—for example, application submission or annual renewal—rather than on every keystroke. Keep the previous snapshot so an operator can see what changed. A removed status should pause the dependent decision and explain the next step; it should not delete the customer record or erase previously supplied evidence.

A resilient Next.js registered-number lookup

The server route below validates the input, keeps the key out of the browser, uses the documented registered-number route with main-record suffix 0, applies a timeout, preserves provenance and returns a manual-review state for no exact match. Configure the base URL, key and current header name from the API definition in your developer-hub subscription rather than copying credentials into source.

// app/api/charities/[number]/route.ts
import { NextResponse } from "next/server";

type RegisterRow = {
  organisation_number: number;
  reg_charity_number: number;
  group_subsid_suffix: number;
  charity_name: string;
  reg_status: "R" | "RM";
  date_of_registration: string;
  date_of_removal: string | null;
};

const BASE_URL = process.env.CCEW_API_BASE_URL;
const API_KEY = process.env.CCEW_API_KEY;
const API_KEY_HEADER = process.env.CCEW_API_KEY_HEADER;

export async function GET(
  _request: Request,
  context: { params: Promise<{ number: string }> },
) {
  const { number } = await context.params;
  if (!/^\d{6,8}$/.test(number)) {
    return NextResponse.json({ error: "invalid_charity_number" }, { status: 400 });
  }
  if (!BASE_URL || !API_KEY || !API_KEY_HEADER) {
    return NextResponse.json({ error: "register_not_configured" }, { status: 503 });
  }

  // suffix 0 asks for the main charity record. Do not silently pick a linked
  // record when the returned suffix or organisation number differs.
  const url = new URL(`charityRegNumber/${number}/0`, BASE_URL);
  const response = await fetch(url, {
    headers: { [API_KEY_HEADER]: API_KEY },
    cache: "no-store",
    signal: AbortSignal.timeout(4500),
  });

  if (response.status === 404) {
    return NextResponse.json({ match: null, next: "manual_review" });
  }
  if (!response.ok) {
    return NextResponse.json(
      { error: "register_unavailable", next: "retry_or_manual_review" },
      { status: 503 },
    );
  }

  const rows = (await response.json()) as RegisterRow[];
  const exact = rows.find(
    (row) => row.reg_charity_number === Number(number) && row.group_subsid_suffix === 0,
  );

  return NextResponse.json({
    match: exact
      ? {
          jurisdiction: "england-wales",
          organisationNumber: exact.organisation_number,
          registeredNumber: exact.reg_charity_number,
          suffix: exact.group_subsid_suffix,
          name: exact.charity_name,
          status: exact.reg_status === "R" ? "registered" : "removed",
          removedAt: exact.date_of_removal,
          source: "Charity Commission for England and Wales",
          retrievedAt: new Date().toISOString(),
        }
      : null,
    next: exact ? "confirm_with_user" : "manual_review",
  });
}

Do not proxy arbitrary path fragments from the browser. Expose a narrow endpoint for the operation your product needs, validate the number before the upstream call and log latency, HTTP status and request purpose without logging the API key or unnecessary personal data. Cache exact public-record responses for a bounded period, but bypass or revalidate that cache when a user is about to make a consequential submission.

The Commission’s terms require API keys to remain confidential, prohibit embedding them in code or an open-source tree, recommend environment or configuration storage, and permit quotas or rate limits. They also require source attribution under the Open Government Licence. Charity Commission API terms

Failure modes that matter in production

1. Treating a fuzzy name result as the charity

Common words, local branches and historical names produce plausible candidates. Display the number, status and enough non-sensitive context for the user to choose. Save only after explicit confirmation. If the user already has a registration number, skip name search.

2. Collapsing linked charities onto one registered number

If the product discards the suffix and organisation number, later refreshes can attach the wrong linked body to an application. Make the composite source identity unique in your database and reject a different organisation number as a conflict.

3. Calling every miss “not a charity”

A miss may mean the wrong jurisdiction, a small unregistered body, an excepted or exempt charity, a spelling problem, an API outage or a record not yet available. Give the user the official registers and a manual-evidence route. The absence of one registry row is not a legal conclusion.

4. Letting an upstream outage block the entire service

Separate “register unavailable” from “no match”. Use a short timeout, limited retries with jitter, a circuit breaker and an operator-visible queue. Let a user save a draft and resume; do not convert a 503 into a rejection.

5. Copying every public field into the CRM

Public does not mean purpose-free. The API can expose contact and trustee data, but the Commission’s terms make the consumer the controller of personal data it receives, require a lawful basis and security, and can require deletion following a register-data removal notice. Retrieve the minimum fields needed, document retention and avoid using trustee data for marketing. Charity Commission API terms: personal data duties

6. Mixing registry updates with customer-confirmed facts

Do not let a refresh overwrite the operational email, billing contact, bank evidence or delivery preferences supplied by the charity. Registry data and customer data have different sources and change rules. Show a comparison and ask an authorised user or operator to resolve material differences.

Recommendations by UK product type

After real integration discovery, Appycodes recommends proving the narrowest risky flow before estimating the whole system. For a charity lookup, that means testing authentication, exact-number and linked-record behaviour, outage handling, cache rules and the handoff into the CRM or eligibility workflow with non-production data. Our API and integration service covers that discovery, adapter design, security, observability and operational handover.

Primary sources

• Charity Commission: API documentation and beta status
• Charity Commission: current API operations
• Charity Commission: API data definitions
• Charity Commission: developer-hub API terms
• GOV.UK: Register of Charities coverage and exclusions
• OSCR: Scottish Charity Register public APIs
• CCNI: Northern Ireland charity register search

Technical and operational guidance, not legal, regulatory, tax, safeguarding, fraud, sanctions or due-diligence advice. Confirm your decision policy and data use with qualified advisers where required.