A validation API is only useful when everyone agrees on what its answer means. A developer may use “valid” to mean that a JSON value has the right shape. A support agent may hear the same word as confirmation that a passport is genuine. A product manager may assume the person holding that passport has been identified. Those are different conclusions, supported by different evidence. Confusing them can produce both unnecessary friction and misplaced trust.
The solution is not a more impressive score. It is a precise vocabulary, a response that preserves uncertainty, and a product policy that names the evidence it actually needs. This guide proposes a practical way to organize those decisions before choosing an integration.
Start with the question, not the endpoint
Write the business question as a sentence. “Can we send a parcel to this address?” is different from “Does this person live here?” “Can this number receive a message?” is different from “Is this the account holder?” The same input may appear in both questions, but the second question requires a different relationship to be established. Treat the requested outcome as a requirement rather than inferring it from the field name.
Make the purpose actionable
Next, identify what happens after the answer. A spelling suggestion can be reversible and low consequence. A decision that blocks access needs a more deliberate exception process. Make a small decision table with the action, the evidence required, the tolerated uncertainty, and the person responsible for the policy. This gives engineering a concrete target and prevents a library function from accidentally becoming company policy.
Separate five kinds of signals
For integration design, use separate concepts for structure, normalization, consistency, source comparison, and holder linkage. Structure asks whether a value can be parsed under an explicit rule. Normalization creates a useful representation. Consistency compares related values. Source comparison checks a claim against a specified record. Holder linkage concerns the relationship between evidence and the person presenting it. These are a proposed working vocabulary, not interchangeable certifications.
An address can be normalized without having been checked against a delivery database. A document can have internally consistent dates without an issuer lookup. Keep those distinctions in separate response fields so consumers do not have to guess. In your internal contract, make each field answer one question, state the method, and identify when no attempt was made. Avoid a single green badge standing in for all five concepts.
Use identity terminology carefully
The distinction is supported by NIST’s identity proofing guidance. It describes evidence validation and attribute validation separately from identity verification, which establishes a linkage between a validated identity and the real-life applicant. That is a useful reference when teams are aligning terminology; it is not a claim that a basic formatting service satisfies a particular assurance level.
For your own product, reserve “identity verified” for a defined process with appropriate evidence and review. A successful parser should instead report that parsing succeeded. A document workflow should say which checks ran, which were unavailable, and what remains unresolved. This narrower language is easier to defend in documentation and easier for a customer to understand when something needs correction.
Design a response that cannot overclaim
Consider a proposed response containing status, checks, reasons, next_action, and request_id. A structure check might return pass, while an issuer comparison returns not_checked. A separate overall status might be needs_review because a required method was unavailable. The important property is not the exact field name; it is that the client can distinguish a negative finding from an absent observation without interpreting free text.
Document the aggregation rules beside the schema. Does one failed check stop the workflow? Does an unavailable optional check permit continuation? Can a user correct a value and resubmit? Each answer belongs to a named policy version. The ValidAPI response reference illustrates this approach with fictional fixtures, rather than implying that the website performs live identity checks.
Preserve uncertainty as useful information
A timeout is an operational problem, not an invalid person. An unsupported country is a coverage limitation, not evidence of fraud. A missing unit number may be a correction opportunity, not a reason to refuse service. If these cases collapse into false, every downstream team must reconstruct the cause from logs, and the interface will probably give the user the wrong instruction.
Create explicit routes for unsupported, unavailable, and needs_review. Then decide which routes pause the action, which permit a limited action, and which need human attention. Keep the wording factual: “We could not complete this check” is different from “Your information is incorrect.” A well-designed uncertain result gives the product something actionable without manufacturing confidence.
Keep the evidence and policy layers separate
Imagine that an address response reports an unconfirmed apartment number. A delivery product might ask the user to review it. A mailing-list tool might retain the supplied text with an unresolved flag. Neither choice changes the underlying observation. Store the observation separately from the action taken, so another workflow can apply its own appropriate rule without pretending the evidence changed.
This separation also helps when requirements change. Instead of rewriting old results, preserve the method and observation time, then apply a new policy to the eligible data. Do not automatically reprocess sensitive records merely because a new policy exists. Decide whether reprocessing is necessary, permitted, and useful. A policy history should explain decisions, not become a reason to collect more information indefinitely.
Choose metrics that reveal mistakes
A high percentage of passing requests is not, by itself, a useful quality target. It could mean excellent input quality, permissive rules, or a check that silently skips difficult cases. Track the distribution of outcomes and reasons. Separate corrected entries from abandoned journeys, and separate unsupported inputs from genuine mismatches. Otherwise a change that harms one group of users can hide inside an attractive headline number.
Create a review set of fictional or appropriately governed test cases with known expected outcomes. Include missing values, ambiguous records, out-of-coverage inputs, and service failures. Compare the user-visible message with the actual observation. An integration is not ready merely because the happy-path JSON looks right; its uncertainty and recovery paths must also behave as designed.
Ask vendors questions your schema can answer
Before adopting a provider, ask what each result establishes, which source is used, how freshness is represented, and what happens when a source cannot be reached. Request examples of partial matches and unsupported records, not only successful demonstrations. Ask whether formatting, source comparison, and holder verification are distinct services, and which commercial or authorization requirements apply to each.
Turn the answers into acceptance criteria. A statement such as “global identity validation” is too broad to test. “This documented method is available for these document types in these jurisdictions, with these unavailable states” is more useful. The validation overview provides a starting framework for organizing the five data families without treating them as equivalent evidence.
Conclusion: make every green check explainable
A good validation integration makes a smaller, clearer claim than an ambiguous all-purpose score. It tells you what was tested, what was observed, and what was not established. Your application then applies an explicit policy and gives the person a reasonable next step. That division of responsibility makes documentation, support, and future changes easier to manage.
Start with one workflow and write down its evidence boundary. Give unknown outcomes their own paths. Make the interface use the same vocabulary as the response contract. When every green check has an explanation, your team can improve the experience without quietly increasing the meaning of “valid.”
