Semaphore provides a comprehensive endpoint to retrieve detailed information about a specific company. This endpoint allows you to request various data points and documents related to the company.

​
Available Data Points

When retrieving company data, you can request the following data points:
  1. companyProfile: Basic company information, including legal representatives and shareholders
  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 providing their IDs in the documents array. Document IDs can be:
  1. Random IDs obtained from the availableDocuments data point
  2. Smart IDs for quick access to common documents

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

​
Synchronous vs Asynchronous Data

Data retrieval can be either synchronous (immediate) or asynchronous (requiring additional time):
  1. Synchronous Data: Available in the initial response within milliseconds
  2. Asynchronous Data: May take from seconds to multiple business days to retrieve
For asynchronous data, the initial response will indicate in_progress status in the dataStatus object.

​
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": "Semaphore",
    "registrationNumber": "123456789"
  }
}

// Later webhook delivery
{
  "company": {
    "name": "Semaphore",
    "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 synchronous 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.getsemaphore.com/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.