Search companies

Build a prospect shortlist from company activity relevant to what you sell. Describe the need in query; use filters for exact constraints and exclude_domains to leave out existing customers. Natural-language planning does not broaden the supported evidence kinds or countries.

Each company includes up to three observations with sources, timestamps, and an explanation of why the activity may matter. Ranking is not a buying probability. Coverage is partial, and an empty list does not prove no matching company exists.

Set background to true to receive an operation ID, then poll GET /api/usages/. Reuse the same Idempotency-Key only for identical retries. For the next page, keep query, filters and limit unchanged, pass next_cursor as cursor, and use a new key.

See the quickstart, filtering and pagination, or MCP tools.

POST /api/companies/search

Search companies

cURL

curl --request POST \
  --url https://app.jolts.xyz/api/companies/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "query": "Companies seeking EV charging equipment",
  "filters": {
    "countries": [
      "CA",
      "US"
    ],
    "exclude_domains": [
      "example.com"
    ]
  },
  "limit": 10,
  "background": true
}
'

200

{
  "usage": {
    "id": 2,
    "status": "pending",
    "request_key": "<string>",
    "request_units": 1,
    "delivered_units": 1,
    "fresh_evidence_units": 1
  },
  "request_allowance": {
    "window_seconds": 1,
    "window_remaining": 1,
    "weekly_remaining": 1
  },
  "coverage_status": "partial",
  "retrieval": "lexical",
  "as_of": "2023-11-07T05:31:56Z",
  "next_cursor": "<string>",
  "withheld_units": 1,
  "delivery_unit": "company",
  "companies": [
    {
      "id": 2,
      "name": "<string>",
      "limitations": [
        "<string>"
      ],
      "demand_class": "explicit_request",
      "why_it_may_matter": "<string>",
      "match": {
        "query": "<string>",
        "observation_ids": [
          2
        ]
      },
      "observations": [
        {
          "id": 456,
          "kind": "facility_expansion",
          "observed_fact": "Example Logistics announced a new distribution warehouse.",
          "why_it_may_matter": "A new warehouse may need handling equipment; no purchasing decision is confirmed.",
          "demand_class": "proxy",
          "country": "CA",
          "confidence": 0.8,
          "occurred_at": "2026-09-20T00:00:00Z",
          "observed_at": "2026-09-21T12:00:00Z",
          "expires_at": null,
          "evidence": [
            {
              "source_uri": "https://logistics.example/news/warehouse",
              "excerpt": "We are opening a new distribution warehouse.",
              "occurred_at": "2026-09-20T00:00:00Z",
              "observed_at": "2026-09-21T12:00:00Z"
            }
          ]
        }
      ]
    }
  ],
  "ranking": "query_relevance_baseline",
  "candidate_limit": 100,
  "coverage": {
    "requested_companies": 1,
    "returned_companies": 1,
    "stop_reason": "<string>",
    "limitations": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key · string · required

Unique operation key. Reuse only for identical retries, including across HTTP/MCP. Each new page needs a new key.

Body

application/json

query · string · required

Required string length: 1 - 500

filters · object

Lists use OR within a field, AND between fields; exclusions win. Each list permits at most 100 values. IDs must be positive integers. Domains are hostnames, not URLs; case, surrounding whitespace and trailing dots normalize. Empty lists do not restrict. Only current evidenced domain relationships match.

Show child attributes

limit · integer · default: 10

Maximum page size is subscription-owned: builder 25, professional 50.

Required range: x >= 1

cursor · string | null

Opaque cursor. Keep query, filters and limit unchanged; use a new request key for each page.

background · boolean · default: false

Queue the same company operation through Active Job; poll GET /api/usages/{id}. This option does not change idempotent request identity.

Response

200

application/json

Completed company page (may be empty).

usage · object · required

Show child attributes

request_allowance · object · required

Show child attributes

coverage_status · string · required

Allowed value: "partial"

retrieval · enum<string> · required

Available options: lexical, hybrid

as_of · string<date-time> · required

next_cursor · string | null · required

withheld_units · integer · required

Required range: x >= 0

delivery_unit · enum<string> · required

Available options: company, observation

companies · object[] · required

Show child attributes

ranking · string · required

Allowed value: "query_relevance_baseline"

candidate_limit · integer · required

coverage · object · required

Show child attributes