> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poddata.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# A diligence, start to end

> Take a company as a target, have a person confirm its links and rivals, ask PodData to read them, write the report, and save every file to disk.

This is the whole of a commercial diligence on one company: the target, the sources PodData reads for it, its rivals, and a report whose every figure comes from what was read. Each step gives its route under `https://api.poddata.ai/v1` and the MCP tool that does the same. The examples use a made-up dental group, Northwind Dental, whose id is `northwind-dental`.

Send the key on every call as `Authorization: Bearer $PODDATA_API_KEY`, as [Keys and limits](https://docs.poddata.ai/keys-and-limits.md) says. A person confirms each link and each rival: you propose, show, and ask.

## 1. Take the company

Find it first, so you take the company PodData holds rather than making a second of the same name.

```bash theme={null}
curl -s 'https://api.poddata.ai/v1/companies?q=Northwind%20Dental' -H "Authorization: Bearer $PODDATA_API_KEY"
```

Then add it to the team's targets: by its `company` id if PodData holds it, or by its `name` and its own website's `domain` if not. A company that files with the SEC can be added by its `ticker` instead, and PodData reads its filings.

```bash theme={null}
curl -s -X POST https://api.poddata.ai/v1/targets \
  -H "Authorization: Bearer $PODDATA_API_KEY" -H 'Content-Type: application/json' \
  -d '{"name": "Northwind Dental", "domain": "northwind-dental.example"}'
```

```json theme={null}
{
  "company": { "id": "northwind-dental", "name": "Northwind Dental" },
  "listed_on": "target_only",
  "added_at": "2026-11-12T15:04:00.000Z",
  "added_by": { "kind": "member", "email": "ana@lakeside-capital.example" },
  "links": { "confirmed": 0, "proposed": 1 },
  "filings": null
}
```

`201` is a new target; `200` means it was one already. Tools: `find_company`, `add_target`, and `list_targets` for the team's targets.

## 2. Its links

PodData reads a company only through its links: its domain, its places on Google, its listings on review sites and marketplaces, its accounts, its numbers at registries. `POST /targets/{company}/find` reads the company's own site and proposes each account its pages link to, and lists the addresses on its location pages.

```bash theme={null}
curl -s -X POST https://api.poddata.ai/v1/targets/northwind-dental/find -H "Authorization: Bearer $PODDATA_API_KEY"
```

`GET /companies/{id}/links` lists every link, each `proposed`, `confirmed` or `struck`, with the page that shows it's theirs. Propose one PodData missed, such as a Google place you matched to an address, with `POST /companies/{id}/links`:

```bash theme={null}
curl -s -X POST https://api.poddata.ai/v1/companies/northwind-dental/links \
  -H "Authorization: Bearer $PODDATA_API_KEY" -H 'Content-Type: application/json' \
  -d '{"kind": "google_place", "value": "ChIJ…", "evidence": "https://northwind-dental.example/locations/riverside"}'
```

Tools: `find_links`, `company_links`, `propose_link`.

## 3. Its rivals

`POST /targets/{company}/rivals/find` tests candidates like for like: from a `list` the person gives, from what PodData holds, and from stories that name the target. It reads each candidate's own site, and two models of different families each say what it sells, to whom and where. Only a rival both agree on is proposed; every other candidate comes back in `left_out` with why.

```bash theme={null}
curl -s -X POST https://api.poddata.ai/v1/targets/northwind-dental/rivals/find \
  -H "Authorization: Bearer $PODDATA_API_KEY" -H 'Content-Type: application/json' \
  -d '{"list": [{"name": "Bluebird Dental", "domain": "bluebird-dental.example"}]}'
```

Each proposed rival has its `verdict`, the words of its own page that show it (`shows`), and `overlap`: the codes, towns and words the two firms share that no model said. `supported: false` marks a rival only the models' reading backs: say so to the person. `GET /companies/{id}/rivals` lists them; propose one the person names with `POST /companies/{id}/rivals`. Tools: `find_rivals`, `company_rivals`, `propose_rival`.

If it's refused with a `400` asking for `about`, the target's own site couldn't be read: ask the person what the company sells, to whom and where, and send it as `about`.

## 4. A person says yes to each

Show the person each proposed link and rival, with its page and why, and ask. Only on their yes, confirm it; on their no, strike it with `why`. Never confirm one on your own.

| To | Route | Tool |
| - | - | - |
| Confirm a link | `POST /companies/{id}/links/{link}/confirm` | `confirm_link` |
| Strike a link | `POST /companies/{id}/links/{link}/strike` | `strike_link` |
| Confirm a rival | `POST /companies/{id}/rivals/{rival}/confirm` | `confirm_link` |
| Strike a rival | `POST /companies/{id}/rivals/{rival}/strike` | `strike_link` |

```bash theme={null}
curl -s -X POST https://api.poddata.ai/v1/companies/northwind-dental/rivals/bluebird-dental/confirm -H "Authorization: Bearer $PODDATA_API_KEY"
```

Once a rival is confirmed, confirm its own links the same way, at `/companies/bluebird-dental/links`, or propose them from its site with `POST /targets/{company}/find` and `{"rival": "bluebird-dental"}`. Links and rivals already confirmed stay confirmed: ask only about what's still proposed.

A `409` on a confirm means the value is confirmed for another company already. Show the person the message: if the two are the same company, it says how to take that one.

## 5. The read

Each source reads on its own cadence, a day or a week for most. Ask PodData to read the target and its confirmed rivals now:

```bash theme={null}
curl -s -X POST https://api.poddata.ai/v1/targets/northwind-dental/read \
  -H "Authorization: Bearer $PODDATA_API_KEY" -H 'Content-Type: application/json' -d '{"rivals": true}'
```

`202` lists the sources `queued` for the target and for each rival, and those `waiting` on a kind of link no one has confirmed. Each queued source takes it first on its next run, within the quarter hour. `200` with nothing queued means no source here can read it yet: confirm more links.

Then `GET /targets/{company}/coverage` says, source by source, where each stands (`read`, `due`, `waiting` and the rest), what it holds and over which days, and the same for each confirmed rival:

```bash theme={null}
curl -s https://api.poddata.ai/v1/targets/northwind-dental/coverage -H "Authorization: Bearer $PODDATA_API_KEY"
```

Coverage's `read` says where the read you asked for stands, for the target and, under `rivals`, for each rival:

* `going`: sources still to run. `left` lists each, with why.
* `done`: every source it queued has run since you asked. Go on.
* `held`: each source still to run is stopped at its cap for the day. `left` gives `opens`, when each starts again, at midnight UTC: come back then, or go on with what's held.

`read.why` says all of it in a sentence. To wait, ask coverage again every five minutes or so, never faster. Tools: `read_target`, `target_coverage`.

A `403` with the code `plan` means the team's reads for the day are used up: tell the person, and work with what's held.

## 6. The report

A report has an overview and five pages: customer, competitive, news, trends and expert. Make one:

```bash theme={null}
curl -s -X POST https://api.poddata.ai/v1/diligence-reports \
  -H "Authorization: Bearer $PODDATA_API_KEY" -H 'Content-Type: application/json' -d '{"company": "northwind-dental"}'
```

It answers the report with its five pages empty, its id (`dlr_…`) and its version (`rev`). Then write it yourself, by the diligence skill:

1. Plan two questions a page, as a buyer would ask them.
2. Ask a number tool for each figure, such as `GET /companies/{id}/numbers/rating-rivals`. Never add up rows yourself. See [Number tools](https://docs.poddata.ai/number-tools.md).
3. Save each page with `PUT /diligence-reports/{id}/pages/{page}`, its copy citing each figure in braces, `{customer-1.average}`, from an exhibit that saves the tool's question. See [A diligence report](https://docs.poddata.ai/reports.md).
4. Check it with `POST /diligence-reports/{id}/check`, and fix what it refuses, until it refuses nothing.
5. Read it with every figure filled with `GET /diligence-reports/{id}`, or download it as Markdown with `?format=md`, or as a zip of its pages, each exhibit's rows as CSV and its evidence with `?format=zip`.

Tools: `start_report`, `save_report_page`, `check_report`, `get_report`, `list_reports`.

Or have PodData's own agent write it. PodData pays for its turns, so ask the person first:

```bash theme={null}
curl -s -X POST https://api.poddata.ai/v1/diligence-reports/dlr_01JD9K4M5N6P00000000000000/runs \
  -H "Authorization: Bearer $PODDATA_API_KEY" -H 'Content-Type: application/json' -d '{}'
```

It answers `202` with the run, which goes on in the background: an agent a page, one for the overview, then the check. Read it with `GET /diligence-runs/{id}` every minute or so until its status is `done`, `stopped`, `capped`, `refused` or `failed`, then read the report. With `message`, a run makes that one change and leaves the rest. One run of a report at a time: a second is a `409` that names the first. A plan sets how many runs a key starts a UTC day, and past them it's a `429` with `Retry-After`. Tools: `start_report_run`, `get_report_run`, `list_report_runs`.

## 7. Save everything

`GET /targets/{company}/folder` is the index of everything held for the target, each confirmed rival, and its parent and comparables: for each source and kind, how many rows, their days, a CSV address (`file`) and a JSON address (`rows`), and why a file is held back where one is. `?format=zip` is the folder's files in one zip. See [A target's folder](https://docs.poddata.ai/folder.md).

The skill's puller does it all in one command, with Node 18 or later and the key in `PODDATA_API_KEY`:

```bash theme={null}
node .claude/skills/poddata-diligence/scripts/pull.mjs northwind-dental --out .
```

It saves `northwind-dental/`, with `target/`, `rivals/<id>/`, `parent/<id>/` and `comparables/<id>/`, each with its records, signals, documents, site and ads, then the quotes, the team's licensed figures, each report as JSON, `index.json`, `coverage.csv`, a `manifest.json` of every file and a `README.md` of what's there and what was left out and why. It keeps under the key's limits, can be run again and fetches only what changed, and never prints or saves the key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.