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

> ## Agent Instructions
> getclean's own MCP server is at https://mcp.getclean.ai/mcp. The /mcp path of this docs site is Mintlify's search over these pages, not getclean.
> Every answer of the API opens with outcome. A page that could not be read is a record whose outcome says why, never an HTTP error; read outcome before anything else.
> The API's contract is the OpenAPI 3.1 file at https://docs.getclean.ai/openapi.yaml; the SDKs are generated from it.
> The product's name is written getclean, in lower case.

# Find the exact paper, case, or company by its identifier

> Search by an exact code in place of words: a DOI, a docket number, a ticker, a registry number, and 12 more schemes. The search goes to the datasources that can look the code up, and each result says which codes it matches.

A name is a poor way to find one thing. The same name can belong to 2 companies, one paper is cited under 3 spellings of its title, and a draft can cite a court case that was never decided. An identifier names exactly one thing: a DOI names one paper, a docket number one case, a registry number one company. A search takes identifiers beside the question, or in place of it.

## Search by an identifier

Send the code in `subject_identifiers`, with its `scheme`. This search looks up one paper by its DOI.

```bash cURL theme={"theme":"css-variables"}
curl https://api.getclean.ai/v1/search \
  --header "Authorization: Bearer $GETCLEAN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "subject_identifiers": [{ "scheme": "doi", "value": "10.1000/xyz123" }]
  }'
```

```python Python theme={"theme":"css-variables"}
from getclean import GetClean, SubjectIdentifier

client = GetClean()

search = client.search(
    subject_identifiers=[SubjectIdentifier(scheme="doi", value="10.1000/xyz123")],
)
```

```typescript TypeScript theme={"theme":"css-variables"}
import { GetClean } from "getclean";

const client = new GetClean();

const search = await client.search({
    subject_identifiers: [{ scheme: "doi", value: "10.1000/xyz123" }],
});
```

The search needs no `query` here: the code itself is searched. The datasources that can look up a DOI are added to the search, and the response lists each of them with the reason `identifier`.

A result says which of your codes it matches. This response is cut to that part of its first result.

```json 201 Created theme={"theme":"css-variables"}
{
  "candidates": [
    {
      "identifier_matches": [{ "scheme": "doi", "value": "10.1000/xyz123" }],
      "source_profile": { "kind": "scholarly_publisher", "role": "primary" }
    }
  ]
}
```

A result can also have `declared`, which is what the datasource says about the item: its authors, its publisher, its version, its license, and its status.

## Choose the scheme

A search takes up to 10 identifiers of these 16 schemes.

| What you look for | Schemes |
| - | - |
| A paper, a book, or a journal | `doi`, `pmid`, `arxiv`, `isbn`, `issn` |
| A company or a security | `lei`, `isin`, `ticker`, `tax_id`, `registry` |
| A court case | `docket`, `reporter_citation`, `ecli` |
| A patent | `patent` |
| A product | `asin`, `gtin` |

The number of a certificate or of a license is sent as `registry`, with the body that issued it.

## Give the issuer where a scheme needs one

A docket number means nothing without its court, and a ticker nothing without its exchange. The schemes `docket`, `ticker`, `tax_id`, and `registry` need an `issuer`.

```json Part of a request theme={"theme":"css-variables"}
{
  "subject_identifiers": [
    { "scheme": "docket", "value": "DOCKET_NUMBER", "issuer": "nysd" }
  ]
}
```

Replace `DOCKET_NUMBER` with the number of the case.

The codes of the issuers are in the catalog. Each datasource that can look up such a scheme lists the issuers it knows, so an agent reads a code from the catalog and does not guess one. If a request has a code that no datasource lists, it is refused, and the problem has the codes that are allowed.

## Check a citation before it is used

A draft cites a case by its docket number. Search by the number, and a result that matches it says the case is in the register, with its address to read.

A search that finds nothing has the outcome reason `none`. That outcome is not proof that the case does not exist. It says that the datasources named in the response do not have it, and the response names them.

## Separate what a subject says from what others say

An identifier also tells the search who the subject is. With the subject known, each result says in `source_profile.independence` whether its publisher is the subject itself, `self`, or independent of it, `independent`. `source_independence` returns only one of the 2 sides.

```json Request body theme={"theme":"css-variables"}
{
  "query": "supply chain audit findings forced labor",
  "alternate_queries": [
    "supplier audit violations working conditions",
    "Lieferkette Audit Zwangsarbeit Vorwürfe",
    "audit fournisseurs travail forcé"
  ],
  "subject_identifiers": [
    { "scheme": "lei", "value": "LEI_CODE" },
    { "scheme": "isin", "value": "ISIN_CODE" },
    { "scheme": "ticker", "value": "TICKER_SYMBOL", "issuer": "xnys" }
  ],
  "source_independence": "independent",
  "ranking_priorities": ["primary", "reviewed"]
}
```

Replace `LEI_CODE`, `ISIN_CODE`, and `TICKER_SYMBOL` with the company's codes. The 3 codes name one company, so a namesake cannot enter the results, and the question runs in 4 wordings and 3 languages.

Run the search once for each side, and a diligence report can have 2 columns: what the company says of itself, and what independent sources say.

## Check what a lookup costs

A search by identifier is charged as any search: one unit for the search and one for each wording on each datasource. Each identifier without a `query` counts as one wording.


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