--- name: "companies_match" area: "companies" title: "Match a company list to the registers" price: "$0.01 per row matched" method: "POST" url: "https://api.conecto.chat/v1/tools/companies_match" mcp_server: "https://api.conecto.chat/mcp/companies" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/companies/companies_match" --- # Match a company list to the registers (`companies_match`) Matches a company list (CSV, Excel or rows) to the registers in the background, with a results file of each match. Matches a list of companies (a CSV or Excel file in the store, or rows) to the registers: each row by its registry number, or by name with its city counting in its favour, in its country's register (GLEIF where there is none). It runs in the background within the registers' pace (a few hundred rows a minute; slower for countries only GLEIF covers): the reply is 202 with a call_id; follow it with account_get_call, or wait for the companies.matched event. The result: counts, a sample and a results file with the list's columns and each match (id, name, score, city, status, industry, founded, LEI). Only clear matches count; close calls come back ambiguous with candidates, free. The call holds $0.01 a row (max_rows) and charges only the rows matched. Price: $0.01 per row matched. A call that fails costs nothing. ## Use it when When the business has a list of companies to identify and enrich: a trade fair list, a CRM export, a target list. - For one company by name, use [companies_search](https://conecto.chat/tools/companies/companies_search.md). ## Say this to your agent > Here is the list of 240 companies we met at the trade fair. Find each one in the registers. ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `file_id` | string | no | A CSV or .xlsx list in the file store, with a header row. Exactly 36 characters. | | | | `rows` | array of objects | no | 1 to 500 items. | | | | `rows[].name` | string | no | Up to 200 characters. | | | | `rows[].country` | string | no | Up to 200 characters. | | | | `rows[].city` | string | no | Up to 200 characters. | | | | `rows[].postcode` | string | no | Up to 200 characters. | | | | `rows[].domain` | string | no | Up to 200 characters. | | | | `rows[].number` | string | no | Up to 200 characters. | | | | `country` | string | no | For rows without a country column, e.g. DE. Matches ^[A-Za-z]{2}$. | | | | `columns` | object | no | Which of the list's columns holds what, where its headers are unusual, e.g. {"name": "Firma", "city": "Sitz"}. | | | | `columns.name` | string | no | Up to 100 characters. | | | | `columns.country` | string | no | Up to 100 characters. | | | | `columns.city` | string | no | Up to 100 characters. | | | | `columns.postcode` | string | no | Up to 100 characters. | | | | `columns.domain` | string | no | Up to 100 characters. | | | | `columns.number` | string | no | Up to 100 characters. | | | | `max_rows` | integer | no | At least the list's rows; the call holds $0.01 for each. 1 to 5,000. | | `100` | | `name` | string | no | The results file's name. Up to 200 characters. | | | ## Example Written for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff. MCP: call `companies_match` on the MCP server `https://api.conecto.chat/mcp/companies` with these arguments: ```json { "file_id": "3f6c1e2a-8b7d-4c5e-9f01-2a3b4c5d6e7f", "country": "DE", "max_rows": 240, "name": "Trade fair contacts matched" } ``` REST: ```bash curl https://api.conecto.chat/v1/tools/companies_match \ -H "Authorization: Bearer $CONECTO_KEY" \ -H "Content-Type: application/json" \ -d '{"file_id": "3f6c1e2a-8b7d-4c5e-9f01-2a3b4c5d6e7f", "country": "DE", "max_rows": 240, "name": "Trade fair contacts matched"}' ``` ## Response ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "companies_match", "status": "succeeded", "replayed": false, "cost_usd": "$2.11", "balance_usd": "$19.75", "result": { "match_id": "6d0f4b2e-3a71-4c8e-9b15-7e2f1a9c4d38", "rows": 240, "matched": 211, "ambiguous": 12, "not_found": 15, "no_country": 2, "register_unavailable": 0, "charged_usd": "$2.11", "file": { "file_id": "9b3e7c1d-2f4a-4d8b-a6e5-0c1d2e3f4a5b", "name": "Trade fair contacts matched.csv", "content_type": "text/csv", "size": "41.6 KB", "size_bytes": 42598, "sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b", "created_at": "2026-10-14T08:00:00+00:00", "download_url": "https://cncto.co/d/9b3e7c1d2f4a4d8ba6e50c1d2e3f4a5b", "link_expires_in_hours": 24 }, "sample": [ { "row": "Arnestad Storkjøkken", "status": "matched", "via": "name", "id": "no:961920566", "name": "ARNESTAD STORKJØKKEN AS", "score": 100.0, "city": "Oslo", "register_status": "active", "industry": "46.49", "founded": "1991-09-01", "lei": null }, { "row": "Bremer Großküchen GmbH", "status": "not_found" } ] } } ``` `result`: First 202 with a call_id. When the list is done, account_get_call gives match_id, rows, matched, ambiguous, not_found, no_country, register_unavailable, charged_usd, file (the results file) and a sample of the first ten rows (row, status and the match). ## Errors | Code | Status | When | Fix | |---|---|---|---| | `invalid_input` | 400 | Both or neither of file_id and rows, a list longer than max_rows, or no column of names. | The message says what to change, such as the max_rows to set. | | `not_found` | 404 | No file with that id on this account. | files_list shows them. | | `unsupported_type` | 400 | The file isn't a CSV or an Excel workbook. | Save the list as CSV or .xlsx. | The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md ## Related - [companies_search](https://conecto.chat/tools/companies/companies_search.md): Companies by name or id across the public registers, each with its id, country, status, city and industry, best match first. Free up to 1,000,000 reads a month. - [companies_get](https://conecto.chat/tools/companies/companies_get.md): A company's record in its register: legal form, status, address, industry, employees, LEI and its officers by name and role. $0.05 a call. - [companies_financials](https://conecto.chat/tools/companies/companies_financials.md): Up to ten years of a company's filed figures in one shape, each with its source document, plus growth, margins, returns and payment days. $0.05 a call. - [companies_save_accounts](https://conecto.chat/tools/companies/companies_save_accounts.md): A UK company's annual accounts as filed with Companies House, saved to the file store as a PDF: the latest, or a year's. $0.001 a call. - [companies_read_accounts](https://conecto.chat/tools/companies/companies_read_accounts.md): The balance sheet and income statement read out of an annual report PDF, a scan by OCR, line by line with its page, German HGB or English. $0.05 a call. - [companies_owners](https://conecto.chat/tools/companies/companies_owners.md): A company's parents and subsidiaries from GLEIF, the SEC and Wikidata and, in the UK, the people and companies with significant control. $0.05 a call. - [companies_legal_notice](https://conecto.chat/tools/companies/companies_legal_notice.md): A company's legal notice (Impressum) read from its own website: legal name, register court and number, managers and VAT number. $0.01 a call. - [companies_estimate](https://conecto.chat/tools/companies/companies_estimate.md): A revenue estimate from headcount and Eurostat's turnover per person employed for the size class and industry, always labeled as an estimate. Free up to 1,000,000 reads a month.