Request shape
A clean identity-verification endpoint keeps the request minimal — the identifier being checked, a face capture where relevant, and an idempotency key — rather than overloading a single call with unrelated concerns.
Response shape
The response should distinguish clearly between outcome types: a registry status (active, not-found, mismatch), a face-match result (match, no-match, too-close-to-call, liveness-failed), and never return a raw registry photo alongside either.
Error handling as part of the design
Treating specific failure modes — liveness failure, rate-limit exceeded, registry timeout — as distinct, well-documented error codes rather than a generic failure response is what makes an API actually integratable, not just technically functional.