> For the complete documentation index, see [llms.txt](https://docs.corpdev.ai/corpdev.ai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.corpdev.ai/corpdev.ai-docs/company-research-and-sourcing-api.md).

# Company research and sourcing API

All paths are relative to `https://api.corpdev.ai/v1/public`. Search, research and contact operations have different schemas and billing behavior.

## Company lookup

`GET /companies/lookup?query=...&limit=...` searches company names or text. `query` is required; `limit` defaults to 10 and is capped at 50. It returns `companies` and `total`, where total is the number returned, not a claim about an exhaustive global count.

```sh
curl --fail-with-body --get \
  'https://api.corpdev.ai/v1/public/companies/lookup' \
  --header "Authorization: Bearer ${CORPDEV_API_KEY}" \
  --data-urlencode 'query=Northstar' \
  --data-urlencode 'limit=5'
```

Verify the entity and domain before using a lookup result. `GET /companies/:domain` returns the accessible workspace and reference company information. `GET /companies/apollo/:id` reads a provider organization by its identifier.

## Structured company and people search

Use `POST /companies/search` with `filters`, `page` and `per_page`. A minimal body is:

```json
{
  "filters": {},
  "page": 1,
  "per_page": 10
}
```

Add supported filters for a useful production query. Unsupported filter names return 422 with supported-filter information; they are not silently ignored. Company search defaults to 25 results per page and allows up to 100.

`POST /people/search` uses its own supported filter set and defaults to 10 results per page, with a maximum of 100. Email reveal is off by default; enabling `reveal_emails` can incur metered work. Confirm the person's current employer and contact details before acting on the result.

## Description-based sourcing

`POST /search/semantic` starts a semantic sourcing request and returns HTTP 202. Supply a `query` of 3–2,000 characters and an optional numeric `limit` (default 25):

```json
{
  "query": "Independent industrial packaging manufacturers in northern Europe",
  "limit": 10
}
```

Unknown request fields are rejected. List requests with `GET /search/semantic` and inspect a known request with `GET /search/semantic/:jobId`. Deleting a saved search uses `DELETE /search/semantic/:jobId` and requires write access. Deletion removes the job record and subsequent polling returns 404; it **does not interrupt an already-running sourcing pipeline**.

Use the semantic request's own status response, not the document-generation polling contract. Research coverage is not exhaustive, and a result is not a verified acquisition recommendation.

## Web research

Use `POST /research/web` with a required `query` and optional `mode`. **fast** returns a synchronous research response; **reasoning** is the default and returns asynchronous job information. Both can consume credits.

```json
{
  "query": "What recent public announcements describe European packaging consolidation? Cite the sources and dates.",
  "mode": "fast"
}
```

Optional fields include `context`, `recency`, `after_date` and `before_date`. Follow the returned job information for reasoning mode; do not treat HTTP 202 as a completed research answer.

## Other research surfaces

| Route family                                          | Use                                                                                            |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `POST /research/web`                                  | Web research using the requested supported mode. Responses may be synchronous or asynchronous. |
| `GET /companies/:domain/overview`                     | Read the company overview.                                                                     |
| `/markets/company/:ticker/...`                        | Public-market profile, financials, peers, transcripts, analyst data or filings.                |
| `GET /markets/filings`                                | Filings search.                                                                                |
| `GET /markets/maps` and `GET /markets/maps/:marketId` | Accessible market maps.                                                                        |

Mode, filter and provider availability differ by operation. Check currencies, dates, source provenance and pagination in the response. Do not apply the legacy “get company field” or “ask document question” contract to these routes.

For uploaded source documents, use the AI Room family described in [Workspace data API](https://docs.corpdev.ai/corpdev.ai-docs/workspace-data-api), or reference the source in a document-generation prompt.