> For the complete documentation index, see [llms.txt](https://docs.heron-intelligence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heron-intelligence.com/overview/quickstart.md). # Quickstart Connect to the Heron Intelligence API and retrieve your first interview transcripts in minutes. You will need an API key. Contact the Heron Intelligence team to obtain one. See [Authentication](/api-reference/api-reference/authentication.md) for security guidance. *** ## Setup Set your API key as an environment variable so you can reuse it across requests: ```bash export HERON_API_KEY="" ``` Base URL for all requests: ``` https://api.heron-intelligence.com/api/v1 ``` Building or testing? Use the [sandbox environment](/api-reference/api-reference/sandbox.md) instead — same API and auth, against non-production data: ``` https://api-sandbox.heron-intelligence.com/api/v1 ``` *** ## Step 1 — Verify your API key ```bash curl -s "https://api.heron-intelligence.com/api/v1/health" \ -H "x-api-key: $HERON_API_KEY" | python3 -m json.tool ``` Expected response: ```json { "status": "ok", "service": "api", "timestamp": "2026-01-15T12:00:00.000000+00:00" } ``` *** ## Step 2 — Search for a company Find a company by name. The search is case-insensitive and supports partial matches: ```bash curl -s "https://api.heron-intelligence.com/api/v1/companies?name=nubank" \ -H "x-api-key: $HERON_API_KEY" | python3 -m json.tool ``` Response: ```json { "data": [ { "company_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "company_name": "Nubank", "stock_ticker": "NU", "exchange": "NYSE", "isin": null } ], "pagination": { "current_page": 1, "per_page": 20, "total_items": 1, "total_pages": 1, "has_next": false, "has_previous": false } } ``` Copy the `company_id` for the next step. *** ## Step 3 — Retrieve interviews for a company Use the `company_id` from Step 2 to fetch interview transcripts: ```bash curl -s "https://api.heron-intelligence.com/api/v1/interviews?company_id=" \ -H "x-api-key: $HERON_API_KEY" | python3 -m json.tool ``` Each interview includes: * **companies** — the companies discussed in the interview * **people** — the interviewees, with `full_name`, `title` and `bio` * **transcript\_id** — unique identifier for the interview * **call\_date** / **post\_date** — when the interview was conducted and published * **project\_affiliation** — the research project name * **transcript\_type** — `conversation` or `monologue` * **transcript** — the full interview as question/answer pairs * **transcript\_summary** — a pre-written summary, when available * **data\_source\_provider** — `{ id, name }`, the dataset that produced this interview * **metadata** — call quality, tone, and compliance information To filter by due-diligence methodology, use the `due_diligence_type` query parameter with `MDD` or `BDD`. The `call_type` field in the response is free text and is not that value — see [Interviews](/api-reference/api-reference/interviews.md) for the full filter and field reference. *** ## Step 4 — Filter interviews by date range Narrow results to a specific time period: ```bash curl -s "https://api.heron-intelligence.com/api/v1/interviews?company_id=&call_date_min=2025-01-01&call_date_max=2025-12-31" \ -H "x-api-key: $HERON_API_KEY" | python3 -m json.tool ``` *** ## Step 5 — Filter by data source Heron Intelligence research comes from four datasets. Resolve the provider ids your key can read, then filter on them: ```bash curl -s "https://api.heron-intelligence.com/api/v1/data-sources" \ -H "x-api-key: $HERON_API_KEY" | python3 -m json.tool curl -s "https://api.heron-intelligence.com/api/v1/interviews?company_id=&data_source_provider_ids=" \ -H "x-api-key: $HERON_API_KEY" | python3 -m json.tool ``` `data_source_provider_ids` takes provider **ids**, not names. See [Data Providers](/documentation/data-providers.md) for what each dataset is — and why an empty result after filtering by provider usually means "not entitled", not "no coverage". *** ## Step 6 — Get a single interview by ID Retrieve the full details of a specific interview: ```bash curl -s "https://api.heron-intelligence.com/api/v1/interviews/" \ -H "x-api-key: $HERON_API_KEY" | python3 -m json.tool ``` *** ## Python Example ```python import requests API_KEY = "" BASE_URL = "https://api.heron-intelligence.com/api/v1" HEADERS = {"x-api-key": API_KEY} # 1. Search for a company resp = requests.get(f"{BASE_URL}/companies", headers=HEADERS, params={"name": "Nubank"}) companies = resp.json()["data"] company_id = companies[0]["company_id"] print(f"Found: {companies[0]['company_name']} ({company_id})") # 2. Get interviews for that company resp = requests.get( f"{BASE_URL}/interviews", headers=HEADERS, params={ "company_id": company_id, "call_date_min": "2025-01-01", "per_page": 5, }, ) interviews = resp.json()["data"] print(f"Found {len(interviews)} interviews") # 3. Read the first transcript, reporting which dataset each came from for interview in interviews: provider = (interview.get("data_source_provider") or {}).get("name", "unknown") print(f"\n--- {interview['project_affiliation']} ({interview['call_date']}) [{provider}] ---") for item in interview["transcript"][:3]: # first 3 Q&A pairs print(f"Q: {item['question'][:100]}...") print(f"A: {item['answer'][:100]}...") ``` When you report across interviews, keep the per-dataset counts separate — see [Reporting provenance to end users](/documentation/data-providers.md#reporting-provenance-to-end-users). *** ## Next Steps * [API Reference](/api-reference/api-reference.md) — full endpoint documentation * [Data Models](/documentation/data-models.md) — understand interview types (MDD vs BDD) and response structures * [Data Providers](/documentation/data-providers.md) — the four datasets, and how to reference and report them * [Error Handling](/documentation/error-handling.md) — handle errors gracefully