> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topograph.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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:

```bash theme={null}
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.