# Enrich a contact from email, phone or LinkedIn with Bytemine's API

Bytemine's contact enrichment API turns one identifier you already hold into a full person profile: an email, a phone number, a LinkedIn URL, or a name plus company. Each match costs $0.01, and a lookup that finds no one is not billed. Send `POST https://agents.bytemine.ai/zcj/7nmedhnx1syl/functions/v1/api-gateway/contacts/enrich` for one contact or `POST https://agents.bytemine.ai/zcj/7nmedhnx1syl/functions/v1/api-gateway/bulk-contact-enrich` for up to 100, then pay the 402 price quote and retry.

## At a glance

- **Endpoints:** `POST https://agents.bytemine.ai/zcj/7nmedhnx1syl/functions/v1/api-gateway/contacts/enrich` for one contact, `POST https://agents.bytemine.ai/zcj/7nmedhnx1syl/functions/v1/api-gateway/bulk-contact-enrich` for up to 100
- **Body:** one identifier (`email`, `phone`, `linkedin`, or `firstName` and `lastName` with `companyDomain`), plus optional `has*` filters such as `hasWorkEmail`
- **Price:** $0.01. A lookup with no match is not billed.
- **Payment:** each request answers with a 402 price quote, paid from a wallet over x402 or MPP, or drawn from prepaid Credits. No account or API key is needed.
- **Response:** `data` with name, title, seniority, department, work and personal email, company fields, work history and education. Bulk adds a `status` per contact and totals.
- **Limits:** one contact per single request. Up to 100 contacts per bulk request, answered in the same response.
- **Full purchase flow:** [the buyer skill](https://agents.bytemine.ai/zcj/7nmedhnx1syl/SKILL.md)

## Choose the identifier to send

Send whatever the record already has. One identifier is enough.

| You hold | Send |
| --- | --- |
| An email address | `email` |
| A phone number | `phone` |
| A LinkedIn profile URL | `linkedin` |
| A name and a company | `firstName`, `lastName` and `companyDomain`. The single endpoint also takes `companyName`. |
| A Facebook profile URL | `facebook` (single endpoint only) |

## Add match filters

The `has*` fields are boolean match filters. `"hasWorkEmail": true` requests a work email in results, and `"hasPersonalEmail": true` requests a personal email. The other filters are `hasPhone`, `hasPhoneCell`, `hasDirectDial`, `hasLocalAddress` and `hasPrimaryContact`.

On the single endpoint the filters are top-level fields. On the bulk endpoint they go in a `filters` object that applies to every contact, and at least one must be `true` when you send it.

## Enrich one contact

1. Send the request:

   ```bash
   curl -i -X POST https://agents.bytemine.ai/zcj/7nmedhnx1syl/functions/v1/api-gateway/contacts/enrich \
     -H 'Content-Type: application/json' \
     -d '{"email": "alex@example.com", "hasWorkEmail": true, "hasDirectDial": true}'
   ```

   The storefront answers `402 Payment Required`, the price quote.

2. Pay the 402 and resend the same body with the proof attached. [The buyer skill](https://agents.bytemine.ai/zcj/7nmedhnx1syl/SKILL.md) has the steps for each way to pay.

3. Read the profile from `data`:

   ```json
   {
     "data": {
       "pid": "<pid>",
       "full_name": "Alex Example",
       "job_title": "<job title>",
       "seniority": "<seniority>",
       "department": "<department>",
       "work_email": "alex@example.com",
       "personal_email": "<personal email>",
       "company_name": "Example Inc",
       "company_domain": "example.com",
       "company_industry": "<industry>",
       "company_revenue_range": "<range>",
       "company_employee_range": "<range>",
       "linkedin_profile": "linkedin.com/in/alex-example",
       "work_experience": [],
       "education": []
     }
   }
   ```

   `work_experience` and `education` are arrays of objects. Write the fields you need back to the record.

## Enrich contacts in bulk

1. Send up to 100 contacts in `contacts`. Each needs at least one identifier:

   ```bash
   curl -i -X POST https://agents.bytemine.ai/zcj/7nmedhnx1syl/functions/v1/api-gateway/bulk-contact-enrich \
     -H 'Content-Type: application/json' \
     -d '{
       "contacts": [
         {"email": "alex@example.com"},
         {"phone": "+1-202-555-0142"},
         {"linkedin": "https://www.linkedin.com/in/alex-example"},
         {"firstName": "Jordan", "lastName": "Example", "companyDomain": "example.com"}
       ],
       "filters": {"hasWorkEmail": true},
       "fullResponse": true
     }'
   ```

   Set `fullResponse` to `false` to cut each result down to its email and phone fields. The default is `true`, complete profiles. The answer is a 402, paid and retried as in the single call.

2. Read the totals and the per-contact results:

   ```json
   {
     "total": 4,
     "processed": 4,
     "enriched": 2,
     "no_match": 1,
     "skipped": 1,
     "failed": 0,
     "credits_used": "<integer>",
     "results": [
       {"index": 0, "status": "enriched", "data": {}},
       {"index": 1, "status": "no_match"}
     ]
   }
   ```

   `status` is `enriched`, `no_match`, `skipped` or `failed`. Join results back to your records by `index`. Only `enriched` results carry a profile in `data`.

## What a match costs

- Each match costs $0.01. A contact with no match costs nothing. For example, 100 contacts with 60 matches cost $0.60.
- The 402 can quote a ceiling: the most the request could cost. You are charged only for the matches returned.
- Every paid response carries a `zc-billing` header. Its `chargedUsd` field holds the amount charged for that request. A delivered response with no `zc-billing` header billed nothing.
- Card pays a pay-as-you-go call only when it costs $0.50 or more. For smaller calls by card, buy Credits, from $0.50 by card, and let each match draw the balance down. [The buyer skill](https://agents.bytemine.ai/zcj/7nmedhnx1syl/SKILL.md) covers the purchase.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `402` with a `payment` block and no `reason` | The price quote. | Pay and retry the same request, or stop |
| `400 invalid_request` | The body is malformed | Fix the JSON. Give every contact at least one identifier. |
| `settlement_failed` | The payment did not settle. `settlementReason` says why. | Fix the wallet, then resend for a fresh 402 |
| `409 payment_request_mismatch` | A payment was reused for a different body | Request a new 402 for this body and pay that one |
| `401 bearer_required` | Buying Credits needs an agent identity | Register at [auth.md](https://agents.bytemine.ai/zcj/7nmedhnx1syl/auth.md), or pay per call |
| `usage_exhausted` | The Credits balance is used up | Top up with `POST https://agents.bytemine.ai/zcj/7nmedhnx1syl/extend` and `{"amountUsd": "..."}` |

After a paid call reaches Bytemine, its own status codes and error bodies come back unchanged.

## Frequently asked questions

### Does Bytemine charge for a contact it cannot find?

No. Contact enrichment bills only on a match, at $0.01 each. A `no_match` result costs nothing, and a response with no `zc-billing` header billed nothing.

### Is there a reverse email lookup API for B2B contacts?

Yes. Send only `email` to `POST https://agents.bytemine.ai/zcj/7nmedhnx1syl/functions/v1/api-gateway/contacts/enrich`, and a match returns the person's profile with job title, company fields and work history. Add match filters such as `"hasWorkEmail": true`, which requests a work email in results.

### How many contacts can one bulk enrichment request take?

Up to 100 in the `contacts` array, returned in the same response. For a larger list, send one request per batch of 100 and pay each request's own 402.

### Do I need an account or API key to call the contact enrichment API?

No. Pay-as-you-go calls are paid per request through the 402 quote, with no registration. Only buying Credits needs an agent identity, which the storefront issues through its identity flow.

### Can I pay for contact enrichment by card?

Card pays a pay-as-you-go call only when that call costs $0.50 or more. To pay for smaller calls by card, buy Credits from $0.50 and let each match draw the balance down.

## Keep reading

- [Buyer skill](https://agents.bytemine.ai/zcj/7nmedhnx1syl/SKILL.md): the full purchase flow
- [How to pay](https://agents.bytemine.ai/zcj/7nmedhnx1syl/payment.md): rails, ceilings, Credits and top-ups
- [Contact Enrichment API reference](https://agents.bytemine.ai/zcj/7nmedhnx1syl/services/contact-enrichment/openapi.json): every request and response field
- [Error reference](https://agents.bytemine.ai/zcj/7nmedhnx1syl/errors.md): every error code and what to do
- [Identity](https://agents.bytemine.ai/zcj/7nmedhnx1syl/auth.md): the agent credential for Credits

---

Updated 2026-10-16. All Bytemine guides: https://agents.bytemine.ai/guides.md. Storefront: https://agents.bytemine.ai/zcj/7nmedhnx1syl/llms.txt.