Look Up a Profile, Post, Page, or File and Identify Every Company and Person It Names
Looks up a pasted URL: a LinkedIn or X profile or post identifies the person or company it belongs to and can add that record when aVenture has none, and any other page identifies the companies and people it names. Use it to look up, identify, or add someone from a profile, post, or page URL; to research a record aVenture already holds, use POST /v1/research/runs. Reads a page (sourceUrl or sourceNewsId), a recorded document such as an email (sourceDocumentId, sent alone; read live with editor authority, or durably as your own captured PDF with Prefer: respond-async, source-read), a screenshot or PDF (multipart file part), or a page and screenshot, lists every company, organization, investor, and person it names, and identifies each one as POST /v1/lookup would, with the page as its source. A PDF’s link annotation targets and printed URLs identify as URLs, and names from every readable text chunk identify as mentions under the same mention cap; names left out set truncated. A page fetched from sourceUrl first lists its own site’s company, looked up by that site’s URL, unless the site is a news outlet, a shared platform such as LinkedIn, or aVenture; when no record holds that site, it is added from the name the site declares, as POST /v1/lookup adds a URL. A caller that read the names itself sends them as mention instead, alone, so neither page nor screenshot leaves it. Answers within seconds: a name still identifying when the time is up carries failureReason instead of identification; send it alone to POST /v1/lookup. Each NO_MATCH name whose own site a web search finds, and whose live page names it, is added as a new record whose visibility follows canonical publication rules, queued for research as scheduleEnrichment says, and returned as shell; adding it spends no research unit, and a name not added carries shellDetail saying why. Without Prefer: respond-async, JSON and text answers await filing within the live deadline. Only callers sending Prefer: respond-async release the identifications with filing pending in a lookup job; poll filing.statusUrl and merge its mention rows by mentionType and name. The event stream sends each identification immediately and each committed shell before complete. Needs a signed-in user. Each name spends one name-identification quota slot, as POST /v1/lookup does; reading a page, screenshot, or PDF also spends one natural-search slot and the free daily lookup allowance (20 name lookups per UTC day), sending mention does neither. JSON body: {“sourceUrl”:“https://techcrunch.com/2024/01/01/example”} or {“mention”:[{“name”:“Visa”,“type”:“COMPANY”}]}; multipart: a file part plus an optional JSON body part. With maxNames, the request answers 202 with a lookup-only bulk job instead: it identifies up to that many names from an article or mention names alone, adds no records, queues no research, spends one name-identification slot per bound name, and is read at GET /v1/lookup/jobs/{jobId}; the same request sent again soon reuses its paid job.
Authentication
Your aVenture API key (https://aventure.vc/settings/api-keys) or OAuth access token
Headers
Send respond-async to release identifications before shell filing completes; poll filing.statusUrl. A signed-in user can also send source-read with respond-async for durable source reading of a supported URL-only event-stream lookup, including cataloged news, LinkedIn or X profiles, and supported social posts, or of a PDF the caller captured in an aVenture app (its sourceDocumentId, sent alone), which any signed-in user may send this way and is metered as other durable source reads; another caller’s capture answers 404. The source event describes the source; accepted carries sourceRead.continuation after the background lookup commits. Follow its caller-scoped statusUrl with Retry-After; accepted is not completion. An exact stored profile can still complete inline. Without both preferences, lookup starts live, but a supported source whose live attempt runs out of time or whose provider remains running can still continue in a caller-scoped lookup job, including for JSON responses.
Query parameters
true queues research on each record this lookup adds and on supplied profiles. false never queues research. When omitted, LinkedIn and X profiles, including a social post author profile, use the automatic profile-enrichment policy; other records are added without research. Logo import and synchronous profile adoption can still run when research is disabled.
When omitted, uses the signed-in user’s saved refreshLinkedin search setting, which defaults to true; callers without a user account default to true. An explicit value overrides the saved choice, except that a deterministic source never refreshes, even when true is sent, and a maxNames bulk lookup ignores this value. Import supported LinkedIn profile data before the lookup finishes. Set false to skip re-import when this exact profile is already linked; initial profile attachment and separately requested research are unchanged. Evidence follows the existing capture cache policy; this never forces a new capture. Company profiles attach their proven URL, fill an absent founding year, retain a dated employee count or size range, resolve an exact current industry label, and fill an absent operating headquarters address only from one unambiguous office. A missing description is composed and judged from retained evidence, never copied from About. Current curated descriptions, classifications and addresses are preserved; unsupported industry or address values remain capture evidence.
Opt in to lookup-only bulk; cap is 1 through app.jobs.lookup-job.bulk-mention-limit. Accepts an article or mention names alone; no shells or enrichment are scheduled.
Request
POST /v1/lookup/mentions without maxNames only: identify extracted names using deterministic stages, without judgment, web-evidence identity or shell filing. Name extraction is unchanged. Lookup jobs reject true.
True answers each name with only its name, mentionType, failureReason, and identification status, stage, match, officialUrl, and detail: no entity or person rows and empty candidate and duplicate lists. Defaults to false.
Id of a stored source document whose text is the article; send it alone. Only POST /v1/lookup/mentions without maxNames reads it. An event-stream request with Prefer respond-async, source-read accepts any signed-in user’s own captured PDF; every other read needs editing rights.
aVenture news id of the article; an id that names no stored article is an error.
URL of the article; read from aVenture news when stored there, otherwise fetched.
Response headers
Requests allowed per client IP in the current rate-limit window.
Requests left before the tightest applicable rate-limit bucket rejects.
Seconds until the exhausted rate-limit bucket admits another request; 0 when none is exhausted.
Response
Each distinct name: the page’s own company first, then the order the source shows them, with news outlets and the page’s bylined authors last.
Present only for callers that sent Prefer: respond-async. Identifications are settled but shell filing is pending. Poll statusUrl until the lookup job completes; merge its filing outcomes by mentionType and name.
The stored aVenture news article the source page is, when it is one; absent otherwise.
On a shared LinkedIn or X profile lookup’s source event and JSON answer: whether the server’s profile policy (app.lookup-mentions.profile-auto-enrich-enabled) researches the profile at once. A caller that sends scheduleEnrichment=false and files research itself follows it. Absent on every other event and lookup.
Publisher reading state, available before the first name settles; a continuation is present only after its durable job commits.
True when the page names more than this answer holds: more names than one live lookup reads, or a body longer than the read limit. A lookup job with maxNames reads every name.