Skip to main content

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.

This guide will get you up and running with Topograph. You’ll learn how to authenticate, find a company, create a data request, and retrieve the results.

​
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 a list of matching companies. Locate the one you want and copy its id (e.g., 552032534 for “BNP PARIBAS”).

​
3. Create a Data Request

Now use that id to create a request for company data. The /v2/company endpoint is asynchronous: it starts fetching data from the official register and returns a requestId you’ll use to retrieve the results. 
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 data points may already be succeeded, while others are still in_progress. The response is not necessarily complete at this point. 
{
  "request": {
    "requestId": "req_abc123",
    "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. 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/req_abc123 \
  --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.

​
5. 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

Understand the Sources

Learn why retrieving data from public registers is difficult

API Reference

Explore all endpoints and parameters