Skip to main content
Tutorial

Build a Due-Diligence Agent on Official Public Data

An agent that checks a company across SEC EDGAR, Companies House and GLEIF, cites every source and flags what it could not find.

fastcrw
By RecepNovember 19, 20269 min read

By the fastCRW team · Catalogue figures checked 2026-11-05 against GET /v1/data · Verify independently before relying on any figure.

A due-diligence agent answers a short list of questions about one company: who it is, what it files, who runs it, who owns it, and who its parent is. Each answer comes from an official register, and each fact carries its citation. When the agent cannot find something, it says so instead of guessing. This guide builds that agent on three public sources: SEC EDGAR, Companies House and GLEIF. All three are in the Pergamon catalogue, so one API key and one response shape cover them.

What the agent answers

Keep the scope small and fixed. The agent answers five questions:

  • Identity: the legal name and the registry identifier, from GLEIF or Companies House.
  • Filings: recent SEC filings for a US issuer, from SEC EDGAR.
  • Officers: the directors and officers on the UK register, from Companies House.
  • Owners: the persons with significant control on the UK register, from Companies House.
  • Parent: the direct parent, if GLEIF reports one.

Each question maps to one or two catalogue calls. A company that is not in a register is a result too, and the brief must show it.

Tool wiring

You can wire the agent in two ways. Both call the same capabilities and both return the same provenance block. Use MCP tools when a person works with the agent inside an editor or chat client. Use the SDK when a scheduled job writes briefs to a file.

  • MCP tools. Your agent calls crw_find_data to discover a capability and crw_get_data to run it. Install the server with the command below, or point an MCP client at the hosted endpoint for server-run sources:
npx -y crw-mcp install --api-key <your fastCRW API key>
{"name": "crw_get_data", "arguments": {"provider": "gleif", "capability": "lei-record", "options": {"lei": "HWUPKR0MPOU8FGXBT394"}}}
  • Python SDK. A script calls get_data in order, collects the citations and writes the brief. The rest of this guide uses the SDK, because the code is easier to test and to read.

With MCP tools, the instruction to the agent can be short and strict:

Check the company the user names. Use crw_find_data only if you do not know the
capability, and crw_get_data to run it. Resolve the company to an identifier first.
Write one line per fact and end each line with the source's attributionText and
upstreamUrl. List every lookup that returned nothing under "Not found". Do not
give a verdict and do not guess a missing fact.

A first tool call then looks like this, with the options for the capability taken from the find output:

{"name": "crw_get_data", "arguments": {"provider": "companieshouse", "capability": "company-search", "options": {"q": "monzo"}}}

For the SDK, set your key in the CRW_API_KEY environment variable, then install it with pip install crw. The SDK reads the key and defaults to the public API.

Step 1: resolve the entity

Names are not identifiers. A single name can match several companies and similar names. Resolve the company first, then carry the identifier through every later step. Three search capabilities cover the three sources:

curl "https://api.fastcrw.com/v1/data/gleif/autocomplete?q=monzo" \
  -H "Authorization: Bearer $CRW_API_KEY"

curl "https://api.fastcrw.com/v1/data/secfts/entity-suggest?keysTyped=apple" \
  -H "Authorization: Bearer $CRW_API_KEY"

curl "https://api.fastcrw.com/v1/data/companieshouse/company-search?q=monzo" \
  -H "Authorization: Bearer $CRW_API_KEY"

Each search returns candidates. Pick one only when the name, the jurisdiction and the identifier agree. If two candidates are close, stop and ask the user, or record the ambiguity in the brief. Do not take the first hit as the answer. Keep the rejected candidates in the brief as well, so a reader can see what the agent set aside and why.

Step 2: pull the records

With the identifiers in hand, pull each record. The GLEIF record is keyed by the LEI, the 20-character legal entity identifier. The SEC submissions record is keyed by the CIK, and the CIK must be zero-padded to 10 digits. Apple's CIK is 0000320193. Pad the number to 10 digits before you call, as in this example:

curl "https://api.fastcrw.com/v1/data/sec/submissions?cik=0000320193" \
  -H "Authorization: Bearer $CRW_API_KEY"

Companies House is keyed by the company number. The company, officers and psc capabilities each take it as companyNumber. psc is the register of persons with significant control, the people or entities that own or control the company:

curl "https://api.fastcrw.com/v1/data/companieshouse/officers?companyNumber=09446231" \
  -H "Authorization: Bearer $CRW_API_KEY"

The catalogue also lists USAspending for federal awards. It is optional for this brief. Read its options from the find output before you add it.

GLEIF has a direct-parent capability keyed by the LEI. When GLEIF has no parent for an entity, that call answers 404, and it did for Apple's LEI on 2026-11-05. Treat that as "no parent reported", not as an error. The script below records any failed call as a gap, so a 404 shows up as a line in the "not found" list.

Step 3: write the brief with one citation per fact

Every successful response includes a provenance block. Use attributionText and upstreamUrl from it in the brief, so a reader can open the register that said the thing. The SDK returns these as camelCase keys. The REST response uses snake_case, as attribution_text and upstream_url. Keep one style per script.

A brief has one line per fact, and each line ends with its source. The reason is practical: a reader who doubts a line can open the register page in one click, and a reviewer can tell at a glance which fact came from which register. A fact without a citation goes into the brief as a claim you cannot defend, so leave it out. The gaps go in their own section:

Legal name: Apple Inc.
  Source: GLEIF Global LEI Index (CC0 1.0). https://api.gleif.org/api/v1/lei-records/HWUPKR0MPOU8FGXBT394
Not found or not reported:
  GLEIF direct parent: not returned (404 upstream_error)

The script

This script resolves nothing by itself. You pass the identifiers that step 1 found, and each one is optional: --lei and --cik for a US issuer, --number for a UK company. For each identifier it pulls the records, keeps the citation for every call, and records a gap for every call that fails.

# pip install crw
import argparse

from crw import CrwApiError, CrwClient

client = CrwClient()  # reads CRW_API_KEY
facts: list[str] = []
citations: list[str] = []
gaps: list[str] = []


def pull(label: str, provider: str, capability: str, options: dict) -> dict | None:
    """Call one capability, keep its citation, and record a gap on failure."""
    try:
        result = client.get_data(provider, capability, options)
    except CrwApiError as err:
        gaps.append(f"{label}: not returned ({err.status_code} {err.error_code})")
        return None
    prov = result["provenance"]
    citations.append(f"{label}: {prov['attributionText']} {prov['upstreamUrl']}")
    return result["data"]


def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument("--lei", help="20-character LEI")
    parser.add_argument("--cik", help="SEC CIK, zero-padded to 10 digits")
    parser.add_argument("--number", help="Companies House company number")
    args = parser.parse_args()

    if args.lei:
        record = pull("GLEIF record", "gleif", "lei-record", {"lei": args.lei})
        if record:
            facts.append(f"Legal name: {record['data']['attributes']['entity']['legalName']['name']}")
        # a 404 here means GLEIF reports no direct parent, which lands in the gaps list
        pull("GLEIF direct parent", "gleif", "direct-parent", {"lei": args.lei})
    if args.cik:
        filings = pull("SEC EDGAR submissions", "sec", "submissions", {"cik": args.cik})
        if filings:
            facts.append(f"SEC name: {filings['name']}, tickers: {filings['tickers']}")
    if args.number:
        company = pull("Companies House company", "companieshouse", "company", {"companyNumber": args.number})
        if company:
            facts.append(f"UK company: {company['company_name']}, status: {company['company_status']}")
            officers = pull("Companies House officers", "companieshouse", "officers", {"companyNumber": args.number})
            pscs = pull("Companies House PSC", "companieshouse", "psc", {"companyNumber": args.number})
            if officers:
                facts.append(f"Officers on the register: {officers['active_count']} active")
            if pscs:
                facts.append(f"Persons with significant control: {pscs['active_count']} active")

    for title, lines in (("Facts", facts), ("Sources", citations), ("Not found or not reported", gaps)):
        print(f"\n{title}:")
        print("\n".join(lines) or "none")


if __name__ == "__main__":
    main()

The script prints facts, citations and gaps. It does not print a verdict, because a verdict about a company is a human decision. It checks the Companies House company record first and only then reads officers and persons with significant control. Run on 2026-11-05, an officers call for the made-up number 00000000 returned a 200 with 0 active officers, so an empty officers list alone does not tell you the company is missing.

Test it on a known company before you trust it

Run the script on companies whose records you can check by hand. With Apple's identifiers it printed two facts, two citations and one gap:

python due_diligence.py --lei HWUPKR0MPOU8FGXBT394 --cik 0000320193

Facts:
Legal name: Apple Inc.
SEC name: Apple Inc., tickers: ['AAPL']

Not found or not reported:
GLEIF direct parent: not returned (404 upstream_error)

With --number 09446231 it printed MONZO BANK LIMITED, status active, 9 active officers and 1 active person with significant control. With --number 00000000 it printed no facts and one gap, Companies House company: not returned (404 upstream_error). Compare each fact with the register page its citation points to. A brief that looks complete on a real company but stays silent on a fake one is the failure to catch.

Keep the gaps list in your logs as well. A pattern of gaps for one jurisdiction usually means a matching problem in step 1, not missing public data.

Honest limits

  • No sanctions list. The catalogue has no sanctions source today. A find for sanctions and a find for OFAC both returned 0 items on 2026-11-05. Check a sanctions source separately, and re-run the find before you write this line into a product.
  • Jurisdiction matters. SEC EDGAR covers companies that file with the SEC. Companies House covers UK companies. A UK company may have no SEC filings, and a US company may have no UK register entry. An empty result means the register has no match, not that the company is clean.
  • Matching is fuzzy. Name search returns candidates. Confirm the identifier before you trust a record.
  • Records can lag. Registers update on their own schedules. Show the retrieval time from the provenance block next to any fact that could change.
  • Not legal advice. The brief is a research aid. A lawyer or compliance team makes the decision.

Sources

Related: GLEIF on Pergamon · Companies House on Pergamon · SEC EDGAR on Pergamon · SEC EDGAR API in Python · Company registry APIs: Companies House, GLEIF and SIREN · Lead enrichment with fastCRW · Financial research agent · Public data API for AI agents · Pergamon catalogue

FAQ

Frequently asked questions

Does this agent run a sanctions or KYC check?
No. The catalogue has no sanctions source today, and the agent does not screen names against any list. Use a dedicated sanctions source for that check, and treat this agent's output as research support.
What does it mean when a company has no parent in the brief?
GLEIF answers 404 when no direct parent is reported for an entity. The script records that as a gap, which means no parent was reported. It does not mean the company has no owner.
Why does a UK company show no SEC filings?
SEC EDGAR covers companies that file with the US Securities and Exchange Commission. A UK company that does not file there has nothing in EDGAR, so the brief lists it under not found and relies on Companies House.
Do failed calls cost credits?
No. An upstream error, such as a 404 or a timeout, returns success set to false with no credits_used, so a failed lookup in the script does not bill you.

Get Started

Try fastCRW free

Run a live request in the playground — no signup required. Or grab a free API key with 500 credits, earn up to 500 more, no credit card.

Continue exploring

More tutorial posts

View category archive