> ## Documentation index
> Fetch the complete documentation index at: https://docs.leadity.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Purchase owner names

> Buy owner names for a finished scrape's delivered leads.

Takes credits: hunts the owner's name for a finished scrape's delivered leads that carry a phone and no name, and delivers each lead whose owner it confirms as a new scrape, until it has confirmed targetNames. Price it first with list_scrape_offers, which is free and answers the pool, the smallest target and the price in credits per confirmed name. It holds targetNames times that price now, rounded up once to a whole credit (21 names at 2.5 credits hold 53), which maxCredits must cover, keeps only confirmed names, and refunds the rest when the run ends. Watch the new scrape with get_scrape_status every 30 to 60 seconds. A second run while one is going answers already_running. Needs a key with the spend scope.

`POST https://api.leadity.io/v1/scrapes/{id}/owner-names`

- Scope: `spend`
- Spends credits: yes
- MCP tool: `purchase_owner_names`

## Headers

- `Authorization`, string, required. Bearer, a space, then an API key: Bearer lk_api_... An MCP key is refused here with wrong_key_kind.
- `Idempotency-Key`, string, required. Your own key for this one purchase. Send the same key again to retry it safely: the retry replays the first answer instead of charging twice, and carries Idempotent-Replayed: true. The same key on a different request answers idempotency_conflict, and a spend without one answers idempotency_key_required. 16 to 64 characters, matches ^[A-Za-z0-9_-]+$.
- `Content-Type`, string, required. application/json

## Path parameters

- `id`, string, required. The scrape's id, as create_scrape and list_scrapes answer it. 1 to 64 characters, matches ^[A-Za-z0-9]{1,64}$.

## Body parameters

- `targetNames`, integer, required. How many confirmed names to buy: at least the offer's minTargetNames. Above the pool it is cut to the pool. 1 to 1,000,000.
- `maxCredits`, integer, required. The most this call may take, in whole credits. If the price is higher nothing is charged and the call answers quote_exceeded. At most 100,000,000, greater than 0.

## Example request

```bash cURL
curl -X POST "https://api.leadity.io/v1/scrapes/Vb7nW3xQ9k/owner-names" \
  -H "Authorization: Bearer $LEADITY_API_KEY" \
  -H "Idempotency-Key: order-2026-10-04-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "targetNames": 100,
    "maxCredits": 250
  }'
```

```javascript Node.js
// Make the key once per purchase and reuse it on every retry.
const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.leadity.io/v1/scrapes/Vb7nW3xQ9k/owner-names", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LEADITY_API_KEY}`,
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "targetNames": 100,
    "maxCredits": 250
  }),
});

const data = await response.json();
console.log(data);
```

```python Python
import os
import uuid

import requests

# Make the key once per purchase and reuse it on every retry.
idempotency_key = str(uuid.uuid4())

response = requests.post(
    "https://api.leadity.io/v1/scrapes/Vb7nW3xQ9k/owner-names",
    headers={
        "Authorization": f"Bearer {os.environ['LEADITY_API_KEY']}",
        "Idempotency-Key": idempotency_key,
    },
    json={"targetNames": 100, "maxCredits": 250},
)

print(response.json())
```

## Response

- `scrapeId`, string, required. The new scrape that delivers the named leads. Watch it and stop it like any other.
- `targetNames`, integer, required. The names ordered, at most the pool.
- `reservedCredits`, integer, required. Credits held now: targetNames times the price per name, rounded up once to a whole credit.

## Example response

```json 201
{
  "scrapeId": "Rm8xK2pT7w",
  "targetNames": 100,
  "reservedCredits": 250
}
```

## Errors

Every refusal answers `{ error, message }` with the status below. The full list is on the [Errors](https://docs.leadity.io/errors) page.

| Code | Status | Meaning | Extra fields |
| --- | --- | --- | --- |
| `unauthorized` | 401 | The API key is missing, malformed, revoked or expired. | - |
| `wrong_key_kind` | 401 | This key opens the other surface: an API key works on the HTTP API, an MCP key on the MCP server. | - |
| `insufficient_scope` | 403 | The key does not carry the scope this operation needs. | `requiredScope`: The scope the operation needs: read, write or spend. |
| `account_suspended` | 403 | The account is suspended. | - |
| `email_not_verified` | 403 | The account's email address is not verified yet. | - |
| `invalid_body` | 400 | The request does not match the operation's schema. | `issues`: The problems found, each with path (the field as a dotted path, led by the part of the request it travels in: path, query or body, such as body.items.1) and message (what is wrong there). |
| `not_found` | 404 | No such resource on this account. | `id`: On export_scrapes: the first id that is not one of the account's scrapes. |
| `paywall_required` | 402 | This operation needs a purchase on the account first. | - |
| `insufficient_credits` | 402 | The balance does not cover the price. Nothing was charged. | `required`: On create_validation: the credits the list holds. |
| `quote_exceeded` | 409 | The price is above the maxCredits the call allowed. Nothing was charged. | `credits`: What the call would have taken: the whole hold on an order or a list, the price or the hold on an upgrade. `maxCredits`: The ceiling the call sent. `reviewsReservedCredits`: On create_scrape: the part of credits held for review scraping. `count`: On purchase_phone_reveal, when the count was the cause: how many numbers the reveal would name. `maxNumbers`: On purchase_phone_reveal, when the count was the cause: the maxNumbers the call sent. |
| `idempotency_key_required` | 400 | A spending operation must carry an Idempotency-Key header (16 to 64 characters of A-Z, a-z, 0-9, _ and -). | - |
| `invalid_idempotency_key` | 400 | The Idempotency-Key must be 16 to 64 characters of A-Z, a-z, 0-9, _ and -. | - |
| `idempotency_conflict` | 409 | This Idempotency-Key was already used for a different request. | - |
| `already_running` | 409 | An owner-name run is already going on this scrape. | - |
| `rate_limited` | 429 | Too many requests. Wait for the Retry-After seconds and try again. | `retryAfterSeconds`: The seconds to wait, the same number as the Retry-After header. |
| `try_again` | 503 | Leadity could not answer just now. Retry in a moment, with the same Idempotency-Key on a spending call. | `retryAfterSeconds`: When a request with this Idempotency-Key is still being processed: the seconds to wait before retrying with the same key, as the Retry-After header says. |
| `internal_error` | 500 | Something failed on our side. Nothing was charged twice. | `body`: On the MCP server, when Leadity answered in a shape the tool does not publish: that answer as it came. |