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

# Quickstart

> Make your first request to the Topograph API in minutes

This guide gets you from an API key to your first company data response. You will authenticate, search for a company, create an asynchronous request, and retrieve the result.

<Tip>
  **Building with an AI coding agent?** Install the [Topograph MCP](/guides/topograph-mcp) so Claude Code, Cursor, or any MCP-aware editor can pull live country coverage, pricing, and integration rules while it writes your integration. One install, no API key needed for the MCP itself.

  ```
  /plugin marketplace add getsemaphore/topograph-mcp-library
  /plugin install topograph@topograph
  ```
</Tip>

## 1. Get your API Key

You'll need an API key to authenticate your requests.

1. Sign up or log in to the [Topograph Dashboard](https://app.topograph.co).
2. Navigate to **Settings > API Keys**.
3. Create a new key (e.g., "Development Key").
4. Copy the key. You won't be able to see it again.

## 2. Search for a Company

The entry point to Topograph is usually a search. Let's find BNP Paribas in France.

```bash theme={null}
curl --request GET \
  --url 'https://api.topograph.co/v2/search?country=FR&query=BNP%20Paribas' \
  --header 'x-api-key: <your-api-key>'
```

This returns matching companies. Pick the company you want and copy its `id`. The `id` returned by search is the value to pass to other Topograph endpoints.

<Tip>
  Country-specific identifier formats vary. Use the [coverage and pricing page](/essentials/coverage-and-pricing) to find the live country catalog, accepted identifiers, and available sources before building a country-specific flow.
</Tip>

## 3. Create a Data Request

Now use that `id` to create a request for company data. The `/v2/company` endpoint is asynchronous: it starts retrieval and returns a `requestId` you use to poll or correlate webhooks.

```bash theme={null}
curl --request POST \
  --url https://api.topograph.co/v2/company \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <your-api-key>' \
  --data '{
    "countryCode": "FR",
    "id": "552032534",
    "dataPoints": ["company", "legalRepresentatives"]
  }'
```

The response contains a `requestId` and a `dataStatus` object. Some datapoints may already be `succeeded`, while others are still `in_progress`. The first response is not necessarily complete.

```json theme={null}
{
  "request": {
    "requestId": "253299d1-e8d0-4268-945b-f175f98bc114",
    "dataStatus": {
      "dataPoints": {
        "company": { "status": "succeeded" },
        "legalRepresentatives": { "status": "in_progress" }
      }
    }
  },
  "company": {
    "id": "552032534",
    "countryCode": "FR",
    "legalName": "BNP PARIBAS",
    "identifiers": {
      "siren": "552032534"
    }
  }
}
```

<Note>
  Retrieval time depends on the country and data point. Some resolve in milliseconds, others can take minutes. In rare cases (e.g., registers with manual processing), it can take hours.
</Note>

## 4. Pick the right mode

`/v2/company` supports two modes:

| Mode                   | Use it for                                | What to expect                                                                                    |
| ---------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Verification (default) | Compliance checks and final KYB decisions | Authoritative data from official sources. Slower, but optimized for completeness.                 |
| Onboarding             | Form prefill and early screening          | Fast data with a short per-datapoint deadline. Some countries use non-authoritative fast sources. |

For the full tradeoff, read [Verification vs onboarding mode](/essentials/modes).

## 5. Retrieve the results

Use the `requestId` from step 3 to poll for the complete data. Polling is free: requests made with a `requestId` are never rebilled.

```bash theme={null}
curl --request GET \
  --url https://api.topograph.co/v2/company/253299d1-e8d0-4268-945b-f175f98bc114 \
  --header 'x-api-key: <your-api-key>'
```

Poll every 3 seconds until all data points in `dataStatus` show `succeeded` or `failed`. Once resolved, the response contains the full verified data: legal name, address, company status, legal representatives, and more.

<Tip>
  Polling works well for getting started. In production, set up [webhooks](/guides/webhooks) instead so Topograph pushes completed data to your server automatically.
</Tip>

## 6. Explore more features

Now that you have the basics, explore what else you can do:

<CardGroup cols={2}>
  <Card title="Guide to KYB onboarding" icon="rocket" href="/guides/kyb-onboarding">
    Build a KYB flow with high conversion rates
  </Card>

  <Card title="Verification Data" icon="building" href="/essentials/retrieve_company">
    Retrieve high-quality, detailed data, including UBOs and company documents
  </Card>

  <Card title="Coverage & Pricing" icon="database" href="/essentials/coverage-and-pricing">
    Find live country coverage, sources, pricing, identifiers, and available documents
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/data/get-company-data-and-documents">
    Explore all endpoints and parameters
  </Card>

  <Card title="Topograph MCP for AI agents" icon="robot" href="/guides/topograph-mcp">
    Give Claude Code, Cursor, and other AI editors live Topograph context while they write your integration
  </Card>
</CardGroup>