Manual Delivery

Most Topograph datapoints resolve in seconds or minutes. A small number are fulfilled through a manual process and take longer: from 1–2 business days in most countries up to 14–20 business days in a few, depending on the country. 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. Where the delivery window is known, manualDeliveryEstimate gives it in business days as minBusinessDays and maxBusinessDays. 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:

curl --request GET \
  --url 'https://api.topograph.co/v2/catalog'

In the response, a manually delivered data block mode looks like this (Slovenia, trimmed to the relevant fields):

{
  "SI": {
    "dataBlocks": [
      {
        "datapoints": ["ultimateBeneficialOwners"],
        "modes": [
          {
            "fast": false,
            "authoritative": true,
            "manual": true,
            "manualDescription": "Sourced through our SI partner — typically 1–2 business days.",
            "manualDeliveryEstimate": { "minBusinessDays": 1, "maxBusinessDays": 2 }
          }
        ]
      }
    ],
    "countryDocuments": [
      {
        "type": "ubo_extract",
        "displayName": "Beneficial Ownership Extract",
        "manual": true,
        "manualDescription": "Sourced through our SI partner — typically 1–2 business days.",
        "manualDeliveryEstimate": { "minBusinessDays": 1, "maxBusinessDays": 2 }
      }
    ]
  }
}

manualDeliveryEstimate is an estimate, not a measured time, and is separate from the indicative response times published for automated datapoints. 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 configurable retry window described in Automatic retries applies to eligible automated retrieval in verification mode. Manual items have their own turnaround and are not retried by maxRetryDelaySeconds. A retry waits until the other items in the same request have finished. Request manual items separately from automatic items that use maxRetryDelaySeconds, so a manual delivery does not consume their retry window. If a manual item is not delivered within 15 days, 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.

Getting Started

AI Agents

Integration Guides

Core Features

Behavior & Operations

What is affected

Detect it at runtime

How it works in a request

Concurrency

Timeouts and retries

Integration recommendations