Topograph Data API
The Data API from Topograph — 3 operation(s) for data.
OpenAPI Specification
openapi: 3.0.0
info:
title: Topograph Billing Data API
description: The Topograph API
version: '0.1'
contact: {}
servers:
- url: https://api.topograph.co
security:
- x-api-key: []
tags:
- name: Data
paths:
/v2/company:
post:
description: 'Retrieve company data and documents for a specific company.
You can either:
1. Create a new request by providing countryCode, id, dataPoints, optional mode, and optional document IDs.
2. Re-fetch a previous request by providing requestId (returns cached data and is not billed again).
Available datapoints include:
- company: core company information
- legalRepresentatives: directors, managers, and signing officers
- otherKeyPersons: auditors, board members, and similar roles when available
- establishments: branches and secondary locations when available
- shareholders: shareholder structure
- subsidiaries: downstream equity holdings when available
- ultimateBeneficialOwners: beneficial owner information
- availableDocuments: list of available official documents
- graph: ownership graph traversal
Legacy companyProfile is still accepted and maps to company + legalRepresentatives for billing.
Modes:
- verification (default): authoritative live registry sources
- onboarding: cheapest compatible fast source; unsupported datapoints fail with fast_source_unavailable
To retrieve documents, first request availableDocuments to discover document IDs, then pass those IDs in the documents field of a follow-up request.'
operationId: CompanyController_getCompany_v2
parameters:
- name: transliterate
required: false
in: query
description: If true, transliterates non-Latin strings in the response to Latin script.
schema:
type: boolean
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateCompanyRequestDTO'
- $ref: '#/components/schemas/GetCompanyRequestResultDTO'
responses:
'200':
description: Company information
content:
application/json:
schema:
$ref: '#/components/schemas/GetCompanyResultDTO'
security:
- x-api-key: []
summary: Get Company Data and Documents
tags:
- Data
/v2/company/{requestId}:
get:
description: 'Retrieve the result of a previous company data request by its ID. Returns the latest available data including all subrequests (documents, additional datapoints).
This endpoint is free and will not be billed again. Use it to poll for results after creating a request via POST /v2/company.'
operationId: CompanyController_getCompanyRequest_v2
parameters:
- name: requestId
required: true
in: path
description: The request ID returned by the initial POST /v2/company call
schema:
example: 253299d1-e8d0-4268-945b-f175f98bc114
type: string
- name: transliterate
required: false
in: query
description: If true, transliterates non-Latin strings in the response to Latin script.
schema:
type: boolean
responses:
'200':
description: Company request result
content:
application/json:
schema:
$ref: '#/components/schemas/GetCompanyResultDTO'
'404':
description: Request not found or does not belong to this account
security:
- x-api-key: []
summary: Get Company Request Result
tags:
- Data
/v2/onboarding:
post:
deprecated: true
description: 'Deprecated: Use POST /v2/company with mode: "onboarding" instead.
This endpoint is internally routed as a companyProfile request with mode: "onboarding" and a 50-cent budget cap.'
operationId: CompanyOnboardingController_getOnboarding_v2
parameters:
- name: transliterate
required: false
in: query
description: If true, transliterates non-Latin strings in the response to Latin script.
schema:
type: boolean
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateOnboardingRequestDTO'
- $ref: '#/components/schemas/GetCompanyRequestResultDTO'
responses:
'200':
description: Company onboarding information
content:
application/json:
schema:
$ref: '#/components/schemas/GetCompanyResultDTO'
security:
- x-api-key: []
summary: Get Onboarding Data (Deprecated)
tags:
- Data
components:
schemas:
BirthDateDTO:
type: object
properties:
day:
type: number
description: Day of birth (1-31)
example: 15
month:
type: number
description: Month of birth (1-12), where January is 1
example: 7
year:
type: number
description: Year of birth
example: 1980
PeriodDTO:
type: object
properties:
startDate:
$ref: '#/components/schemas/PeriodDateDTO'
endDate:
$ref: '#/components/schemas/PeriodDateDTO'
AddressDTO:
type: object
properties:
addressLine1:
type: string
description: First line of the address
example: 10 rue de la Fraternité
addressLine2:
type: string
description: Second line of the address
example: Topograph Building
city:
type: string
description: City of the address
example: Bagnolet
postalCode:
type: string
description: Postal code of the address
example: '93170'
region:
type: string
description: Region of the address
example: FR
countryCode:
type: string
description: Country of the address using ISO 3166-1 alpha-2 country code
example: FR
poBox:
type: string
description: Post Office Box number
example: PO Box 123
careOf:
type: string
description: Care of (c/o) recipient
example: c/o John Doe
state:
type: string
description: State of the address
example: Île-de-France
latitude:
type: number
description: Latitude coordinate
example: 59.9139
longitude:
type: number
description: Longitude coordinate
example: 10.7522
DataStatus:
type: object
properties:
dataPoints:
type: object
description: Retrieval status of data points
additionalProperties:
oneOf:
- $ref: '#/components/schemas/DataPointStatusSucceeded'
- $ref: '#/components/schemas/DataPointStatusInProgress'
- $ref: '#/components/schemas/DataPointStatusEnriching'
- $ref: '#/components/schemas/DataPointStatusFailed'
discriminator:
propertyName: status
mapping:
succeeded: '#/components/schemas/DataPointStatusSucceeded'
in_progress: '#/components/schemas/DataPointStatusInProgress'
enriching: '#/components/schemas/DataPointStatusEnriching'
failed: '#/components/schemas/DataPointStatusFailed'
documents:
type: object
description: Retrieval status of documents
additionalProperties:
oneOf:
- $ref: '#/components/schemas/DataPointStatusSucceeded'
- $ref: '#/components/schemas/DataPointStatusInProgress'
- $ref: '#/components/schemas/DataPointStatusEnriching'
- $ref: '#/components/schemas/DataPointStatusFailed'
discriminator:
propertyName: status
mapping:
succeeded: '#/components/schemas/DataPointStatusSucceeded'
in_progress: '#/components/schemas/DataPointStatusInProgress'
enriching: '#/components/schemas/DataPointStatusEnriching'
failed: '#/components/schemas/DataPointStatusFailed'
required:
- dataPoints
- documents
DataPointStatusSucceeded:
type: object
properties:
cost:
type: number
description: The cost in credits for this data point or document
example: 10
costMarkup:
type: number
description: The percentage markup when final cost is not yet known
example: 20
status:
type: string
description: The data point completed successfully
enum:
- succeeded
example: succeeded
authoritative:
type: boolean
description: Whether the data comes from an authoritative official registry source
example: true
required:
- status
ControlDTO:
type: object
properties:
types:
type: array
description: Types of control held by the beneficial owner
items:
type: string
enum:
- ownership-of-shares
- voting-rights
- appoint-and-remove-directors
- significant-influence-or-control
example:
- ownership-of-shares
description:
type: string
description: Description of why the person is of significant control
example: The person holds more than 50% of the shares in the company.
details:
description: Details about the percentage of control
type: array
items:
$ref: '#/components/schemas/PercentageDetailDto'
required:
- types
- description
GetCompanyResultDTO:
type: object
properties:
request:
description: The request
allOf:
- $ref: '#/components/schemas/RequestMetadataDTO'
company:
description: The main profile information of the company, including, if available, details such as name, registration number, address, and other core data.
allOf:
- $ref: '#/components/schemas/CompanyDTO'
ultimateBeneficialOwners:
description: The persons of significant control of the company, including, if available, their name, nationality, and other relevant details.
type: array
items:
$ref: '#/components/schemas/UltimateBeneficialOwnerDTO'
legalRepresentatives:
description: The legal representatives of the company, which can be either individuals or companies.
type: array
items:
$ref: '#/components/schemas/LegalRepresentativeDTO'
shareholders:
description: The shareholders of the company, which can be either individuals or companies.
type: array
items:
$ref: '#/components/schemas/ShareholderDTO'
subsidiaries:
description: Companies in which the queried company holds equity (downstream participations). Includes any equity stake regardless of size — the relationship classification (controlled, associated, minority investment) is derived from sharePercentage by the consumer.
type: array
items:
$ref: '#/components/schemas/SubsidiaryDTO'
establishments:
description: The establishments of the company, including physical locations where business activities are conducted.
type: array
items:
$ref: '#/components/schemas/EstablishmentDTO'
otherKeyPersons:
description: Other key persons associated with the company who do not have legal signing authority, such as board members, auditors, and compliance officers.
type: array
items:
$ref: '#/components/schemas/OtherKeyPersonDTO'
graph:
description: 'Ownership graph: the entities (`nodes`) and ownership relationships (`edges`) discovered while traversing the company structure, plus a human-readable `description`, a `mermaidDiagram` rendering, and traversal `metadata`. Individual nodes carry UBO flags (`flags.isUbo`, `flags.uboCalculationMethod`) and `totalOwnershipPercentage`.'
allOf:
- $ref: '#/components/schemas/EnhancedGraphResultDTO'
documents:
$ref: '#/components/schemas/DocumentsDTO'
companyRelationships:
type: array
items:
$ref: '#/components/schemas/CompanyRelationshipDTO'
dataSources:
description: Per-field data source provenance for each entity. Keys are field names, values describe the origin of the data.
allOf:
- $ref: '#/components/schemas/DataSourcesDTO'
enrichmentReport:
type: string
description: Human-readable summary of enrichment results when agenticEnrichment was requested.
required:
- request
GetCompanyRequestResultDTO:
type: object
properties:
requestId:
type: string
example: 123e4567-e89b-12d3-a456-426614174000
description: Optional UUID that references a previous request. When provided, returns cached data from that specific request instead of fetching fresh data.
required:
- requestId
DataPointStatusInProgress:
type: object
properties:
cost:
type: number
description: The cost in credits for this data point or document
example: 10
costMarkup:
type: number
description: The percentage markup when final cost is not yet known
example: 20
status:
type: string
description: The data point is being retrieved
enum:
- in_progress
example: in_progress
required:
- status
AccountsOverdueFlagDTO:
type: object
properties:
active:
type: boolean
example: true
description: Whether the signal is currently active (the accounts are currently overdue).
dueDate:
type: string
example: '2024-09-30'
description: The date the accounts were due (and missed), when the register reports it. ISO 8601 (YYYY-MM-DD).
since:
type: string
example: '2024-10-01'
description: The date the flag became active, when the register reports it. ISO 8601 (YYYY-MM-DD).
source:
type: string
example: companies_house
description: The register that reported the signal.
required:
- active
FinancialAnalysisDTO:
type: object
properties:
summary:
type: string
description: Executive summary (2-3 sentences)
narrativeAnalysis:
type: string
description: Detailed multi-paragraph narrative analysis
healthScore:
type: number
description: Overall health score (1-10)
overallRisk:
type: string
enum:
- low
- medium
- high
- critical
ratios:
$ref: '#/components/schemas/FinancialRatiosDTO'
insights:
type: array
items:
$ref: '#/components/schemas/FinancialInsightDTO'
strengths:
type: array
items:
type: string
concerns:
type: array
items:
type: string
trends:
$ref: '#/components/schemas/FinancialTrendsDTO'
required:
- summary
- narrativeAnalysis
- healthScore
- overallRisk
- ratios
- insights
- strengths
- concerns
- trends
AnnualFilingOverdueFlagDTO:
type: object
properties:
active:
type: boolean
example: true
description: Whether the signal is currently active (the annual filing is currently overdue).
dueDate:
type: string
example: '2024-03-01'
description: The date the filing was due (and missed), when the register reports it. ISO 8601 (YYYY-MM-DD).
since:
type: string
example: '2024-03-15'
description: The date the flag became active, when the register reports it. ISO 8601 (YYYY-MM-DD).
source:
type: string
example: companies_house
description: The register that reported the signal.
required:
- active
OtherKeyPersonRoleEnum:
type: string
enum:
- Board Member
- Non-Executive Director
- Independent Director
- Advisory Board Member
- Board Observer
- Auditor
- Compliance Officer
- Data Protection Officer
- Money Laundering Reporting Officer
- Secretary
- Supervisor
- Supervisory Board Member
- C-Level Executive
- Registered Agent
- Other
description: The standardized role of the individual.
PercentageDetailDto:
type: object
properties:
type:
type: string
description: Type of percentage detail (shares, voting rights)
enum:
- shares
- voting-rights
example: shares
percentageRange:
description: Range of control as a lower and upper bound
example:
lower: 25
upper: 50
allOf:
- $ref: '#/components/schemas/RangeDto'
percentageValue:
type: number
description: Exact percentage of control
example: 30
monetaryAmount:
description: Monetary amount of shares controlled
allOf:
- $ref: '#/components/schemas/MonetaryAmountDTO'
numberOfShares:
type: number
description: Number of shares controlled
example: 1000
nature:
type: string
description: Indicates whether the control is direct or indirect
enum:
- direct
- indirect
example: direct
required:
- type
CreateOnboardingRequestDTO:
type: object
properties:
id:
type: string
example: '932884117'
description: '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.'
countryCode:
type: string
enum:
- 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
- RU
- SE
- SG
- SI
- SK
- VG
example: FR
description: The country code in ISO 3166-1 alpha-2 format (e.g., "FR" for France, "DE" for Germany).
dataPoints:
type: array
items:
type: string
enum:
- companyProfile
description: The data points to retrieve. Only companyProfile is supported for onboarding.
metadata:
type: object
additionalProperties:
type: string
maxLength: 500
description: '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).'
required:
- id
- countryCode
PhysicalPersonBaseDTO:
type: object
properties:
gender:
type: string
description: Gender of the person
enum:
- Male
- Female
- Other
- PreferNotToSay
example: Female
name:
description: Full name of the person
example:
fullName: John Doe
allOf:
- $ref: '#/components/schemas/PersonNameDTO'
birthDate:
description: Birth date of the person
example:
day: 15
month: 7
year: 1980
allOf:
- $ref: '#/components/schemas/BirthDateDTO'
birthAddress:
description: Birth address of the person
example:
country: FR
city: Paris
street: 1 Rue de Rivoli
postalCode: '75001'
allOf:
- $ref: '#/components/schemas/AddressDTO'
nationality:
type: string
description: Nationality ISO2 country code of the person
example: US
residenceAddress:
description: Residence address of the person
allOf:
- $ref: '#/components/schemas/AddressDTO'
identifiers:
type: object
description: Identifiers for the person, as a flat object keyed by identifier type (e.g., codice fiscale, national ID). Each value is the identifier string.
additionalProperties:
type: string
example:
codiceFiscale: RSSMRA80A01H501U
EnhancedGraphResultDTO:
type: object
properties:
nodes:
description: All entities in the ownership structure
type: array
items:
$ref: '#/components/schemas/GraphNodeDTO'
edges:
description: All ownership relationships
type: array
items:
$ref: '#/components/schemas/GraphEdgeDTO'
mermaidDiagram:
type: string
description: Mermaid diagram representation
description:
type: string
description: Human-readable description of the graph
metadata:
description: Metadata about the graph traversal process
allOf:
- $ref: '#/components/schemas/GraphMetadataDTO'
required:
- nodes
- edges
DataPointError:
type: object
properties:
code:
type: string
description: Error code identifying the type of failure
example: resource_not_found
enum:
- resource_not_found
- service_unavailable
- processing_failed
- invalid_request
- datapoint_not_supported
- fast_source_unavailable
- onboarding_timeout
- insufficient_funds
message:
type: string
description: User-friendly error message explaining the failure
example: The requested company was not found. Please verify the registration number and try again.
details:
type: array
description: Additional specific error details when applicable
items:
type: string
example:
- Query must be at least 2 characters
source:
type: string
description: Source register that failed, when the failure is attributable to a specific external register
example: handelsregister
retryable:
type: boolean
description: Whether retrying the request may eventually succeed
example: true
required:
- code
- message
CompanyStatusDetailsDTO:
type: object
properties:
status:
type: string
enum:
- ACTIVE
- UNDER_INSOLVENCY_PROCEEDING
- INACTIVE_NOT_CLOSED
- PENDING_DISSOLUTION
- CLOSED
- UNKNOWN
example: ACTIVE
description: The standardized status of the company
closureReason:
type: string
enum:
- BANKRUPTCY
- LIQUIDATION
- MERGER
- ACQUISITION
- VOLUNTARY_DISSOLUTION
- ADMINISTRATIVE_DISSOLUTION
- COURT_ORDER
- SPLIT
- OTHER
- UNKNOWN
example: BANKRUPTCY
description: The reason for company closure, if applicable
closureDate:
type: string
example: '2024-01-15'
description: The date when the company was closed, if applicable
insolvencyStartDate:
type: string
example: '2023-12-01'
description: The date when insolvency proceedings started, if applicable
additionalInfo:
type: string
example: Company entered voluntary liquidation due to retirement of owner
description: Additional information about the status
required:
- status
SubsidiaryDTO:
type: object
properties:
entityId:
type: string
description: Unique identifier to track the same company across different roles (subsidiaries, shareholders, etc.). Since data is retrieved from multiple registries, the same entity may appear with slightly different names or details. This ID lets you correlate a subsidiary with its appearance elsewhere in the response.
example: company_001
company:
description: The company in which the queried company holds equity. Always present — a subsidiary is, by definition, a company.
allOf:
- $ref: '#/components/schemas/CompanyDTO'
sharePercentage:
type: number
description: Direct equity stake in the subsidiary, as a percentage (0–100). For Italian register data this maps to "percentuale-capitale" on the diritti-partecipazione element.
example: 75
totalSharePercentage:
type: number
description: Total equity stake including ownership held indirectly through other entities in the chain. Populated only when the source can compute consolidated ownership (e.g. financial statements). Sources that only carry direct stakes leave this undefined.
example: 80
votingRightsPercentage:
type: number
description: Voting-rights percentage in the subsidiary. May differ from sharePercentage when non-voting shares exist (preferred shares, dual-class structures). Populated when the source distinguishes equity from voting power.
example: 75
numberOfShares:
type: number
description: Absolute number of shares held in the subsidiary.
example: 1000
nominalCapitalHeld:
description: Total nominal (stated) capital value of the equity held in the subsidiary. Face value × number of shares. Equivalent to "valore nominale × n-azioni" in Italian InfoCamere data.
allOf:
- $ref: '#/components/schemas/MonetaryAmountDTO'
paidInAmount:
description: Total amount actually paid for the equity held, including any premium over nominal value. Italian "valore versato".
allOf:
- $ref: '#/components/schemas/MonetaryAmountDTO'
acquisitionDate:
type: string
description: 'Date the equity stake was acquired (ISO 8601: YYYY-MM-DD). Sourced from register filings — for Italian InfoCamere this is the earliest dt-evento on the participation record.'
example: '2020-06-15'
endDate:
type: string
description: 'Date the equity stake ended (sale, dissolution of the subsidiary, etc.). When present, the participation is historical rather than current. ISO 8601: YYYY-MM-DD.'
example: '2024-03-15'
required:
- company
RoleEnum:
type: string
enum:
- Director
- Manager
- Employee
- Chief Executive Officer
- Chief Financial Officer
- Chief Operating Officer
- President
- Vice President
- Secretary
- Treasurer
- Legal Advisor
- General Counsel
- Partner
- Associate
- Other
- Chairman of the Board
- Board Member
- Managing Director
- Executive Director
- Non-Executive Director
- General Partner
- Managing Partner
- Limited Partner
- Administrator
- Liquidator
- Receiver
- Owner
- Chairman
- Auditor
- Authorized Signatory
description: The standardized role of the individual.
PeriodDateDTO:
type: object
properties:
year:
type: number
month:
type: number
day:
type: number
DataPointStatusFailed:
type: object
properties:
cost:
type: number
description: The cost in credits for this data point or document
example: 10
costMarkup:
type: number
description: The percentage markup when final cost is not yet known
example: 20
status:
type: string
description: The data point retrieval failed
enum:
- failed
example: failed
error:
description: Error information for the failed data point
allOf:
- $ref: '#/components/schemas/DataPointError'
errors:
type: array
description: Deprecated - use error.message instead
deprecated: true
items:
type: string
required:
- status
- error
TaxIdVerificationDTO:
type: object
properties:
status:
type: string
enum:
- verified
- unverified
- unavailable
description: Verification status of the tax ID
example: verified
verifiedAt:
type: string
description: ISO date when the tax ID was verified
example: '2024-01-15T10:30:00Z'
verifiedName:
type: string
description: Company name returned by the validation service (e.g., VIES)
example: TOPOGRAPH SAS
verifiedAddress:
type: string
description: Address returned by the validation service (e.g., VIES)
example: 123 RUE DE PARIS, 75001 PARIS
consultationNumber:
type: string
description: VIES consultation number (requestIdentifier) - the legal proof of validation for audit purposes
example: WAPIAAAAW1234567890
required:
- status
GraphEdgeDTO:
type: object
properties:
id:
type: string
description: Unique identifier for the edge
fromId:
type: string
description: ID of the company being owned
toId:
type: string
description: ID of the entity that owns shares (shareholder)
percentage:
type: number
description: Ownership percentage (0-100)
source:
type: string
description: Source information about where this relationship was found
required:
- id
- fromId
- toId
CompanyRelationshipDTO:
type: object
properties:
relation:
type: string
enum:
- mergedFrom
- mergedInto
- acquired
- acquiredBy
- demergedFrom
- demergedTo
- spunOffFrom
- spunOffTo
- assetTransferFrom
- assetTransferTo
- other
company:
$ref: '#/components/schemas/CompanyDTO'
effectiveDate:
type: string
description: Legal effective date if known (YYYY-MM-DD)
description:
type: string
required:
- relation
- company
ComplianceFlagsDTO:
type: object
properties:
accountsOverdue:
description: Present when the company’s statutory annual accounts are overdue with the register.
allOf:
- $ref: '#/components/schemas/AccountsOverdueFlagDTO'
annualFilingOverdue:
description: Present when the company’s periodic confirmation/annual filing is overdue with the register (in the
# --- truncated at 32 KB (99 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/topograph/refs/heads/main/openapi/topograph-data-api-openapi.yml