Results and billing | LeadX API docs

A successful API request does not always mean LeadX found a record or charged a credit. Treat processing, result quality, and billing as separate outcomes.

Evaluate outcomes independently

Outcome	Fields to inspect	Meaning
Request processing	HTTP status and `success`	Whether LeadX accepted and processed the request
Match result	`records`, `email`, `mobile_number`, or row-level `result`	Whether the request returned usable data
Data quality	`email_status` or `email_validation_status`	The quality classification associated with an email
Credit usage	`billing`, `credits_debited`, or job counters	Whether the completed work consumed credits

Do not treat success: true as result found, and do not infer a charge from the presence of a result. Inspect the endpoint-specific result and billing fields.

Interpret search responses

Search endpoints that return a records array use an empty successful response for no matches:

{
  "success": true,
  "records": [],
  "page_number": 1,
  "per_page": 50,
  "total_pages": 0,
  "total_records": 0
}

This is not an error. Continue only when records contains the data your workflow requires.

Interpret email discovery

POST /v1/emails/find returns 200 OK for both a match and a confirmed no-result lookup.

Condition	`email`	`billing.credits_debited`	`billing.reason`
New billable result	Email address	`1`	`null`
No email found	`null`	`0`	`EMAIL_NO_RESULTS`
Catch-all result	Email address	`0`	`EMAIL_CATCH_ALL`
Same lookup was charged within 30 days	Email address	`0`	`EMAIL_FREE_WITHIN_30D`

{
  "success": true,
  "email": null,
  "email_status": null,
  "input": {
    "first_name": "Jane",
    "last_name": "Smith",
    "url": "example.com",
    "linkedin_url": null
  },
  "billing": {
    "credit_type": "EMAIL",
    "credits_debited": 0,
    "reason": "EMAIL_NO_RESULTS",
    "balance_after": 125,
    "mode": "CLIENT"
  }
}

Email discovery normalizes a returned email to one of these statuses:

`email_status`	Meaning	Recommended handling
`VALID`	The address passed the discovery workflow's validation checks	Use it according to your outreach policy
`CATCH_ALL`	The domain can accept mail without confirming the individual mailbox	Apply additional verification or suppress automated outreach
`null`	LeadX did not return an email	Record a no-result outcome instead of treating it as an error

Interpret mobile discovery

POST /v1/mobile-numbers/find follows the same processing pattern, but its no-debit field is named credits_no_debit_reason.

Condition	`mobile_number`	`billing.credits_debited`	`billing.credits_no_debit_reason`
New billable result	Phone number	`1`	Omitted
No number found	`null`	`0`	`MOBILE_NO_RESULTS`
Same lookup was charged within 30 days	Phone number	`0`	`MOBILE_FREE_WITHIN_30D`

Always use credits_debited as the authoritative per-response charge. Use the reason field to explain a zero-credit result.

Interpret email validation

Email validation reports a quality result. The status does not itself indicate whether a credit was charged.

Status	Meaning	Recommended handling
`Valid`	The address passed the available validation checks	Keep the address if it also meets your business rules
`Invalid`	The address failed syntax or validation checks	Suppress it and correct the source data before retrying
`Risky`	LeadX could not confirm the mailbox with enough certainty for a `Valid` result	Route it through a stricter review or outreach policy
`Unknown`	Validation did not produce a definitive classification	Preserve the status and retry only if your policy allows a later recheck

These values are case-sensitive. Email discovery uses uppercase VALID and CATCH_ALL; email validation uses title-case Valid, Invalid, Risky, and Unknown.

mx_records adds the normalized primary MX hostname when available. It does not change the meaning of email_status.

Interpret bulk email rows

The JSON bulk-email results endpoint returns one outcome per external_id:

`result`	Meaning	Fields to inspect
`pending`	The row has not finished	Poll the job, then fetch this row again
`found`	An email was returned	`email`, `email_status`, `credits_debited`, and `reason`
`not_found`	Processing completed without an email	`reason` and `credits_debited`
`error`	The row could not complete	`error`, `reason`, and `credits_debited`

Use external_id to join the result to your source system. Use row_index only for cursor pagination and input-order reconciliation.

The job status response aggregates processed, found, and credits_debited. These counters answer different questions and are not expected to have the same value.

Reconcile credits safely

Record credits_debited with the result you persist.
Preserve the no-debit reason for support and audit workflows.
Sum row-level credits_debited when reconciling a JSON bulk job.
Do not retry a successful no-result row as though it were a transient failure.
Treat a received 502 or 504 as a transient processing failure, not a confirmed no-result.

See Reliability and retries before automating retries. For an end-to-end bulk workflow, see Run a bulk enrichment workflow.