# Find companies similar to one you know with Pubrio's lookalike API

Pubrio's lookalike search takes one company you already know is a good fit and returns the companies most like it. Each row carries a `similarity_score` from 0 to 1, and you can search worldwide or narrow the results to one market. Each call is 3 credits, which is $0.03 pay as you go: send `POST https://agents.pubrio.com/zcj/ka31i2gjggec/companies/search/similar` with exactly one identifier for the reference company, pay the 402 price quote, and retry the request.

## At a glance

- **Endpoint:** `POST https://agents.pubrio.com/zcj/ka31i2gjggec/companies/search/similar`
- **Body:** exactly one reference identifier: `domain`, `domain_search_id` or `linkedin_url`. Optional filters, plus `per_page` (defaults to 25, the ceiling on most plans) and `page`.
- **Price:** 3 credits per call. That is $0.03 pay as you go at $0.01, or $0.027 on Scale.
- **Payment:** a 402 price quote, paid over x402 (Base USDC) or MPP (Tempo USDC) and then retried. No account or API key is needed. Calls can also draw on a prepaid credit plan, bought with an agent credential.
- **Response:** `data`, a list of company records, each with a `similarity_score`. `metadata` echoes the filters as they were applied.
- **Limits:** one reference company per call, and `per_page` up to your plan's ceiling (25 on most plans). Each request is its own call with its own 402.
- **Full purchase flow:** [the buyer skill](https://agents.pubrio.com/zcj/ka31i2gjggec/SKILL.md)

## Find companies similar to a reference company

1. Send the request with one identifier for the reference company:

   ```bash
   curl -s -X POST https://agents.pubrio.com/zcj/ka31i2gjggec/companies/search/similar \
     -H 'Content-Type: application/json' \
     -d '{"domain": "stripe.com", "per_page": 5}'
   ```

   The storefront answers `402 Payment Required` with a price for 3 credits. The body carries `payment.amountUsd` and a challenge for each rail it offers. Nothing is charged until you pay the 402.

2. Pay the 402 with an x402 or MPP client, then send the same request again with the proof attached. [The buyer skill](https://agents.pubrio.com/zcj/ka31i2gjggec/SKILL.md) covers settling the challenge.

3. Read the rows in `data`. This example request paid $0.03 and returned in 4.4 seconds. The excerpt shows the start of its first row:

   ```json
   {
     "metadata": {"parameters": null, "filters": {"domain": "stripe.com", "per_page": 5, "language": "en"}, "profile": null},
     "data": [
       {"company_name": "PayU", "domain": "payu.com", "similarity_score": 0.7099609375, "industry": "Financial Services", "company_type": "Public Company", "country_code": "NL", "company_size": 3400, "founded_year": 2002, "…": "more fields"},
       "… 4 more"
     ]
   }
   ```

Each row is a full company record. The fields include:

- identity: `domain_search_id`, `company_name` and `domain`
- firmographics: `industry`, `company_size`, `founded_year` and `country_code`
- profile and topic fields: `linkedin_url`, `specialties` and `company_keywords`
- classification: `verticals` and `categories`, given as ids
- contact fields: `emails`, `phones` and `contacts`. Entries in `contacts` are typed, such as `email-generic`.

To leave the contact fields out of the response, send `"exclude_fields": ["emails", "phones", "contacts"]`.

`data` is a bare list. Unlike other Pubrio searches, it has no `pagination` object. To get the next page, send the same body with `page` set to 2.

## Narrow the lookalikes to one market

Keep the same reference company and add a filter to narrow the results:

```bash
curl -s -X POST https://agents.pubrio.com/zcj/ka31i2gjggec/companies/search/similar \
  -H 'Content-Type: application/json' \
  -d '{"domain": "stripe.com", "locations": ["SG"], "per_page": 5}'
```

This example request paid $0.03 and returned in 6.7 seconds. The first row it returns is `{"company_name": "SHOPLINE", "domain": "shopline.com", "similarity_score": 0.5323189255050581, "country_code": "SG", "industry": "Software Development", "company_size": 1000, "founded_year": 2013}`.

The other filters work the same way:

| To keep only | Field | Example value |
| --- | --- | --- |
| Companies in given countries | `locations` | `["SG"]` (ISO 3166-1 alpha-2 codes) |
| Companies outside given countries | `exclude_locations` | `["US"]` |
| A city or region | `places` (or `exclude_places`) | `["Tokyo"]` |
| A headcount band | `employees` | `[[1,10],[11,20]]` |
| A revenue range | `revenues` | `[0, 100000]` (minimum, maximum) |
| A topic or specialty | `keywords` | `["fintech"]` |
| A technology in use | `technologies` | `tag_id` integers, or free text such as `["Shopify"]` with `"is_enable_similarity_search": true` |
| A founding window | `founded_dates` | `[2018, 2024]` |

## Use the similarity score

Treat `similarity_score` as a ranking signal:

- **Rank:** sort the rows by score.
- **Cut off:** keep the rows above a threshold you choose.
- **Not a probability:** the score runs from 0 to 1. It does not state the chance that a company is a match.

The request body also accepts a field named `similarity_score`, but it does not filter rows by their score. It sets how strictly free-text filter values match Pubrio's ids when `is_enable_similarity_search` is on. Apply your score cut-off in your own code.

## Find similar people

`POST https://agents.pubrio.com/zcj/ka31i2gjggec/people/search/similar` takes one reference, given by one of these fields:

- `people_search_id`, a single Pubrio person id
- `peoples`, a list of `people_search_id` values
- `linkedin_url`, a single LinkedIn profile URL
- `linkedin_urls`, a list of profile URLs
- `people_titles`, a list of job titles

Each person row carries a `similarity_score` from 0 to 1. The call costs the same 3 credits.

## What is charged, and when

- **Each call is billed on its own.** A call is charged when you pay its 402. An unpaid 402 charges nothing, so you can stop there safely.
- **Each request is its own call.** A request for another page gets its own 402.
- **One reference per call.** A search has exactly one reference company. To find lookalikes for several companies, send one call per company.
- **Paying by card:** a pay-as-you-go card payment needs a call of at least $0.55. A single lookalike call is below that, so pay it on a wallet rail or from prepaid credit.
- **Prepaid credit:** Starter has a minimum of $50 and Scale a minimum of $495. Buy either with `POST /plans/{planId}/purchase`, using the plan id from the [catalog](https://agents.pubrio.com/zcj/ka31i2gjggec/manifest.json).

## Errors

| Status or code | Meaning | Action |
| --- | --- | --- |
| `402` | The price quote. Nothing is charged yet. | Pay it and retry the same request, or stop. |
| `400` | The body is malformed or a parameter is invalid. | Send exactly one reference identifier and check field types. |
| `416`, code `41613` | `per_page` is above your plan's ceiling. | Send a `per_page` within the ceiling, 25 on most plans. |
| `429` | The rate limit is exceeded. | Wait for the window to reset, then retry. |
| `settlement_failed` | The payment did not settle. `settlementReason` says why. | Fix the wallet, then send a fresh request for a new 402. |

## Frequently asked questions

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

Yes. Send `POST https://agents.pubrio.com/zcj/ka31i2gjggec/companies/search/similar` with one identifier for the reference company: `domain`, `domain_search_id` or `linkedin_url`. You get back company records ranked by a `similarity_score` from 0 to 1, paid per call with no account or API key.

### What does the similarity score mean?

It is a number from 0 to 1 that measures how close each company is to your reference. Use it to rank the rows and to drop the ones below a threshold you set. It is not a probability.

### Can lookalike search return only companies in one country?

Yes. Add `locations` with ISO 3166-1 alpha-2 codes, such as `["SG"]`, to the same request. You can also use `exclude_locations`, `places`, `employees`, `revenues`, `keywords` and `technologies` to narrow the results further.

### How much does a lookalike search cost?

Each call is 3 credits: $0.03 pay as you go, or $0.027 on Scale. Each request, including a request for another page, gets its own 402. The 402 states the exact amount before you pay.

### Can I find people similar to a person or a job title?

Yes. `POST https://agents.pubrio.com/zcj/ka31i2gjggec/people/search/similar` takes one reference: `people_search_id`, `peoples`, `linkedin_url`, `linkedin_urls` or `people_titles`. It returns people rows with a `similarity_score`, for the same 3 credits per call.

## Keep reading

- [Buyer skill](https://agents.pubrio.com/zcj/ka31i2gjggec/SKILL.md): the full purchase flow
- [Lookalike Search API reference](https://agents.pubrio.com/zcj/ka31i2gjggec/services/lookalike/openapi.json): every request field and the response schema
- [How to pay](https://agents.pubrio.com/zcj/ka31i2gjggec/payment.md): rails, credit plans and top-ups
- [Error reference](https://agents.pubrio.com/zcj/ka31i2gjggec/errors.md): every storefront error code
- [Identity](https://agents.pubrio.com/zcj/ka31i2gjggec/auth.md): the agent credential needed for plans and the free trial

---

Updated 2026-11-04. All Pubrio guides: https://agents.pubrio.com/guides.md. Storefront: https://agents.pubrio.com/zcj/ka31i2gjggec/llms.txt.