> ## 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). ## 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. 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). 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' '202': description: Pending or processing; poll the returned usage ID. content: application/json: schema: $ref: '#/components/schemas/Pending' '401': description: Missing or revoked API credential. content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: An active or trialing subscription is required. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- Invalid request, conflicting retry, expired operation or processing failure. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Subscription request or delivery allowance reached. content: application/json: schema: $ref: '#/components/schemas/Error' 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 securitySchemes: bearerAuth: type: http scheme: bearer ````