Key takeaways
- Event ingestion must be idempotent and attributable.
- Tenant, client, and website boundaries belong in authorization and data models.
- Decision responses need reasons, confidence, and version.
- Retries must not duplicate actions.
Start with the event contract
Define event ID, occurrence time, receipt time, source, website, consent state, acquisition identifiers, validation result, and schema version. Keep raw values where appropriate and record normalization separately.
Use idempotency keys and explicit retry semantics so network failure does not create duplicate clicks, sessions, conversions, or actions.
Return an explainable decision object
The API response should distinguish observed features, calculated signals, score, confidence, classification, decision status, policy eligibility, and recommended action. Historical responses should remain reconstructable after model changes.
- Use unclassified and unavailable states explicitly.
- Expose coverage and freshness.
- Version schemas, rules, and models.
- Avoid encoding provider application as a boolean shortcut.
Design action and privacy controls
Action endpoints need authorization, scope, idempotency, approval policy, provider response, verification, expiry, and reversal. Data minimization, retention, deletion, audit logs, rate limits, and secret rotation belong in the integration design—not in a later checklist.
Limitations
What this guide does not claim
An API contract cannot compensate for poor upstream measurement or unsupported provider capabilities. Security and privacy controls require implementation-specific review.
Evidence
Primary sources
- Automated Threats to Web ApplicationsOWASP Foundation
- AI Risk Management FrameworkNIST
- Consent mode overviewGoogle for Developers
Read how we source, review, update, and correct content in our editorial standards.