Insurance Intelligence API

Overview

Policy Penguin extracts structured data from insurance policy documents: coverage types, limits, deductibles, endorsements, discounts, vehicles, properties. This API gives you programmatic access to that data.

Use it to pull policy details into spreadsheets, automate renewal monitoring, build custom dashboards, or integrate insurance data into your existing financial tools. Any language, any platform.

Looking for AI agent access instead? See the Insurance MCP Server, which exposes the same data through the Model Context Protocol.

What you can build

• Pull your full insurance portfolio into a spreadsheet with one request
• Get alerts when a renewal has rate changes above your threshold
• Feed structured policy data into your financial planning tools
• Build a custom dashboard across all your carriers

Authentication

Bearer token authentication. API keys are generated from your Policy Penguin dashboard and scoped to your account.

curl -H "Authorization: Bearer pp_live_abc123..." \
https://api.policypenguin.ai/v1/portfolio

Keys can be scoped to read-only or full access. Revoke any key instantly from the dashboard.

Base URL

https://api.policypenguin.ai/v1

All endpoints are versioned in the URL. The current version is v1.

Endpoints

Four endpoints covering portfolio overview, policy detail, asset detail, and document upload. All return JSON.

GET /v1/portfolio

All policies and assets in your account.

Example Request

curl -H "Authorization: Bearer pp_live_abc123..." \
"https://api.policypenguin.ai/v1/portfolio"

Example Response

{
  "policies": [
    {
      "id": "pol_a1b2c3",
      "carrier": "State Farm",
      "carrier_slug": "state-farm",
      "policy_number": "SF-12345678",
      "type": "auto",
      "state": "GA",
      "premium": {
        "amount": 2400,
        "period": "6-month",
        "currency": "usd"
      },
      "effective": {
        "start": "2025-12-01",
        "end": "2026-06-01"
      },
      "vehicles": [
        {
          "year": 2022,
          "make": "Honda",
          "model": "Accord"
        },
        {
          "year": 2020,
          "make": "Toyota",
          "model": "Camry"
        }
      ],
      "coverage": {
        "summary": [
          "Bodily Injury: $250K/$500K",
          "Property Damage: $100K",
          "Collision: $750 deductible"
        ],
        "limits": "250K / 500K / 100K",
        "deductible": "$750"
      },
      "insights": {
        "total": 8,
        "issues": 2,
        "status": "completed"
      },
      "renewals": 3
    }
  ],
  "assets": [
    {
      "id": "ast_x1y2z3",
      "type": "vehicle",
      "name": "2022 Honda Accord",
      "status": "covered",
      "covered_by": {
        "carrier": "State Farm",
        "policy_number": "SF-12345678"
      },
      "premium": {
        "amount": 2400,
        "period": "6-month",
        "currency": "usd"
      },
      "effective_end": "2026-06-01"
    }
  ]
}

GET /v1/policies/:id

Full detail for a single policy. Returns coverage with structured numeric data, generated insights, discount analysis with savings estimates, and renewal timeline. One call, everything you need.

Example Request

curl -H "Authorization: Bearer pp_live_abc123..." \
https://api.policypenguin.ai/v1/policies/pol_a1b2c3

Example Response

{
  "policy": {
    "id": "pol_a1b2c3",
    "carrier": "State Farm",
    "carrier_slug": "state-farm",
    "policy_number": "SF-12345678",
    "type": "auto",
    "state": "GA",
    "premium": {
      "amount": 2400,
      "period": "6-month",
      "currency": "usd"
    },
    "effective": {
      "start": "2025-12-01",
      "end": "2026-06-01"
    },
    "coverage": {
      "summary": [
        "Bodily Injury: $250K/$500K",
        "Property Damage: $100K",
        "Collision: $750 deductible"
      ],
      "limits": "250K / 500K / 100K",
      "deductible": "$750",
      "exclusions": [
        "Rideshare and delivery exclusion"
      ],
      "state_minimum": {
        "meetsMinimum": true,
        "stateCode": "GA",
        "minimumDisplay": "25/50/25"
      },
      "policy_level": [
        {
          "slug": "auto_bi",
          "name": "Bodily Injury Liability",
          "limits": [
            {
              "type": "per_person",
              "amount": 250000
            },
            {
              "type": "per_accident",
              "amount": 500000
            }
          ],
          "deductibles": [],
          "premium": 1157
        },
        {
          "slug": "auto_pd",
          "name": "Property Damage Liability",
          "limits": [
            {
              "type": "flat",
              "amount": 100000
            }
          ],
          "deductibles": [],
          "premium": 520
        }
      ],
      "by_vehicle": [
        {
          "vehicle": {
            "year": 2022,
            "make": "Honda",
            "model": "Accord"
          },
          "items": [
            {
              "slug": "collision",
              "name": "Collision",
              "limits": [],
              "deductibles": [
                {
                  "amount": 750
                }
              ],
              "premium": 281
            },
            {
              "slug": "comprehensive",
              "name": "Comprehensive",
              "limits": [],
              "deductibles": [
                {
                  "amount": 200
                }
              ],
              "premium": 206
            }
          ]
        }
      ]
    }
  },
  "insights": [
    {
      "category": "market",
      "priority": 1,
      "title": "Upcoming Rate Change",
      "description": "A rate filing indicates a 12% increase for renewals starting next quarter.",
      "action": null
    },
    {
      "category": "savings",
      "priority": 3,
      "title": "Missing Discount Available",
      "description": "Defensive driving course discount could reduce your premium.",
      "action": "Complete a state-approved defensive driving course."
    }
  ],
  "discounts": {
    "currency": "usd",
    "current": [
      {
        "name": "Multi-Line Discount",
        "category": "multi_line",
        "applied": true
      },
      {
        "name": "Paid In Full Discount",
        "category": "payment",
        "applied": true
      }
    ],
    "missing": [
      {
        "name": "Defensive Driving Discount",
        "category": "driver_behavior",
        "estimated_savings": {
          "min": 120,
          "max": 240
        },
        "requirements": "Complete a state-approved course"
      }
    ],
    "total_potential_savings": {
      "min": 120,
      "max": 240
    }
  },
  "timeline": [
    {
      "carrier": "State Farm",
      "premium": 2400,
      "premium_annual": 4800,
      "percent_change": 8.1,
      "effective": {
        "start": "2025-12-01",
        "end": "2026-06-01"
      },
      "is_current": true
    },
    {
      "carrier": "State Farm",
      "premium": 2220,
      "premium_annual": 4440,
      "effective": {
        "start": "2025-06-01",
        "end": "2025-12-01"
      },
      "is_current": false
    }
  ]
}

GET /v1/assets/:id

Detail for a single asset (vehicle or property), including current coverage and premium trends.

Example Request

curl -H "Authorization: Bearer pp_live_abc123..." \
https://api.policypenguin.ai/v1/assets/ast_x1y2z3

Example Response

{
  "asset": {
    "type": "vehicle",
    "name": "2022 Honda Accord",
    "details": {
      "year": 2022,
      "make": "Honda",
      "model": "Accord"
    }
  },
  "current_coverage": {
    "carrier": "State Farm",
    "policy_number": "SF-12345678",
    "premium": {
      "amount": 2400,
      "period": "6-month",
      "currency": "usd"
    },
    "effective": {
      "start": "2025-12-01",
      "end": "2026-06-01"
    },
    "status": "active"
  },
  "premium_trends": {
    "current_monthly": 400,
    "change_percent": 8.1,
    "trend": "increasing"
  }
}

POST /v1/upload

Upload a policy document for extraction. Send the file as base64-encoded data in JSON. Returns structured policy data in about 15 seconds.

Request Body

Name	Type	Required	Description
file	string	Yes	Base64-encoded file content
filename	string	Yes	Original filename
mime_type	string	Yes	application/pdf, image/jpeg, or image/png

Example Request

curl -X POST -H "Authorization: Bearer pp_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"file": "JVBERi0xLjQK...", "filename": "my-policy.pdf", "mime_type": "application/pdf"}' \
  https://api.policypenguin.ai/v1/upload

Example Response

{
  "policies": [
    {
      "id": "pol_new123",
      "carrier": "Progressive",
      "type": "auto",
      "premium": {
        "amount": 1850,
        "period": "6-month",
        "currency": "usd"
      },
      "effective": {
        "start": "2026-03-15",
        "end": "2026-09-15"
      },
      "vehicles": [
        {
          "year": 2020,
          "make": "Toyota",
          "model": "Camry"
        }
      ],
      "extraction_quality": "clean",
      "is_renewal": false
    }
  ],
  "insights_status": "generating"
}

Rate Limits

Request type	Limit
Read endpoints (GET)	1,000 requests/minute
Upload endpoint (POST /v1/upload)	60 requests/minute

Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

Status Codes

Code	Meaning
200	Success
400	Bad request. Check parameters
401	Missing or invalid API key
404	Resource not found (e.g., invalid policy ID)
429	Rate limit exceeded
500	Server error

Error Response Format

{
  "error": {
    "code": "POLICY_NOT_FOUND",
    "message": "No policy found with the given ID"
  }
}

Use Cases

Renewal Monitoring

Call GET /v1/portfolio weekly. When a policy's renewal is 30 days out, pull its details with GET /v1/policies/:id. The insights and timeline in the response tell you exactly what changed. Feed that into a Slack alert or email so you know before the bill arrives.

Portfolio Spreadsheet

Hit GET /v1/portfolio and dump the JSON into Google Sheets or Excel. Every policy, every vehicle, every coverage limit in one place. No more logging into three different carrier portals.

Financial Planning Integration

Pull total premiums from GET /v1/portfolio into your budgeting tools. Track insurance spend over time alongside your other financial data.

Discount Optimization

Run GET /v1/policies/:id across all your policies. The discount analysis in each response shows what's applied, what's missing, and the estimated savings. One API call per policy tells you exactly which phone calls to make and how much each one is worth.

Agent Upload Workflow

Use POST /v1/upload to send a policy document for extraction, then poll GET /v1/policies/:id until insights are ready. Ideal for automation pipelines where an agent receives a document and needs structured data back without manual steps.

Building with OpenClaw or another MCP client? The same data is available through our MCP server. See the OpenClaw tutorial for a step-by-step walkthrough.