Skip to main content

​
Overview

Welcome to the AI Insurance V1 API documentation. The V1 API provides a modern, configuration-driven interface for managing your insurance operations — exposures, events, policies, quotes, and custom objects — all backed by the flexible Field Model V1 system. API Resources:
  • Exposures — Create and manage insured entities with configurable fields
  • Events — Create and manage claims and incidents with configurable fields
  • Policies — Transaction-based policy lifecycle (new business, endorsements, cancellations, reinstatements, renewals) with version history, earned premium reporting, and bordereau export
  • Quotes — Create and manage quotes, bind quotes to create policies, and send quotes to recipients
  • Custom Objects — Define and manage configurable entity types with typed relationships between objects
  • Configuration Management — Programmatic import, export, validation, and diff of company configuration via spreadsheets

​
Getting Started

​
Base URL

All API endpoints are relative to your AI Insurance instance base URL: 
https://app.aiinsurance.io

​
Route Prefix

All V1 API endpoints are served under the /api/v1/external/ path prefix. If you’re looking for legacy API endpoints, those are under /api/external/ (without the v1 segment) — see the Legacy API Reference.

​
Authentication

All API requests require authentication using an API key. Include your API key in the request headers: 
Authorization: YOUR-API-KEY
To generate an API key, see Generating API Keys.

​
Configuration-Driven Fields

V1 API entities use configurable fields defined through the Field Model system. Each entity type (exposures, events, policies) has a /configuration endpoint that returns the available fields, their types, and validation rules for your company. Always call the configuration endpoint first to understand what fields are available before creating or updating entities.

​
Example: Check Available Fields

curl -X GET \
  "https://app.aiinsurance.io/api/v1/external/companies/<YOUR-COMPANY-ID>/exposures/configuration" \
  -H "Authorization: <YOUR-API-KEY>"

​
Key Capabilities

Beyond basic CRUD, the V1 API provides several deeper capabilities:
  • Transaction-based policy lifecycle — Policies are managed through immutable transactions (new business, endorse, cancel, reinstate, renew) rather than direct mutation. Each transaction produces a new policy version, giving you a complete audit trail. See Policy Concepts and the Lifecycle Walkthrough.
  • Earned premium & bordereau — Calculate earned premium at the individual policy, list, or aggregate level. Export bordereau reports for bulk policy transaction data.
  • Quote-to-policy binding — Bind a quote to convert it into a policy, or send quotes directly to recipients.
  • Custom object relationships — Link custom objects to each other with typed relationships (one-to-one, one-to-many, many-to-one, many-to-many).
  • Spreadsheet-based configuration — Generate configuration templates, export current configuration, validate proposed changes, compare diffs, and import updates — all programmatically.

​
Quick Start Example

Here’s a simple example to create an exposure: 
curl -X POST \
  "https://app.aiinsurance.io/api/v1/external/companies/<YOUR-COMPANY-ID>/exposures" \
  -H "Authorization: <YOUR-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "exposureType": "your-exposure-type",
    "fields": {
      "name": "Example Insured",
      "email": "example@test.com"
    }
  }'

​
Audit Logging

All external API calls are automatically logged for audit and debugging purposes. The audit log captures request details, response status, and timing information.

​
Batch ID for Request Correlation

When making multiple related API calls, you can include an optional batchId field in the request body of any mutation endpoint (POST, PUT, PATCH, DELETE). This allows you to correlate and query related requests later. Key points:
  • batchId is a pass-through field — it’s not validated or part of the request schema
  • Include it at the root level of your request body
  • Use any string value that helps you identify related requests (e.g., UUID, timestamp, job ID)