Validations

Preview validation

Quote a list for free: how many items survive parsing and what they cost.

POSTapi.leadity.io/v1/validations/preview

Scope readMCP tool preview_validation

Parses a list of phone numbers or email addresses without buying anything and takes no credits. It answers how many items survive parsing and de-duplication, which is what a run holds credits for, and what that costs. rejectedSample shows a few refused lines, so a wrong column is easy to spot. A list holding UK or Australian numbers answers numbering_unavailable while that country's register is not loaded. Call it before create_validation and set maxCredits from credits.

Example request

curl -X POST "https://api.leadity.io/v1/validations/preview" \
  -H "Authorization: Bearer $LEADITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "phone",
    "items": [
      "+1 512 555 0123",
      "(415) 555-0199",
      "not a number"
    ],
    "region": "US"
  }'

Example response

{
  "kind": "phone",
  "region": "US",
  "submitted": 3,
  "total": 2,
  "rejected": 1,
  "duplicates": 0,
  "truncated": false,
  "credits": 1,
  "rejectedSample": [
    "not a number"
  ]
}

Headers

Authorizationstringrequired

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

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

Response

kindstringrequired

phone to classify line types, email to check deliverability.

One ofphoneemail

regionstringrequired

The region the list was read under.

One ofUSGBAU

submittedintegerrequired

Lines or items submitted.

totalintegerrequired

Items that would be checked.

rejectedintegerrequired

Items refused as not a phone number or address.

duplicatesintegerrequired

Repeats collapsed to one.

truncatedbooleanrequired

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

creditsintegerrequired

What a run of this list holds, in credits. Answers that tell nothing are refunded when it settles.

rejectedSamplestring[]required

Up to eight refused lines.

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.	-
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).
numbering_unavailable	409	The list holds numbers whose country register is not loaded yet. The body names the plan.	`region`: The region the list was read under.`plan`: The register not loaded yet: gb or au.
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.