API Documentation

Reference design for production deployment. These endpoints power the Guardian Shield UI and can be integrated into any CRM or quoting system.

REST API — JSON over HTTPS

Endpoints

POST/api/extract

Extracts policy data from a declarations page (PDF or image). Accepts base64-encoded file.

POST/api/analyze

Analyzes extracted policy data for coverage gaps and risks. Accepts PolicyData JSON.

POST/api/talking-points

Generates agent talking points from policy data. Can run in parallel with /api/analyze.

Extract — Request

Send a base64-encoded PDF or image of a declarations page.

{
  "fileBase64": "<base64-encoded-file>",
  "mimeType": "application/pdf"  // or "image/jpeg", "image/png"
}

cURL Example

curl -X POST https://your-domain.vercel.app/api/extract \
  -H "Content-Type: application/json" \
  -d '{
    "fileBase64": "<base64-encoded-pdf>",
    "mimeType": "application/pdf"
  }'

Analyze & Talking Points — Request

For manual entry or when you already have extracted data, send PolicyData JSON directly to the analysis and talking points endpoints.

# Step 1: Analyze coverage
curl -X POST https://your-domain.vercel.app/api/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "policyIdentification": { "carrier": "State Farm", ... },
    "coverages": { "dwellingA": 350000, ... },
    ...
  }'

# Step 2: Generate talking points (can run in parallel with Step 1)
curl -X POST https://your-domain.vercel.app/api/talking-points \
  -H "Content-Type: application/json" \
  -d '{ ... same policy data ... }'

Combined Response Example

The UI combines all three endpoint responses into a single ApiResponse object. Here's the full shape:

{
  "policyData": {
    "policyIdentification": {
      "carrier": "State Farm",
      "policyNumber": "HO-98765432",
      "policyType": "HO-3",
      "effectiveDate": "01/15/2025",
      "expirationDate": "01/15/2026",
      "agentName": "Jane Wilson",
      "agentContact": "(555) 234-5678"
    },
    "peopleAndProperty": {
      "namedInsured": "John & Sarah Smith",
      "propertyAddress": "456 Oak Drive, Tampa, FL 33601",
      "mortgageCompany": "Wells Fargo Home Mortgage",
      "mortgageAddress": null
    },
    "coverages": {
      "dwellingA": 350000,
      "otherStructuresB": 35000,
      "personalPropertyC": 175000,
      "lossOfUseD": 70000,
      "personalLiabilityE": 300000,
      "medicalPaymentsF": 5000
    },
    "cost": {
      "annualPremium": 2150,
      "premiumBreakdown": [],
      "deductibles": [
        { "type": "All Perils", "amount": "$1,000" },
        { "type": "Hurricane", "amount": "2%" }
      ]
    },
    "endorsements": ["Water Backup", "Equipment Breakdown"],
    "discounts": ["Multi-policy", "Claims-free"],
    "confidence": "high"
  },
  "coverageAnalysis": {
    "flags": [
      {
        "id": "hurricane-deductible",
        "category": "deductible",
        "severity": "medium",
        "title": "Separate Hurricane Deductible",
        "description": "Policy has a 2% hurricane deductible ($7,000 on $350K dwelling).",
        "recommendation": "Ensure the customer understands this higher deductible for hurricane claims."
      }
    ],
    "overallRisk": "medium",
    "summary": "Solid coverage with one concern: the hurricane deductible could be a surprise."
  },
  "talkingPoints": {
    "currentCoverageSummary": "You have an HO-3 policy with State Farm covering your home at 456 Oak Drive for $350,000...",
    "whatsGood": [
      "Your liability coverage at $300K meets industry recommendations.",
      "You have water backup and equipment breakdown endorsements."
    ],
    "whatToDiscuss": [
      "Your hurricane deductible is 2% — that's $7,000 out of pocket for hurricane damage.",
      "Consider adding scheduled personal property if you have valuables over $2,500."
    ],
    "reshopAngle": "Your renewal is in 9 months — let us start comparing rates now so you have options."
  },
  "metadata": {
    "processingTimeMs": 4523,
    "confidence": "high",
    "documentType": "HO-3",
    "timestamp": "2026-04-27T12:00:00.000Z"
  }
}

Error Responses

400

Bad Request

Missing required fields (fileBase64, mimeType)

422

Unprocessable Entity

AI response failed Zod schema validation. The document may not be a declarations page.

500

Internal Server Error

AI provider error or unexpected failure

CRM Integration Pattern

This API is designed to integrate with Guardian Service's existing CRM and quoting systems. Example integration flow:

Agent uploads a dec page to the customer's record in Salesforce
A Salesforce trigger sends the file to POST /api/extract
Extracted data is written back to the customer profile fields
Analysis and talking points are generated and attached as a note
Agent sees the analysis when they open the customer record — no manual data entry needed

Production deployment note

This API specification is a reference design. For production deployment on AWS/GCP, the edge runtime handlers would be replaced with containerized services behind an API gateway, with authentication, rate limiting, and persistent storage.