Test Country

Use the TEST country to validate your integration

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

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 ID	Description
Any valid ID	Returns a complete company response

Error Cases

Use these IDs to test every error response your integration needs to handle:

Company ID	Error Code	Message	HTTP Status
RESOURCE_NOT_FOUND	resource_not_found	The requested resource was not found. Please verify the identifier and try again.	404
INVALID_REQUEST	invalid_request	Invalid request. Please check the request parameters and try again.	400
PROCESSING_FAILED	processing_failed	Unable to process the request. Please try again later.	422
SERVICE_UNAVAILABLE	service_unavailable	Service 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 ID	Delivery delay
DELAY_1M	1 minute
DELAY_10M	10 minutes
DELAY_1H	1 hour
DELAY_10H	10 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 ID	Description
GRAPH_SIMPLE_001	2 individual shareholders (30%, 20%)
GRAPH_CHAIN_001	Company → Company → Individual chain
GRAPH_UBO_001	Clear UBO structure (51%, 25%, 24%)
GRAPH_CIRCULAR_001	Circular ownership (A owns B owns A)
GRAPH_WIDE_001	5 individual shareholders (15% each)
GRAPH_MIXED_001	2 individuals + 2 company shareholders
GRAPH_DEEP_001	Deep chain up to 3 levels
GRAPH_EMPTY_001	Company 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.