Skip to main content
Batches is the spreadsheet path to Topograph. Instead of calling the API for one company at a time, you upload a file with hundreds or thousands of companies, let Topograph find each one in its national register, review the matches that need a human decision, fetch the data points you need, and export a single file with the results. It lives in the product app, in the sidebar under Batches. Every lookup and every data request it makes is an ordinary request: it appears in your request history, is billed in credits like any other request, and can be opened on its own page.

​
What a batch does

1

Import

Drop a CSV or XLSX file. Topograph reads the columns and proposes which one holds the country, the identifier, the legal name and the address. You confirm or correct the mapping once, and the file becomes a saved batch you can come back to at any time.
2

Match

Each row is searched in its country’s register, by identifier when you have one, otherwise by legal name. Rows that resolve unambiguously are matched on their own. Rows that need a decision wait for you in a review queue.
3

Get data

Pick the data points you need (company details, legal representatives, other key persons, establishments, shareholders, subsidiaries, ultimate beneficial owners) and the request mode. Topograph fetches them for every matched row, ten at a time, and keeps going while you close the tab.
4

Export

Download the whole batch, or the rows you selected, as CSV or XLSX. One row per company you imported, in the order of your file, with the match and the data alongside your original columns.

​
Importing a file

The file needs a header row and one company per row. Any column layout works. Topograph looks at the headers and a sample of rows to suggest which columns are:
  • Country: an ISO code (FR, DE), a country name, or a US state code. A column of US states can be read as US-AK, US-CA and so on with one checkbox. If a row has no country, a fallback country can be applied to it.
  • Identifier: the register number, SIREN, Companies House number, EIN or whatever your file holds. Leading zeroes are preserved.
  • Legal name.
  • Address: either one combined column or separate street, city, postal code and region columns. Addresses are optional, but they are what tells two companies with the same name apart.
Every original cell is kept and exported unchanged. Multi-sheet workbooks ask which sheet to import.
Limits per batch: 50,000 rows, 100 columns, 5 MB.

​
How matching works

After a search, each row lands in one of these states: The table shows the state of every row with a badge. A green check means the match was reviewed; an amber triangle means one field, such as the postal code, disagrees with your input.

​
Reviewing

Review opens the rows that need a decision one after the other. Each one shows your row and the suggested company side by side, with the evidence as plain sentences (“Legal name agrees once the legal form is added”, “Postal code differs: 72714 vs 72715”, “Address not included in this register’s search results”) and the reasoning behind the suggestion one click away. From the dialog you can confirm, mark no match, skip, search another name in the same country, or type an identifier by hand. Keyboard shortcuts cover the whole pass: arrow keys to pick a candidate, N for no match, ⌘↵ to confirm, S to skip, / to search. Clicking a single row in the table reviews only that row.
On a file where the suggested matches look right, use Review → Trust suggested matches. It marks every unreviewed suggestion as reviewed in one go and leaves ambiguous and unmatched rows for you.

​
Fixing a row

Any row can be edited: country, identifier, legal name, address. Saving new inputs clears the row’s match and any data fetched for it, so search the row again afterwards. Searching a row that already has a reviewed match or fetched data asks for confirmation first.

​
Getting data

Get company data works on the rows in view: every matched row in the current filter, or the rows you selected. The dialog shows how many rows will be fetched, which of them already have data, the data points to fetch, the request mode, and the price per company for each country in the batch, with an upper bound for the whole run before you commit.
  • Verification mode uses authoritative sources first. It is slower and is the right choice for KYB files.
  • Onboarding mode uses the fastest available sources first. See Modes.
Rows that already have data are left alone unless you tick Fetch again. A data point the country does not offer is skipped and noted on the row (“2 not offered”). In onboarding mode, a data point that has no fast source is also noted rather than counted as a miss (“1 onboarding-only”): the mode returned what it could, and a verification request would fill the gap. In both cases the row counts as Ready. A request that delivered most data points but hit a register error on one is marked Partial: the data is kept and the missing points are named. A request that produced no data is marked Failed with the register’s own reason, and can be retried from the row.

​
Data statistics

Open Data statistics from the Data step to see how many rows returned each data point. The breakdown separates successful results, data not offered by the country, onboarding mode limits, failures, pending results and data not requested. Successful empty lists are counted and labelled separately within the obtained total. These counts cover the whole batch, regardless of table filters or selection. They use each row’s latest saved result, so fetching a row again does not count it twice.

​
Following progress

The filter bar has two steps. Match shows To review, Matched and Unmatched; Data shows Not fetched, Ready and, only when they exist, Partial and Failed. A running run shows how many rows are in flight and how many are queued, and Activity lists every run of the batch with the option to stop the rows that have not started yet. Runs continue on our side. You can close the page, come back later and pick up where the batch is.

​
Exporting

Export downloads the rows in view (or your selection) as CSV or XLSX. The file has a fixed layout, one row per imported company, in the order of your file:
  • your input: input_country, input_identifier, input_legal_name, input_address_json;
  • the match: matched_country, matched_identifier, matched_legal_name, matched_address_json, match_type, search_status;
  • the data: data_status, request_id, requested_datapoints, and one JSON column per data point (company_json, legal_representatives_json, other_key_persons_json, establishments_json, shareholders_json, subsidiaries_json, ultimate_beneficial_owners_json);
  • error_code and error_message for rows that could not be completed;
  • schema_version, batch_id, source_row and completed_at.
Structured data is exported as JSON inside the cell, so a company with three shareholders stays one row. Identifiers are written as text, so leading zeroes survive a round trip through a spreadsheet. Export never triggers a new request: it writes what the batch already holds.

​
Good to know

  • Batches belong to a workspace. Requests made from a batch use that workspace’s register credentials and appear in its history.
  • Ownership graphs and document orders are not part of batches yet. Open the request behind any row to order documents for that company.
  • In a development environment, batches work end to end on generated data, so you can test an import without spending credits.