Matching

Always send name. Match resolves the companies in your data to AggKnowledge companies: POST /v2/{environment}/company/match takes any combination of the fields below and returns up to 50 candidates, best match first. Every field is optional; in practice, the name is the one to never leave out.

Exception on v3: the path is POST /v3/{environment}/company/match and every field below keeps its name and semantics, except that name is called companyName, and it, website, socialProfile, and socialProfileId are plain strings rather than or/not filters. At least one of those four is required.

Two kinds of fields#

This is the most important thing to understand — it decides what happens when a value is wrong.

Filters narrow the results: a company must satisfy them to be returned.

Field	How it’s matched
`name`	Matched against the name, display name, and known aliases. Minor typos are tolerated (a misspelled `Saleforce` still finds `Salesforce`) and common legal suffixes like `Inc`, `Ltd`, or `Corp` are handled automatically, so `Acme Inc` still finds `Acme`. Casing, spacing, and punctuation are normalized away. Other extra words still narrow the match, so send the core name. Always include it — an exact, correctly-spelled name still ranks highest. These tolerances apply when finding companies with `or`; `not` exclusions are matched exactly.
`website`	Exact, on the domain. We strip `https://`, `www`, paths, and query strings, so `https://www.acme.com/about` and `acme.com` are treated the same.
`socialProfile`	Exact, on the normalized LinkedIn URL.
`listing`	Exact, on a `{ "ticker": …, "exchange": … }` pair — both halves required, and matched together. A ticker is only unique within an exchange (`BMW` is Bayerische Motoren Werke on `xetr` and Bavarian Nordic on `xcse`), so the pair is what identifies a listing. Give several under `or` to resolve a list of securities at once. Exchanges are MIC codes (`xnys`, `xnas`), not names like `NYSE`. Only a company’s primary listing is searchable, so a secondary cross-listing won’t match.
`fundingTotal`, `latestFundingAmount`, `fundingRoundCount`	Numeric range: `{ "min": …, "max": … }`
`latestFundingDate`	Date range: `{ "gte": …, "lte": … }` (accepts `YYYY`, `YYYY-MM`, or `YYYY-MM-DD`; the day is ignored — see Dates & Precision).
`keywords`	Words to match in the company’s description or tags. By default (`or`) any one matches; use `and` to require all of them.

Ranking signals sharpen the order but never remove a company: primaryTicker, primaryExchange, companyType, industry, country, region, locality, latestFundingStage, revenueRangeInferred, and employeeCountRange. Providing these pushes the right company toward the top; providing one that’s wrong or unrecognized is harmless — it just doesn’t help.

Each text field takes the shape { "and": ["A"], "or": ["B", "C"], "not": ["D"] } — or means “any of these,” not means “none of these” (e.g. "companyType": { "not": ["private"] }).

Warning: On a ranking signal, or only boosts — it does not filter, so "companyType": { "or": ["public"] } still returns private companies. To make one a hard requirement, use and: "companyType": { "and": ["public"] }. Each of these fields holds exactly one value per company, so and takes a single value; pass two and the request is rejected, since nothing could satisfy both. name, website, and socialProfile do not accept and at all — they are already hard requirements under or. keywords honors and with any number of terms, requiring every one.

How ranking works#

Each candidate is scored on:

How well it matches your filters — the name match is the strongest relevance signal.
How many ranking signals it matches — stronger identifiers (ticker, industry) count for more than weaker ones (city, employee range).
A consistent boost toward larger, more established companies — strong enough that it can outweigh small differences in relevance, so a much bigger company can outrank a slightly closer textual match.

Results come back best-first. We don’t expose a numeric score, so treat the first result as the top match and apply your own acceptance rule — e.g. auto-accept position 1, or review the top 3 when you need higher confidence.

Failure conditions#

Situation	Cause	What to do
No results returned	A filter couldn’t be satisfied — usually a wrong or unknown `website`/`socialProfile`, an over-tight funding/date range, or a keyword we don’t recognize.	Drop the exact filter and rely on `name` plus ranking signals.
Right company missing, others returned	The name differs from how we store it beyond a small typo or a legal suffix.	Use the common name; supply alternates as multiple `or` values.
Wrong company ranked first	A common name with nothing to distinguish it.	Add signals (`primaryTicker`, `industry`, `companyType`, `country`) or a trusted `website`.
A wrong ranking signal (wrong ticker, wrong industry)	Signals never filter.	No action — it’s ignored and doesn’t affect whether the right company is found.
An industry value we don’t recognize	Doesn’t match our taxonomy.	No error and no harm — it simply contributes nothing.

When your data is wrong#

The fields behave very differently when a value is wrong:

If this value is wrong…	Result
`primaryTicker`, `industry`, `companyType` (a signal)	Ignored. You still get the right company via `name` — no penalty, but no help either.
`website` or `socialProfile` (an exact filter)	Removes the true match. Combined with a `name` it returns nothing; sent alone, a wrong-but-real domain can return a different company. Only send these when you trust them.
`name` (totally different)	Narrows to the wrong set, or nothing.
Too-tight funding/date range	Can exclude the true company.

Tip: The practical rule: name plus ranking signals is forgiving; website and socialProfile are precise but unforgiving. Send the exact filters only when you trust the value.

Recommended queries#

Tailored to the data you usually have — name always; a ticker, public/private, industry, and sometimes a website.

1. Public company — your most common case

Request body

{
  "name": { "or": ["Salesforce"] },
  "primaryTicker": { "or": ["CRM"] },
  "companyType": { "or": ["public"] }
}

name finds the candidates; the ticker and public type rank the right one to the top. If the ticker is wrong it won’t break the match to Salesforce — it just won’t help disambiguate.

When you know the exchange as well, send the two together as listing instead. That turns them from a ranking signal into a filter, so a wrong pair returns nothing rather than the wrong company:

Request body

{
  "name": { "or": ["Salesforce"] },
  "listing": { "or": [{ "ticker": "CRM", "exchange": "xnys" }] }
}

2. Common name — add industry to separate look-alikes

Request body

{
  "name": { "or": ["Progressive"] },
  "primaryTicker": { "or": ["PGR"] },
  "companyType": { "or": ["public"] },
  "industry": { "or": ["insurance"] }
}

3. Private company / no ticker

Request body

{
  "name": { "or": ["Atlas"] },
  "industry": { "or": ["software"] },
  "companyType": { "not": ["public"] }
}

Industry ranks the right sector; excluding public removes the listed namesakes.

4. When you have a trusted website — the most precise match

Request body

{
  "name": { "or": ["Acme"] },
  "website": { "or": ["acme.com"] }
}

Exact on the domain. Use this only when you’re confident in the website — if it’s wrong, this returns nothing rather than a best guess. When you’re unsure, prefer pattern 1.