Validations

Create validation

Validate a list of phone numbers or email addresses you supply.

POSTapi.leadity.io/v1/validations

Scope spendSpends creditsMCP tool create_validation

Takes credits: checks a list of phone numbers or email addresses you supply, answering a verdict per item (the line type of a number, whether an address can receive mail), and holds the price of the whole list up front. Price it first with preview_validation, which is free and answers how many items survive parsing and what they cost in credits. maxCredits must cover the hold. An answer that tells nothing (unknown or invalid for a number, unknown or catch_all for an address) costs nothing, and its credits come back when the run settles. The call answers at once: watch the run with get_validation every 30 to 60 seconds, never faster, until its status is final; a few thousand items take a minute or two. Read the answers with list_validation_items or download_validation. Needs a key with the spend scope.

Example request

curl -X POST "https://api.leadity.io/v1/validations" \
  -H "Authorization: Bearer $LEADITY_API_KEY" \
  -H "Idempotency-Key: order-2026-10-04-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "email",
    "items": [
      "owner@lonestarroofing.example",
      "info@acme-roofing.example"
    ],
    "maxCredits": 1
  }'

Example response

{
  "validation": {
    "id": "Wq5nB8kT3m",
    "title": "Email validation | Oct 4, 2:12 PM",
    "kind": "email",
    "region": "US",
    "status": "queued",
    "source": "api",
    "submitted": 2,
    "rejected": 0,
    "duplicates": 0,
    "total": 2,
    "processed": 0,
    "billable": 0,
    "reservedCredits": 1,
    "creditsUsed": null,
    "creditsPerItem": 0.2,
    "createdAt": "2026-10-04T14:12:09.000Z",
    "startedAt": null,
    "settledAt": null
  },
  "truncated": false,
  "rejectedSample": [],
  "replayed": false
}

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

Body parameters

kindstringrequired

phone to classify line types, email to check deliverability.

One ofphoneemail

itemsstring[]

The list as an array, one phone number or address per item: 1 to 50,000 items of at most 254 characters, and at most 8 MB joined one per line, as raw. Send items or raw, not both.

1 to 50,000 items, each 1 to 254 characters.

rawstring

The list as pasted text, one item per line or separated by commas, at most 8 MB (8,388,608 bytes of UTF-8). Send items or raw, not both.

1 to 8,388,608 characters.

regionstring

For a phone list, the country a number written without its country code is read under: US (also Canada), GB or AU. Default US. Ignored for addresses.

One ofUSGBAU

titlestring

A name for the run. Left out, one is derived from its kind and date.

1 to 100 characters.

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

validationobjectrequired

Show child attributes

idstringrequired

The run's id.

titlestringrequired

The run's name.

kindstringrequired

phone to classify line types, email to check deliverability.

One ofphoneemail

regionstringrequired

The region a phone list was read under. US on an email run.

One ofUSGBAU

statusstringrequired

queued and running are live; completed, failed and canceled are final. A failed run bills only what was answered.

One ofqueuedrunningcompletedfailedcanceled

sourcestringrequired

Where this was started: dashboard (the Leadity app), api (an API key), mcp (an MCP key), stress or import (Leadity's own tools).

One ofdashboardapimcpstressimport

submittedintegerrequired

Lines or items submitted.

rejectedintegerrequired

Items the parser refused as not a phone number or address.

duplicatesintegerrequired

Repeats collapsed to one.

totalintegerrequired

Items checked: submitted minus rejected and duplicates.

processedintegerrequired

Items answered so far.

billableintegerrequired

Answers that cost credits so far. An answer that tells nothing costs nothing.

reservedCreditsintegerrequired

Credits held when the run was created.

creditsUsedinteger | nullrequired

Credits kept, set when the run settles; the rest was refunded. Null before.

creditsPerItemnumberrequired

The price of one billable answer.

createdAtstringrequired

When the run was created. An ISO 8601 timestamp in UTC.

startedAtstring | nullrequired

When the run started. An ISO 8601 timestamp in UTC, or null.

settledAtstring | nullrequired

When the run settled. An ISO 8601 timestamp in UTC, or null.

truncatedbooleanrequired

True when the list held more than the most one run takes, and only that many are checked.

rejectedSamplestring[]required

Up to eight refused lines.

replayedbooleanrequired

True when this idempotency key had already created the run: nothing new was charged, and this is that run.

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