aVenture APISearch

Find a company or person by name, URL, or id

View as Markdown
Identifies a company or a person in one call. A name that is exactly a record's id, public handle, registry id (ticker, LEI, EIN), or slug settles at once; otherwise the company and person ladders of entities lookup and people lookup both run. Returns MATCHED when exactly one kind matches and the other finds nothing, NO_MATCH when neither finds the subject, and NEEDS_REVIEW otherwise, including when a company and a person share the name. match.owner says which kind matched. Takes the same fields as entities lookup and people lookup. Example: lookup --name "Acme AI" --url https://acme.ai. Exact id only: lookup --legacy --name eV1StGXR8Z5a. Output: --text (default) is compact text, --json the full envelope, --data the Identification object for scripts.

Authentication

AuthorizationBearer

User bearer token: Clerk session JWT, Clerk OAuth access token, or Clerk API key

Query parameters

includePrivatebooleanOptional

Also considers hidden and unpublished records; needs private-visibility authority. Without it, NO_MATCH covers only records you can see.

legacybooleanOptional

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 natural-search quota, with or without this flag.

Request

This endpoint expects an object.
namestringRequired0-200 characters
Name exactly as the source writes it, such as Acme AI or Jane Doe.
contextstring or nullOptional0-2000 characters

Specific facts in plain words: product, industry, employer and title, or founder names. Generic words like startup add nothing.

locationstring or nullOptional0-2000 characters

City, region, or country, such as Austin, TX. Tells namesakes apart; not proof on its own.

sourceNewsIdinteger or nullOptional

aVenture news id of the article that mentions the subject; an unknown id is a 400.

sourceUrlstring or nullOptional0-2000 characters

URL of the article that mentions the subject; read from aVenture news when stored there, otherwise fetched.

urllist of stringsOptional

URLs the subject owns: its website, its LinkedIn company or person profile, or a registry page. At most 10. Put articles in sourceUrl.

Response headers

X-RateLimit-Limitinteger

Requests allowed per client IP in the current rate-limit window.

X-RateLimit-Remaininginteger

Requests left before the tightest applicable rate-limit bucket rejects.

X-RateLimit-Resetinteger

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.

candidatelist of objects
Records considered, most probable first.
detailstring
One sentence naming what settled the answer or what the user must decide.
stageenum
The ladder step that settled the answer.
Allowed values:
statusenum

What the caller does next: act on match, create, or ask the user.

Allowed values:
matchobject or nullOptional
The matched record when status is MATCHED.
officialUrlstring or nullOptional
The subject's own website or profile page found in web search. Use it as the website when creating the record only if it is the subject's own domain, not a LinkedIn, Crunchbase, or other profile page.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
406
Not Acceptable Error
409
Conflict Error
415
Unsupported Media Type Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error