Documentation without the guesswork.

Start with the scope.

ValidAPI.com is a static reference website. The examples below are local, predefined fixtures—not results from an identity, postal, telephone, or government database. There is no live API endpoint, API key issuance, document upload, or account system here.

Use the proposed shapes to discuss your client interface. Before connecting a real provider, replace the illustrative contract with its documented capabilities, authentication, terms, coverage, and failure behavior.

Example explorer

Choose a data family, then switch between request and response. A passed structure signal in these fixtures is a demonstration value, not the output of a running validator.

{
  "demo": true,
  "request_id": "sample_address_001",
  "status": "needs_review",
  "checks": {
    "structure": "pass",
    "postal_reference": "not_checked",
    "residence": "not_checked"
  },
  "reasons": [
    {
      "code": "example_only",
      "message": "Fictional fixture; no real-world validation performed."
    }
  ],
  "next_action": "review_requirements"
}

Request design

The proposed contract uses JSON POST requests and a distinct route for each data shape. These are illustrative routes only. The downloadable specification points to a non-operational example hostname so it is not confused with an available ValidAPI service.

Specify which context is required, what transformations are permitted, and how unknown properties are handled. Keep source comparison, document capture, and possession challenges separate from basic structure checks unless the real integration explicitly supports those methods.

Response model

Keep observations, overall workflow state, and next action distinct. In every published fixture, real-world checks remain unperformed and the overall state is needs_review. The broader states below are proposed contract vocabulary for discussion, not current service capabilities.

Proposed overall states

Errors & recovery

Keep malformed requests separate from completed checks with unresolved findings. Choose a documented problem envelope for request and operational errors, stable reason codes for client behavior, and reviewed wording for the person using the product.

Before adding automatic retries, decide which failures are transient and how repeated or delayed responses are reconciled. A missing country needs clarification; an unavailable provider needs an operational route. Neither should become an unexplained “invalid identity” message.

Before a production integration

A sample contract is not a production readiness assessment. Resolve these questions with the responsible engineering, product, security, and legal reviewers for the real implementation.

Take the reference with you.

These local files are included in the website package. They contain no credentials or real customer records.