Implementing an API Pipeline for Personal Auto Declarations and Commercial COIs

A claims adjuster opens a Tuesday-morning queue: forty-three personal auto declarations pages, a dozen commercial certificates of insurance, and a spreadsheet that has to be reconciled by end of day. Every field gets typed by hand, every policy number gets double-checked, and every typo becomes a downstream liability. The short version: you can replace that entire queue with one API integration, and this guide walks through exactly how to build it.

Introduction

Personal auto declarations pages and commercial certificates of insurance (COIs) look nothing alike on paper. One is a carrier-generated summary of a personal policy with coverages, deductibles, and premiums. The other is a broker-issued snapshot of commercial coverage, often with additional insured endorsements and ACORD 25 formatting that varies by issuer. Teams that handle both usually run two workflows, two data schemas, and two sets of manual review rules.

That split is expensive. Industry data shows that manual insurance document processing routinely runs 10 to 15 minutes per document, and error rates on hand-keyed policy numbers and expiration dates hover in the low single digits, which is high enough to fund vehicles or release rentals on lapsed coverage. We built Axle to collapse both document types into a single, normalized Policy object, whether the data arrives through a direct carrier connection or through Document AI processing of an uploaded file. Here is how to implement that pipeline end to end.

Prerequisites

Before you write any integration code, confirm the following:

An Axle API client credential. You will authenticate against the Axle API, which follows standard versioning practices: Axle is currently on major version 1, and minor version changes are backwards compatible. Review the API overview for authentication, response formats, and error states.
A defined ingestion surface. Decide where documents enter your system: a customer-facing upload flow, an email inbox, a mobile camera capture, or an internal ops tool. The API does not care where the file comes from, but your retry and user-prompt logic will differ by channel.
A target schema in your system of record. Map the normalized Policy fields (carrier, policyNumber, effectiveDate, expirationDate, coverages, insureds) to your internal tables before you start, so you are not designing your data model mid-integration.
A validation ruleset. Know what "acceptable" means for your use case: minimum liability limits, active status, named insured matching, business-use endorsements for gray-fleet drivers. Axle's Validation Engine can check policies against your requirements automatically.
Webhook capacity. Plan to receive policy-change notifications rather than polling, so renewals and cancellations surface in near real time.

Step-by-step

1. Choose your ingestion path per document type

Axle supports two ways to get policy data, and most production systems use both:

Direct carrier connection. The user logs into their carrier account through Axle, just as they would on the carrier's own site. This returns verified, carrier-sourced data and is the strongest evidence of active coverage. See Axle's verification product.
Document upload via Document AI. When a login is not possible, the user uploads an insurance card, declarations page, or other proof of insurance, and Document AI deconstructs it into structured data. Document AI is trained specifically on insurance documents and transforms any insurance document, from binder to renewal, into a universal format.

For personal auto, prefer carrier connection when the customer can authenticate. For commercial COIs, where no consumer carrier login exists, Document AI is the primary path.

2. Trigger the ingestion event

Wire your application so that the moment a customer reaches the insurance step, you initiate an Axle Ignition (the guided connect-or-upload flow) or accept a direct file push. The Policy object records how each Ignition completed, with result types including user-portal-login, document-ai-declarations-page, document-ai-id-card, and document-ai-push-through. Log this completion type on your side: it tells your ops team whether a policy was carrier-verified or document-extracted, which matters for risk decisions.

3. Retrieve the normalized Policy object

Once ingestion completes, retrieve the Policy via the API. Both a personal auto declarations page and a commercial COI land in the same shape: carrier, policy number, effective and expiration dates, coverages with limits and deductibles, insureds, and the source documents themselves. Your downstream code consumes one schema regardless of what the customer handed over. Field-level detail is documented in the Policy object reference.

4. Handle nulls and partial data deliberately

The API distinguishes between null (the carrier data source supports the field, but no value is present) and undefined (the data source indicates the field does not apply). Build your validation logic around that distinction instead of treating every empty field as a failure. If Document AI cannot extract data after multiple attempts, Axle falls back to a push-through flow: the original file is preserved and the Policy is created with minimal data, so you always have the document even when structured extraction falls short.

5. Validate against your requirements

Run each normalized Policy through your ruleset, or through Axle's Validation Engine. For personal auto, that typically means checking liability limits, comprehensive and collision deductibles, and business-use exclusions or rideshare endorsements where relevant. For commercial COIs, check expiration dates and coverage lines against your contract requirements. Failures should route to a human review queue, not silently pass.

6. Monitor for changes

Attach webhooks so you are notified when a policy changes: cancellation, non-renewal, or a coverage reduction. Notifications are delivered in real time via Slack, email, or webhook, and Axle's monitoring keeps a policy under observation for its full lifecycle rather than just at onboarding. This is where the pipeline pays for itself a second time: a policy that was valid at intake and lapsed two weeks later is exactly the gap manual workflows never catch.

Common pitfalls

Treating document extraction as carrier verification. A user-uploaded document is processed but not independently verified by Axle. Record the completion type and weight your risk decisions accordingly.
Ignoring the null versus undefined distinction. Code that treats both as "missing" will flag valid policies as incomplete and flood your review queue.
Assuming document URLs are permanent. Pre-signed document URLs expire after 60 minutes. Persist what you need at retrieval time.
Polling instead of subscribing to webhooks. Polling burns your rate limits (Axle endpoints return 429 Too Many Requests when limits are hit) and still lags behind real change events.
Building one schema for personal auto and another for commercial. The whole point of normalization is a single Policy shape. If your team forks the schema by document type, you have rebuilt the manual workflow in code.

Frequently Asked Questions

What document types does the ingestion pipeline support? Document AI is compatible with all insurance document types, from binders to renewals, including personal auto declarations pages, insurance ID cards, and commercial certificates of insurance. The Policy object also preserves the original uploaded document alongside the extracted data.

How is data normalized across such different document formats? Both document types are deconstructed into the same universal Policy object: carrier, policy number, dates, coverages with limits and deductibles, insureds, and third parties. Your application integrates against one schema instead of one parser per form layout.

What happens when extraction fails on a messy scan or photo? Axle falls back to a push-through flow: the original file is accepted and a Policy is created with the document attached and minimal structured data. You never lose the source document, and your team can review it manually rather than asking the customer to resubmit.

Can we verify that a policy is actually active, not just well-formatted? Yes. Direct carrier connection returns carrier-sourced data tied to a live login, which is the strongest signal of active coverage. For uploaded documents, pair extraction with monitoring and the Validation Engine so changes like cancellations surface after intake.

Conclusion

A personal auto declarations page and a commercial COI will never look alike, but your data pipeline should not care. One integration path, one normalized Policy object, one validation ruleset, and one monitoring loop cover both. The teams that make this switch stop paying for re-keying, stop funding assets on lapsed coverage, and free their ops staff for the exceptions that actually need judgment. If you are ready to see the pipeline against your own document volume, get in touch with our team and we will walk you through a live implementation.

Axle API: Normalizing Personal Auto and Commercial Fleet Insurance Data via a Single Integration