> ## Documentation Index
> Fetch the complete documentation index at: https://dev.jolts.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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/{id}`. 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](/quickstart), [filtering and pagination](/workflows), or [MCP tools](/mcp-tools).

Examples use fictional test data and illustrative IDs, dates, and allowances. They are not live prospects or current account balances.



## OpenAPI

````yaml /openapi.json post /api/companies/search
openapi: 3.1.0
info:
  title: Jolts API
  version: 1.0.0
  description: >-
    Implemented HTTP contract. Authentication uses an account-scoped bearer
    credential. Current coverage is partial; a matching company is not a
    guarantee of buying intent.


    Response examples use fictional test companies and illustrative IDs, dates
    and allowances. They are not live customer results or evidence of market
    coverage.
servers:
  - url: https://app.jolts.xyz
    description: Application API
security:
  - bearerAuth: []
tags:
  - name: Companies
    description: Find prospects and investigate their supporting evidence.
  - name: Observations
    description: Search individual company activities and inspect their sources.
  - name: Operations
    description: Start background work and retrieve its results.
  - name: Account
    description: Check your subscription and shared usage allowance.
paths:
  /api/companies/search:
    post:
      tags:
        - Companies
      summary: Search companies
      description: >-
        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/{id}`. 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](/quickstart), [filtering and
        pagination](/workflows), or [MCP tools](/mcp-tools).


        Examples use fictional test data and illustrative IDs, dates, and
        allowances. They are not live prospects or current account balances.
      operationId: searchCompanies
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
          description: >-
            Unique operation key. Reuse only for identical retries, including
            across HTTP/MCP. Each new page needs a new key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanySearch'
            example:
              query: Companies seeking EV charging equipment
              filters:
                countries:
                  - CA
                  - US
                exclude_domains:
                  - example.com
              limit: 10
              background: true
      responses:
        '200':
          description: Completed company page (may be empty).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResult'
              examples:
                matched_companies:
                  $ref: '#/components/examples/searchCompanies200'
                empty:
                  $ref: '#/components/examples/emptyCompanies'
        '202':
          description: Pending or processing; poll the returned usage ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pending'
              examples:
                pending:
                  $ref: '#/components/examples/searchCompanies202'
        '401':
          description: Missing or revoked API credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  $ref: '#/components/examples/invalidCredential'
        '402':
          description: An active or trialing subscription is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  $ref: '#/components/examples/subscriptionRequired'
        '422':
          description: >-
            Invalid request, conflicting retry, expired operation or processing
            failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  $ref: '#/components/examples/invalidSearch'
        '429':
          description: Subscription request or delivery allowance reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  $ref: '#/components/examples/requestLimit'
components:
  schemas:
    CompanySearch:
      type: object
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 500
        filters:
          $ref: '#/components/schemas/CompanyFilters'
        limit:
          type: integer
          minimum: 1
          default: 10
          description: >-
            Maximum page size is subscription-owned: builder 25, professional
            50.
        cursor:
          type:
            - string
            - 'null'
          description: >-
            Opaque cursor. Keep query, filters and limit unchanged; use a new
            request key for each page.
        background:
          type: boolean
          default: false
          description: >-
            Queue the same company operation through Active Job; poll `GET
            /api/usages/{id}`. This option does not change idempotent request
            identity.
      required:
        - query
      additionalProperties: false
    CompanyResult:
      type: object
      properties:
        usage:
          $ref: '#/components/schemas/Operation'
        request_allowance:
          $ref: '#/components/schemas/Allowance'
        coverage_status:
          const: partial
          type: string
        retrieval:
          type: string
          enum:
            - lexical
            - hybrid
        as_of:
          type: string
          format: date-time
        next_cursor:
          type:
            - string
            - 'null'
        withheld_units:
          type: integer
          minimum: 0
        delivery_unit:
          type: string
          enum:
            - company
            - observation
        companies:
          type: array
          items:
            $ref: '#/components/schemas/CompanyMatch'
        ranking:
          type: string
          const: query_relevance_baseline
        candidate_limit:
          type: integer
          const: 100
        coverage:
          type: object
          properties:
            requested_companies:
              type: integer
              minimum: 0
            returned_companies:
              type: integer
              minimum: 0
            stop_reason:
              type: string
            limitations:
              type: array
              items:
                type: string
          required:
            - requested_companies
            - returned_companies
            - stop_reason
            - limitations
          additionalProperties: false
      required:
        - usage
        - request_allowance
        - coverage_status
        - retrieval
        - as_of
        - next_cursor
        - withheld_units
        - delivery_unit
        - companies
        - ranking
        - candidate_limit
        - coverage
      additionalProperties: false
    Pending:
      type: object
      examples:
        - usage:
            id: 789
            status: pending
            request_key: first-company-search
            request_units: 0
            delivered_units: 0
            fresh_evidence_units: 0
          request_allowance:
            window_seconds: 18000
            window_remaining: 99
            weekly_remaining: 499
      properties:
        usage:
          $ref: '#/components/schemas/Operation'
        request_allowance:
          $ref: '#/components/schemas/Allowance'
      required:
        - usage
        - request_allowance
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            retry_at:
              type: string
              format: date-time
              description: >-
                Advisory retry time for the reached capacity limit, based on
                usage at rejection. Other requests or completing reservations
                may change availability.
            retry_after_seconds:
              type: integer
              minimum: 0
              description: >-
                Seconds from rejection to retry_at. For stored failed
                operations, prefer the absolute retry_at timestamp.
          required:
            - code
            - message
          additionalProperties: false
        usage:
          $ref: '#/components/schemas/Operation'
        request_allowance:
          $ref: '#/components/schemas/Allowance'
      required:
        - error
      additionalProperties: false
    CompanyFilters:
      type: object
      properties:
        countries:
          type: array
          items:
            type: string
            enum:
              - CA
              - US
        kinds:
          type: array
          items:
            type: string
            enum:
              - procurement_request
              - facility_expansion
        demand_classes:
          type: array
          items:
            type: string
            enum:
              - explicit_request
              - proxy
              - structural
        occurred_after:
          type: string
          format: date-time
        observed_after:
          type: string
          format: date-time
        company_ids:
          type: array
          items:
            type: integer
            minimum: 1
          maxItems: 100
        exclude_company_ids:
          type: array
          items:
            type: integer
            minimum: 1
          maxItems: 100
        domains:
          type: array
          items:
            type: string
          maxItems: 100
        exclude_domains:
          type: array
          items:
            type: string
          maxItems: 100
      required: []
      additionalProperties: false
      description: >-
        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.
    Operation:
      type: object
      properties:
        id:
          type: integer
          minimum: 1
        status:
          type: string
          enum:
            - pending
            - processing
            - delivered
            - failed
        request_key:
          type: string
        request_units:
          type: integer
          minimum: 0
        delivered_units:
          type: integer
          minimum: 0
        fresh_evidence_units:
          type: integer
          minimum: 0
      required:
        - id
        - status
        - request_key
        - request_units
        - delivered_units
        - fresh_evidence_units
      additionalProperties: false
    Allowance:
      type: object
      properties:
        window_seconds:
          type: integer
          minimum: 0
        window_remaining:
          type: integer
          minimum: 0
        weekly_remaining:
          type: integer
          minimum: 0
      required:
        - window_seconds
        - window_remaining
        - weekly_remaining
      additionalProperties: false
    CompanyMatch:
      type: object
      properties:
        id:
          type: integer
          minimum: 1
        name:
          type: string
        limitations:
          type: array
          items:
            type: string
        demand_class:
          type: string
          enum:
            - explicit_request
            - proxy
            - structural
        why_it_may_matter:
          type: string
        match:
          type: object
          properties:
            query:
              type: string
            observation_ids:
              type: array
              items:
                type: integer
                minimum: 1
          required:
            - query
            - observation_ids
          additionalProperties: false
        observations:
          type: array
          items:
            $ref: '#/components/schemas/SupportingObservation'
          maxItems: 3
      required:
        - id
        - name
        - limitations
        - demand_class
        - why_it_may_matter
        - match
        - observations
      additionalProperties: false
    SupportingObservation:
      type: object
      description: >-
        One activity and its supporting sources. The example is fictional, not a
        live company result.
      examples:
        - 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'
      properties:
        id:
          type: integer
          minimum: 1
        kind:
          type: string
          enum:
            - procurement_request
            - facility_expansion
        observed_fact:
          type: string
        why_it_may_matter:
          type: string
        demand_class:
          type: string
          enum:
            - explicit_request
            - proxy
            - structural
        country:
          type: string
          enum:
            - CA
            - US
        confidence:
          type: number
          minimum: 0
          maximum: 1
        occurred_at:
          type: string
          format: date-time
        observed_at:
          type: string
          format: date-time
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
        evidence:
          type: array
          items:
            $ref: '#/components/schemas/Evidence'
      required:
        - id
        - kind
        - observed_fact
        - why_it_may_matter
        - demand_class
        - country
        - confidence
        - occurred_at
        - observed_at
        - expires_at
        - evidence
      additionalProperties: false
    Evidence:
      type: object
      properties:
        source_uri:
          type: string
        excerpt:
          type: string
        occurred_at:
          type: string
          format: date-time
        observed_at:
          type: string
          format: date-time
      required:
        - source_uri
        - excerpt
        - occurred_at
        - observed_at
      additionalProperties: false
  examples:
    searchCompanies200:
      summary: Illustrative result (fictional test data)
      value:
        as_of: '2026-09-25T02:47:07.454303Z'
        ranking: query_relevance_baseline
        coverage:
          limitations:
            - limited_source_coverage
            - relevance_not_validated
          stop_reason: sources_exhausted
          returned_companies: 2
          requested_companies: 10
        retrieval: lexical
        next_cursor: null
        delivery_unit: company
        candidate_limit: 100
        coverage_status: partial
        usage:
          id: 981239949
          status: delivered
          request_key: company
          request_units: 1
          delivered_units: 2
          fresh_evidence_units: 0
        request_allowance:
          window_seconds: 10800
          window_remaining: 198
          weekly_remaining: 998
        companies:
          - id: 23
            name: Sequoia Freight
            limitations: []
            demand_class: explicit_request
            why_it_may_matter: >-
              Evidence relevant to "charging": "Issued a request for fleet
              charging equipment at a new depot.". This is classified as
              explicit_request; verify fit before acting.
            match:
              query: charging
              observation_ids:
                - 23
            observations:
              - id: 23
                kind: procurement_request
                observed_fact: Issued a request for fleet charging equipment at a new depot.
                why_it_may_matter: >-
                  This observed company activity may be relevant to the search
                  objective; verify fit against the evidence.
                demand_class: explicit_request
                country: US
                confidence: 1
                occurred_at: '2026-09-18T00:00:00Z'
                observed_at: '2026-09-25T02:47:06Z'
                expires_at: null
                evidence:
                  - source_uri: https://sequoia.example.test/tenders/fleet-charging
                    excerpt: >-
                      Issued a request for fleet charging equipment at a new
                      depot.
                    occurred_at: '2026-09-18T00:00:00Z'
                    observed_at: '2026-09-25T02:47:06Z'
          - id: 22
            name: Northstar Transit
            limitations: []
            demand_class: explicit_request
            why_it_may_matter: >-
              Evidence relevant to "charging": "Issued a request for depot
              charging equipment.". This is classified as explicit_request;
              verify fit before acting.
            match:
              query: charging
              observation_ids:
                - 22
            observations:
              - id: 22
                kind: procurement_request
                observed_fact: Issued a request for depot charging equipment.
                why_it_may_matter: >-
                  This observed company activity may be relevant to the search
                  objective; verify fit against the evidence.
                demand_class: explicit_request
                country: CA
                confidence: 1
                occurred_at: '2026-09-04T00:00:00Z'
                observed_at: '2026-09-25T02:47:06Z'
                expires_at: null
                evidence:
                  - source_uri: https://northstar.example.test/tenders/depot-charging
                    excerpt: Issued a request for depot charging equipment.
                    occurred_at: '2026-09-04T00:00:00Z'
                    observed_at: '2026-09-25T02:47:06Z'
        withheld_units: 0
    emptyCompanies:
      summary: No deliverable matches; coverage is still partial
      value:
        as_of: '2026-09-25T02:47:07.454303Z'
        ranking: query_relevance_baseline
        coverage:
          limitations:
            - limited_source_coverage
            - relevance_not_validated
          stop_reason: sources_exhausted
          returned_companies: 0
          requested_companies: 10
        retrieval: lexical
        next_cursor: null
        delivery_unit: company
        candidate_limit: 100
        coverage_status: partial
        usage:
          id: 981239949
          status: delivered
          request_key: company
          request_units: 1
          delivered_units: 0
          fresh_evidence_units: 0
        request_allowance:
          window_seconds: 10800
          window_remaining: 198
          weekly_remaining: 998
        companies: []
        withheld_units: 0
    searchCompanies202:
      summary: Accepted; poll usage.id
      value:
        usage:
          id: 981239949
          status: pending
          request_key: company
          request_units: 0
          delivered_units: 0
          fresh_evidence_units: 0
        request_allowance:
          window_seconds: 10800
          window_remaining: 198
          weekly_remaining: 998
    invalidCredential:
      summary: invalid_api_key
      value:
        error:
          code: invalid_api_key
          message: Provide a valid API credential.
    subscriptionRequired:
      summary: subscription_required
      value:
        error:
          code: subscription_required
          message: An active or trialing subscription is required.
    invalidSearch:
      summary: invalid_search
      value:
        error:
          code: invalid_search
          message: background must be a boolean
    requestLimit:
      summary: Request allowance reached (illustrative retry time)
      value:
        error:
          code: request_limit_reached
          message: The subscription request limit has been reached.
          retry_at: '2026-09-25T05:00:00Z'
          retry_after_seconds: 60
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````