---
title: "Find businesses and their source evidence"
method: POST
path: "/api/v1/search"
---

# Find businesses and their source evidence

`POST /api/v1/search`

## Request

- Base URL: `https://crawdar.com`
- URL: `https://crawdar.com/api/v1/search`
- Auth: one of:
  - none
  - API key in header `x-api-key`

## Request body

- SearchRequest
  - `target` string, required
  - `geography` string, required
  - `limit` integer: Maximum number of results retained and returned.
  - `qualifier` string: Optional public-evidence requirements. Missing evidence remains unverified.
  - `fields` string[]

## Response `200`

Completed search

- SearchResponse
  - `schemaVersion` string, required
  - `requestId` string, required
  - `resultCount` integer, required
  - `durationMs` integer
  - `remainingFreeSearches` integer
  - `searchedSources` string[], required
  - `warnings` string[], required
  - `diagnostics` Diagnostics, required
    - `discoveredCandidates` integer, required
    - `inspectedCandidates` integer, required
    - `acceptedResults` integer, required
    - `verifiedResults` integer, required
    - `likelyResults` integer, required
    - `rejectedCandidates` object[], required
      - `name` string, required
      - `url` string, required
      - `reason` string, required
    - `sourceStatus` object[], required
      - `source` string, required
      - `status` 'complete' | 'partial' | 'failed', required
      - `detail` string, required
    - `providerRequests` object
      - `attempted` integer, required
      - `succeeded` integer, required
      - `failed` integer, required
      - `denied` integer, required
  - `results` Result[], required
    - `name` string, required
    - `website` string
    - `websiteUrl` string
    - `city` string
    - `email` string
    - `phone` string
    - `prospectStatus` 'qualified' | 'possible', required: Qualified means all retained criteria are confirmed. Possible means one or more criteria remain unknown.
    - `whyMatch` string[], required
    - `criteria` ProspectCriterion[], required
      - `criterion` string, required
      - `status` 'confirmed' | 'unknown' | 'contradicted', required
      - `evidence` string, required
      - `sourceUrl` string, required
    - `contactRoute` ContactRoute, required
      - `status` 'confirmed' | 'route_available' | 'not_found', required
      - `type` 'public_role_email' | 'public_phone' | 'website' | 'none', required
      - `value` string, required
      - `sourceUrl` string, required
      - `confidence` integer, required
      - `reason` string, required
    - `fitStatus` 'verified' | 'likely', required: Verified means every requested qualification check passed. Likely means at least one check is open or unverified.
    - `confidence` integer
    - `entityConfidence` integer, required
    - `qualificationConfidence` integer, required
    - `evidenceQuality` 'strong' | 'moderate' | 'weak'
    - `evidence` Evidence[], required
      - `label` string, required
      - `url` string, uri, required
      - `kind` string, required
    - `qualificationChecks` QualificationCheck[], required
      - `requirement` string, required
      - `status` 'passed' | 'failed' | 'unverified', required
      - `excerpt` string, required
      - `sourceUrl` string, required

## Other responses

- `400`: Invalid search brief
- `429`: Free usage or provider capacity reached
- `502`: A public web source did not respond

---

[API](https://skmtc.dev/crawdar/apis/crawdar-public-api.md) · [All operations](https://skmtc.dev/crawdar/apis/crawdar-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawdar/apis/crawdar-public-api/revisions/355bc1f722ee?raw)