Warnvo API Reference
Embed ShieldEngine™ bill analysis directly into your platform. Submit bills via REST, get back structured JSON with flagged items, overcharge estimates, and dispute recommendations.
Overview
REST + JSON
Standard HTTP. Multipart for file uploads, JSON for everything else.
ShieldEngine™
Same AI that powers the Warnvo consumer app — now available via API.
Async by default
POST /scan returns a jobId. Poll GET /jobs/:id or use webhooks.
Base URL
https://warnvo.com/api/v1Authentication
All API requests require a Bearer token in the Authorization header. Generate keys from your Account page under API Access.
Authorization: Bearer wv_live_YOUR_KEYSecurity note
Keys are shown only once at creation time. Store them in environment variables — never in client-side code or version control.
Endpoints
Response Schema
All responses are JSON. The result field is populated once status === "done".
{
"jobId": 42,
"status": "done",
"scansRemaining": 487,
"result": {
"verdict": "FLAGGED",
"overchargeEstimate": 47.50,
"flaggedItems": [
{
"item": "Resort fee",
"amount": 35.00,
"issue": "Not disclosed at booking",
"severity": "high"
}
],
"summary": "Hotel bill contains 1 undisclosed fee totalling $35.",
"disputeRecommended": true
}
}Verdict values
FLAGGEDOvercharges or suspicious items detected. Dispute recommended.
HEADS_UPMinor issues found. Review before paying.
LOOKS_OKNo significant issues detected.
Errors
Errors follow a consistent shape: { error: string, code: string }.
| HTTP Status | Code | Meaning |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid API key. |
| 403 | REVOKED | API key has been revoked. |
| 429 | RATE_LIMITED | Scan quota exhausted for this billing period. |
| 400 | NO_FILE | No file attached to the request. |
| 400 | FILE_TOO_LARGE | File exceeds 10 MB limit. |
| 404 | JOB_NOT_FOUND | Job ID does not exist or belongs to another key. |
| 500 | ENGINE_ERROR | ShieldEngine™ encountered an internal error. Retry after a moment. |
JavaScript Example
const form = new FormData();
form.append("file", fs.createReadStream("bill.pdf"));
form.append("category", "hotel");
const res = await fetch("https://warnvo.com/api/v1/scan", {
method: "POST",
headers: { Authorization: "Bearer wv_live_YOUR_KEY" },
body: form,
});
const { jobId, status, result } = await res.json();
// status: "queued" | "processing" | "done" | "error"
// result: populated when status === "done"API Pricing
API access is billed separately from Warnvo consumer subscriptions. All plans include full ShieldEngine™ accuracy, JSON responses, and email support.
Starter
500 scans/mo
- Full ShieldEngine™ analysis
- All bill categories
- JSON responses
- Email support
Growth
2,000 scans/mo
- Everything in Starter
- Webhook callbacks
- Priority queue
- Slack support
Enterprise
10,000+ scans/mo
- Everything in Growth
- SLA guarantee
- Dedicated support
- Custom categories
Overage scans are billed at $0.12 per scan. All prices in USD. Cancel anytime.