# COI Parse API - Complete Reference

> REST API that parses Certificate of Insurance PDFs and returns structured JSON with compliance scoring. Built for property management, construction, and staffing platforms managing 50+ vendors.

## Company Overview

COI Parse API is an InsurTech SaaS product that automates the extraction and compliance verification of Certificate of Insurance (COI) documents. The API accepts PDF uploads (ACORD 25 and ACORD 28 forms) and returns structured JSON with all extracted fields plus a compliance score against custom requirement templates.

The core problem: 70% of COIs are non-compliant on first submission. Manual review takes 8-12 minutes per certificate. A 300-vendor property management firm spends ~100 hours per employee per year on COI review. COI Parse API reduces this to seconds at $0.50 per parse vs $10-15 in staff time.

## Technical Architecture

### OCR Pipeline
1. PDF text extraction via pdfplumber (for digitally-created PDFs)
2. ACORD form field mapping using known coordinate positions
3. AI fallback via Claude Vision for scanned, stamped, or low-quality documents
4. 95%+ extraction accuracy on standard ACORD forms
5. Each result includes a confidence score

### Processing Modes
- **Synchronous**: Add sync=true to get results in the response (avg 3 seconds)
- **Asynchronous**: Returns a job ID immediately; results delivered via webhook or polling

### Webhook Delivery
- Events: parse.complete, parse.failed
- Security: HMAC-SHA256 signed payloads
- Retry: Automatic retry with exponential backoff

## Extracted Fields

### From ACORD 25 (Certificate of Liability Insurance)
- Insured: Name, address, contact info
- Insurance Carrier: Name, NAIC number
- Policy Numbers: For each coverage type
- Effective/Expiration Dates: Per policy
- Coverages:
  - Commercial General Liability (each occurrence, general aggregate, products/completed ops)
  - Automobile Liability (combined single limit, bodily injury per person/per accident)
  - Umbrella/Excess Liability (each occurrence, aggregate)
  - Workers Compensation (WC statutory limits, employer's liability)
- Additional Insured: Present/not present, endorsement details
- Certificate Holder: Name, address
- Description of Operations: Free text field

### From ACORD 28 (Evidence of Commercial Property Insurance)
- Property coverage details
- Building/contents values
- Deductibles
- Special conditions
- Mortgagee/loss payee information

## Compliance Rules Engine

Create templates with minimum requirements:
- Minimum coverage limits per type (e.g., GL each occurrence >= $1,000,000)
- Required coverage types (e.g., workers comp must be present)
- Additional insured requirement
- Policy must not be expired
- Specific carrier requirements

Each parse against a template returns:
- Overall compliance score: 0-100
- Per-field pass/fail verdicts
- List of deficiencies with descriptions
- Overall pass/fail determination

## API Reference

### Authentication
All requests require a Bearer token:
Authorization: Bearer cpk_live_your_api_key

### POST /v1/parse
Upload a COI PDF for parsing.

Request (multipart/form-data):
- file (required): PDF file
- sync (optional): "true" for synchronous processing
- template_id (optional): Compliance template ID

Response (sync):
{
  "id": "parse_abc123",
  "status": "complete",
  "form_type": "acord_25",
  "ocr_method": "pdfplumber",
  "ocr_confidence": 96.5,
  "processing_ms": 2847,
  "parsed_fields": {
    "insured": {"name": "Smith Construction LLC", "address": "..."},
    "coverages": {
      "commercial_general_liability": {
        "present": true,
        "policy_number": "GL-2026-001234",
        "effective_date": "2026-01-01",
        "expiration_date": "2027-01-01",
        "limits": {
          "each_occurrence": 1000000,
          "general_aggregate": 2000000
        }
      }
    },
    "additional_insured": {"present": true},
    "certificate_holder": {"name": "Acme Property Management LLC"}
  },
  "compliance": {
    "template_id": "tpl_xyz",
    "score": 92,
    "overall": "pass",
    "fields": [
      {"field": "gl_each_occurrence", "required": 1000000, "actual": 1000000, "result": "pass"},
      {"field": "additional_insured", "required": true, "actual": true, "result": "pass"}
    ]
  }
}

### GET /v1/jobs/{id}
Check status of an async parse job.

### POST /v1/templates
Create a compliance requirement template.

### GET /v1/templates
List all compliance templates.

### POST /v1/auth/register
Register for a free API key (50 free parses included).

## Target Markets

### Property Management
- Platforms: Buildium, AppFolio, Yardi
- Volume: 200-5,000 COIs per firm per year
- Key need: Additional insured verification, expiration alerts

### Construction Project Management
- Platforms: Procore, PlanGrid, Buildertrend
- Volume: 500-5,000 COIs per project
- Key need: Tier-1 to tier-3 subcontractor verification

### Staffing & HR
- Volume: 1,000-50,000 COIs per year
- Key need: Workers comp verification, OSHA compliance

### Franchise Operations
- Volume: Varies by franchise size
- Key need: Standardized compliance across locations

## Pricing

| Plan | Monthly | Parses Included | Overage |
|------|---------|----------------|---------|
| Pay As You Go | $0 | 50 free | $0.50/parse |
| Starter | $99 | 250 | $0.40/parse |
| Growth | $299 | 1,000 | $0.30/parse |
| Scale | $499 | 2,500 | $0.20/parse |
| Enterprise | Custom | 10,000+ | $0.10-$0.15/parse |

## FAQ

Q: What forms does COI Parse support?
A: ACORD 25 (Certificate of Liability Insurance) and ACORD 28 (Evidence of Commercial Property Insurance). These cover 80%+ of all certificates used in commercial real estate, construction, and vendor management.

Q: How accurate is the extraction?
A: 95%+ on standard ACORD forms. We use pdfplumber for clean PDFs and fall back to Claude Vision AI for scanned or low-quality documents. Each result includes a confidence score.

Q: How do compliance templates work?
A: Create a template with your minimum requirements (e.g., GL occurrence limit >= $1M, additional insured required). Every parse evaluated against a template returns a 0-100 compliance score plus per-field pass/fail verdicts.

Q: Is the original PDF stored?
A: Yes. All PDFs are stored in encrypted cloud storage for audit trail purposes. You can retrieve them via the API. Storage is included in all plans.

Q: Can I process PDFs asynchronously?
A: Yes. POST to /v1/parse returns a job ID immediately. Use webhooks to receive results, or poll /v1/jobs/{id}. For small PDFs, use sync=true for instant results.

Q: What about non-ACORD forms?
A: Our Claude Vision fallback can extract data from non-standard forms, though accuracy may be lower. We log all parse attempts to continuously improve coverage.

## Contact
- General: hello@coiparseapi.com
- Sales: sales@coiparseapi.com
- Website: https://coiparseapi.com