# Find companies by industry, size or similarity with PredictLeads

PredictLeads' API builds a target company list in two ways. A discovery search filters by location, size, industry, NAICS code and revenue, and a similar-companies lookup starts from one domain you already know. Discovery costs $0.04 per record ($0.08 per record for extended records), similar companies cost $0.04 per record, and the `limit` you send caps both the page size and the charge, since you pay for the records returned. Send a plain GET, pay the 402 price quote over x402 or MPP, and retry the same request, with no account or API key.

## At a glance

- **Search endpoint:** `GET https://agents.predictleads.com/zcj/nbiiy9f6jgjv/api/v3/discover/companies`, or `GET https://agents.predictleads.com/zcj/nbiiy9f6jgjv/api/v3/discover/extended_companies` for extended records
- **Lookalike endpoint:** `GET https://agents.predictleads.com/zcj/nbiiy9f6jgjv/api/v3/companies/{domain}/similar_companies`
- **Search filters:** `location`, `sizes`, `naics_codes`, `industry`, `revenue_range_low`, `revenue_range_high`, plus `page` and `limit`
- **Price:** discovery $0.04 per record, extended discovery $0.08 per record, similar companies $0.04 per record
- **Limit:** discovery `limit` defaults to 30, maximum 1000. Similar companies `limit` defaults to 20, maximum 50.
- **Payment:** a 402 price quote, paid over x402 or MPP and retried (a card pays only a call of $0.50 or more). Nothing is charged until you pay.
- **Response:** JSON with `data` (one object per company or match), `included` and `meta`
- **Full purchase flow:** [the buyer skill](https://agents.predictleads.com/zcj/nbiiy9f6jgjv/SKILL.md)

## Choose the endpoint

| You want | Endpoint | Price | `limit` default / max |
| --- | --- | --- | --- |
| Companies matching filters, with a basic profile | `/api/v3/discover/companies` | $0.04 per record | 30 / 1000 |
| The same search, with `employees_min`, `employees_max` and `revenue_range` fields | `/api/v3/discover/extended_companies` | $0.08 per record | 30 / 1000 |
| Companies like one you already know | `/api/v3/companies/{domain}/similar_companies` | $0.04 per record | 20 / 50 |

Base discovery records carry `domain`, `company_name`, `friendly_company_name`, `ticker`, `meta_title`, `meta_description`, `description`, `description_short`, `language`, `location` and `location_data`. Extended records add `employees_min`, `employees_max`, `revenue_range`, `revenue_range_data`, `naics6_codes`, `social_industry`, `social_company_type`, `social_founded` and other social profile fields. Both discovery endpoints take the same filters.

## Search companies by location, size and industry

1. Build the query. `sizes` takes one or more of `1`, `2-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000` and `10001+`, comma-separated. `location` takes a country name, or a state name or abbreviation. `industry` takes one value from the list in the [Companies API reference](https://agents.predictleads.com/zcj/nbiiy9f6jgjv/services/companies/openapi.json), such as `Software Development`. `naics_codes` takes comma-separated codes. `revenue_range_low` and `revenue_range_high` take whole numbers.

2. Send the request without payment to read the quote:

   ```bash
   curl -i "https://agents.predictleads.com/zcj/nbiiy9f6jgjv/api/v3/discover/companies?location=United%20States&sizes=51-200&limit=3"
   ```

   The storefront answers `402 Payment Required` with the price quote. Stopping here costs nothing.

3. Pay the quote and resend the same request with the proof attached; [the buyer skill](https://agents.predictleads.com/zcj/nbiiy9f6jgjv/SKILL.md) has the steps. The response is a `200` with one company object per record in `data`:

   ```json
   {
     "id": "<id>",
     "type": "company",
     "attributes": {
       "domain": "<domain>",
       "company_name": "<company_name>",
       "friendly_company_name": "<friendly_company_name>",
       "ticker": null,
       "meta_title": "<meta_title>",
       "description": null,
       "description_short": null,
       "language": "<language>",
       "location": "<location>",
       "location_data": [
         {"city": null, "state": "<state>", "country": "<country>", "continent": "<continent>", "category": "headquarters"}
       ]
     }
   }
   ```

4. Read each company from `data[].attributes`. `location_data` gives the structured address, with `category` marking a `headquarters`, `office` or other site. `description` and `description_short` can be `null`.

## Find companies similar to one you know

1. Put the known company's domain in the path and send the request:

   ```bash
   curl -i "https://agents.predictleads.com/zcj/nbiiy9f6jgjv/api/v3/companies/stripe.com/similar_companies?limit=3"
   ```

   The storefront answers with a 402. Pay it and retry the same request. This example paid $0.12 for three matches.

2. Read the matches. The response holds one `company_similarity` object per match:

   ```json
   {
     "data": [
       {
         "type": "company_similarity",
         "attributes": {
           "score": 0.9989,
           "position": 1,
           "reason": "Both provide comprehensive payment gateway and merchant services for online busi…",
           "refreshed_at": "2026-09-16T11:54:41Z"
         },
         "relationships": {
           "company": {"data": {"id": "<id>", "type": "company"}},
           "similar_company": {"data": {"id": "<id>", "type": "company"}}
         }
       }
     ],
     "included": [
       {"id": "<id>", "type": "company", "attributes": {"domain": "stripe.com", "company_name": "Stripe, Inc.", "ticker": null}}
     ]
   }
   ```

   `score` is the similarity score and `position` the match's rank. Match `relationships.similar_company.data.id` to an entry in `included` to get the `domain`, `company_name` and `ticker`. `included` holds the queried company as well as each match. `meta.message` can suggest a related query, such as the same lookup on a subsidiary's domain.

## Page through results

Each page is a separate paid call, and its `limit` caps its charge. To go past the first page, keep the filters and `limit` unchanged and raise `page` from 1. Sending `page` also adds `meta.count`, the total number of results, which is an estimate on discovery. Without `page`, `meta.count` is omitted.

| List | Cost |
| --- | --- |
| 100 companies from discovery | $4 |
| 100 extended company records | $8 |
| 50 lookalikes for each of 10 known companies | $20 |

## Limits

- Discovery filters are location, size, NAICS code, industry and revenue. The endpoints take only these filters, with `page` and `limit`. Results come ordered by last updated date.
- `industry` takes one value per request.
- Base discovery records carry no employee count or revenue. Extended records do.
- Similar companies give a `reason` for the top 20 matches. For the rest, `reason` can be `null`.
- A card pays a single call only at $0.50 or more. Smaller calls settle over x402 or MPP, or draw on prepaid Credits (from $0.50); [the buyer skill](https://agents.predictleads.com/zcj/nbiiy9f6jgjv/SKILL.md) covers buying them.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `402` with a `payment` block and no `reason` | The normal per-call price | Pay the challenge and retry, or stop |
| `400` | A parameter is invalid, such as a size outside the list | Fix the value from the API reference |
| `404` | Record not found, such as an unknown domain | Check the domain or company ID |
| `429` | Too many requests | Wait the `Retry-After` seconds, then retry |
| `settlement_failed` | The payment did not settle. `settlementReason` says why. | Fix the wallet and send a fresh request for a new 402 |
| `usage_exhausted` | The Credits balance is used up | Top up with `POST https://agents.predictleads.com/zcj/nbiiy9f6jgjv/extend` and `{"amountUsd": "..."}` |

## Frequently asked questions

### Is there an API to find companies similar to a given company?

Yes. `GET https://agents.predictleads.com/zcj/nbiiy9f6jgjv/api/v3/companies/{domain}/similar_companies` returns up to 50 lookalike companies for a domain, each with a similarity `score`, a `position` and, for the top 20, a `reason`. PredictLeads has Similar Companies data for over 18.5 million companies.

### How much does a company search cost?

Discovery costs $0.04 per record, extended discovery $0.08 per record, and similar companies $0.04 per record. The `limit` you send caps both the page size and the charge, and the 402 states the most a call can cost before you pay.

### How many companies can one search return?

A discovery call returns up to 1000 records, with 30 by default. A similar-companies call returns up to 50, with 20 by default. For longer discovery lists, page with `page`.

### Do I need a PredictLeads account or API key?

No. Each pay-as-you-go call is paid through its own 402, with no registration. Only prepaid Credits need an agent credential, which the storefront issues through [auth.md](https://agents.predictleads.com/zcj/nbiiy9f6jgjv/auth.md).

## Keep reading

- [Buyer skill](https://agents.predictleads.com/zcj/nbiiy9f6jgjv/SKILL.md): the full purchase flow
- [How to pay](https://agents.predictleads.com/zcj/nbiiy9f6jgjv/payment.md): rails, Credits and top-ups
- [Companies API reference](https://agents.predictleads.com/zcj/nbiiy9f6jgjv/services/companies/openapi.json): discovery parameters and the industry list
- [Similar Companies API reference](https://agents.predictleads.com/zcj/nbiiy9f6jgjv/services/similar-companies/openapi.json): match fields
- [Error reference](https://agents.predictleads.com/zcj/nbiiy9f6jgjv/errors.md): every payment and access error

---

Updated 2026-10-28. All PredictLeads guides: https://agents.predictleads.com/guides.md. Storefront: https://agents.predictleads.com/zcj/nbiiy9f6jgjv/llms.txt.