# 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)**

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

```bash
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**

```javascript
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**

```python
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)**

```json
{
  "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)**

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

<details>

<summary>400 Bad Request</summary>

Missing or invalid files.

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

</details>

<details>

<summary>401 Unauthorized</summary>

Invalid or missing API key.

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

</details>

<details>

<summary>413 Payload Too Large</summary>

Files exceed size limit (10MB per file).

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

</details>

<details>

<summary>422 Unprocessable Entity</summary>

Could not extract data from the provided documents.

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

</details>

<details>

<summary>429 Too Many Requests</summary>

Rate limit exceeded.

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

</details>

<details>

<summary>500 Internal Server Error</summary>

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

</details>

## 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: <support@insurgrid.com>
* Documentation: <https://docs.insurgrid.com>
* Status Page: <https://status.insurgrid.com>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.insurgrid.com/policy-comparison-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.