Scrapes

Purchase owner names

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

POSTapi.leadity.io/v1/scrapes/{id}/owner-names

Scope spendSpends creditsMCP tool purchase_owner_names

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.

Example request

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
  }'

Example response

{
  "scrapeId": "Rm8xK2pT7w",
  "targetNames": 100,
  "reservedCredits": 250
}

Headers

Authorizationstringrequired

Bearer, a space, then an API key: Bearer lk_api_... An MCP key is refused here with wrong_key_kind.

Idempotency-Keystringrequired

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-Typestringrequired

application/json

Path parameters

idstringrequired

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

targetNamesintegerrequired

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.

maxCreditsintegerrequired

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.

Response

scrapeIdstringrequired

The new scrape that delivers the named leads. Watch it and stop it like any other.

targetNamesintegerrequired

The names ordered, at most the pool.

reservedCreditsintegerrequired

Credits held now: targetNames times the price per name, rounded up once to a whole credit.

Errors

Every refusal answers { error, message } with the status below. The full list is on the 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.