Identify a Company or Person | aVenture Developer Docs

Lookup is an experimental feature. Its behavior and response fields can change between releases. If an answer looks wrong for the clues you sent, report the request body and the response through Support.

Lookup answers one question: which aVenture record is this name? You send a name as your source writes it plus any clues you have. The answer says whether one record matches, none does, or a person has to decide.

Pick an Entry Point

Operation	Use it when	CLI
`POST /v1/lookup`	JSON body clues identify a company, product, service, or person without scheduling research	`aventure lookup-from-file`
`POST /v1/lookup`	You send the clues as a JSON body, optionally with a known `kind`	`aventure lookup-from-file`
`GET /v1/entities/lookup-exact` or `/v1/people/lookup-exact`	You hold an exact slug, website, domain, or profile URL and want the full record	`aventure entities lookup-exact get` or `aventure people lookup-exact get`

Send POST /v1/lookup with kind set to ENTITY for a company or PERSON for a person.

The /v1/lookup operation returns the identification shape shown below. Send the clues as a JSON body.

A name that is exactly a record’s id, handle, registry id, or slug settles on every plan. Any other name counts against the free plan’s 20 lookups a day; past those it answers 402 with code subscription_required until the next UTC day, and AI Plus or AI Pro lifts the limit. On every plan, GET /v1/entities/lookup-exact (CLI: aventure entities lookup-exact get) returns the record for an exact website, domain, or slug.

The universal POST /v1/lookup first checks whether the name is exactly a record’s id, public handle, slug, or registry id such as a ticker, LEI, or EIN. If it is, that record is the answer. Otherwise it runs the company lookup and the person lookup together. match.owner says which kind matched: entityId for a company, personId for a person. When a company and a person share the name, the answer is NEEDS_REVIEW.

If you already hold an exact slug, URL, or domain and want the full record, use GET /v1/entities/lookup-exact or GET /v1/people/lookup-exact instead. Those reads return 404 or 409 rather than guessing. When you need only a company’s names, logos, links, and categories, the thinner company brand lookup returns them from any URL the company owns.

Send Every Clue You Have

Send name, url, or both. name is required only when url is absent; a subject-owned URL can identify the record by itself. Each other field narrows the answer.

Field	What to send	Why it helps
`name`	The name exactly as the source writes it, such as `Mercury` or `Patrick Collison`	Starting point for every match
`url`	Up to 10 URLs the subject owns: its website, its LinkedIn company or person profile, or a registry page	A URL the record already holds proves the match without further judgment
`location`	City, region, or country, such as `Austin, TX`	Tells namesakes apart; not proof on its own
`context`	Specific facts: product, industry, employer and title, or founder names	Separates companies or people with the same name. Generic words like “startup” add nothing
`sourceUrl`	The URL of the article that mentions the subject	Supplies the surrounding text as evidence
`sourceNewsId`	The aVenture news id of that article, instead of `sourceUrl`	Same as `sourceUrl`; an unknown id returns `400`

Put articles in sourceUrl, not in url: url is only for pages the subject owns. A parent company, subsidiary, or namesake is a different company. The same person name at a different employer is a different person.

Act on the Answer

Every response has a status, a one-sentence detail, and a candidate list ordered most probable first.

`status`	Meaning	What to do next
`MATCHED`	One record is the subject	Read it by `match.record.id`: `GET /v1/entities/{entityId}` for a company or `GET /v1/people/{personId}` for a person
`NO_MATCH`	No record you can see is the subject	Treat the subject as new. For a company, use `officialUrl` as its website when it is present and is the company’s own domain
`NEEDS_REVIEW`	The clues fit more than one record, or cannot rule one in	Research every plausible candidate, refine once with independently evidenced clues, and ask only if the separating fact remains user-held. Never create a record on `NEEDS_REVIEW`

duplicate lists other stored records that appear to be the same subject stored again. NO_MATCH covers only the records your credential can see.

How the Answer Was Settled

stage names the step that settled the answer:

DETERMINISTIC: exact proof. A URL you sent is already held by the record, or the name is an exact id, slug, or registry id. No judgment is involved.
JUDGMENT: a decision model compared the candidates against your name and clues. Each candidate’s probability, from 0 to 1, is the confidence to act on.
WEB_EVIDENCE: the judgment also used a web search. officialUrl holds the subject’s own website or profile when the search found one.

Deterministic answers are the most reliable. Sending the subject’s website or LinkedIn URL is the best way to reach one.

Examples

A company with its website and location:

curl -X POST "https://api.aventure.vc/v1/lookup" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Mercury","kind":"ENTITY","url":["https://mercury.com"],"location":"San Francisco"}'

A person, with their employer as context:

curl -X POST "https://api.aventure.vc/v1/lookup" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Patrick Collison","kind":"PERSON","context":"Stripe co-founder"}'

A name when you do not know whether it is a company or a person:

curl -X POST "https://api.aventure.vc/v1/lookup" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Mercury","url":["https://mercury.com"]}'

To accept only an exact id, handle, registry id, or slug on POST /v1/lookup, add exact=true (--exact true in the CLI). The lookup then skips judgment and web search and returns 404 when nothing matches exactly.

Access and Limits

Lookup and article lookup require a signed-in caller: an API key or a CLI or MCP sign-in (see Authentication). A signed-in caller whose plan does not include natural search receives 402 with code subscription_required.

Each company or person lookup spends one call of your per-minute name-identification quota. On POST /v1/lookup, a name that exactly matches an id, handle, registry id, or slug settles for free; only names that go on to the company and person lookups spend quota. When the quota is exhausted the call returns 429 with a Retry-After header. A lookup that may outlast your client’s timeout can run as a job you poll: send it with Prefer: respond-async. Plans and usage explains what counts against an allowance.

Next Steps

Identify names in an article runs this lookup on every company and person an article names.
Identify a list of names runs up to 2,000 lookups as one background job.
Update records with research refreshes the records you identified.
Use cases and examples matches a whole list of websites to companies without a name lookup.