PersonClarity integration guide

This page describes the validation rules used by this website. A public developer API, access plan and service commitment are not currently offered here. Do not send credentials or personal records to historical endpoints. For an integration request, contact Support.

Inputs and scope

Phone input accepts a ten-digit NANP number or an eleven-digit number starting with 1, with spaces, parentheses, a plus sign or hyphens. ZIP input accepts five digits or ZIP+4; normalization keeps the first five digits. Format validation does not prove that a number is assigned or that a record is available. Searches and private receipts are not public API identifiers.

Validated response contract

The internal version 1 contract requires an integer totalResultados, an array persons with at most 2,500 entries, a boolean total_is_exact, and a nullable next_cursor of at most 512 characters. Duplicate canonical IDs, malformed envelopes or suppressed records fail validation. An empty result is different from a service outage.

{
  "contract_version": 1,
  "totalResultados": 0,
  "persons": [],
  "total_is_exact": true,
  "next_cursor": null
}

This synthetic example is an empty response, not an instruction to call a public endpoint. For any returned entity, publication requires a canonical_id, public_safe=true and suppressed=false. Search eligibility additionally needs seo_eligible=true, a source_version and a verified_at timestamp within the current 180-day freshness window. Eligibility is a data quality decision, not a guarantee of indexing.

Errors and retry behavior

• Invalid input or a malformed response must not become a successful empty search.
• Restricted legacy API operations return 403.
• Public missing records can return 404; a privacy restriction can return 410.
• Rate limiting can return 429. Respect Retry-After when provided.
• Service unavailability can return 503. Retry conservatively; do not scrape alternative routes to bypass a limit.

These are website behaviors, not a promised public API error envelope. Authentication, quotas, endpoints, cursor transport and commercial terms for external consumers remain unconfirmed.

Privacy and support

Suppression takes precedence over imports and search eligibility. Never log private query values, receipts, credentials or raw response payloads. Removal and corrections use the Privacy Center; a request receipt does not confirm completion. Report service problems through Support.