Get Verification Data and Documents

This endpoint allows you to retrieve detailed information about a specific company.

You can either:

1. Make a new request by providing:

   • country code
   • company id
   • desired data points
   • optional document IDs

2. Get results from a previous request by providing:

   • requestId (this will return cached data and avoid being billed again)

Available data points are:

• companyProfile: Basic company information, legal representatives and shareholders
• ultimateBeneficialOwners: Information about beneficial owners
• availableDocuments: List of available official documents

There are two ways to retrieve documents:

1. Two-step process:

   • First, request the “availableDocuments” data point to get a list of all available documents with their IDs
   • Then, use these specific document IDs in a second request

2. Direct access using smart IDs:

   • Use predefined smart IDs for quick access to common documents:
     • trade_register_extract: Latest trade register extract
     • certified_trade_register_extract: Latest certified trade register extract Refer to our country coverage documentation to check which smart IDs are available for each country.

POST /v2/company

Get Verification Data and Documents

cURL

curl --request POST \
  --url https://api.topograph.co/v2/company \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "id": "932884117",
  "countryCode": "FR",
  "dataPoints": [
    "companyProfile"
  ],
  "documents": [
    "trade_register_extract"
  ],
  "metadata": {},
  "graphMaxBudget": 1000,
  "profileMaxBudget": 500,
  "agenticEnrichment": true
}
'

200

{
  "request": {
    "country": "FR",
    "dataPoints": [
      "<string>"
    ],
    "documents": [
      "<string>"
    ],
    "companyId": "932884117",
    "requestId": "request-12345",
    "metadata": {},
    "enrichmentReport": "<string>",
    "companyLegalName": "<string>",
    "workspace": {}
  },
  "company": {
    "countryCode": "FR",
    "id": "932884117",
    "identifiers": {
      "VAT": "02580590541",
      "Codice Fiscale": "RSSMRA70A01H501U",
      "CCIAA": "TO",
      "REA Code": "1234567"
    },
    "legalName": "Topograph",
    "legalNameInEnglish": "Test Display Hong Kong Trading Limited",
    "commercialNames": [
      "Topograph",
      "TopographHQ"
    ],
    "legacyLegalNames": [
      "Semaphore",
      "SemaphoreHQ"
    ],
    "legacyCommercialNames": [
      "Semaphore",
      "SemaphoreHQ"
    ],
    "registrationDate": "2024-04-22",
    "incorporationDate": "2024-04-15",
    "legalForm": {
      "localName": "EURL, entreprise unipersonnelle à responsabilité limitée",
      "englishTranslation": "Single Member Limited Liability Company",
      "semaphoreStandard": "Limited Liability Company",
      "standardized": "Limited Liability Company",
      "iso20275Code": "F8DD",
      "isAIEnriched": true
    },
    "activities": {
      "NACE": [
        {
          "code": "62.01",
          "description": "Computer programming activities"
        }
      ],
      "ISIC": [
        {
          "code": "J620",
          "description": "Computer programming, consultancy and related activities"
        }
      ]
    },
    "activityDescription": "Development of software solutions and IT consulting services",
    "phones": [
      "[phone]",
      "[phone]"
    ],
    "website": "https://www.example.com",
    "employeeCount": {
      "exact": 150,
      "min": 100,
      "max": 200,
      "lastUpdated": "2024-03-15",
      "isEstimate": false
    }
  },
  "ultimateBeneficialOwners": [
    {
      "gender": "Female",
      "name": {
        "fullName": "John Doe"
      },
      "birthDate": {
        "day": 15,
        "month": 7,
        "year": 1980
      },
      "birthAddress": {
        "country": "FR",
        "city": "Paris",
        "street": "1 Rue de Rivoli",
        "postalCode": "75001"
      },
      "nationality": "US",
      "residenceAddress": {
        "addressLine1": "10 rue de la Fraternité",
        "city": "Bagnolet",
        "postalCode": "93170",
        "region": "FR",
        "countryCode": "FR",
        "state": "Île-de-France",
        "addressLine2": "Topograph Building",
        "poBox": "PO Box 123",
        "careOf": "c/o John Doe",
        "latitude": 59.9139,
        "longitude": 10.7522
      },
      "control": {
        "controlType": "ownership-of-shares",
        "description": "The person holds more than 50% of the shares in the company.",
        "percentageDetails": [
          {
            "type": "shares",
            "range": {
              "lower": 50,
              "upper": 75
            }
          }
        ],
        "additionalDetails": "Direct ownership of shares"
      },
      "identifiers": [
        {
          "type": "<string>",
          "value": "<string>"
        }
      ],
      "entityId": "person_001"
    }
  ],
  "legalRepresentatives": [
    {
      "type": "individual",
      "entityId": "person_001",
      "startDate": "2022-01-01",
      "endDate": "2023-12-31"
    }
  ],
  "shareholders": [
    {
      "type": "individual",
      "entityId": "person_001",
      "sharePercentage": 25.5,
      "numberOfShares": 1000
    }
  ],
  "establishments": [
    {
      "name": "Main Office",
      "id": "EST-001",
      "creationDate": "2020-01-15",
      "endDate": "2023-12-31",
      "active": true
    }
  ],
  "otherKeyPersons": [
    {
      "type": "individual",
      "entityId": "person_001",
      "startDate": "2022-01-01",
      "endDate": "2023-12-31"
    }
  ],
  "graph": {},
  "companyRelationships": [
    {
      "relation": "mergedFrom",
      "company": {
        "countryCode": "FR",
        "id": "932884117",
        "identifiers": {
          "VAT": "02580590541",
          "Codice Fiscale": "RSSMRA70A01H501U",
          "CCIAA": "TO",
          "REA Code": "1234567"
        },
        "legalName": "Topograph",
        "legalNameInEnglish": "Test Display Hong Kong Trading Limited",
        "commercialNames": [
          "Topograph",
          "TopographHQ"
        ],
        "legacyLegalNames": [
          "Semaphore",
          "SemaphoreHQ"
        ],
        "legacyCommercialNames": [
          "Semaphore",
          "SemaphoreHQ"
        ],
        "registrationDate": "2024-04-22",
        "incorporationDate": "2024-04-15",
        "legalForm": {
          "localName": "EURL, entreprise unipersonnelle à responsabilité limitée",
          "englishTranslation": "Single Member Limited Liability Company",
          "semaphoreStandard": "Limited Liability Company",
          "standardized": "Limited Liability Company",
          "iso20275Code": "F8DD",
          "isAIEnriched": true
        },
        "activities": {
          "NACE": [
            {
              "code": "62.01",
              "description": "Computer programming activities"
            }
          ],
          "ISIC": [
            {
              "code": "J620",
              "description": "Computer programming, consultancy and related activities"
            }
          ]
        },
        "activityDescription": "Development of software solutions and IT consulting services",
        "phones": [
          "[phone]",
          "[phone]"
        ],
        "website": "https://www.example.com",
        "employeeCount": {
          "exact": 150,
          "min": 100,
          "max": 200,
          "lastUpdated": "2024-03-15",
          "isEstimate": false
        }
      },
      "effectiveDate": "<string>",
      "description": "<string>"
    }
  ],
  "dataSources": {
    "company": {},
    "shareholders": [
      "<string>"
    ],
    "ultimateBeneficialOwners": [
      "<string>"
    ],
    "legalRepresentatives": [
      "<string>"
    ],
    "establishments": [
      "<string>"
    ],
    "otherKeyPersons": [
      "<string>"
    ]
  },
  "enrichmentReport": "<string>"
}

Authorizations

x-api-key · string · header · required

Body

application/json

Option 1

Option 2

id · string · required

The company id. In some countries, this might be a concatenation of the registry and city (e.g., in Germany: "Augsburg HRB 34617"). The search function will always return a usable company number. Check the documentation to see which number format is used for each country.

Example:

"932884117"

countryCode · enum<string> · required

The country code in ISO 3166-1 alpha-2 format (e.g., "FR" for France, "DE" for Germany).

Available options: AT, BE, BG, CH, CN, CZ, CY, DE, DK, EE, ES, FI, FR, GB, GG, GR, HK, HR, HU, IE, IS, IT, JE, LI, LU, LV, MC, MT, MU, NL, NO, PL, PT, RO, SE, SG, SI, SK, VG

Example:

"FR"

dataPoints · enum<string>[]

The data points to retrieve. Available data points are companyProfile, ultimateBeneficialOwners, availableDocuments, shareholders, or graph.

Available options: companyProfile, onboardingProfile, ultimateBeneficialOwners, availableDocuments, shareholders, graph

Example:

["companyProfile"]

documents · string[]

There are two ways to retrieve documents:

1. Two-step process:

   • First, request the "availableDocuments" data point to get a list of all available documents with their IDs
   • Then, use these specific document IDs in a second request

2. Direct access using smart IDs:

   • Use predefined smart IDs for quick access to common documents:
     • trade_register_extract: Latest trade register extract
     • certified_trade_register_extract: Latest certified trade register extract
       Refer to our country coverage documentation to check which smart IDs are available for each country.

Example:

["trade_register_extract"]

metadata · object

Arbitrary key-value string pairs to associate with the request. Limits: max 50 keys, keys up to 40 chars (longer keys are skipped), values up to 500 chars (longer values are truncated).

Show child attributes

graphMaxBudget · number

Maximum budget in credit cents for graph traversal. When the "graph" datapoint is requested, the traversal will stop once this budget is reached. If not provided, uses a default maximum.

Example:

1000

profileMaxBudget · number

Maximum budget in credit cents for company profile retrieval. For countries with variable pricing (e.g., Hungary), the request will fail with a budget_exceeded error if the actual cost exceeds this budget. The error includes the quoted price so the user can retry with a higher budget.

Example:

500

agenticEnrichment · boolean

Enable best-effort enrichment of legal representative person details (birth date, nationality, residence address) from official publications. Belgium only. Not all fields are guaranteed — depends on publication availability. Fixed 50 cent cost per request, charged only if enrichment yields results. Introduces enriching datapoint status while processing is in progress.

Example:

true

Response

200 - application/json

Company information

request · object · required

The request

Show child attributes

company · object · required

The main profile information of the company, including, if available, details such as name, registration number, address, and other core data.

Show child attributes

ultimateBeneficialOwners · object[]

The persons of significant control of the company, including, if available, their name, nationality, and other relevant details.

Show child attributes

legalRepresentatives · object[]

The legal representatives of the company, which can be either individuals or companies.

Show child attributes

shareholders · object[]

The shareholders of the company, which can be either individuals or companies.

Show child attributes

establishments · object[]

The establishments of the company, including physical locations where business activities are conducted.

Show child attributes

otherKeyPersons · object[]

Other key persons associated with the company who do not have legal signing authority, such as board members, auditors, and compliance officers.

Show child attributes

graph · object

documents · object

Show child attributes

companyRelationships · object[]

Show child attributes

dataSources · object

Per-field data source provenance for each entity. Keys are field names, values describe the origin of the data.

Show child attributes

enrichmentReport · string

Human-readable summary of enrichment results when agenticEnrichment was requested.