Company Watchlist - newscatcher

Company Watchlist filters CatchAll job results to a predefined list of companies and scores each matching record per company. Use it to track specific companies — a portfolio, a competitor set, or any curated list — instead of running broad queries.

How it works

Company Watchlist uses three connected concepts: Entities are individual company definitions. Each entity stores identifying information — name, domain, alternative names, key persons — that the system uses to recognize the company in web content. Datasets are named collections of entities. A dataset acts as a watchlist or portfolio. You create it once and can reuse it across multiple jobs and monitors. Connected jobs are standard CatchAll jobs submitted with a connected_dataset_ids parameter. Adding this parameter activates company search mode; everything else about the job — query, validators, enrichments, date ranges — works identically to a normal job.

Create entities

Matching quality depends on what you provide. domain is the most reliable signal — two companies can share a name, but not a domain.

Single entity

curl -X POST "https://catchall.newscatcherapi.com/catchAll/entities" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NewsCatcher",
    "entity_type": "company",
    "description": "AI-powered news data provider",
    "additional_attributes": {
      "company_attributes": {
        "domain": "newscatcherapi.com",
        "alternative_names": ["NC", "NewsCatcher API"],
        "key_persons": ["Artem Bugara", "Maksym Sugonyaka"]
      }
    }
  }'

Show Create entity response

{
  "id": "854198fa-f702-49db-a381-0427fa87f173",
  "status": "pending"
}

Entities move through pending → enriching → ready (or failed) after creation. You don’t need to wait for individual entities to be ready before creating a dataset — the dataset status is what matters before submitting a job.

External enrichment is not yet active. Entities move directly to ready based on the fields you supply. This will change in a future release.

Batch

Use batch creation when adding multiple entities at once. Each entity is processed independently — one failure does not affect the others.

curl -X POST "https://catchall.newscatcherapi.com/catchAll/entities/batch" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entities": [
      {
        "name": "NewsCatcher",
        "entity_type": "company",
        "additional_attributes": {
          "company_attributes": { "domain": "newscatcherapi.com" }
        }
      },
      {
        "name": "OpenAI",
        "entity_type": "company",
        "additional_attributes": {
          "company_attributes": {
            "domain": "openai.com",
            "key_persons": ["Sam Altman"]
          }
        }
      }
    ]
  }'

Show Create entities batch response

{
  "entities": [
    {
      "id": "854198fa-f702-49db-a381-0427fa87f173",
      "status": "pending"
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "pending"
    }
  ],
  "count": 2
}

Results are returned in the same order as the input array.

Create a dataset

From entity IDs

Create a dataset from existing entity IDs. All IDs must belong to your organization — any invalid ID returns 400.

curl -X POST "https://catchall.newscatcherapi.com/catchAll/datasets" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Portfolio",
    "description": "Companies we track for partnership activity",
    "entity_ids": [
      "854198fa-f702-49db-a381-0427fa87f173",
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ]
  }'

Show Create dataset response

{
  "id": "ccabb755-afc2-4047-b84c-78d1f23d49b2",
  "organization_id": "org_6f3a2b1c",
  "name": "My Portfolio",
  "description": "Companies we track for partnership activity",
  "entity_count": 2,
  "latest_status": "pending",
  "created_at": "2026-04-10T09:00:00Z",
  "updated_at": "2026-04-10T09:00:00Z"
}

From CSV

Upload a CSV to create both entities and the dataset in a single request — the fastest path for most use cases. The name and domain columns are required; all other columns are optional. Use semicolons to separate multiple values in alternative_names and key_persons. Rows with an empty name are skipped and reported in validation_report.

name,description,domain,alternative_names,key_persons
NewsCatcher,"AI-powered news data provider",newscatcherapi.com,"NC;NewsCatcher API","Artem Bugara;Maksym Sugonyaka"
OpenAI,"Artificial intelligence research company",openai.com,"Open AI","Sam Altman"
Stripe,"Online payments platform",stripe.com,"","Patrick Collison;John Collison"

curl -X POST "https://catchall.newscatcherapi.com/catchAll/datasets/upload" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@companies.csv" \
  -F "name=My Portfolio"

Show Create dataset from CSV response

{
  "dataset_id": "ccabb755-afc2-4047-b84c-78d1f23d49b2",
  "dataset_name": "My Portfolio",
  "entities_created": 3,
  "validation_report": {
    "total_rows": 3,
    "valid_rows": 3,
    "skipped_count": 0,
    "skipped_rows": []
  }
}

The CSV response returns dataset_id, not id. This differs from the JSON API path.

Wait for the dataset to be ready

Poll GET /catchAll/datasets/{dataset_id} until latest_status reaches ready. Do not submit a job before this step completes.

curl "https://catchall.newscatcherapi.com/catchAll/datasets/ccabb755-afc2-4047-b84c-78d1f23d49b2" \
  -H "x-api-key: YOUR_API_KEY"

Show Get dataset response

{
  "id": "ccabb755-afc2-4047-b84c-78d1f23d49b2",
  "organization_id": "org_6f3a2b1c",
  "name": "My Portfolio",
  "description": "Companies we track for partnership activity",
  "entity_count": 2,
  "latest_status": "ready",
  "created_at": "2026-04-10T09:00:00Z",
  "updated_at": "2026-04-10T09:00:05Z"
}

Submit a connected job

Add connected_dataset_ids to a standard job submission to activate company search mode:

Only one dataset per job is supported at this time, even though connected_dataset_ids accepts an array.

curl -X POST "https://catchall.newscatcherapi.com/catchAll/submit" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI chip partnerships",
    "connected_dataset_ids": ["ccabb755-afc2-4047-b84c-78d1f23d49b2"]
  }'

Poll GET /catchAll/status/{job_id} until status is completed, then retrieve results. See Jobs for the polling pattern.

Filter by association type

When a job is connected to a dataset, you can control how strictly entities must relate to each result by setting ed_association_type.

Value	Behavior
`event_associated`	Only returns events where a tracked entity is the primary actor — the company that raised funding, was acquired, announced layoffs, etc. Passing references are excluded.
`mention`	Returns any event where a tracked entity appears, whether as a primary actor or a passing reference.

When omitted, no association-type filter is applied and all matching records are returned regardless of how the entity relates to the event.

curl -X POST "https://catchall.newscatcherapi.com/catchAll/submit" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI fundraising rounds",
    "connected_dataset_ids": ["ccabb755-afc2-4047-b84c-78d1f23d49b2"],
    "ed_association_type": "event_associated"
  }'

Each matched entity in the results includes an association_type field (event_associated or mention) indicating how it relates to that specific record.

Get all news for a watchlist

To retrieve all news about your tracked companies without filtering by a specific topic, set fetch_all_watchlist_news: true. Use this when you want a broad news feed for a portfolio or competitor set rather than a targeted event search. Wildcard queries (*) and generic phrases like “all news” also trigger this behavior automatically.

fetch_all_watchlist_news requires connected_dataset_ids to be set. Sending it without a connected watchlist returns a validation error.

curl -X POST "https://catchall.newscatcherapi.com/catchAll/submit" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "all news",
    "connected_dataset_ids": ["ccabb755-afc2-4047-b84c-78d1f23d49b2"],
    "fetch_all_watchlist_news": true
  }'

Monitors created from an all-news job preserve this behavior — each recurring run collects all news for the connected watchlist, not topic-restricted results.

Get results

Retrieve results the same way as a normal job. Each record includes a connected_entities array with one entry per matched company. Entities with ed_score of 0 are filtered out automatically and never appear.

curl "https://catchall.newscatcherapi.com/catchAll/pull/{job_id}" \
  -H "x-api-key: YOUR_API_KEY"

Show Get results response

{
  "job_id": "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c",
  "query": "AI chip partnerships",
  "status": "completed",
  "valid_records": 1,
  "all_records": [
    {
      "record_id": "6417909601438475967",
      "record_title": "NVIDIA Expands AI Infrastructure Partnership with NewsCatcher",
      "enrichment": {
        "partnership_type": "technology integration",
        "deal_stage": "announced",
        "enrichment_confidence": "high"
      },
      "citations": [
        {
          "title": "NVIDIA Announces New AI Data Partners",
          "link": "https://example.com/nvidia-ai-partners",
          "published_date": "2026-04-10T09:00:00Z"
        }
      ],
      "connected_entities": [
        {
          "entity_id": "854198fa-f702-49db-a381-0427fa87f173",
          "name": "NewsCatcher",
          "type": "company",
          "ed_score": 9,
          "association_type": "event_associated",
          "relation": "NewsCatcher is a named partner in the announced AI infrastructure deal",
          "company": {
            "domain": "newscatcherapi.com",
            "description": "AI-powered news data provider",
            "alternative_names": [
              "NC",
              "NewsCatcher API"
            ],
            "key_persons": [
              "Artem Bugara",
              "Maksym Sugonyaka"
            ]
          }
        }
      ]
    }
  ]
}

connected_entities fields:

Field	Type	Notes
`entity_id`	string	UUID of the matched entity
`name`	string	Entity name
`type`	string	Entity type, e.g. `company`
`ed_score`	number	Relevance score from 1 to 10
`association_type`	string	How the entity relates to the event: `event_associated` (primary actor) or `mention` (passing reference)
`relation`	string	Sentence describing how this entity relates to the record. Maximum 100 characters.
`company`	object	Company-specific attributes (domain, alternative names, key persons). Present when `type == "company"`.

​How it works

​Create entities

​Single entity

​Batch

​Create a dataset

​From entity IDs

​From CSV

​Wait for the dataset to be ready

​Submit a connected job

​Filter by association type

​Get all news for a watchlist

​Get results

​See also

How it works

Create entities

Single entity

Batch

Create a dataset

From entity IDs

From CSV

Wait for the dataset to be ready

Submit a connected job

Filter by association type

Get all news for a watchlist

Get results

See also