Identify a Company, Product, Service, or Person by Name, URL, or ID
Identifies the company, Product, Service, or person that a name, URL, or id refers to among the records you can see and may file a missing subject. Choose universal lookup only when that possible filing effect is intended. For an existing-record name read, use POST /v1/entities/search with entityName or POST /v1/people/search with personName (CLI entities search —entity-name or people search —person-name), compare candidate identity fields and evidenced URLs, then read the confirmed id. Search results are candidates, not identity verdicts; an empty result means no visible match for those filters, not permission to file. For an existing URL or slug, use GET /v1/entities/lookup-exact or GET /v1/people/lookup-exact. Send name, at least one url, or both; neither answers 422, and a name that is a URL is read as url. Optional clues narrow the answer: kind (ENTITY or PERSON) when you know which kind the subject is, typeRecord or productServiceProviderId for a Product or Service from a known provider, and context such as an employer or title. A name that is exactly a record’s id, public handle, registry id (ticker, LEI, EIN), or slug answers at once. status is MATCHED, NEEDS_REVIEW, or NO_MATCH. MATCHED: match.owner names one record, by entityId (match.record.typeRecord tells a company from a Product or Service; read it with GET /v1/entities/{entityId}) or by personId (read it with GET /v1/people/{personId}). NEEDS_REVIEW: more than one record fits, such as a company and a person sharing a name; candidate lists them, and resending with a URL the subject owns or its kind usually settles it. NO_MATCH: no record you can see was confirmed as this subject; a former, alternate, or legal name may still match through the entityName array in the JSON body of POST /v1/entities/search (CLI entities search). With filing permitted, a NO_MATCH subject 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 with its name, website, and logo, returned as created; adding it spends no research unit. Ordinary named shells are not researched automatically; explicit filing requests research only when research is also requested. An automatic URL-only lookup of one LinkedIn or X profile can instead file its captured owner without an own site; that profile use is deprecated: send the profile URL as sourceUrl to lookupMentions (POST /v1/lookup/mentions), which identifies and files its owner the same way; these requests answer with Deprecation and Sunset headers. For these profiles, omitted scheduleEnrichment uses app.lookup-mentions.profile-auto-enrich-enabled for new records and existing matches; true requests research and false never queues it. Requests restricted to existing records add nothing; exact=true, deterministic=true, and verifyUrl=true do not opt into automatic profile adoption or research by omission. Other existing matches require an explicit research request outside explicit filing. Queue research separately with POST /v1/entities/{entityId}/enrichments or POST /v1/people/{personId}/enrichments. Accept: text/event-stream streams the same answer as server-sent events. With exact=true, name is read only as an exact id, public handle, registry id, or slug: no model call, no web search, no quota spent, NEEDS_REVIEW listing each holder when several records share the identifier, and 404 when nothing matches. Example body: {“name”:“Acme AI”,“url”:[“https://acme.ai”]}. In DEVELOPMENT, automatic record filing and matched-record research are disabled; nothing is filed automatically. Explicit filing and manual record enrichments and run APIs remain available. A signed-in caller that sends Prefer: respond-async gets 202 with a Location status URL instead: a lookup job runs this same identification without the live deadline, and GET /v1/lookup/jobs/{jobId} returns it as identification once COMPLETED. A repeat of the same request returns the same job while it is still PENDING or RUNNING.
Authentication
Your aVenture API key (https://aventure.vc/settings/api-keys) or OAuth access token
Headers
Send respond-async to request a pollable lookup job; filing options are preserved.
Stable intake identity for requested status verification; reuse it to recover the accepted job.
Query parameters
Treat name only as an exact id, public handle, registry id, or slug: no model call, no web search, and 404 when nothing matches; several records sharing the identifier answer NEEDS_REVIEW with each as a candidate. An exact match never spends the name-identification quota, with or without this flag.
Deprecated: send exact instead. Treat name only as an exact id, public handle, registry id, or slug: no model call, no web search, and 404 when nothing matches. An exact match never spends the name-identification quota, with or without this flag.
On universal lookup, LinkedIn and X profiles use app.lookup-mentions.profile-auto-enrich-enabled when omitted; false never queues research. Other existing matches require true. Ordinary named shells are not researched automatically. In DEVELOPMENT, automatic record filing and matched-record research are disabled; nothing is filed automatically. Explicit filing and manual record enrichments and run APIs remain available.
When true, the server fetches each submitted URL and returns its preferred form (for example with or without www) and the HTTP results; defaults to false.
Skip web search, article fetching, semantic retrieval, and model judgment; defaults to false. Unresolved subjects return NEEDS_REVIEW when a scored candidate is plausible, otherwise NO_MATCH, at stage DETERMINISTIC.
Set visibility only for a record this lookup creates: true makes it public, false keeps it hidden, and omission preserves the filing default. Existing records and suppression or duplicate checks are unaffected.
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 exact, deterministic, and verifyUrl lookups never refresh, even when true is sent. 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.
Request
Specific facts in plain words: product, industry, employer and title, or founder names. Generic words like startup add nothing.
Exact email address the record holds as a contact detail. Requires private visibility; when exactly one record of the requested kind holds it, that record matches before names or URLs.
Companies the subject is known to work at; a person filing accepts a LinkedIn profile only when one of them appears in the profile’s employer fields.
Facts a government registry filing (SEC Form D, IRS, HRSA, NPPES) states about the organization. A lookup weighs each stored record’s former names, addresses, team, registry ids, and founded year against them and matches without any model call only at about 220:1 odds. Invalid for a person lookup.
Kind of record to identify when you know it: ENTITY for companies, funds, and firms (and their products or services); PERSON for people. Only that kind is looked up; typeRecord or productServiceProviderId implies ENTITY.
City, region, or country, such as Austin, TX. Tells namesakes apart; not proof on its own.
Name exactly as the source writes it, such as Acme AI or Jane Doe. Send name, url, or both; a name that is an absolute http(s) URL is read as url.
Part the subject plays in the source: INVESTOR when the source lists it as an investor. Unlike typeRecord it keeps every record type a candidate, so a Company or Nonprofit that invests can still match. With it, a lookup with no url, filing, or sourceIdentifier binds a same-named Investment Firm or Fund over a record that does not invest; without a sourceNewsId it also answers NEEDS_REVIEW when the bound record shares its name with another live firm, or a visible record of its type family, unless the location’s place names only the bound record’s address and every namesake stores one. Without it, an Investment Firm or Fund typeRecord applies the firm preference alone. Omit it otherwise.
Exact stored capture of sourceUrl, never an owned website. Requires capture-read authority and a matching successful evidence body; cannot accompany sourceNewsId. Private CSV rows require private body-read authority and their matching canonical relative body#row locator in sourceUrl. Bound lookups remain synchronous.
Permanent source identity with idType and identifier for a catalog source-binding type. Legacy source may be omitted or null; non-null labels are rejected. Requires private visibility and resolves before names or URLs.
aVenture news id of the article that mentions the subject; an unknown id is a 400.
URL of the article that mentions the subject; read from aVenture news when stored there, otherwise fetched. Private CSV evidence uses the canonical relative body#row locator with its matching sourceDocumentId, never an owned website.
Entity type to identify. A Product or Service never matches its provider organization, but a record stored under a neighboring type of the same family (Product or Service; Fund, Investment Firm, or Company) still matches, and a Business Line lookup sees both families. Invalid for a person lookup.
URLs the subject owns: its website, its LinkedIn company or person profile, an aVenture page, or a registry page. At most 10. Required when name is omitted. Put articles in sourceUrl.
Deprecated: send productServiceProviderId, the name the entity duplicate-check and create routes use. Still read as productServiceProviderId; a request that sends it answers with Deprecation and Sunset headers.
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
The identification as canonical JSON or compact text/plain.
What to do next: use the match, record that no match exists in this scope, or add evidence to settle an ambiguous identity.
Results of live URL checks the server ran because verifyUrl=true; empty otherwise.
The owner to bind without confirming: a match no language model settled whose record an exact id, URL, slug, or registry id proved, or whose name spells the requested name up to a trailing legal or group form (an Investment Firm also by its bare brand); or created when its name keeps the requested name as whole words. Absent otherwise: confirm the match or created record before binding it.
The new record a NO_MATCH subject with a proven own site was added as, or the existing one that already held its website. A new company is public and a new person hidden unless publishCreated says otherwise. Absent otherwise.
Whether this answer is a deterministic match to the scoped record. Absent on older stored responses; absence is not proof of a deterministic match.
Research request filed for the created record; absent without created, when the lookup did not request research on it, and when the record is already public.
Present only for callers that sent Prefer: respond-async. The identification is settled, but filing is pending. Poll statusUrl until the lookup job completes and use its identification; do not treat this as a final unfiled absence.
Conflict kind that refused creating the shell, from ProblemDetail.details.conflictType. Absent when no typed conflict refused filing; detail retains the explanation.
Reason that pre-insert validation refused filing; present for verified previews as well as filing requests when validation refuses the subject. Absent when validation admits it; a preview never creates a record or claims a source identifier.
The naming owner’s typed correction for a refused verified preview or filing. Absent on older responses or when no correction was supplied; absence never permits a retry.
Present only for callers that sent Prefer: respond-async. For a completed filing job, whether that request inserted created.
true when the match was settled on a second, slower review; confirm it before relying on it. Absent otherwise.