# Enrich a company by domain with Pubrio's company enrichment API

Pubrio's Company Enrichment API returns one company's record together with its recent job postings, news, advertisements and similar companies in a single call. Each enrichment is 3 credits ($0.03 pay as you go), against 1 credit ($0.01) for the record alone from Company Lookup. Send `POST https://agents.pubrio.com/zcj/p03y4ozir8ao/companies/lookup/enrich` with a `domain`, `linkedin_url` or `domain_search_id`, then pay the 402 price quote over x402 or MPP and retry.

## At a glance

- **Endpoint:** `POST https://agents.pubrio.com/zcj/p03y4ozir8ao/companies/lookup/enrich`, one company per request
- **Body:** at least one of `domain`, `linkedin_url` (a `linkedin.com/company/` URL) or `domain_search_id` (Pubrio's company id)
- **Price:** 3 credits per call: $0.03 pay as you go, $0.027 on Scale
- **Payment:** a 402, which is the price quote you pay and then retry, settled over x402 (Base USDC) or MPP (Tempo USDC). No account or API key.
- **Response:** `data` (the company record), `jobs`, `news`, `advertisements`, `similar_companies`, `metadata`
- **Timing:** a company enriched from scratch can take tens of seconds. Set the client timeout to at least 90 seconds.
- **Record only:** `POST https://agents.pubrio.com/zcj/p03y4ozir8ao/companies/lookup`, 1 credit
- **Full purchase flow:** [the buyer skill](https://agents.pubrio.com/zcj/p03y4ozir8ao/SKILL.md)

## Choose lookup or enrichment

Both calls accept `domain`, `linkedin_url` or `domain_search_id`, and both return the company record in `data`. Enrichment adds the signal lists.

| Need | Call | Credits | Price |
| --- | --- | --- | --- |
| The record alone: firmographics, addresses, social links, ids | `POST /companies/lookup` | 1 | $0.01 |
| The record plus hiring, news, ads and lookalikes | `POST /companies/lookup/enrich` | 3 | $0.03 |
| Record first, then signals for companies that qualify | Lookup, then enrichment | 4 | $0.04 |
| Signals for 100 companies | 100 enrichments | 300 | $3 |

A lookup returns a JSON object with `metadata` and `data`. Trimmed to part of `data`, the lookup of `stripe.com` returns:

```json
{
  "data": {"company_name": "Stripe", "domain": "stripe.com", "country_code": "US", "industry": "Technology, Information And Internet", "founded_year": 2010, "company_size": 11300, "company_size_printed": "11,300+", "company_type": "Privately Held", "estimated_revenue": 14400000000, "linkedin_name": "stripe"}
}
```

The full record also carries `emails`, `phones` and a `contacts` list typed by contact kind (such as `email-generic` and `phone`). The example lookup paid $0.01 and returned in 5.2 seconds.

## Enrich one company

1. Send the request with a client timeout of at least 90 seconds. A 30-second default, common in HTTP clients, cuts off a cold call before it finishes:

   ```bash
   curl -s -X POST https://agents.pubrio.com/zcj/p03y4ozir8ao/companies/lookup/enrich \
     -H 'Content-Type: application/json' \
     -d '{"domain": "stripe.com"}' \
     --max-time 120
   ```

   The storefront answers `402` with `payment.amountUsd`, the `plan` and a `protocols` block. The signable challenges also arrive in the `payment-required` (x402) and `www-authenticate` (MPP) headers. Nothing is charged yet.

2. Pay with an x402 or MPP client. The client signs the challenge and retries the identical request with the proof attached. The example enrichment of `stripe.com` paid $0.03 and returned in 4.8 seconds. A company Pubrio has to enrich from scratch takes far longer, and the API reference gives 45 seconds for one such cold call.

3. Read the response. It has this shape:

   ```json
   {
     "data": {"company_name": "<name>", "domain": "<domain>", "domain_search_id": "<domain_search_id>"},
     "jobs": [{"title": "<title>", "posting_date": "<date>", "job_search_id": "<id>"}],
     "news": [{"title": "<headline>", "published_at": "<time>", "news_search_id": "<id>"}],
     "advertisements": [{"title": "<ad text>", "advertisement_format": "<format>", "publisher_platforms": ["<platform>"], "started_at": "<date>"}],
     "similar_companies": [{"company_name": "<name>", "similarity_score": "<score>"}],
     "metadata": {"filters": {}, "parameters": "<parameters>"}
   }
   ```

   The example enrichment of `stripe.com` returned five job postings, five news items, five advertisements and a longer list of similar companies.

4. Keep `data.domain_search_id`. Later calls for the same company accept it in place of the domain.

## What the enrichment response contains

| Field | Contents |
| --- | --- |
| `data` | The same company record a lookup returns |
| `jobs` | Recent job postings: `title`, `location`, `country`, `country_code`, `posting_date`, `job_url`, `job_search_id` |
| `news` | Recent news mentions: `title`, `summary`, `source`, `url`, `published_at`, `category`, `companies` (every company the article names), `news_search_id` |
| `advertisements` | Recent ads: `title`, `advertiser`, `advertisement_format`, `publisher_platforms`, `target_country_codes`, `started_at`, `ended_at`, `total_impressions` with its lower and upper bounds, `advertisement_url`, `destination_url`, `advertisement_id` |
| `similar_companies` | Company records shaped like `data`, each with a `similarity_score`. Empty when no close match is found. |
| `metadata` | Echoed `filters` and `parameters`, plus a `profile` credit block when credit accounting is requested |

## Go deeper on one signal

The enrichment request takes only `domain`, `linkedin_url` or `domain_search_id`, and its lists hold recent items. For one signal in depth, call its own operation:

| Signal | Operation | Credits |
| --- | --- | --- |
| Weekly series of one signal over a date window | [Company Insights](https://agents.pubrio.com/zcj/p03y4ozir8ao/services/insights): `POST /companies/jobs/insights`, `/companies/news/insights`, `/companies/advertisements/insights` or `/companies/cloud_footprints/insights` | 3 |
| Job postings | [Search](https://agents.pubrio.com/zcj/p03y4ozir8ao/services/search): `POST /companies/jobs/search` | 3 |
| News | [Search](https://agents.pubrio.com/zcj/p03y4ozir8ao/services/search): `POST /companies/news/search` | 3 |
| Ads | [Search](https://agents.pubrio.com/zcj/p03y4ozir8ao/services/search): `POST /companies/advertisements/search` | 3 |

Searches return 25 results per page.

## Limits

- One company per request. There is no batch call; 100 companies are 100 requests.
- A 402 you have not paid charges nothing, so it is safe to stop there.
- Card pays per call only at $0.55 or more. Below that, pay per call on a wallet rail, or buy prepaid credit (Starter, minimum $50) and draw it down.
- A timeout after you have paid is an uncertain result. Reconcile it before retrying, and do not pay twice.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `402` with a `payment` block | The price quote | Pay and retry the same request, or stop |
| `400` | Malformed request or invalid parameter, with `code`, `message` and `details` | Send at least one valid identifier; `linkedin_url` must start with `http` and contain `linkedin.com/company/` |
| `429` | Rate limit exceeded | Wait for the window to reset, then retry |
| `settlement_failed` | The payment did not settle; `settlementReason` says why | Fix the wallet and start again for a fresh 402 |
| Client timeout | A cold enrichment outlasted the client's timeout | Raise the timeout to at least 90 seconds; reconcile any paid call first |

## Frequently asked questions

### What is the difference between company lookup and company enrichment in Pubrio?

A lookup returns the stored company record for 1 credit. Enrichment returns the same record plus recent job postings, news, advertisements and similar companies for 3 credits. Use lookup when the record is enough and enrichment when hiring, news or ad activity matters to the decision.

### Why can a company enrichment call take tens of seconds?

When a company has to be enriched from scratch, Pubrio builds the record in real time, which can take tens of seconds and up to a minute. A company that is already enriched returns quickly. Set the HTTP client timeout to at least 90 seconds.

### Can I enrich a company by its LinkedIn URL?

Yes. Send `linkedin_url` with the full company page URL, or `domain_search_id` from an earlier lookup or search, in place of `domain`.

### Does company enrichment return verified contact emails?

The record includes the company's `emails`, `phones` and `contacts` lists. Verified work emails, personal emails and phone numbers for a person come from the Contacts service: each email returned costs 5 credits, each phone returned costs 10, and a reveal that finds nothing costs nothing.

### How much does company enrichment cost?

3 credits per call: $0.03 pay as you go, or $0.027 on Scale. The free trial grants $1 of credit once per human, to a credential claimed with a verified email.

## Keep reading

- [The buyer skill](https://agents.pubrio.com/zcj/p03y4ozir8ao/SKILL.md): the full purchase flow
- [How to pay](https://agents.pubrio.com/zcj/p03y4ozir8ao/payment.md): rails, credit plans and top-ups
- [Error reference](https://agents.pubrio.com/zcj/p03y4ozir8ao/errors.md): every storefront error code
- [Company Enrichment API reference](https://agents.pubrio.com/zcj/p03y4ozir8ao/services/enrichment/openapi.json): request and response schema

---

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