Skip to main content
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 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

​
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.
  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. 
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 data point. Some resolve in milliseconds, others can take minutes. In rare cases (e.g., registers with manual processing), it can take hours.

​
4. Pick the right mode

/v2/company supports two modes:
ModeUse it forWhat to expect
Verification (default)Compliance checks and final KYB decisionsAuthoritative data from official sources. Slower, but optimized for completeness.
OnboardingForm prefill and early screeningFast data with a short per-datapoint deadline. Some countries use non-authoritative fast sources.
For the full tradeoff, read Verification vs onboarding 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

Give Claude Code, Cursor, and other AI editors live Topograph context while they write your integration