API
COIProve API v1
JSON over HTTPS. One key per workspace. Everything the UI does, the API does.
Authentication
Send your key as a bearer token. Keys are created in API keys and shown once.
Authorization: Bearer ck_live_...
Extract a certificate
The workhorse endpoint. Send a PDF or plain text, receive normalized policy data.
curl -X POST https://your-host/api/v1/extract \
-H "Authorization: Bearer $COIPROVE_KEY" \
-F "file=@acord25.pdf"
{
"insured_name": "Sunrise Roofing & Exteriors LLC",
"insurers": ["Travelers Casualty and Surety Company"],
"policies": [
{
"type": "GL",
"number": "GL-4471902-01",
"effective": "2026-03-24",
"expiration": "2027-03-24",
"limits": { "each_occurrence": 1000000, "aggregate": 2000000 }
}
],
"additional_insured": true,
"waiver_of_subrogation": true,
"confidence": 0.95
}
Scanned documents
If the PDF has no text layer — or the upload is a photo of the certificate — the API runs OCR automatically and reports where the text came from.
{
"engine": "ocr:embedded-image",
"ocr": { "used": true, "available": true, "strategy": "embedded-image", "pages": 1 },
"confidence": 0.95
}
engine is pypdf, native, text,
ocr:embedded-image, ocr:rendered-page or ocr:photo.
When OCR is unavailable, ocr.strategy returns unavailable and the
document goes to manual review — it never fails silently.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/vendors | List vendors with compliance status |
| POST | /api/v1/vendors | Create a vendor |
| GET | /api/v1/vendors/{id} | Vendor detail, requirements and latest COI |
| POST | /api/v1/extract | Upload a COI (PDF) or raw text, get structured JSON |
| GET | /api/v1/compliance | Portfolio summary and score |
| GET | /healthz | Liveness and database check (no auth) |
The full machine-readable spec is at /api/v1/openapi.json.
Errors
All errors return JSON with a stable code and a human message.
{ "ok": false, "error": { "code": "invalid_api_key", "message": "Missing or revoked key." } }
Rate limits
60 requests per minute per key. Uploads are capped at 8 MB. The extract endpoint accepts one file per call.