Skip to main content
The TEST country allows you to test your integration without making real requests to external registries. It returns predictable mock data instantly.

​
Basic Usage

Use country code TEST with any company ID. Special IDs trigger specific behaviors: 
curl -X POST https://api.topograph.co/v2/company \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"countryCode": "TEST", "id": "SUCCESS-12345", "dataPoints": ["company", "legalRepresentatives"]}'
Search returns your query plus example test IDs you can use: 
curl -G https://api.topograph.co/v2/search \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "country=TEST" \
  --data-urlencode "query=my-company"

​
Test Company IDs

​
Success Cases

Any ID that doesn’t match an error pattern returns a valid company:
Company IDDescription
Any valid IDReturns a complete company response

​
Error Cases

Use these IDs to test every error response your integration needs to handle:
Company IDError CodeMessageHTTP Status
RESOURCE_NOT_FOUNDresource_not_foundThe requested resource was not found. Please verify the identifier and try again.404
INVALID_REQUESTinvalid_requestInvalid request. Please check the request parameters and try again.400
PROCESSING_FAILEDprocessing_failedUnable to process the request. Please try again later.422
SERVICE_UNAVAILABLEservice_unavailableService temporarily unavailable. Please try again in a few moments.503
These error IDs work across all request types: company data, available documents, and document downloads. Use them as the id to trigger errors on any datapoint or document retrieval.

​
Delivery Delays

By default the TEST country responds instantly. To test how your integration handles slow requests, such as polling, timeouts, and loading states, use an ID containing a DELAY_ token. The request stays pending for the given duration, then returns successful data.
Company IDDelivery delay
DELAY_1M1 minute
DELAY_10M10 minutes
DELAY_1H1 hour
DELAY_10H10 hours
The delay applies to both company data and document downloads. Each request to the TEST country runs independently, so the same ID triggers the full delay every time, including on repeated and concurrent requests. You can still add a - or _ separated suffix such as DELAY_1M-001 to label requests in your own logs. The token also combines with the GRAPH_ prefixes below. GRAPH_CHAIN_DELAY_1M delays every company resolved in the ownership graph. Use the shorter durations (1M, 10M) for graph IDs, since the delay applies to each company in the chain.

​
Documents

All test companies return a free “Trade Register Extract” document.

​
Graph/Ownership Testing

IDs starting with GRAPH_ return specific ownership structures:
Company IDDescription
GRAPH_SIMPLE_0012 individual shareholders (30%, 20%)
GRAPH_CHAIN_001Company → Company → Individual chain
GRAPH_UBO_001Clear UBO structure (51%, 25%, 24%)
GRAPH_CIRCULAR_001Circular ownership (A owns B owns A)
GRAPH_WIDE_0015 individual shareholders (15% each)
GRAPH_MIXED_0012 individuals + 2 company shareholders
GRAPH_DEEP_001Deep chain up to 3 levels
GRAPH_EMPTY_001Company with no shareholders
These IDs work with the shareholders, ultimateBeneficialOwners, and graph data points:
  • shareholders returns the direct shareholders of the company.
  • ultimateBeneficialOwners returns the individual shareholders holding 25% or more. For GRAPH_UBO_001 this is the 51% and 25% holders; the 24% holder is excluded.
  • graph returns the full ownership tree, recursing through company shareholders and flagging beneficial owners on the individual nodes.