Skip to main content
Topograph provides a comprehensive endpoint to retrieve detailed information about a specific company. Use this endpoint to request various data points and documents.

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

​
Smart Document IDs

Smart IDs are predefined identifiers that can always be included in your document requests. While they can be used in any request, they don’t guarantee document availability. If a corresponding document exists, it will be returned in the response. Our smart IDs are:
  • trade_register_extract: Latest trade register extract
  • certified_trade_register_extract: Latest certified trade register extract
  • last_fiscal_year_financial_statement: Previous year’s financial statement (not the last available one)
Smart IDs can be used in any request, but document availability varies by company. For example, if you request last_fiscal_year_financial_statement, it specifically looks for the previous year’s statement - if that specific year is not available, the request for this document will fail even if older statements exist. Similarly, a French K-bis (trade register extract) might be temporarily unavailable for specific companies.

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