Scrapes

Purchase phone reveal

Buy the phone line types of a finished scrape's delivered leads.

POSTapi.leadity.io/v1/scrapes/{id}/reveal-phones

Scope spendSpends creditsMCP tool purchase_phone_reveal

Takes credits: reveals the line type (mobile, landline, voip or toll free) of every delivered number of a finished scrape that ordered no phone filter, on that same scrape. Price it first with list_scrape_offers, which is free and answers how many numbers the reveal covers and what it costs in credits. It is all or nothing: maxCredits must cover the whole price, and maxNumbers, when given, the whole count, or nothing is charged and the call answers quote_exceeded. Once bought, list_leads and download_leads carry phoneType. Needs a key with the spend scope.

Example request

curl -X POST "https://api.leadity.io/v1/scrapes/Vb7nW3xQ9k/reveal-phones" \
  -H "Authorization: Bearer $LEADITY_API_KEY" \
  -H "Idempotency-Key: order-2026-10-04-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "maxCredits": 200,
    "maxNumbers": 1000
  }'

Example response

{
  "count": 963,
  "credits": 193
}

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

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.

maxNumbersinteger

The most numbers the reveal may cover. Above it nothing is charged and the call answers quote_exceeded.

At most 10,000,000, greater than 0.

Response

countintegerrequired

Numbers revealed.

creditsintegerrequired

Credits charged.

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