Policy Comparison API

parsing_statusstringYesCurrent parsing status (e.g., pending, completed)Overview

The Policy Comparison API compares old (current) and new (proposed) insurance policy documents side-by-side using AI-powered analysis. It extracts structured data from both policies and generates a detailed comparison including coverage changes, premium differences, driver/vehicle changes, and agent talking points.

Base URL

https://api.insurgrid.com/api/v1/agent

Authentication

All API requests require an API key passed in the request header.

Header	Value
X-API-Key	Your API key

Endpoints

Upload Policy Document

Upload a policy PDF document for comparison. Each file (old and new) must be uploaded separately.

POST /{agent_id}/policy/upload

Content-Type: multipart/form-data

Request

Field	Type	Required	Description
file	file	Yes	The policy PDF file to upload
entity_type	string	No	Type of policy document (default: declaration_page)

Response

Field	Type	Required	Description
id	string	Yes	Unique document identifier (UUID)
filename	string	Yes	Name of the uploaded file
entity_type	string	Yes	Type of the policy document
created_at	UTC datetime string	Yes	Creation time

Response (200 OK)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "filename": "old_policy.pdf",
  "entity_type": "auto_policy",
  "parsing_status": "pending",
  "created_at": "2025-03-15T10:30:00Z"
}

---

Create Policy Comparison

Create a comparison job between old and new policy documents. The comparison runs asynchronously in the background.

POST /{agent_id}/policy/compare

Content-Type: application/json

Request Body

Field	Type	Required	Description
prospect	string	Yes	Client/prospect name
old_policies	string[]	Yes	Array of document IDs for old/current policies
new_policies	string[]	Yes	Array of document IDs for new/proposed policies

cURL Example

curl --location 'https://api.insurgrid.com/api/v1/agent/123/policy/compare' \
  --header 'X-API-Key: ig_live_abc123xyz789' \
  --header 'Content-Type: application/json' \
  --data '{
    "prospect": "John Smith",
    "old_policies": ["doc-uuid-old-1"],
    "new_policies": ["doc-uuid-new-1"]
  }'

JavaScript Example

const response = await fetch('https://api.insurgrid.com/api/v1/agent/123/policy/compare', {
  method: 'POST',
  headers: {
    'X-API-Key': 'ig_live_abc123xyz789',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prospect: 'John Smith',
    old_policies: ['doc-uuid-old-1'],
    new_policies: ['doc-uuid-new-1']
  })
});

const result = await response.json();

Python Example

import requests

url = "https://api.insurgrid.com/api/v1/agent/123/policy/compare"
headers = {"X-API-Key": "ig_live_abc123xyz789"}

payload = {
    "prospect": "John Smith",
    "old_policies": ["doc-uuid-old-1"],
    "new_policies": ["doc-uuid-new-1"]
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

Response (200 OK)

{
  "id": "comp-uuid-5678",
  "status": "processing",
  "prospect": "John Smith",
  "old_policies": ["doc-uuid-old-1"],
  "new_policies": ["doc-uuid-new-1"],
  "created_at": "2025-03-15T10:35:00Z"
}

List All Comparisons

List all policy comparisons for an agent.

GET /{agent_id}/policy/compare

Response (200 OK)

[
  {
    "id": "comp-uuid-1234",
    "status": "completed",
    "prospect": "John Smith",
    "details": { },
    "created_at": "2025-03-15T10:35:00Z"
  }
]

Response Schema

The comparison_result object contains three top-level sections:

current_or_old_policy Object

Full extraction of the old/current policy.

Field	Type	Description
policy	object	Provider, policy number, coverage period, premium, payment details
drivers	array	List of drivers with license, DOB, status, violations
vehicles	array	List of vehicles with VIN, make/model, coverages, premiums
discounts	array	Applied discounts with amounts
surcharges	array	Applied surcharges

new_policy Object

Full extraction of the new/proposed policy (same structure as above).

comparison Object

Detailed comparison between old and new policies.

Field	Type	Description
provider_changed	boolean	Whether the insurance provider changed
driver_changes	object	Added, removed, and changed drivers
vehicle_changes	object	Added, removed, replaced, and changed vehicles
premium_comparison	object	Annual, monthly, 6-month premium differences
coverage_changes_by_vehicle	array	Per-vehicle coverage and deductible changes
added_discounts	array	Discounts in new policy not in old
removed_discounts	array	Discounts in old policy not in new
savings	object	Total savings amount and description
key_changes	array	Summary of key differences
coverage_comparison_table	array	Tabular coverage comparison by vehicle
premium_difference_reasons	array	Reasons for premium changes
talking_points	array	Agent talking points for client conversations

premium_comparison Object

Field	Type	Description
annual.old	number	Old annual premium
annual.new	number	New annual premium
annual.difference	number	Premium difference
annual.percent_change	number	Percentage change
monthly.old	number	Old monthly payment
monthly.new	number	New monthly payment
monthly.difference	number	Monthly difference
six_month.old	number	Old 6-month premium
six_month.new	number	New 6-month premium
six_month.difference	number	6-month difference
per_vehicle_breakdown	array	Premium breakdown per vehicle

coverage_changes_by_vehicle Array Item

Field	Type	Description
vehicle_identifier	string	VIN or year/make/model
coverage_changes	array	Changed coverage types with old/new values
deductible_changes	array	Changed deductibles with old/new values
added_coverages	array	Coverages in new but not old policy
removed_coverages	array	Coverages in old but not new policy
missing_coverages	array	Coverages that should be considered

driver_changes Object

Field	Type	Description
added_drivers	array	Drivers in new policy only
removed_drivers	array	Drivers in old policy only
changed_drivers	array	Drivers with changed details
driver_count_change	object	Old count, new count, difference

vehicle_changes Object

Field	Type	Description
added_vehicles	array	Vehicles in new policy only
removed_vehicles	array	Vehicles in old policy only
replaced_vehicles	array	Vehicles swapped between policies
changed_vehicles	array	Vehicles with changed details
vehicle_count_change	object	Old count, new count, difference

How It Works

1. Upload Documents — Upload both the old/current policy and new/proposed policy PDFs using the upload endpoint. Note the returned document_id for each.

2. Create Comparison — Call the comparison endpoint with the prospect name and arrays of old and new document IDs. The API returns a comparison_id and begins processing in the background.

3. AI Analysis — The system generates presigned URLs for all documents and sends them to Claude AI with a structured comparison prompt. Claude extracts data from both policies and generates a comprehensive comparison.

4. Poll for Results — Use the status endpoint to check when processing is complete.

5. Retrieve Results — Once completed, fetch the full comparison result with extracted policy data and detailed diff analysis.

6. Real-time Updates — The API also sends real-time events via Pusher when comparison completes or errors, allowing for webhook-based notification instead of polling.

Error Responses

400 Bad Request

Missing or invalid files.

{
  "error": "bad_request",
  "message": "Input not valid"
}

401 Unauthorized

Invalid or missing API key.

{
  "error": "unauthorized",
  "message": "Invalid API key"
}

413 Payload Too Large

Files exceed size limit (10MB per file).

{
  "error": "payload_too_large",
  "message": "File size exceeds 50MB limit"
}

422 Unprocessable Entity

Could not extract data from the provided documents.

{
  "error": "extraction_failed",
  "message": "Unable to extract data",
  "details": "PDF appears to be image-only without extractable text"
}

429 Too Many Requests

Rate limit exceeded.

{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Try again in 60 seconds",
  "retry_after": 60
}

500 Internal Server Error

{
  "error": "internal_error",
  "message": "An unexpected error occurred"
}

Rate Limits

Plan	Requests/minute	Requests/day
Free	5	50
Pro	30	1,000
Enterprise	Custom	Custom

Rate limit headers are included in all responses:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1699574400

Supported Document Types

Type	Extensions	Notes
PDF	.pdf	Recommended. Supports text and scanned documents via OCR
Image	.jpg, .png	Single page documents only

Changelog

Version	Date	Changes
1.0.0	2024-11	Initial release

Support

• Email: [e-mail]

• Documentation: https://docs.insurgrid.com

• Status Page: https://status.insurgrid.com