Quickstart

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.

Building with an AI coding agent? Install the Topograph plugin. Its Topograph Wizard gives Claude Code live country coverage, pricing and integration rules while it writes your integration, and the Topograph MCP lets it look up real companies with your account. Other editors and chat apps can connect to either server directly.

/plugin marketplace add getsemaphore/topograph-mcp-library
/plugin install topograph@topograph

1. Get your API Key

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

Sign up or log in to the Topograph Dashboard.
Open Settings & More > Developer. Only organisation admins can see API keys.
Reveal and copy the API key of your live environment. Each environment has one key, and you can copy it again at any time from this page.
If a key leaks, rotate it from the same page. Rotation invalidates the previous key immediately.

Want to integrate without real data or real charges? Create a development environment from the same page. It has its own API key.

2. Search for a Company

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

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.

Country-specific identifier formats vary. Use the coverage and pricing page to find the live country catalog, accepted identifiers, and available sources before building a country-specific flow.

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.

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.

{
  "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"
    }
  }
}

Retrieval time depends on the country and datapoint. Most resolve in seconds, some take minutes. A small number of datapoints are manually delivered and typically take 1–3 business days. The manual flag on GET /v2/catalog tells you which ones before you order.

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.
Prefill	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 prefill mode.

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.

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.

Polling works well for getting started. In production, set up webhooks instead so Topograph pushes completed data to your server automatically.

6. Explore more features

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

Guide to KYB onboarding

Build a KYB flow with high conversion rates

Verification Data

Retrieve high-quality, detailed data, including UBOs and company documents

Coverage & Pricing

Find live country coverage, sources, pricing, identifiers, and available documents

API Reference

Explore all endpoints and parameters

Topograph MCP for AI agents

Let Claude, ChatGPT, Cursor and other AI agents look up companies in official registers

Topograph Wizard

Give your coding agent live coverage, pricing, docs and code samples while it writes your integration

Getting Started

AI Agents

Integration Guides

Core Features

Behavior & Operations

1. Get your API Key

2. Search for a Company

3. Create a Data Request

4. Pick the right mode

5. Retrieve the results

6. Explore more features

Guide to KYB onboarding

Verification Data

Coverage & Pricing

API Reference

Topograph MCP for AI agents

Topograph Wizard

​1. Get your API Key

​2. Search for a Company

​3. Create a Data Request

​4. Pick the right mode

​5. Retrieve the results

​6. Explore more features

Guide to KYB onboarding

Verification Data

Coverage & Pricing

API Reference

Topograph MCP for AI agents

Topograph Wizard

1. Get your API Key

2. Search for a Company

3. Create a Data Request

4. Pick the right mode

5. Retrieve the results

6. Explore more features