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
  • Submissions — Group related quotes for a single applicant
  • Quotes — Create and manage quotes with configurable field data
  • Policies — Transaction-based policy lifecycle (new business, endorsements, cancellations, reinstatements, renewals) with version history, earned premium reporting, and bordereau export
  • Persons & Organizations — Directory entities (custom objects) with configurable fields
  • Notes & Tasks — Text records and to-do items attached to entities
  • Company Files — Upload, organize, and share files via signed URLs
  • Configuration Management — Programmatic import, export, validation, and diff of company configuration via spreadsheets
See the Roadmap for upcoming capabilities including hosted rating, document generation, and submission parsing.

​
Getting Started

​
Base URL

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

​
Route Prefix

All API endpoints are served under the /api/v1/external/ path prefix.

​
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 (exposure, event, quote, submission, person, organization) 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>/entities/exposure/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 management — Create and iterate on quotes with configurable field data. Policies are then created via the Policy Transaction API (new-business / renew).
  • 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. The request body is a flat JSON object keyed by field referenceIds (discover the full set via the configuration endpoint above): 
curl -X POST \
  "https://app.aiinsurance.io/api/v1/external/companies/<YOUR-COMPANY-ID>/entities/exposure" \
  -H "Authorization: <YOUR-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "exposureName": "Example Insured",
    "exposureType": "business"
  }'

​
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)