Warnvo/API Reference
v1
Developer API

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.

Jump to endpoints

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/v1

Authentication

All API requests require a Bearer token in the Authorization header. Generate keys from your Account page under API Access.

http
Authorization: Bearer wv_live_YOUR_KEY

Security 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".

json
{
  "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

FLAGGED

Overcharges or suspicious items detected. Dispute recommended.

HEADS_UP

Minor issues found. Review before paying.

LOOKS_OK

No significant issues detected.

Errors

Errors follow a consistent shape: { error: string, code: string }.

HTTP StatusCodeMeaning
401UNAUTHORIZEDMissing or invalid API key.
403REVOKEDAPI key has been revoked.
429RATE_LIMITEDScan quota exhausted for this billing period.
400NO_FILENo file attached to the request.
400FILE_TOO_LARGEFile exceeds 10 MB limit.
404JOB_NOT_FOUNDJob ID does not exist or belongs to another key.
500ENGINE_ERRORShieldEngine™ encountered an internal error. Retry after a moment.

JavaScript Example

javascript
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

$79/mo

500 scans/mo

  • Full ShieldEngine™ analysis
  • All bill categories
  • JSON responses
  • Email support
Most popular

Growth

$149/mo

2,000 scans/mo

  • Everything in Starter
  • Webhook callbacks
  • Priority queue
  • Slack support

Enterprise

Custom

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.