GET /v1/entities/search?q=…matches on name. It cannot find a person whose name you spell differently than we do, and the top hit is not guaranteed to be the right one even when the names look identical.GET /v1/people/{id}andGET /v1/companies/{id}take our slug, our ID, or a company domain. They do not take a LinkedIn slug, an Instagram handle, or a CIK.
Look up a LinkedIn profile
Pass the identifier exactly as you have it. You do not need to know how we store it.slug feeds straight into GET /v1/people/{id}, and a company
match’s slug or domain feeds GET /v1/companies/{id}.
You do not have to normalize the identifier
All three of these resolve to the same person:
The same applies elsewhere:
@mkbhd and mkbhd both find the YouTube
channel, Satya Nadella and Satya_Nadella both find the Wikipedia
article, 320193 and 0000320193 are both the same SEC CIK, and
www.apple.com and apple.com are the same domain.
The identifier in each result is echoed back exactly as you sent
it, never normalized, so you can join the response to your own rows by
identifier. Join by identifier rather than by position: duplicate
identifiers in the request collapse to a single result, so the response
can be shorter than the request.
Bulk lookup
Pass a comma-separated list, up to 100 per call. Results come back in request order, one per unique identifier; duplicates in the request collapse to a single result.matches array and match_count of 0, so a bulk caller never has to
reconcile a shorter response against a longer request.
Narrowing the search
platform restricts the lookup to one platform. Omit it when you hold
a handle but do not know where it came from — a bare handle is matched
on every platform at once, and the result’s platforms array tells you
where it landed.
type restricts results to person or company.
Accepted platforms
Every platform reported on the external-links endpoints, plus four company identifier namespaces that live in their own columns:
An unrecognized
platform returns 400 listing the accepted values.
An identifier that does not resolve is never an error.
Behavior and edge cases
One identifier can resolve to several entities
matches is an array, not a single entity, because an identifier is
not unique to an entity. Particle stores at most one identifier per
platform per entity, which means two records for the same real person
can each carry the same LinkedIn profile — and 8.7% of the LinkedIn
identifiers we hold are shared that way.
Returning one of them and hiding the rest would be an identity claim
decided by row order, so the matches come back as a list, best first, up
to the ten documented below. match_count tells you how many entities
carry the identifier in total — consult it rather than assuming
matches is exhaustive — and treat a value above 1 as a signal to
disambiguate on your side rather than as an error.
Matches are ordered, and capped at ten
Entities linked to a knowledge graph entity come first, because that is the enriched record a caller almost always means, then oldest first, then by ID so the order never varies between calls. At most ten entities are returned per identifier.match_count still
reports the true total.
Deleted entities never appear
An identifier whose entity has since been removed resolves to nothing rather than to a dangling reference, and it is not counted inmatch_count.
Coverage differs sharply by platform and entity kind. Companies are
near-universally covered by
domain and well covered by linkedin;
ticker, sec, and wikidata apply only to the small share of
companies that have them. People are best covered by linkedin and
the major social platforms.