Skip to navigation
GuidesIdentify Records

Identify Names in an Article

Beta
Extract every company and person an article names and identify each one
View as Markdown

An article lookup reads one article, extracts every company and person it names, and identifies each name as POST /v1/lookup would, with the article as the source. It shares the lookup’s plan requirement. To identify more names than an article job’s limit, or a list of names you already hold, start a bulk lookup job instead.

Choose an Article Path

NeedCLIResult
One synchronous JSON response from an article, screenshot, or supplied mention namesaventure lookup mentions --source-url "<article-url>" (or --file "<image>", --mention-name ...)Identifications only; it creates no records or research runs
Records and research for new namesaventure lookup mentions --source-url "<article-url>" --schedule-enrichment trueIdentifications, plus a record for each confirmed new name with a research run
Bounded identification-only workaventure lookup mentions --max-names 8 --source-url "<article-url>" or repeated --mention-nameIdentifications only; it creates no records or research runs

Use the first row when you need only the answers. Add scheduleEnrichment=true when the article may name companies or people aVenture does not have yet and you want each new record researched. Use --max-names when you want a bounded batch of identifications and will continue the article yourself; that call answers 202 with a jobId you read at GET /v1/lookup/jobs/{jobId}.

  1. Send POST /v1/lookup/mentions with a body holding sourceUrl, sourceNewsId, or both. Add scheduleEnrichment=true to queue research on each record it adds. The call answers 200 with every name in mention.
  2. To get the identifications before new records finish filing, also send Prefer: respond-async. The answer then carries filing; read its statusUrl until the job completes, and merge its filing outcomes into the names you already have.
  3. Act on each entry in mention. Every entry has the name as the article writes it and a mentionType of COMPANY, PRODUCT_SERVICE, or PERSON:
    • identification is the lookup answer, read exactly as in Act on the answer.
    • shell is set when the answer is NO_MATCH and the lookup filed a new record for the name, or found a record aVenture already holds for the subject’s website. It files one only when the article and the subject’s own live website both name it. shell holds the record’s entityId or personId; when enrichmentRunId is present, it names the research run that fills in the profile. Filing it costs nothing.
    • shellDetail says, in one sentence, why no new record was filed for a NO_MATCH name.
    • failureReason replaces identification when a name could not be identified. Send that name alone to POST /v1/lookup.

Reading the article spends one natural-search call, and each name it identifies spends one name-identification call, up to its per-article limit. The call answers 402 and 429 under the same rules as a single lookup.

Example

Set ARTICLE_URL to the article’s address and look it up, queueing research on new records:

curl -X POST "https://api.aventure.vc/v1/lookup/mentions?scheduleEnrichment=true" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sourceUrl":"'"$ARTICLE_URL"'"}'

Collect the ids from each matched mention’s match.owner and from each shell without an enrichmentRunId, then queue research on the ones worth updating.