Retrieve company data

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)
• last_consolidated_article_of_association: Latest consolidated articles of association

​

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)

​

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"
}

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

​

Example Request

curl --request POST \
  --url https://api.getsemaphore.com/v1/company \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "country": "FR",
    "companyNumber": "928020932",
    "dataPoints": [
      "companyProfile",
      "ultimateBeneficialOwners",
      "availableDocuments"
    ],
    "documents": [
      "trade_register_extract"
    ]
  }'