Prospect discovery

Prospect discovery finds companies or people matching a natural-language description and creates a prospect list that can be queried and paginated over time. The system interprets the criteria and begins searching automatically; no manual approval of intermediate criteria is required.

Current API paths and response fields use websets / webset for this list. Creating a webset starts one prospect-discovery run, and every later webset_id refers to that list.

Create a prospect list

POST/api/v2/websets

Idempotency-Key is optional. If the caller automatically retries after network timeouts, send one and reuse the same value on each retry.

cURL
curl -X POST "https://revor.ai/api/v2/websets" \
  -H "Authorization: Bearer sk-revor-REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Excavator manufacturers, dealers, and rental companies in North America",
    "title": "North American excavator companies",
    "count": 25,
    "target_kind": "company",
    "locale": "en"
  }'

Field	Type	Required	Constraints
`query`	string	Yes	1-2000 characters describing the target companies in natural language.
`title`	string	No	Up to 200 characters.
`count`	integer	No	`25`, `100`, `500`, or `1000`; default `25`. Available values depend on membership tier.
`target_kind`	string	No	`company` or `person`; default `company`.
`locale`	string	No	`zh` or `en`; default `en`.

The response is HTTP 202:

JSON
{
  "ok": true,
  "request_id": "req_xxx",
  "webset": {
    "id": "webset-uuid",
    "status": "generating_criteria",
    "count": 25,
    "target_kind": "company"
  },
  "preparation_job": {
    "id": "job-uuid",
    "status": "queued"
  }
}

Save webset.id and use it to query the list. preparation_job only reports whether the list started successfully; it does not mean prospect discovery is complete.

Count permissions match the web app: Free 25, Starter up to 100, Scale up to 500, and Pro / Enterprise up to 1000. The service does not silently reduce an out-of-tier request; it returns 403 webset_count_not_available_for_tier.

List prospect lists

GET/api/v2/websets

Query	Default	Constraints	Description
`limit`	`20`	1-100	Items per page.
`cursor`	None	opaque string	Use the previous `next_cursor`; do not parse or modify it.
`target_kind`	None	`company` / `person`	Optional filter.

cURL
curl "https://revor.ai/api/v2/websets?limit=20" \
  -H "Authorization: Bearer sk-revor-REPLACE_ME"

Each list item includes id, name, query, target_kind, status, progress, and timestamps. When has_more=true, pass next_cursor as cursor in the next request.

Get list progress

GET/api/v2/websets/{webset_id}

cURL
curl "https://revor.ai/api/v2/websets/WEBSET_ID" \
  -H "Authorization: Bearer sk-revor-REPLACE_ME"

Common statuses:

Status	Description
`generating_criteria`	Interpreting the target-company criteria.
`ready` / `queued`	Ready and waiting to search.
`searching`	Finding candidate companies.
`verifying`	Verifying whether candidates match the criteria.
`completed`	Complete; final results can be paginated.
`failed`	Failed; read `failure.code`.
`cancelled`	Cancelled.

progress reports the target count, verified count, qualified count, update time, and related progress. Counts may continue changing while the list is active.

Page through companies or people

GET/api/v2/websets/{webset_id}/items

Verified results can be read while generation is still running. Such items have provisional=true, meaning they may still change. Wait for completed when you need a stable final list.

For agent platforms, start with 10 compact results per request:

cURL
curl "https://revor.ai/api/v2/websets/WEBSET_ID/items?match=qualified&detail=compact&limit=10" \
  -H "Authorization: Bearer sk-revor-REPLACE_ME"

Query	Default	Description
`limit`	`10`	Items per page; maximum depends on `detail`.
`cursor`	None	Cursor returned by the previous page.
`match`	`qualified`	Result-filter preset; see below.
`detail`	`compact`	`compact`, `standard`, or `full`.

Result filters

match accepts individual match statuses and common result sets:

Value	Results returned
`qualified`	`full` and `partial`; suitable for usable prospects.
`full`	Only fully matched results.
`partial`	Only partially matched results.
`rejected`	Only results that do not match.
`verified`	Every verified result: `full`, `partial`, and `rejected`.

An individual result's match.status is only full, partial, or rejected. qualified and verified are query sets, not item statuses.

Detail levels

Mode	Page limit	Content
`compact`	50	Company name, website, industry, match status, and score; best for continuous pagination.
`standard`	25	Adds public company details and the decision for each criterion.
`full`	10	Adds per-criterion reasoning and source links; recommended only for a small number of results.

JSON
{
  "ok": true,
  "request_id": "req_xxx",
  "items": [
    {
      "id": "item-uuid",
      "target_kind": "company",
      "entity": {
        "name": "Example Equipment",
        "website": "https://example.com",
        "industry": "Construction Equipment"
      },
      "match": { "status": "full", "score": 91 },
      "provisional": false
    }
  ],
  "detail": "compact",
  "next_cursor": null,
  "has_more": false,
  "webset_status": "completed"
}

To retrieve the complete final list, continue paging until has_more=false.