Skip to main content
The verification data endpoint (/v2/company) retrieves comprehensive company data directly from official government registers. Use this endpoint when you need verified, up-to-date information for KYB compliance, due diligence, or fraud prevention.
For fast, cost-effective data during customer onboarding, consider the onboarding data endpoint instead. Use verification data after initial qualification when you need authoritative data.

​
Available Data Points

When retrieving company data, you can request the following items:
  1. companyProfile: company information presented as a structured dataset, including legal representatives and shareholders (when available)
  2. ultimateBeneficialOwners: Information about beneficial owners
  3. availableDocuments: List of available official documents
You can request multiple data points in a single request by including them in the dataPoints array: 
{
  "dataPoints": [
    "companyProfile",
    "ultimateBeneficialOwners",
    "availableDocuments"
  ]
}

​
Retrieving Documents

You can request specific documents by inputting their IDs in the documents array. Document IDs can be:
  1. Specific IDs obtained from the availableDocuments data point
  2. Smart IDs for quick access to usual documents
To understand how document URLs, signed URL refresh, and PDF post-processing behave, read the Document Retrieval Guide.

​
Understanding the Response

​
Request Object

The response includes a request object that provides metadata about your request and the status of each requested data point and document: 
{
  "request": {
    "companyId": "932884117",
    "country": "FR",
    "requestId": "request-12345",
    "dataPoints": ["companyProfile", "ultimateBeneficialOwners"],
    "documents": ["trade_register_extract"],
    "dataStatus": {
      "dataPoints": {
        "companyProfile": {
          "status": "succeeded",
          "cost": 10
        },
        "ultimateBeneficialOwners": {
          "status": "in_progress",
          "jobs_in_progress": ["job_1"],
          "costMarkup": 20
        }
      },
      "documents": {
        "trade_register_extract": {
          "status": "failed",
          "errors": [
            "The local register could not be reached. Please retry later."
          ]
        }
      }
    }
  }
}
The dataStatus field is particularly important as it indicates:
  • Whether data is immediately available (succeeded)
  • If retrieval is still in progress (in_progress)
  • If there were any errors (failed)
Currently, error messages are generic. We are working on providing more detailed and specific error messages in future updates.

​
Asynchronous Data Retrieval

The time to availability of requested data might vary from seconds or milliseconds, to hours or days in rare cases. Nevertheless, all data retrieval is treated asynchronously. The initial response will indicate in_progress status in the dataStatus object, which will later be updated.

​
Progressive Data Delivery

Data is delivered progressively through webhooks as it becomes available. This can happen:
  1. At the data point level (e.g., companyProfile arrives before ultimateBeneficialOwners)
  2. Within a single data point (e.g., basic company info arrives before legal representatives)
Example scenario: 
// Initial response
{
  "company": {
    "name": "Topograph",
    "registrationNumber": "123456789"
  }
}

// Later webhook delivery
{
  "company": {
    "name": "Topograph",
    "registrationNumber": "123456789"
  },
  "legalRepresentatives": [
    {
      "name": "John Smith",
      "role": "Director"
    }
  ]
}

​
Webhook Delivery

Webhooks deliver updates in a standardized format: 
{
  "data": {
    // Updated company data
  },
  "requestId": "request-12345"
}
A webhook is always delivered, even for very fast jobs, to ensure consistency in your data processing pipeline.
Webhook delivery follows the Svix retry policy to ensure reliable delivery.

​
Polling Alternative

Instead of using webhooks, you can poll the API using the requestId from the initial response:
  1. Make the same API call with only the requestId
  2. The response will contain the latest available data
  3. Data won’t be rebilled when using requestId
  4. The state will match the original request
Polling recommendations:
  • Maximum rate: 10 requests per second
  • Recommended interval: Every 3 seconds
  • Continue polling until all requested data points show succeeded or failed status
For detailed information about our credit-based billing system and how our caching optimizes costs and performance, please see our Pricing & Caching documentation.

​
Example Request

curl --request POST \
  --url https://api.topograph.co/v2/company \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "countryCode": "FR",
    "id": "928020932",
    "dataPoints": [
      "companyProfile",
      "ultimateBeneficialOwners",
      "availableDocuments"
    ],
    "documents": [
      "trade_register_extract"
    ]
  }'
For country-specific information on:
  • Available data points
  • Document types
  • Expected response times
Please consult our comprehensive Coverage Map.