Company search

Company search filters CatchAll job results to a predefined list of companies and scores each matching record per company. Use it when you want to track a specific set of companies — a portfolio, a competitor list, a watchlist — rather than run broad queries.

How it works

Company search 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 column is 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.

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",
          "ed_score": 9,
          "relation": "NewsCatcher is a named partner in the announced AI infrastructure deal"
        }
      ]
    }
  ]
}

connected_entities fields:

Field	Type	Notes
`entity_id`	string	UUID of the matched entity
`name`	string	Entity name
`ed_score`	number	Relevance score from 1 to 10
`relation`	string	How the entity relates to the record. Maximum 100 characters.

Get started

Guides and concepts

How to

API Reference

Libraries

Integrations

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

Get results

See also

Get started

Guides and concepts

How to

API Reference

Libraries

Integrations

​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

​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

Get results

See also