Most Topograph datapoints resolve in seconds or minutes. A small number are fulfilled through a manual process and take longer: typically 1–3 business days (a few business days in China). The request stays in_progress during that time and delivers through the same response shape, webhooks, and polling as any other datapoint.
What is affected
Manual delivery currently applies to beneficial ownership data (ultimateBeneficialOwners) in several countries, and to shareholder data (shareholders) in China. Some document types in these countries are also manually fulfilled.
The live pricing page marks every affected datapoint and document with a Manual badge. Use it to check the current list before building a country-specific flow.
Detect it at runtime
The public catalog, GET /v2/catalog, exposes manual and manualDescription on each data block mode and on each document type. Use these fields to branch in your integration logic, set user expectations, or skip a datapoint when you need instant results.
The catalog needs no API key and returns every country’s manifest, keyed by country code:
In the response, a manually delivered data block mode looks like this (Slovenia, trimmed to the relevant fields):
A mode or document without manual: true is delivered automatically. GET /v2/pricing returns prices per mode and does not carry these fields.
GET /v2/catalog is the programmatic source of truth. Avoid hardcoding which datapoints are manual: the set can change as countries add automated sources.
How it works in a request
Manual datapoints follow the same lifecycle as any other datapoint:
- Create a request with
POST /v2/company as usual. The response returns in_progress for the manual datapoint.
- The datapoint stays
in_progress while the manual work is underway. This is expected, not an error.
- A
company.updated webhook fires when the datapoint finishes, with the same payload shape as an instant datapoint. If you poll instead, the status moves to succeeded or failed.
- The result is available through
GET /v2/company/{requestId} in the same response shape as any other data.
You do not need separate code paths to consume manually delivered data. The only difference is time.
Concurrency
A request whose only remaining work is manually delivered does not hold a slot against your account’s concurrency limit. The slot is released once the automated portion of the request finishes. Manual items never block your capacity for other requests.
Timeouts and retries
The standard retry windows described in Reliability and errors apply to automated register retrieval (up to 1 hour in verification mode). Manual items have their own turnaround and are not covered by those windows.
If a manual item is not delivered within 14 days (7 days for shareholder data in China), it fails with the error code manual_document_timeout. This failure is final and is not retried automatically. Contact support@topograph.co with the request id if you still need the data, rather than sending the request again.
While a manual item is still in progress, sending the same request again does not restart or speed up the manual process.
If the document turns out not to exist for the company, the item fails as soon as that is confirmed, with no_document_available, instead of waiting out the full window.
Integration recommendations
- Set user expectations. If your flow includes a manually delivered datapoint, tell your users the result will arrive later. The
manual flag from GET /v2/catalog lets you detect this at build time or at runtime.
- Use webhooks. Polling every few seconds for a result that takes days wastes bandwidth. Set up webhooks and process the result when it arrives.
- Consider splitting your request. Request instant datapoints first, then request manual ones in a follow-up call if your UX benefits from showing partial data immediately. Both requests are billed independently through the normal deduplication window.
