# Policy Extraction API

The Policy Extraction API extracts structured data from insurance policy documents (PDFs) using AI-powered parsing.

### Overview

The Policy Extraction API extracts structured data from insurance policy documents (PDFs) using AI-powered parsing. It supports multiple policy types including auto, home, umbrella, cyber, flood, workers compensation, and more. The API processes documents asynchronously and returns structured JSON data.

### Base URL

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

### Authentication

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

| Header      | Value        |
| ----------- | ------------ |
| `X-API-Key` | Your API key |

### Endpoints

#### Upload Document

Upload a policy PDF document to prepare it for extraction.

```
POST /{agent_id}/policy/extract
```

**Request body**

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

**Valid `entity_type` values:**

| Value                          | Description                  |
| ------------------------------ | ---------------------------- |
| `declaration_page`             | Declaration page (default)   |
| `auto_policy`                  | Personal auto insurance      |
| `home_policy`                  | Homeowners insurance         |
| `umbrella_policy`              | Umbrella/excess liability    |
| `cyber_security`               | Cyber security insurance     |
| `flood`                        | Flood insurance              |
| `workers_comp`                 | Workers compensation         |
| `d_and_o`                      | Directors and Officers       |
| `commercial_auto_policy`       | Commercial auto insurance    |
| `commercial_home_policy`       | Commercial property          |
| `commercial_worker_comp`       | Commercial workers comp      |
| `commercial_general_liability` | Commercial general liability |
| `commercial_flood`             | Commercial flood             |
| `commercial_umbrella`          | Commercial umbrella          |

**Response Body**

| Field           | Type    | Required | Description                             |
| --------------- | ------- | -------- | --------------------------------------- |
| `success`       | boolean | Yes      | Indicates if the request was successful |
| `extraction_id` | string  | Yes      | Unique extraction identifier            |
| document\_id    | string  | Yes      | Document UUID                           |
| agent\_id       | integer | Yes      | Agent identifier                        |
| filename        | string  | Yes      | Name of the uploaded file               |
| entity\_type    | string  | Yes      | Type of policy document                 |
| parsing\_status | string  | Yes      | Current parsing status                  |
| parsing\_method | string  | Yes      | Method used for parsing                 |
| extracted\_data | object  | Yes      | Extracted structured policy data        |
| created\_at     | string  | Yes      | Creation timestamp (ISO 8601)           |
| updated\_at     | string  | Yes      | Last update timestamp (ISO 8601)        |

**Response (200 OK)**

```json
{
  "success": true,
  "extraction_id": "ext-uuid-here",
  "document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "agent_id": 123,
  "filename": "policy_document.pdf",
  "entity_type": "auto_policy",
  "parsing_status": "completed",
  "parsing_method": "claude_api",
  "extracted_data": {
    "policy_type": "auto",
    "provider": "State Farm",
    "policy_number": "AU-2025-78432",
    "coverage_period": {
      "start_date": "Jan 15, 2025",
      "end_date": "Jul 15, 2025"
    },
    "drivers": [],
    "vehicles": [],
    "coverages": [],
    "premium": {},
    "discounts": []
  },
  "created_at": "2025-03-15T10:30:00Z",
  "updated_at": "2025-03-15T10:32:00Z"
}
```

## 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-extraction-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.