> ## Documentation Index
> Fetch the complete documentation index at: https://docs.particle.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Look up people and companies by identifier

> Resolve a LinkedIn slug, social handle, company domain, ticker, CIK, or Wikidata QID to the people and companies that carry it — in bulk, with each result echoing the input you sent.

If you already have a list of people or companies identified the way
the rest of your systems identify them — a LinkedIn profile URL from
your CRM, a Twitter handle from a campaign export, a domain from a
sales list, a ticker from a portfolio — the search endpoint is the
wrong tool to reconcile them with Particle:

* `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}` and `GET /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.

The **lookup** endpoint closes that gap. It is the reverse of
[a person's external links](/api-reference/people/list-person-external-links)
and [a company's external links](/api-reference/companies/list-company-external-links):
those tell you which identifiers an entity carries, and this tells you
which entity carries an identifier.

## Look up a LinkedIn profile

Pass the identifier exactly as you have it. You do not need to know how
we store it.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl -s "https://api.particle.pro/v1/entities/lookup?identifier=in/satyanadella" \
    -H "X-API-Key: $PARTICLE_API_KEY"
  ```

  ```javascript JavaScript theme={"dark"}
  const res = await fetch(
    "https://api.particle.pro/v1/entities/lookup?identifier=in/satyanadella",
    { headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
  );
  const { results } = await res.json();
  ```

  ```python Python theme={"dark"}
  import os, requests

  r = requests.get(
      "https://api.particle.pro/v1/entities/lookup",
      params={"identifier": "in/satyanadella"},
      headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
  )
  results = r.json()["results"]
  ```
</CodeGroup>

```jsonc theme={"dark"}
{
  "results": [
    {
      "identifier": "in/satyanadella",
      "platforms": ["linkedin"],
      "matches": [
        {
          "type": "person",
          "person": {
            "id": "Cu2Pn4lefIh8gBYa0igoL",
            "slug": "satya-nadella",
            "name": "Satya Nadella",
            "description": "Chairman and CEO of Microsoft…"
          }
        }
      ],
      "match_count": 1
    }
  ]
}
```

The `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:

| What you send                               | Why it works                                                   |
| ------------------------------------------- | -------------------------------------------------------------- |
| `in/satyanadella`                           | The stored form                                                |
| `satyanadella`                              | A bare slug is tried as both a member and an organization page |
| `https://www.linkedin.com/in/satyanadella/` | The platform and identifier are parsed out of the URL          |

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.

```bash theme={"dark"}
curl -s -G "https://api.particle.pro/v1/entities/lookup" \
  --data-urlencode "identifier=in/satyanadella,company/apple,microsoft.com" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

An identifier that resolves to nothing comes back with an empty
`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`.

```bash theme={"dark"}
# Only companies, only LinkedIn
curl -s -G "https://api.particle.pro/v1/entities/lookup" \
  --data-urlencode "identifier=apple" \
  --data-urlencode "platform=linkedin" \
  --data-urlencode "type=company" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

## Accepted platforms

Every platform reported on the external-links endpoints, plus four
company identifier namespaces that live in their own columns:

| Platform                                                | Identifier                    | Applies to                               |
| ------------------------------------------------------- | ----------------------------- | ---------------------------------------- |
| `linkedin`                                              | `in/jane-doe`, `company/acme` | People, companies                        |
| `twitter`, `instagram`, `tiktok`, `threads`, `facebook` | Handle                        | People, companies                        |
| `youtube`                                               | `@handle` or `UC…` channel ID | People, companies                        |
| `wikipedia`                                             | Article title                 | People, companies                        |
| `website`                                               | Full URL                      | People, companies                        |
| `reddit`, `patreon`, `discord`                          | Handle                        | People, companies                        |
| `domain`                                                | `apple.com`                   | Companies                                |
| `ticker`                                                | `AAPL`                        | Companies (resolved from ticker records) |
| `sec`                                                   | CIK, e.g. `0000320193`        | Companies                                |
| `wikidata`                                              | QID, e.g. `Q312`              | People, companies                        |

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 in
`match_count`.

<Note>
  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.
</Note>

## Choosing the right endpoint

| You have                                       | Use                                                                  |
| ---------------------------------------------- | -------------------------------------------------------------------- |
| A name or partial name                         | [`GET /v1/entities/search`](/api-reference/entities/search-entities) |
| An external identifier for a person or company | `GET /v1/entities/lookup`                                            |
| A Particle person slug or ID                   | [`GET /v1/people/{id}`](/api-reference/people/get-a-person)          |
| A company slug, domain, or ID                  | [`GET /v1/companies/{id}`](/api-reference/companies/get-a-company)   |
| A podcast platform identifier                  | [`GET /v1/podcasts/lookup`](/podcasts/lookup)                        |
| An episode identifier                          | [`GET /v1/podcasts/episodes/lookup`](/podcasts/lookup)               |

## Related

* [A person's external links](/api-reference/people/list-person-external-links)
* [A company's external links](/api-reference/companies/list-company-external-links)
* [Search entities by name](/api-reference/entities/search-entities)