# FAQs Source: https://docs.aiinsurance.io/FAQs/FAQs If a previously sent invoice was updated after you processed an endorsement, this can cause mismatched totals between your **Financials tab** and **Unallocated Funds (Over/Under)** balance. **How to resolve this:** 1. **Create a Manual Invoice**: Create a new invoice in AI Insurance for the **exact amount** of the excess or affected funds. For instructions, see [Generating One-Off Invoices](/financials/invoicing/generating-one-off-invoices). 2. **Capture the Unallocated Funds**: Use the **Capture Unallocated Funds** action to apply the funds to that manual invoice. For detailed instructions, see [Capturing Unallocated Funds](/platform/companies/cash-management/capturing-unallocated-funds). 3. **Process the Refund Externally**: After capturing the funds, issue the refund through your external accounting or payment system (for example, via check or ACH). 4. **Void the Invoice in AI Insurance**: Once the refund has been processed, **void** the manual invoice in AI Insurance to clear the transaction and maintain accurate financial records. **Additional steps:** * If upcoming scheduled invoices are incorrect or not needed, **void them** to prevent automatic issuance When a client overpays and you have excess funds in your **Unallocated Funds (Over/Under)** balance, you can capture these funds by creating a manual invoice and then processing a refund. **Step-by-step solution:** 1. **Create a Manual Invoice**: Create a new invoice in AI Insurance for the **exact amount** of the excess funds you want to capture. For instructions, see [Generating One-Off Invoices](/financials/invoicing/generating-one-off-invoices). 2. **Capture the Unallocated Funds**: Use the **Capture Unallocated Funds** action to apply the excess funds to that manual invoice. For detailed instructions, see [Capturing Unallocated Funds](/platform/companies/cash-management/capturing-unallocated-funds). 3. **Process the Refund Externally**: After capturing the funds, issue the refund through your external accounting or payment system (for example, via check or ACH transfer). 4. **Document the Refund (Choose one option)**: * **Option A**: Create an additional negative invoice to indicate a collection and refund. This provides a clear audit trail for the refund transaction. * **Option B**: Leave the invoice as is. The invoice will remain in the system to document the transaction. **Additional options:** * **Void Scheduled Invoices**: If you don't want upcoming scheduled invoices to be sent automatically, you can **void them** to prevent automatic issuance. * **Repeat the Process**: If clients continue to overpay on future invoices, you can repeat this process (create custom transaction + capture) for each occurrence. **Automatic Return**: If you take no action on overpaid unallocated funds, the system will automatically return the funds to the client after **30 days**. When a policy with premium billing is endorsed and the premium changes, AI Insurance automatically updates the billing schedule and invoices. **How Invoice Voiding Works:** **For Recurring / Installment Billing:** * When an endorsement changes the premium, the system voids and re-schedules any **future scheduled invoices** according to the new billing schedule. * **Sent invoices are not voided** as part of this process. **For Annual Invoices:** * The system voids and re-issues the annual invoice when the policy billing changes after binding. * **Sent invoices are not voided** as part of this process. **Key Rules:** * If an invoice has been **sent**, the system will **not void it** as part of an endorsement. * Only **scheduled (unsent) invoices** are voided and rescheduled when the premium changes. * This rule applies to both annual billing and installment (recurring) billing. **Void Reasons:** The system tracks void reasons for invoices: * **Invoice voided through Stripe**: Indicates the invoice was voided through Stripe or our UI that calls Stripe. * **Policy Billing Updated**: Indicates the invoice was voided as part of a billing update on the policy. You can resend an invoice in two ways, depending on how it was originally created: **For AI-Generated Invoices:** If the invoice was generated automatically by AI Insurance: 1. Navigate to **Financials** → **Transactions** 2. Open the invoice you want to re-send 3. Copy the invoice link 4. Email the link directly to the insured **For Manual Invoices:** If the invoice was created manually or does not include a link, you'll need to generate a payment form to collect payment: 1. Keep the existing invoice (do not void it) 2. Generate a payment form using **Forms** and apply it to the policy through an endorsement 3. Send the form link to the insured so they can pay 4. Once payment lands in your bank account, manually mark the invoice as **Paid** For detailed step-by-step instructions on resending invoices and generating one-off invoices, see [Generating One-Off Invoices](/financials/invoicing/generating-one-off-invoices). If you have a policy that was originally set up as **agency bill** but you decide after the fact that you want to collect payment directly from the insured (direct bill), you need to void the existing invoice and create a new manual invoice. **Note**: This is the only scenario where you should void an existing invoice. For all other cases, keep the existing invoice and use the standard one-off invoice process. **Step-by-step process:** 1. **Void the Agency Bill Invoice**: * Navigate to **Financials** → **Transactions** * Find the agency bill invoice you need to void * Select the checkbox next to the invoice * Click the **"Mark As"** dropdown button and select **"Void"** * Confirm the void action **Important**: Voiding an invoice cannot be undone. The original invoice will be marked as cancelled and will no longer be active for billing purposes. 2. **Generate a Payment Form**: * Open the policy associated with the original invoice * Navigate to the **Forms** section * Create a new form with billing details and ACH information * Apply the form to the policy through an endorsement * The form will be sent directly to the client (insured) instead of the broker 3. **Create a New Transaction (Manual Invoice)**: * Follow the manual invoice creation steps to create a new transaction * Fill in the invoice details matching the voided invoice 4. **Mark Invoice as Paid** (once payment is received): * Navigate to **Financials** → **Transactions** * Find the invoice you created * Select the checkbox next to the invoice * Click the **"Mark As"** dropdown button * Select **"Paid"** to mark the invoice as paid For detailed step-by-step instructions with screenshots and additional information, see [Generating One-Off Invoices](/financials/invoicing/generating-one-off-invoices). The **Company Payees** section and the payee dropdowns when adding payees to **Policies** or **Events** show different sets of payees because they serve different purposes. **Company Payees Section:** * Only displays **payee-type payees** — these are payees that are manually added as designated payees at the company level (such as law firms, vendors, and experts) * These are the payees you manage in your company settings * For more details, see [Payees](/platform/companies/payees/payees) **Policy/Event Payee Dropdowns:** * Include a broader set of payees that may apply to that specific transaction type: * **Insureds** — the parties being insured * **Brokerages** — the brokerage firms associated with policies * **Payee-type payees** — the manually added company-level payees **Why the difference?** * Insureds and brokerages are **not** considered "payee-type payees" * They appear in Policy/Event dropdowns because they may receive payments for those specific transactions * However, they do not appear in the main Company Payees list because they are managed separately as Insureds and Brokerages in your company settings If your invoice email is being returned or not processed, it is usually because the sending email address is not authorized for the company you are submitting invoices for. AI Insurance only accepts invoice emails from addresses that are added as payees for the associated company. If your email address is not listed as a payee, the system will reject the email and return an error message. **What should I check?** Before sending an invoice by email, please make sure that: * Your email address is added as a payee in the AI Insurance platform for the correct company. For more information, see [Payees](/platform/companies/payees/payees) * The invoice is sent as a PDF attachment * The invoice is sent to the correct invoice email address * The email address is entered using all lowercase characters Deposits may take longer to process and appear in the Cash Manager. Transactions typically show up within **5-7 days** after the deposit is initiated. **What to expect:** * Deposits are processed through the operating account * Transaction history will update once the deposit is fully processed * You can view pending and completed transactions in the **Transaction History** section of the Cash Management page For more information about Cash Management, see [Cash Management](/platform/companies/cash-management/cash-management). # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/assignees/overview Assignees allow you to track which users in your organization are responsible for a given entity. The Assignees API supports listing and setting assignees for policies, submissions, insureds, and events. **Key Concepts:** * Assignees are users within your organization assigned to an entity * An entity can have multiple assignees * Setting assignees is a **full replacement** — the provided list replaces any existing assignees * Removed assignees are soft-deleted, preserving an audit trail of assignment history *** ## API Endpoints * **[List Assignees](/api-reference/assignees/list-assignees)** - Retrieve assignees for an entity * **[Set Assignees](/api-reference/assignees/set-assignees)** - Set assignees for an entity (full replace) *** ## Entity Types Assignees can be managed on four entity types: | Entity Type | Read Permission | Update Permission | | ------------- | ------------------------- | ------------------- | | `policies` | `company.policy:read` | `policy:update` | | `submissions` | `company.submission:read` | `submission:update` | | `insureds` | `company.insured:read` | `insured:update` | | `events` | `company.claim:read` | `claim:update` | *** ## Full Replace Semantics The Set Assignees endpoint uses **full replace** semantics. The array of user IDs you provide completely replaces the current assignees. **Assign users:** ```json theme={null} { "assigneeIds": ["google-oauth2|123456789", "google-oauth2|987654321"] } ``` **Remove all assignees:** ```json theme={null} { "assigneeIds": [] } ``` All user IDs in `assigneeIds` must correspond to existing users in your organization. The API returns an error if any user ID is not found. *** ## Example Response ```json theme={null} { "items": [ { "id": "google-oauth2|123456789", "name": "John Smith", "email": "john@example.com", "assignedAt": "Thu Mar 20 2026 14:30:00 GMT+0000 (Coordinated Universal Time)" }, { "id": "google-oauth2|987654321", "name": "Jane Doe", "email": "jane@example.com", "assignedAt": "Sat Mar 21 2026 09:15:00 GMT+0000 (Coordinated Universal Time)" } ], "totalCount": 2 } ``` *** # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/attorneys/overview Attorneys represent legal professionals involved in insurance claims and lawsuits. The Attorneys API allows you to programmatically create, read, update, and delete attorney information within your company. **Key Concepts:** * Attorneys are company-scoped, reusable entities that can be associated with lawsuits * An attorney can serve as plaintiff counsel (on a lawsuit) or defense counsel (on a defendant) * Attorneys can optionally be linked to a law firm payee via `lawFirmId` *** ## API Endpoints * **[List Attorneys](/api-reference/attorneys/list-attorneys)** - Retrieve paginated list of attorneys with filtering and sorting * **[Create Attorney](/api-reference/attorneys/create-attorney)** - Create a new attorney * **[Get Attorney](/api-reference/attorneys/get-attorney)** - Retrieve a single attorney by ID * **[Update Attorney](/api-reference/attorneys/update-attorney)** - Update an existing attorney * **[Delete Attorney](/api-reference/attorneys/delete-attorney)** - Soft delete an attorney *** ## Nullable Fields The following fields may be `null` in the response: | Field | When null | | ------------- | -------------------------------------- | | `email` | Email not provided | | `phoneNumber` | Phone number not provided | | `lawFirmId` | No associated law firm | | `createdAt` | Timestamp not tracked (legacy records) | | `updatedAt` | Attorney has never been updated | *** ## Filtering and Sorting ### Filter Parameters | Parameter | Type | Description | | ------------ | --------------- | --------------------------------- | | `id` | string or array | Filter by specific attorney ID(s) | | `filterText` | string | Text search across attorney name | ### Sorting Parameters | Parameter | Type | Default | Description | | --------------- | ------ | ----------- | --------------------------------------------------- | | `sortBy` | string | `createdAt` | Field to sort by (`createdAt`, `updatedAt`, `name`) | | `sortDirection` | string | `desc` | Sort direction (`asc` or `desc`) | ### Pagination | Parameter | Type | Default | Description | | --------- | ------- | ------- | ----------------------------------- | | `page` | integer | 1 | Page number (1-based, page size 50) | **Response includes:** * `items` - Array of attorneys for the current page * `totalCount` - Total number of matching attorneys across all pages *** ## Permissions Access to attorneys requires the appropriate permissions based on your API key: | Operation | Required Permission | | --------------- | ------------------------- | | List Attorneys | `company.attorney:read` | | Get Attorney | `company.attorney:read` | | Create Attorney | `company.attorney:create` | | Update Attorney | `company.attorney:update` | | Delete Attorney | `company.attorney:delete` | *** ## Example Response ```json theme={null} { "items": [ { "id": "550e8400-e29b-41d4-a716-446655440001", "companyId": "660e8400-e29b-41d4-a716-446655440000", "name": "Jane Smith", "email": "jane@smithlaw.com", "phoneNumber": "+1-555-123-4567", "lawFirmId": "770e8400-e29b-41d4-a716-446655440000", "createdAt": "2026-01-15T10:30:00.000Z", "updatedAt": "2026-01-16T14:20:00.000Z" } ], "totalCount": 1 } ``` *** # Generating API Keys Source: https://docs.aiinsurance.io/api-legacy-reference/authentication ## How to Generate API Keys API keys allow you to programmatically access your AI Insurance data and integrate with external systems. This guide shows you how to generate API keys from your company settings. ## Step-by-Step Instructions ### Step 1: Access Company Settings 1. Log into your AI Insurance account at [https://app.aiinsurance.io](https://app.aiinsurance.io) 2. In the left sidebar, find and click on your company name (e.g., "Demo Insurance Inc.") 3. This will open the company settings page ### Step 2: Navigate to API Keys 1. In the company settings, look for the navigation bar 2. Click on the **"API Keys"** tab 3. Once you're on the **API Keys** page, you will see: * A table of any existing API keys * A button to create a new API key * Your **Company ID** at the bottom of the page (this ID is required in most API requests) Find api key ### Step 3: Create Your API Key 1. Click the purple **"+ Create New API Key"** button 2. You'll be prompted to enter: * **Key Name**: A descriptive name for your API key (e.g., "Production Integration", "Testing API") * **Description**: Optional description of what this key will be used for add key ### Step 4: Save Your API Key 1. After creating the key, you'll receive your API key 2. **Store it securely** - API keys grant access to your company's data **Authentication Header Format** When making API requests, include your API key in the Authorization header: ``` Authorization: YOUR-API-KEY ``` **Correct:** ```bash theme={null} -H "Authorization: abc123xyz789" ``` **Incorrect:** ```bash theme={null} -H "Authorization: Bearer abc123xyz789" ❌ -H "X-API-Key: abc123xyz789" ❌ ``` *** ## Using Your API Key Now that you have your API key, you can use it to access the AI Insurance External API. This API allows you to programmatically manage your insurance operations including submissions, quotes, policies, and more. ### Getting Started with the API **[See the API Overview for complete documentation](/api-legacy-reference/overview)** - This includes: * All available API resources and endpoints * Quick start examples * Request/response formats * Data models reference ### What You Can Do with the API Once you have your API key, you can: * **Submissions**: Create, update, and list insurance submissions * **Quotes**: Retrieve quote information (lightweight or full details) * **Configuration**: Access your company's rating fields and coverage types * **More coming soon**: Policies, Events, Insureds, Financials ### Example: Using Your API Key With your API key, you can make requests like: ```bash theme={null} curl -X GET \ "https://app.aiinsurance.io/api/external/companies/YOUR-COMPANY-ID/submissions" \ -H "Authorization: YOUR-API-KEY" ``` # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/brokerages/overview Brokerages represent insurance agencies or brokers that sell insurance on behalf of an MGA or Insurer running their program on the AI Insurance platform. The Brokerages API allows you to programmatically create, read, update, and delete brokerage information, including commission payment settings. **Key Concepts:** * Brokerages are insurance agencies or brokers that sell insurance on behalf of an MGA or Insurer * Each brokerage has a **commission payment method** that determines how commissions are handled * Brokerages can have contact information including email, phone, and structured address * A **default commission percentage** can be set for each brokerage *** ## API Endpoints * **[List Brokerages](/api-reference/brokerages/list-brokerages)** - Retrieve paginated list of brokerages with filtering and sorting * **[Get Brokerage](/api-reference/brokerages/get-brokerage)** - Retrieve a single brokerage by ID * **[Create Brokerage](/api-reference/brokerages/create-brokerage)** - Create a new brokerage * **[Update Brokerage](/api-reference/brokerages/update-brokerage)** - Update an existing brokerage * **[Delete Brokerage](/api-reference/brokerages/delete-brokerage)** - Soft delete a brokerage *** ## Commission Payment Methods Each brokerage must have a commission payment method that determines how commissions are processed: | Method | Description | | ------------- | --------------------------------------------------------------------------- | | `agencyBill` | The brokerage collects premiums and remits net of commission to the carrier | | `directBill` | The carrier bills the insured directly and pays commission to the brokerage | | `doNotHandle` | Commissions are not processed through the system | *** ## Structured Address The `addressStructured` field contains a structured address object with the following fields: | Field | Type | Description | | --------- | ------ | -------------------------------- | | `line1` | string | Street address line 1 | | `line2` | string | Street address line 2 (optional) | | `city` | string | City | | `state` | string | State or province | | `zip` | string | ZIP or postal code | | `country` | string | Country code | *** ## Nullable Fields The following fields may be `null` in the response: | Field | When null | | ----------------------------- | -------------------------------------- | | `niprBrokerageNumber` | NIPR number not provided | | `email` | Email not provided | | `addressStructured` | Address not provided | | `phone` | Phone number not provided | | `defaultCommissionPercentage` | Default commission not configured | | `createdAt` | Timestamp not tracked (legacy records) | | `updatedAt` | Brokerage has never been updated | *** ## Filtering and Sorting List endpoints support comprehensive filtering and sorting options: ### Filter Parameters | Parameter | Type | Description | | ------------ | --------------- | ------------------------------------------- | | `id` | string or array | Filter by specific brokerage ID(s) | | `filterText` | string | Text search across brokerage name and email | ### Sorting Parameters | Parameter | Type | Default | Description | | --------------- | ------ | ----------- | ------------------------------------------------------------------------------------------- | | `sortBy` | string | `createdAt` | Field to sort by (`createdAt`, `updatedAt`, `name`, `email`, `defaultCommissionPercentage`) | | `sortDirection` | string | `desc` | Sort direction (`asc` or `desc`) | ### Pagination | Parameter | Type | Default | Description | | --------- | ------- | ------- | ----------------------------------- | | `page` | integer | 1 | Page number (1-based, page size 50) | **Response includes:** * `items` - Array of brokerages for the current page * `totalCount` - Total number of matching brokerages across all pages *** ## Permissions Access to brokerages requires the appropriate permissions based on your API key: | Operation | Required Permission | | ---------------- | -------------------------- | | List Brokerages | `company.brokerage:read` | | Get Brokerage | `company.brokerage:read` | | Create Brokerage | `company.brokerage:create` | | Update Brokerage | `company.brokerage:create` | | Delete Brokerage | `brokerage:update` | *** ## Example Response ```json theme={null} { "items": [ { "id": "550e8400-e29b-41d4-a716-446655440001", "name": "Acme Insurance Agency", "commissionPaymentMethod": "agencyBill", "niprBrokerageNumber": "12345678", "email": "contact@acmeagency.com", "addressStructured": { "line1": "123 Main Street", "line2": "Suite 100", "city": "New York", "state": "NY", "zip": "10001", "country": "US" }, "phone": "+1-555-123-4567", "defaultCommissionPercentage": 15, "createdAt": "2025-01-15T10:30:00.000Z", "updatedAt": "2025-01-16T14:20:00.000Z" } ], "totalCount": 42 } ``` *** # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/brokers/overview Brokers are individual agents or producers associated with a brokerage. The Brokers API allows you to programmatically create, read, update, and delete broker information within your company. **Key Concepts:** * Brokers are individual agents who work under a **brokerage** * Each broker must be associated with an existing brokerage via `brokerageId` * Brokers can have their own contact information, commission percentage, and producer number * A broker may optionally have an associated **user ID** for portal access *** ## API Endpoints * **[List Brokers](/api-reference/brokers/list-brokers)** - Retrieve paginated list of brokers with filtering and sorting * **[Get Broker](/api-reference/brokers/get-broker)** - Retrieve a single broker by ID * **[Create Broker](/api-reference/brokers/create-broker)** - Create a new broker * **[Update Broker](/api-reference/brokers/update-broker)** - Update an existing broker * **[Delete Broker](/api-reference/brokers/delete-broker)** - Soft delete a broker *** ## Broker vs Brokerage | Entity | Description | | ------------- | --------------------------------------------------------------------- | | **Brokerage** | An insurance agency or broker organization (company level) | | **Broker** | An individual agent/producer who works for a brokerage (person level) | A brokerage can have multiple brokers, but each broker belongs to exactly one brokerage. *** ## Structured Address The `addressStructured` field contains a structured address object with the following fields: | Field | Type | Description | | --------- | ------ | -------------------------------- | | `line1` | string | Street address line 1 | | `line2` | string | Street address line 2 (optional) | | `city` | string | City | | `state` | string | State or province | | `zip` | string | ZIP or postal code | | `country` | string | Country code | *** ## Nullable Fields The following fields may be `null` in the response: | Field | When null | | ----------------------------- | -------------------------------------- | | `email` | Email not provided | | `phone` | Phone number not provided | | `workPhone` | Work phone not provided | | `addressStructured` | Address not provided | | `defaultCommissionPercentage` | Default commission not configured | | `producerNumber` | Producer number not assigned | | `userId` | Broker does not have portal access | | `createdAt` | Timestamp not tracked (legacy records) | | `createdBy` | Created by system or unknown user | | `updatedAt` | Broker has never been updated | | `updatedBy` | Never updated or updated by system | *** ## Filtering and Sorting List endpoints support comprehensive filtering and sorting options: ### Filter Parameters | Parameter | Type | Description | | ------------- | --------------- | ------------------------------- | | `id` | string or array | Filter by specific broker ID(s) | | `brokerageId` | string | Filter by brokerage ID | | `filterText` | string | Text search across broker name | ### Sorting Parameters | Parameter | Type | Default | Description | | --------------- | ------ | ----------- | ------------------------------------------------------------------------------------------- | | `sortBy` | string | `createdAt` | Field to sort by (`createdAt`, `updatedAt`, `name`, `email`, `defaultCommissionPercentage`) | | `sortDirection` | string | `desc` | Sort direction (`asc` or `desc`) | ### Pagination | Parameter | Type | Default | Description | | --------- | ------- | ------- | ----------------------------------- | | `page` | integer | 1 | Page number (1-based, page size 50) | **Response includes:** * `items` - Array of brokers for the current page * `totalCount` - Total number of matching brokers across all pages *** ## Permissions Access to brokers requires the appropriate permissions based on your API key: | Operation | Required Permission | | ------------- | ----------------------- | | List Brokers | `company.broker:read` | | Get Broker | `broker:read` | | Create Broker | `company.broker:create` | | Update Broker | `broker:update` | | Delete Broker | `company.broker:create` | *** ## Example Response ```json theme={null} { "items": [ { "id": "550e8400-e29b-41d4-a716-446655440001", "companyId": "660e8400-e29b-41d4-a716-446655440000", "brokerageId": "770e8400-e29b-41d4-a716-446655440000", "name": "John Smith", "email": "john.smith@acmeagency.com", "phone": "+1-555-123-4567", "workPhone": "+1-555-123-4568", "addressStructured": { "line1": "123 Main Street", "line2": "Suite 100", "city": "New York", "state": "NY", "zip": "10001", "country": "US" }, "defaultCommissionPercentage": 15, "producerNumber": "PRD-12345", "userId": null, "createdAt": "2025-01-15T10:30:00.000Z", "createdBy": "880e8400-e29b-41d4-a716-446655440000", "updatedAt": "2025-01-16T14:20:00.000Z", "updatedBy": "880e8400-e29b-41d4-a716-446655440000" } ], "totalCount": 42 } ``` *** # API Changelog Source: https://docs.aiinsurance.io/api-legacy-reference/changelog Track updates and improvements to the AI Insurance API ## Product updates New updates and improvements to the AI Insurance REST API. *** ## September 25 2026 ### Export Presets API **Added** * `GET /api/external/companies/{companyId}/export-presets` — List every export preset saved by any user of the company. Each preset returns its `entityType` and `name` (nullable for legacy presets saved without them), ordered `fieldKeys`, and `owner` (`{ id, name, email }` or `null`). Accepts an optional `entityType` query filter; not paginated. Requires `company.export_preset:read`. *** ## May 13 2026 ### Configuration Rating Outputs API **Changed** * `POST /api/external/companies/{companyId}/configuration/rating/outputs` and `GET /api/external/companies/{companyId}/configuration/rating/outputs` — Field definitions now accept and return an optional `smartTagsNeeded` boolean. When `true`, the rater pushes this field's output into the smart-tag bucket at rating time, allowing the auto-created `AII{key}PrimaryInsured` smart tag to resolve a value. When omitted or `false`, the field is still displayed but the smart tag resolves to `null`. ### Submissions API **Added** * `GET /api/external/companies/{companyId}/submissions/{submissionId}/loss-history` — Retrieve the loss history entries on a submission. Returns `{ items: LossHistoryEntry[], totalCount: number }` or `{ items: [], totalCount: 0 }` when no loss history has been set. Requires `company.submission:read`. * `POST /api/external/companies/{companyId}/submissions/{submissionId}/loss-history` — Append entries to a submission's loss history without replacing existing ones. Same request shape as PUT (`{ history: LossHistoryEntry[] }`), but entries are added to the end. Requires at least one entry; rejects unknown fields. Requires `submission:update`. *** ## May 12 2026 ### Submissions API **Added** * `PUT /api/external/companies/{companyId}/submissions/{submissionId}/loss-history` — Set (replace) the loss history on a submission. Accepts `{ history: LossHistoryEntry[] }` where each entry has a `year` and claim `data` (only `totalIncurred` is required). Returns `{ success: true }`. For FMV1-enabled companies, automatically recomputes computed loss history fields on associated quotes. Requires `submission:update`. *** ## May 8 2026 ### Submissions API **Changed** * `POST /api/external/companies/{companyId}/submissions/{submissionId}/files` — Now accepts files of any content type, not just `application/pdf`. The `400 UnsupportedFileType` error has been removed. The multipart field name changed from `files` to `file`. *** ## April 28 2026 ### Submissions API **Added** * `POST /api/external/companies/{companyId}/submissions/{submissionId}/files` — Attach one or more PDF files to an existing submission. Accepts `multipart/form-data` with each file in a part named `files`; non-PDF content types are rejected with `400 UnsupportedFileType`. Returns `201 { fileIds: string[] }` with IDs in upload order. Files appear in the submission's Files tab. Requires `submission.file:create`. *** ## April 27 2026 ### Address Resolution API **Added** * `GET /api/external/companies/{companyId}/resolve-address` — Geocode a freeform address string and return its structured subfields (`street`, `city`, `state`, `county`, `country`, `zipCode`) in the shape Field Model V1 rating expects. Pre-flight utility: integrators call this before building create/update payloads so addresses include all required pieces (especially `county`). `zipCode` is returned as a string with leading zeros preserved. Failures (empty input, no match, missing required subfield, upstream geocoder error) surface as `400` (or `502` for upstream errors) with a distinct `problemCode` — partial addresses are never returned as success. Writes are not auto-enriched. Requires `company:read`. *** ## April 24 2026 ### Configuration Rating Fields API **Added** * `PUT /api/external/companies/{companyId}/configuration/rating/fields/rank` — Reorder rating input fields within a single `(companyId, entityType)` tuple by rewriting `application_fields.rank`. The array index of each `fieldId` becomes its new rank. The provided `fieldIds` must exactly match the set of rating fields currently defined for the entity type — partial reorders, duplicates, unknown ids, and missing ids are rejected with `400`. Updates UI ordering only; does not modify `rating_engine_revisions.config`. Requires `company:update`. **Changed** * `GET /api/external/companies/{companyId}/configuration/rating/fields` — Response now includes `rank` (integer, nullable), the UI rendering order of the field within its entity type. Lower values render first; `null` renders last. Not used as the endpoint's sort key. *** ## April 22 2026 ### Configuration Rating Form Logic API **Added** * `GET /api/external/companies/{companyId}/configuration/rating/form-logic` — List form-logic rules from a rating engine revision's config JSON. Requires `ratingEngineRevisionId` query parameter. Supports filtering by `ruleName` (exact match) and `id`, sorting by `ruleName` (default) or `rank`. * `POST /api/external/companies/{companyId}/configuration/rating/form-logic` — Create a form-logic rule in a rating engine revision's config JSON (`config.policyFormLogicConfigs`). Rules use a `shouldAdd` conditional expression that supports `AND`/`OR` branches, leaf comparisons (`=`, `!=`, `<`, `<=`, `>`, `>=`, `IN`, `NOTIN`, `EXISTS`, `NOTEXISTS`, `SOME`), and an inverted-leaf shape. Requires `ratingEngineRevisionId`, `revisionStrategy`, `ruleName`, `rank`, and `shouldAdd`. * `DELETE /api/external/companies/{companyId}/configuration/rating/form-logic/{formLogicId}` — Remove a form-logic rule from a rating engine revision's config JSON. Requires `ratingEngineRevisionId` and `revisionStrategy` query parameters. *** ## April 15 2026 ### Configuration Rating Presets API **Added** * `GET /api/external/companies/{companyId}/configuration/rating/presets` — List coverage limit presets from a rating engine revision's config JSON. Requires `ratingEngineRevisionId` query parameter. Supports filtering by `coverageTypeKey` and `id`, sorting by `setName` or `coverageTypeKey`. * `POST /api/external/companies/{companyId}/configuration/rating/presets` — Create a coverage limit preset in a rating engine revision's config JSON. For rating-engine companies where presets are stored in `config.coverageLimitPresets`, not in the `coverage_limit_presets` table. Requires `ratingEngineRevisionId` and `revisionStrategy` parameters. Supports default-steal (setting `isDefault: true` unsets existing defaults for the same coverage type). * `DELETE /api/external/companies/{companyId}/configuration/rating/presets/{presetId}` — Remove a coverage limit preset from a rating engine revision's config JSON. The preset is permanently removed from the `coverageLimitPresets` array. *** ## April 13 2026 ### FMV1 Policy Transaction API — Read Endpoints **Added** * `GET /api/v1/external/companies/{companyId}/policies/list` — List policies with segment scope filtering, JSONB field filters, time travel, and pagination * `GET /api/v1/external/companies/{companyId}/policies/versions` — Search across all policy versions (cross-version search) * `GET /api/v1/external/companies/{companyId}/policies/{policyId}/versions` — List all versions for a single policy These endpoints complete the read path for the transaction-based policy model. Use `segmentScope` to filter by date range, `filters` for field-level JSONB queries, and `detail=full` to include complete segment data. ### Configuration Presets API **Changed** * Moved coverage limit preset endpoints from `/configuration/rating/presets` to `/configuration/presets` — these endpoints operate on the `coverage_limit_presets` table (for non-rating-engine companies). The `/configuration/rating/presets` path will be used by new config-JSON endpoints for rating-engine companies. **The old path is no longer available — update existing integrations to use the new path.** ### Exposure Types API **Added** * `DELETE /api/external/companies/{companyId}/exposure-types/{exposureTypeId}` — Permanently delete an exposure type and remove it from the company's enabled types. Validates the type is not referenced by insureds (409) before deletion. ### Coverage Types API **Added** * `DELETE /api/external/companies/{companyId}/coverage-types/{coverageTypeId}` — Permanently delete a company-specific coverage type. Validates the type is not global (403), not enabled (409), and has no field associations (409) before deletion. *** ## April 10 2026 ### Coverage Types API **Added** * `GET /api/external/companies/{companyId}/coverage-types` — List all coverage types (global and company-specific) with optional label filtering * `POST /api/external/companies/{companyId}/coverage-types` — Create a company-specific coverage type * `PUT /api/external/companies/{companyId}/coverage-types/enabled` — Replace the company's enabled coverage types list wholesale ### Exposure Types API **Added** * `GET /api/external/companies/{companyId}/exposure-types` — List exposure types with optional label filtering * `POST /api/external/companies/{companyId}/exposure-types` — Create an exposure type and add it to the company's enabled exposure types ### Configuration Rating Outputs API **Added** * `GET /api/external/companies/{companyId}/configuration/rating/outputs` — List rating output fields with filtering by ID, sorting, and pagination * `DELETE /api/external/companies/{companyId}/configuration/rating/outputs/{fieldId}` — Delete a rating output field and soft-delete its associated smart tag *** ## April 9 2026 ### FMV1 Policy Transaction API The FMV1 Policy API has been rebuilt around an immutable transaction model. Policies are now managed through transaction endpoints rather than direct CRUD operations. **Added** * `POST /api/v1/external/companies/{companyId}/policies/transaction/new-business` — Create a new policy via a NEW\_BUSINESS transaction The previous CRUD endpoints (`POST /v1/policies`, `DELETE /v1/policies/{policyId}`) are deprecated and will be removed in a future release. ### Configuration Rating Outputs API **Added** * `POST /api/external/companies/{companyId}/configuration/rating/outputs` — Create a rating output field (`rating_engine_display`) with auto-created smart tag ### Configuration Rating Fields API **Added** * `DELETE /api/external/companies/{companyId}/configuration/rating/fields/{fieldId}` — Delete a rating input field, its application field association, and its entry in the rating engine revision config * `GET /api/external/companies/{companyId}/configuration/rating/fields` — List rating input fields with filtering by ID and entity type, sorting, and pagination *** ## April 8 2026 ### Configuration Rating Fields API **Added** * `POST /api/external/companies/{companyId}/configuration/rating/fields` — Create a rating input field and associate it with an entity type and rating engine revision ### Field Model V1 Quote Lifecycle Endpoints **Added** * `POST /api/v1/external/companies/{companyId}/quotes/{quoteId}/bind` — Bind a quote, creating a policy * `POST /api/v1/external/companies/{companyId}/quotes/{quoteId}/send` — Send a quote, transitioning status to "sent" *** ## April 7 2026 ### Configuration Fields API **Added** * `GET /api/external/companies/{companyId}/configuration/fields` — List entity fields with filtering by ID and entity name, sorting, and pagination * `POST /api/external/companies/{companyId}/configuration/fields` — Create a field definition and associate it with an entity type (events, insureds, policies) * `DELETE /api/external/companies/{companyId}/configuration/fields/{fieldId}` — Delete a field and its entity association These endpoints manage entity-level configuration fields only. Rating fields are managed through separate `/configuration/rating/` endpoints. *** ### Field Model V1 Quotes API **Added** * `GET /api/v1/external/companies/{companyId}/quotes` — List quotes with pagination, sorting, and submission filtering * `POST /api/v1/external/companies/{companyId}/quotes` — Create a quote with policy and exposure data * `GET /api/v1/external/companies/{companyId}/quotes/{quoteId}` — Get a single quote * `PUT /api/v1/external/companies/{companyId}/quotes/{quoteId}` — Update a quote (full replacement of policy and exposures) * `DELETE /api/v1/external/companies/{companyId}/quotes/{quoteId}` — Soft-delete a quote * `GET /api/v1/external/companies/{companyId}/quotes/configuration` — Get JSON Schemas for policy and exposure fields Lifecycle fields (`quoteType`, `quoteStatus`, `quoteNumber`, `quoteBindErrors`, `quoteSubmissionId`) are read-only in responses and rejected on create/update. *** ## March 31 2026 ### FMV1 Configuration Management API **Added** * `POST /api/v1/external/companies/{companyId}/configuration/generate` — Generate a blank FMV1 configuration template spreadsheet * `POST /api/v1/external/companies/{companyId}/configuration/export` — Export FMV1 configuration to an existing Google Spreadsheet * `POST /api/v1/external/companies/{companyId}/configuration/validate` — Validate a configuration spreadsheet * `POST /api/v1/external/companies/{companyId}/configuration/compare` — Compare spreadsheet against database * `POST /api/v1/external/companies/{companyId}/configuration/import` — Import configuration from a spreadsheet These endpoints require the new **FMV1\_CONFIGURATION\_MANAGER** role. New permissions: `company.configuration:export` and `company.configuration:import`. *** ## March 30 2026 ### Coverage Type Fields API **Added** * `POST /api/external/companies/{companyId}/coverage-types/{coverageTypeId}/fields` - Set fields on a company-specific coverage type **Changed** * `GET /api/external/companies/{companyId}/coverage-types/{coverageTypeId}/fields` - Response now includes a `metadata` object with `coverageTypeScope` (global or company) and `fieldSources` (database, static, or both) *** ## March 27 2026 ### Coverage Type Fields API **Added** * `GET /api/external/companies/{companyId}/coverage-types/{coverageTypeId}/fields` - Get fields associated with a coverage type ### Field Model V1 Events API **Changed** * Event responses no longer include `lawsuitId` — lawsuits are now managed via entity relationships, not auto-created on event creation * `fieldModelV1Data` is now always present (non-nullable) in event responses * List endpoint now filters `type` and `status` via `fieldModelV1Data` JSONB fields instead of legacy columns * Creating an event no longer auto-creates a lawsuit record ### Field Model V1 Exposures API **Changed** * Exposures now read and write exclusively from `fieldModelV1Data`. Legacy columns (`name`, `entity_type`) are no longer populated on create or update. * List endpoint filtering and sorting now operate on JSONB fields (`exposureType`, `exposureName`) instead of legacy columns. *** ## March 23 2026 ### Assignees API **Added** * `GET /api/external/companies/{companyId}/{entityType}/{entityId}/assignees` - List assignees for an entity * `PUT /api/external/companies/{companyId}/{entityType}/{entityId}/assignees` - Set assignees for an entity (full replace) Supports policies, submissions, insureds, and events. *** ## March 16 2026 ### Field Model V1 Custom Objects API **Added** * `GET /api/v1/external/companies/{companyId}/custom-objects` - List custom object types * `GET /api/v1/external/companies/{companyId}/custom-objects/{objectType}/configuration` - Get field schema and relationship metadata * `GET /api/v1/external/companies/{companyId}/custom-objects/{objectType}` - List custom objects (paginated) * `GET /api/v1/external/companies/{companyId}/custom-objects/{objectType}/{objectId}` - Get custom object by ID * `POST /api/v1/external/companies/{companyId}/custom-objects/{objectType}` - Create custom object * `PUT /api/v1/external/companies/{companyId}/custom-objects/{objectType}/{objectId}` - Update custom object (full replacement) * `DELETE /api/v1/external/companies/{companyId}/custom-objects/{objectType}/{objectId}` - Delete custom object * `PUT /api/v1/external/companies/{companyId}/custom-objects/{objectType}/{objectId}/relationships/{fieldRefId}/{targetId}` - Add relationship * `DELETE /api/v1/external/companies/{companyId}/custom-objects/{objectType}/{objectId}/relationships/{fieldRefId}/{targetId}` - Remove relationship *** ## February 27 2026 ### Insureds Configuration API **New Features** * **Get Insureds Configuration**: Response now includes `fieldEntityTypeMappings` (maps field keys to entity type associations). This allows API consumers to determine which fields apply to which entity types. * **Entity-type scoped fields**: The configuration response now only includes fields for entity types that are enabled for your company, instead of the union of all possible entity-type-specific fields. * **Improved validation errors**: When creating or updating an insured with a field that belongs to a different entity type, the error message now indicates which entity types the field belongs to, instead of the generic "Unknown field key" message. *** ## February 26 2026 ### Create Policy API **Breaking Changes** * **Unified exposures array**: The `primaryInsured` field and separate `exposures` array have been replaced with a single `exposures` array. Exactly one exposure must have `role: "primary"`. * **Before**: Separate `primaryInsured` object (no `role` field) + optional `exposures` array (roles: `named`, `additional`, `related`) * **After**: Single required `exposures` array where one entry has `role: "primary"` and others have `role: "named"`, `"additional"`, or `"related"` * **Field renames in docs**: `insuredType` → `role`, `applicationData` → `ratingInfo`, `insureds` → `exposures` (docs now match actual code field names) *** ## February 24 2026 ### Field Model V1 Exposures API **New Features** * **Field Model V1 Exposures CRUD API**: Full operations for managing exposures with company-configured dynamic fields * `GET /api/v1/external/companies/{companyId}/exposures/configuration` - Get JSON Schema of available fields * `POST /api/v1/external/companies/{companyId}/exposures` - Create an exposure with dynamic fields * `GET /api/v1/external/companies/{companyId}/exposures` - List exposures with filtering and pagination * `GET /api/v1/external/companies/{companyId}/exposures/{exposureId}` - Retrieve a single exposure by ID * `PATCH /api/v1/external/companies/{companyId}/exposures/{exposureId}` - Update an exposure (full replacement of field data) * `DELETE /api/v1/external/companies/{companyId}/exposures/{exposureId}` - Soft delete an exposure * Fields are dynamically defined per company — use the configuration endpoint to discover available fields and types * Supports Text, Number, Boolean, Option Set, and Object field types * Required permissions: `company.insured:read`, `company.insured:create`, `insured:update`, `insured:delete` ### Field Model V1 Policies API **New Features** * **FMV1 Policies CRUD API**: Full operations for managing Field Model V1 policies * `GET /api/v1/external/companies/{companyId}/policies` - List policies with filtering, sorting, and pagination * `POST /api/v1/external/companies/{companyId}/policies` - Create a policy with segment data * `GET /api/v1/external/companies/{companyId}/policies/{policyId}` - Retrieve a single policy by ID * `DELETE /api/v1/external/companies/{companyId}/policies/{policyId}` - Soft delete a policy * `GET /api/v1/external/companies/{companyId}/policies/configuration` - Get JSON Schema for available custom fields * Segment-based data structure with policy, coverage, and exposure custom fields * Required permissions: `company.policy:read` (read operations), `company.policy:create` (write operations) *** ## February 19 2026 ### Defendants API **New Features** * **Defendants CRUD API**: Full operations for managing defendants on lawsuits * `GET /api/external/companies/{companyId}/events/{eventId}/lawsuit/defendants` - List defendants with filtering and pagination * `POST /api/external/companies/{companyId}/events/{eventId}/lawsuit/defendants` - Create a defendant for a lawsuit * `GET /api/external/companies/{companyId}/events/{eventId}/lawsuit/defendants/{defendantId}` - Retrieve a single defendant by ID * `PATCH /api/external/companies/{companyId}/events/{eventId}/lawsuit/defendants/{defendantId}` - Update a defendant (send null to clear fields) * `DELETE /api/external/companies/{companyId}/events/{eventId}/lawsuit/defendants/{defendantId}` - Soft delete a defendant * Each defendant is either an insured (`insuredId`) or non-insured party (`nonInsuredName`) * FK validation for `insuredId`, `attorneyId`, and `lawFirmId` * Required permission: `company.event:export` ### Events API **Improvements** * **`lawsuitId` field**: Event responses now include `lawsuitId` (nullable). Create and update event requests accept an optional `lawsuitId` to associate a lawsuit with an event. *** ## February 17 2026 ### Lawsuits API **New Features** * **Lawsuits CRUD API**: Full operations for managing lawsuits on events (1:1 relationship) * `POST /api/external/companies/{companyId}/events/{eventId}/lawsuit` - Create a lawsuit for an event (409 if one already exists) * `GET /api/external/companies/{companyId}/events/{eventId}/lawsuit` - Retrieve the lawsuit for an event * `PATCH /api/external/companies/{companyId}/events/{eventId}/lawsuit` - Update the lawsuit (send null to clear fields) * `DELETE /api/external/companies/{companyId}/events/{eventId}/lawsuit` - Soft delete the lawsuit * All fields are optional on create; update supports partial updates with null clearing * FK validation for `plaintiffAttorneyId` and `plaintiffLawFirmId` * Required permission: `company.event:export` *** ### Event Financials API **New Features** * **Void Event Transaction**: `PATCH /api/external/companies/{companyId}/events/{eventId}/financials/transactions/{transactionId}` * Void an existing financial transaction by setting `status: "void"` * Required `voidReason` field to document why the transaction was voided * Returns full transaction detail after voiding * Required permission: `company.payment:update` *** ## February 16 2026 ### Attorneys API **New Features** * **Attorneys API**: Full CRUD operations for managing attorneys * `GET /api/external/companies/{companyId}/attorneys` - List attorneys with filtering and pagination * `POST /api/external/companies/{companyId}/attorneys` - Create a new attorney * `GET /api/external/companies/{companyId}/attorneys/{attorneyId}` - Get attorney details * `PATCH /api/external/companies/{companyId}/attorneys/{attorneyId}` - Update an attorney * `DELETE /api/external/companies/{companyId}/attorneys/{attorneyId}` - Soft delete an attorney * Filter by ID (single or array) or text search across attorney names * Sort by createdAt, updatedAt, or name * Optional `lawFirmId` to associate an attorney with a law firm payee *** ## February 11 2026 ### Events API **Improvements** * **Get Events Configuration**: Response now includes `fieldCoverageTypeMappings` (maps field keys to coverage type associations) and `companyCoverageTypes` (list of enabled coverage type IDs). This allows API consumers to determine which fields apply to which coverage types. *** ## January 26 2026 ### Exposures API **New Features** * **New `/exposures/` endpoints**: Added `/exposures/` as the preferred endpoint path for managing exposures (previously called "insureds") * `GET /api/external/companies/{companyId}/exposures` - List exposures with filtering and pagination * `GET /api/external/companies/{companyId}/exposures/{exposureId}` - Retrieve a single exposure by ID * `POST /api/external/companies/{companyId}/exposures` - Create a new exposure * `PATCH /api/external/companies/{companyId}/exposures/{exposureId}` - Update an existing exposure * `DELETE /api/external/companies/{companyId}/exposures/{exposureId}` - Soft delete an exposure * The existing `/insureds/` endpoints remain available for backwards compatibility ### Insured API **New Features** * **Get insured endpoint**: `GET /api/external/companies/{companyId}/insureds/{insuredId}` * Retrieve a single insured (exposure) by ID * Returns insured details including name, entity type, and associated policy IDs *** ## January 13 2026 ### Smart Tags API **New Features** * **Smart Tags API**: List smart tags for a company * `GET /api/external/companies/{companyId}/smart-tags` - List smart tags with filtering and pagination * Filter by ID (single or array) or text search across tag names * Sort by createdAt, updatedAt, tagName, or tagDisplayName ### Policies API **New Features** * **Create policy endpoint**: `POST /api/external/companies/{companyId}/policies` * Create policies directly for historical imports without going through quote→bind flow * Takes existing insured IDs (insureds must be created first via POST /insureds) * Creates insured snapshots with optional applicationData for rating * Creates policy snapshot with coverages * Supports: policy type, billing period, timezone, premium override, broker info * Validates exactly one primary insured, policy number uniqueness * Returns `{ id }` with HTTP 201 *** ## January 6 2026 ### Event Financials API **New Features** * **Event Financials API**: Full management of financial transactions and reserves for events * `GET /api/external/companies/{companyId}/events/{eventId}/financials/transactions` - List transactions for an event * `POST /api/external/companies/{companyId}/events/{eventId}/financials/transactions` - Create payment or invoice * `GET /api/external/companies/{companyId}/events/{eventId}/financials/transactions/{transactionId}` - Get transaction details with line items * `GET /api/external/companies/{companyId}/events/{eventId}/financials/reserves` - Get reserve amounts by category * `PATCH /api/external/companies/{companyId}/events/{eventId}/financials/expected-totals` - Update expected totals/reserves * `GET /api/external/companies/{companyId}/events/financials/{transactionType}/totals` - Get financial totals across all events * Support for itemized and non-itemized transaction types * Transaction statuses: owed, paid, approved, void ### Policies API **New Features** * **List policies endpoint**: `GET /api/external/companies/{companyId}/policies` * Retrieve policies with filtering and pagination support ### Insured API **New Features** * **Create insured endpoint**: `POST /api/external/companies/{companyId}/insureds` * Create new insured (exposure) records with name and entity type * **Delete insured endpoint**: `DELETE /api/external/companies/{companyId}/insureds/{insuredId}` * Soft delete insured records *** ## December 30 2025 ### Payees & Transaction Categories **New Features** * **Payees API**: Full CRUD operations for managing payees * `GET /api/external/companies/{companyId}/payees` - List all payees with filtering * `GET /api/external/companies/{companyId}/payees/{payeeId}` - Get payee details * `POST /api/external/companies/{companyId}/payees` - Create new payee * `PUT /api/external/companies/{companyId}/payees/{payeeId}` - Update payee * `DELETE /api/external/companies/{companyId}/payees/{payeeId}` - Delete payee * Support for saved and non-saved payee types * **Transaction Categories endpoint**: `GET /api/external/companies/{companyId}/transaction-categories` * Retrieve available transaction categories for accounting integration **Improvements** * Added `batchId` audit logging support for bulk operations *** ## December 22 2025 ### Submissions & Configuration Endpoints **New Features** * **Submissions CRUD API**: Complete submission management * `GET /api/external/companies/{companyId}/submissions/{submissionId}` - Get submission details * `POST /api/external/companies/{companyId}/submissions` - Create new submission * `PUT /api/external/companies/{companyId}/submissions/{submissionId}` - Update submission * `DELETE /api/external/companies/{companyId}/submissions/{submissionId}` - Delete submission * **Events configuration endpoint**: `GET /api/external/companies/{companyId}/events/configuration` * Retrieve event type configuration and available options **Improvements** * Updated currency field documentation to use JSON Schema `money` format type *** ## December 19 2025 ### Brokers & Quotes Configuration **New Features** * **Brokers CRUD API**: Full broker management * `GET /api/external/companies/{companyId}/brokers` - List brokers * `GET /api/external/companies/{companyId}/brokers/{brokerId}` - Get broker details * `POST /api/external/companies/{companyId}/brokers` - Create broker * `PUT /api/external/companies/{companyId}/brokers/{brokerId}` - Update broker * `DELETE /api/external/companies/{companyId}/brokers/{brokerId}` - Delete broker * **Quotes configuration endpoint**: `GET /api/external/companies/{companyId}/quotes/configuration` * Retrieve quote-related configuration settings **Improvements** * Added `force` parameter to `DELETE /events/{eventId}` for force deletion *** ## December 17 2025 ### Brokerages & API Improvements **New Features** * **Brokerages CRUD API**: Complete brokerage management * `GET /api/external/companies/{companyId}/brokerages` - List brokerages * `GET /api/external/companies/{companyId}/brokerages/{brokerageId}` - Get brokerage details * `POST /api/external/companies/{companyId}/brokerages` - Create brokerage * `PUT /api/external/companies/{companyId}/brokerages/{brokerageId}` - Update brokerage * `DELETE /api/external/companies/{companyId}/brokerages/{brokerageId}` - Delete brokerage **Improvements** * Create endpoints now return `201 Created` status code (previously `200 OK`) * Removed deprecated `requestorEmail` field from all endpoints *** ## December 11 2025 ### Events API **New Features** * **Events CRUD API**: Full event lifecycle management * `GET /api/external/companies/{companyId}/events` - List events with filtering * `GET /api/external/companies/{companyId}/events/{eventId}` - Get event details * `POST /api/external/companies/{companyId}/events` - Create new event * `PUT /api/external/companies/{companyId}/events/{eventId}` - Update event * `DELETE /api/external/companies/{companyId}/events/{eventId}` - Delete event **Improvements** * Added `insuredIds` array field for multi-insured event support * Removed legacy fields from events API for cleaner responses * Added nullable fields documentation for events API *** ## December 5 2025 ### Notes & Quote Operations **New Features** * **Notes API**: Create and retrieve notes * `GET /api/external/companies/{companyId}/notes` - List notes with filtering * `POST /api/external/companies/{companyId}/notes` - Create new note * Support for author override fields * **Quote creation endpoint**: `POST /api/external/companies/{companyId}/quotes` * Create new quotes programmatically * **Quote deletion endpoint**: `DELETE /api/external/companies/{companyId}/quotes/{quoteId}` * Delete quotes that are no longer needed * **Quote update endpoint**: `PATCH /api/external/companies/{companyId}/quotes/{quoteId}` * Update existing quote fields * **Quote binding endpoint**: `POST /api/external/companies/{companyId}/quotes/{quoteId}/bind` * Bind a quote to convert it to a policy *** ## December 4 2025 ### Quotes API Consolidation **Breaking Changes** * **Consolidated quote endpoints**: Moved from submission-scoped paths to single company-level endpoints with optional filters * **Before**: `GET /api/external/companies/{companyId}/submissions/{submissionId}/quotes` * **After**: `GET /api/external/companies/{companyId}/quotes?submissionId={submissionId}` * All quote endpoints now use optional `submissionId` and `applicationId` query parameters instead of path parameters **New Features** * **Lightweight quote info endpoint**: `GET /api/external/companies/{companyId}/quotes-info` * Returns essential fields only (9 fields vs 40+) * Optimized for listing, searching, and filtering * \~3x faster response times for dashboard views * Fields: id, number, status, createdAt, updatedAt, description, policyId, policyCurrency, grandTotal * **Enhanced pagination**: All list endpoints now support robust pagination * Page size: 50 quotes per page * 1-based indexing (page=1 is first page, page=0 coerced to 1) * Response includes `totalCount` for pagination UI * **Advanced filtering**: Comprehensive query parameters for all list endpoints * `status`: Filter by single status or array of statuses * `filterText`: Full-text search across quote fields * `dateFrom`/`dateTo`: Filter by creation date range * `applicationId`: Filter by associated application * **Flexible sorting**: Control result ordering * `sortBy`: Choose field (createdAt, updatedAt, status, number) * `sortDirection`: asc or desc * Default: Most recent first (createdAt desc) **Improvements** * **Unified response format**: All list endpoints return `{ items: [], totalCount: number }` * **Updated quote statuses**: Status values now match actual implementation * Added: `in_progress`, `complete`, `sent`, `accepted`, `applied_to_policy` * Updated: More granular status tracking for quote lifecycle * **Better data models**: Clear distinction between lightweight and full quote representations * **Improved documentation**: Separate guides for submissions and quotes with detailed examples *** ## August 8 2025 ### External API enhancements **Improvements** * **New submission creation**: Create submissions with complete policy, coverage, and insured data via `POST /api/external/companies/{companyId}/submissions` * **Submission updates**: Update existing submissions by adding new quotes via `PUT /api/external/companies/{companyId}/submissions/{submissionId}` * **Enhanced quote retrieval**: Get detailed quote information including policy data, coverages, and billing configuration via `GET /api/external/companies/{companyId}/quotes/{quoteId}` * **Configuration endpoint**: Retrieve company-specific configuration including rating fields, entity types, and coverage options via `GET /api/external/companies/{companyId}/configuration` **API structure improvements** * All endpoints now use `/api/external/` prefix for better organization and versioning * Enhanced data models with comprehensive `ImportPolicy`, `ImportPolicyCoverage`, and `ImportInsured` objects * Added support for policy types: Claims Made (C), Occurrence (O), Claims Paid (P), and more * Expanded quote response with billing details, forms management, and binding settings **Developer experience** * Complete API documentation with detailed request/response examples * Enhanced error handling and validation * Comprehensive data model reference with all field descriptions * Support for complex insurance workflows including renewals and endorsements *** ## Initial Release ### Core API functionality **New features** * **List submissions**: Retrieve paginated submissions for a company with filtering and sorting options * **List quotes**: Get all quotes associated with a specific submission * **Quote management**: Basic quote retrieval and status tracking * **Authentication**: API key-based authentication for secure access **Data models** * Core `Submission` object with status tracking and metadata * Basic `Quote` object with pricing and status information * Support for submission types: new business, renewals, and endorsements * Quote status management: draft, active, expired, bound, declined, superseded **API foundation** * RESTful API design following industry standards * Comprehensive error handling with detailed error responses * Rate limiting and security best practices * UUID-based resource identification # Get Configuration Source: https://docs.aiinsurance.io/api-legacy-reference/configuration **Endpoint:** ``` GET /api/external/companies/{companyId}/configuration ``` Retrieves the configuration for your company in AI Insurance. This includes many enumerated fields like the types of entities that can be covered or whose information is tracked. ### **Parameters** None ## **Response** | Key | Type | Description | | ---------------------- | ------ | --------------------------------------------------------------------- | | `ratingEngineFields` | object | Rating fields with entity type and field key (used to create a quote) | | `nonRatingFields` | object | Non‑rating fields for policy and insured entities | | `insuredEntityTypes` | object | Keys are available insured entity types | | `enabledCoverageTypes` | object | Keys are enabled coverage type IDs | ### **Example Requests** **cURL** ```bash theme={null} curl -X GET \ "https://app.aiinsurance.io/api/external/companies//configuration" \ -H "Authorization: ApiKey " ``` # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/configuration-fields/overview Manage entity field definitions for your company ## Overview Configuration fields define the custom data fields that appear on entity forms (events, insureds, and policies). Each field has a definition specifying its type, key, display label, and optional configuration like select options or calculations. These endpoints manage **entity fields** only. Rating fields, rating outputs, and rating presets are managed through separate `/configuration/rating/` endpoints. ## Key Concepts * **fieldDefinition**: A JSON object defining the field's type (`className`), unique key, data path, and optional properties like label, section, and select options * **entityName**: The entity type the field is associated with — `events`, `insureds`, or `policies` * **className**: The field type — `InputField`, `SelectField`, `DateField`, `RadioSelect`, or `ExportResolvedField` ## API Endpoints | Method | Endpoint | Description | | ------ | --------------------------------- | ---------------------------------------------------- | | GET | `/configuration/fields` | List all entity fields with filtering and pagination | | POST | `/configuration/fields` | Create a new entity field | | DELETE | `/configuration/fields/{fieldId}` | Delete an entity field | ## Permissions | Action | Permission | | ------------ | ---------------- | | List fields | `company:read` | | Create field | `company:update` | | Delete field | `company:update` | ## Field Definition Properties | Property | Type | Required | Description | | ----------- | ------- | -------- | ------------------------------------------------------------------------------------------ | | className | string | Yes | Field type: `InputField`, `SelectField`, `DateField`, `RadioSelect`, `ExportResolvedField` | | key | string | Yes | Unique field key (cannot be `companyId`) | | path | string | Yes | Dot-notation path for the field value in entity data | | label | string | No | Human-readable label | | section | string | No | UI section grouping | | required | boolean | No | Whether the field is required | | fields | object | No | Sub-field configuration (e.g., select options) | | calculation | object | No | Calculation configuration for computed fields | ## Example Response ```json theme={null} { "items": [ { "id": "550e8400-e29b-41d4-a716-446655440100", "entityName": "policies", "fieldDefinition": { "className": "InputField", "key": "policyState", "path": "policyState", "label": "Policy State", "section": "Policy Information", "required": true }, "createdAt": "2025-01-15T10:30:00.000Z", "updatedAt": "2025-01-20T14:00:00.000Z" } ], "totalCount": 1 } ``` # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/configuration-presets/overview Manage coverage limit presets for your company ## Overview Configuration presets define the available coverage limit options for each coverage type. Each preset specifies a set of named limits (e.g., "Per Occurrence", "Aggregate") with their amounts, and can include additional settings for deductibles, defense costs, retroactive dates, and waiting periods. Presets are stored in the `coverage_limit_presets` table and are scoped to a company via `company_id`. Each preset references a coverage type via `coverageTypeKey`. ## Key Concepts * **coverageTypeKey**: The string key of an existing coverage type (global or company-specific). Must exist in the `coverage_types` table. * **limits**: An object containing an array of named limit amounts and an optional `allowLimitEdits` flag controlling whether users can modify amounts on quotes. * **isDefault**: Whether this preset is the default for its coverage type. Multiple presets per coverage type are allowed, but only one can be the default. When creating a preset with `isDefault: true`, any existing default for the same coverage type is automatically set to non-default. * **defenseInsideLimit**: Whether defense costs count inside or outside the limit (`"inside"` or `"outside"`). * **Settings fields**: Optional JSONB configuration for deductibles, limits, retroactive dates, waiting periods, and prior/pending litigation dates. These are opaque blobs passed through to the rating engine. ## API Endpoints | Method | Endpoint | Description | | ------ | ----------------------------------- | ----------------------------------- | | GET | `/configuration/presets` | List coverage limit presets | | POST | `/configuration/presets` | Create a new coverage limit preset | | DELETE | `/configuration/presets/{presetId}` | Soft-delete a coverage limit preset | ## Permissions | Action | Permission | | ------------- | ---------------- | | List presets | `company:read` | | Create preset | `company:update` | | Delete preset | `company:update` | ## Request Properties | Property | Type | Required | Description | | ---------------------------------- | ------- | -------- | ------------------------------------------------------ | | coverageTypeKey | string | Yes | Coverage type key (must exist) | | setName | string | Yes | Display name for the preset | | limits | object | Yes | Limit definitions (see below) | | isDefault | boolean | No | Whether this is the default preset (defaults to false) | | defenseInsideLimit | string | No | `"inside"` or `"outside"` | | deductible | number | No | Deductible amount in dollars | | retroactiveDate | string | No | ISO date (YYYY-MM-DD) | | waitingPeriodSettings | object | No | Waiting period configuration | | deductibleSettings | object | No | Deductible default amount configuration | | limitSettings | object | No | Limit default amounts configuration | | retroactiveDateSettings | object | No | Retroactive date default amount configuration | | priorPendingLitigationDateSettings | object | No | Prior/pending litigation date configuration | ### Limits Object | Property | Type | Required | Description | | ---------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------ | | limits | array | Yes | Array of limit definitions | | limits\[].id | string | Yes | Unique identifier for this limit | | limits\[].name | string | Yes | Display name (e.g., "Per Occurrence") | | limits\[].amount | number \| string | No | Limit amount — a number (e.g. 1000000) or a string (e.g. "100%", "-"). Omit when not applicable. | | allowLimitEdits | boolean | No | Whether users can edit limit amounts on quotes | ## Response Properties (GET) The list endpoint returns `{ items, totalCount }` where each item includes all request properties plus: | Property | Type | Description | | --------- | -------------- | ------------------ | | id | string (UUID) | Preset identifier | | createdAt | string \| null | ISO 8601 timestamp | | updatedAt | string \| null | ISO 8601 timestamp | Nullable fields (`defenseInsideLimit`, `deductible`, `retroactiveDate`, and all settings) return `null` when not set. # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/configuration-rating-fields/overview Manage rating engine input field definitions for your company ## Overview Configuration rating fields define the input fields that feed data into the rating engine. Each field has a definition specifying its type, key, display label, and optional configuration like select options or display conditions. Fields are associated with an entity type (e.g., "policies", "dealership") and a rating engine revision. These endpoints manage **rating input fields** only. Entity fields (events, insureds, policies) are managed through `/configuration/fields` endpoints. ## Key Concepts * **fieldDefinition**: A JSON object defining the field's type (`className`), unique key, data path, and optional properties like label, section, and display conditions * **entityType**: The rating entity type the field applies to — can be `policies` or any exposure type (e.g., `dealership`, `company`) * **ratingEngineRevisionId**: The rating engine revision this field belongs to — must already exist * **revisionStrategy**: Controls how the revision is updated — `UpdateExistingRevision` modifies the specified revision in place. `CreateNewRevision` is not yet implemented. * **className**: The field type — `AddressField`, `DateField`, `GroupField`, `InputField`, `LocalCurrency`, `MultiSelectField`, `SelectField`, or `StaticField` * **rank**: UI rendering order within the entity type — lower values render first, `null` renders last. Returned on list responses. Set via `PUT /configuration/rating/fields/rank`; not set on creation. Not used as the list endpoint's sort key. ## API Endpoints | Method | Endpoint | Description | | ------ | ---------------------------------------- | ------------------------------------------------- | | GET | `/configuration/rating/fields` | List rating input fields | | POST | `/configuration/rating/fields` | Create a new rating input field | | DELETE | `/configuration/rating/fields/{fieldId}` | Delete a rating input field | | PUT | `/configuration/rating/fields/rank` | Reorder rating input fields within an entity type | ## Permissions | Action | Permission | | -------------- | ---------------- | | List fields | `company:read` | | Create field | `company:update` | | Delete field | `company:update` | | Reorder fields | `company:update` | ## Field Definition Properties | Property | Type | Required | Description | | ----------------- | --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | className | string | Yes | Field type: `AddressField`, `DateField`, `GroupField`, `InputField`, `LocalCurrency`, `MultiSelectField`, `SelectField`, `StaticField` | | key | string | Yes | Unique field key (cannot be `companyId`) | | path | string | Yes | Dot-notation path for the field value in rating data | | label | string | No | Human-readable label | | section | string | No | UI section grouping | | required | boolean | No | Whether the field is required | | fields | object | No | Sub-field configuration (e.g., select options) | | displayCondition | string \| boolean \| object | No | Condition controlling when the field is displayed. Create accepts a string; list responses may also return a boolean or structured conditional object. | | displayConditions | object | No | Multiple display conditions | | value | string \| object | No | Default value. Create accepts a string; list responses may also return a structured value reference (e.g., path-based lookup). | # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/configuration-rating-form-logic/overview Manage form-attachment rules in rating engine revision config ## Overview Configuration rating form-logic rules determine which forms are attached to a policy or quote. Rules are stored in the rating engine revision's config JSON (`rating_engine_revisions.config.policyFormLogicConfigs`). Each rule has a `shouldAdd` conditional expression that is evaluated during rating against the policy, insured, coverage, and form data. ## Key Concepts * **ratingEngineRevisionId**: The rating engine revision whose config holds the rules — must already exist. * **revisionStrategy**: Controls how the revision is updated — `UpdateExistingRevision` modifies the specified revision in place. `CreateNewRevision` is not yet implemented. * **ruleName**: Human-readable name for the rule. * **rank**: Controls the position of attached forms in the output list (lower numbers appear first). Does not control evaluation order. Duplicates are permitted. Required on create, so returned rules always carry a rank. * **step**: Optional — tag controlling which form-selection contexts the rule's output appears in. `"policies"` (appears during policy form selection), `"quotes"` (appears during quote form selection), or an array of these values. If omitted, the rule's output only appears during policy form selection. * **shouldAdd**: A conditional expression that evaluates to true or false. When it evaluates to true, the form is attached. See [Expression Shapes](#expression-shapes) below. ## API Endpoints | Method | Endpoint | Description | | ------ | ------------------------------------------------ | --------------------------------------------------- | | GET | `/configuration/rating/form-logic` | List form-logic rules in the revision config | | POST | `/configuration/rating/form-logic` | Create a new form-logic rule in the revision config | | DELETE | `/configuration/rating/form-logic/{formLogicId}` | Remove a form-logic rule from the revision config | ## Permissions | Action | Permission | | ----------- | ---------------- | | List rules | `company:read` | | Create rule | `company:update` | | Delete rule | `company:update` | ## GET Query Parameters | Parameter | Type | Required | Description | | ---------------------- | -------------------------- | -------- | ---------------------------------------------------------------------------------- | | ratingEngineRevisionId | string (UUID) | Yes | Rating engine revision whose config holds the rules | | ruleName | string | No | Filter to rules whose `ruleName` matches exactly. Must be non-empty when provided. | | id | string (UUID) \| string\[] | No | Filter to a single rule ID or an array of rule IDs | | sortBy | `"ruleName"` \| `"rank"` | No | Sort field — default `ruleName` | | sortDirection | `"asc"` \| `"desc"` | No | Sort direction — default `asc`. Ties are broken by `id` in the same direction. | ## GET Response Properties Each item in `items` has the following shape. | Property | Type | Description | | --------- | --------------------------- | ----------------------------------------------------------------------------------------------- | | id | string (UUID) | Server-generated rule ID | | ruleName | string | Human-readable name for the rule | | rank | number | Sort rank controlling output position (lower first) | | step | string \| string\[] \| null | `"policies"`, `"quotes"`, an array of the two, or `null` if the rule was created without a step | | shouldAdd | object | Conditional expression — see [Expression Shapes](#expression-shapes) | Filters and sorts run on raw rules; response validation runs only on the surviving rows. A rule that survives filtering but has a missing or malformed `id`, `rank`, or `shouldAdd` returns a 400 `InvalidProperties` response. In practice, rules written through this API always pass validation, so this condition indicates a data-integrity issue with legacy config rather than a caller error. ## POST Request Properties | Property | Type | Required | Description | | ---------------------- | ------------------- | -------- | ------------------------------------------------------------------ | | ratingEngineRevisionId | string (UUID) | Yes | Rating engine revision to add the rule to | | revisionStrategy | string | Yes | `"UpdateExistingRevision"` or `"CreateNewRevision"` (501) | | ruleName | string | Yes | Human-readable name for the rule | | rank | number | Yes | Sort rank — lower values appear earlier in the attached forms list | | step | string \| string\[] | No | `"policies"`, `"quotes"`, or an array of the two | | shouldAdd | object | Yes | Conditional expression (see below) | ## Expression Shapes `shouldAdd` is a recursive structure built from three variants. ### Branch Expression Combines child expressions with a logical operator. ```json theme={null} { "operator": "AND", "conditions": [ { "leftKey": "policy.data.state", "operator": "=", "rightValue": "CA" }, { "leftKey": "form.number", "operator": "=", "rightValue": "FM-0002" } ] } ``` Supported `operator` values: `AND`, `OR`. ### Leaf Expression Compares the value at `leftKey` against `rightValue` using the given operator. ```json theme={null} { "leftKey": "policy.data.state", "operator": "=", "rightValue": "CA" } ``` Supported `operator` values: `=`, `!=`, `<`, `<=`, `>`, `>=`, `IN`, `NOTIN`, `EXISTS`, `NOTEXISTS`, `SOME`. Operator-specific behavior: * `EXISTS` / `NOTEXISTS` — check only whether `leftKey` resolves to a defined, non-null value. `rightValue` is required structurally but ignored. * `IN` / `NOTIN` — `rightValue` is either an array (membership: the `leftKey` value must be an element) or a string (substring: the `leftKey` value must appear within `rightValue`). * `SOME` — `rightValue` is a nested expression evaluated against each element of the array at `leftKey`. Returns `false` if `leftKey` does not resolve to an array. * `=`, `!=`, `<`, `<=`, `>`, `>=` — standard JavaScript-style comparison between the resolved `leftKey` value and `rightValue`. `rightValue` may be a primitive, an array, `null`, or — for `SOME` — a nested expression. ### Inverted Leaf Expression Checks whether a static `leftValue` appears in the array (or string) stored at `rightKey`. Only the `IN` operator is supported in this shape. ```json theme={null} { "leftValue": "FM-0001", "operator": "IN", "rightKey": "policy.attachedFormNumbers" } ``` # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/configuration-rating-outputs/overview Manage rating output field definitions for your company ## Overview Configuration rating outputs define the fields that display rating engine results (e.g., annual rate, monthly rate). All rating output fields use the entity name `rating_engine_display` and are stored in `company_fields` with an association in `company_entity_fields`. Each rating output field automatically gets a smart tag created with the naming convention `AII{key}PrimaryInsured`, enabling the field's output to be referenced in policy and quote documents. ## Key Concepts * **fieldDefinition**: A JSON object defining the field's type (`className`), unique key, data path, and optional properties like label and display flag * **className**: Currently restricted to `InputField` (the only type used for rating outputs) * **Smart tag**: Always auto-created with name `AII{key}PrimaryInsured` and categories `["policy", "quote"]`. The field key must be alphanumeric. * **displayNeeded**: Whether this field appears in rating output display tables * **smartTagsNeeded**: Whether the auto-created smart tag can resolve a value at rating time. The smart tag row is always created, but the rater only pushes this field's output into the smart-tag bucket when `smartTagsNeeded` is `true`. ## API Endpoints | Method | Endpoint | Description | | ------ | ----------------------------------------- | ---------------------------------------------- | | GET | `/configuration/rating/outputs` | List rating output fields | | POST | `/configuration/rating/outputs` | Create a new rating output field | | DELETE | `/configuration/rating/outputs/{fieldId}` | Delete a rating output field and its smart tag | ## Permissions | Action | Permission | | ------------ | ---------------- | | List fields | `company:read` | | Create field | `company:update` | | Delete field | `company:update` | ## Field Definition Properties | Property | Type | Required | Description | | --------------- | ------- | -------- | ------------------------------------------------------------------- | | className | string | Yes | Field type: `InputField` | | key | string | Yes | Unique field key (cannot be `companyId`; must be alphanumeric) | | path | string | Yes | Dot-notation path for the field value in entity data | | label | string | No | Human-readable label | | section | string | No | UI section grouping | | required | boolean | No | Whether the field is required | | fields | object | No | Sub-field configuration | | displayNeeded | boolean | No | Whether this field is displayed in rating output tables | | smartTagsNeeded | boolean | No | Whether this field's output is exposed to smart tags at rating time | # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/configuration-rating-presets/overview Manage coverage limit presets in rating engine revision config ## Overview Configuration rating presets define coverage limit options stored in the rating engine revision's config JSON (`rating_engine_revisions.config.coverageLimitPresets`). These endpoints are for **rating-engine companies** where presets live in the revision config, not in the `coverage_limit_presets` table. For non-rating-engine companies, use the [Configuration Presets](/api-legacy-reference/configuration-presets/overview) endpoints instead. ## Key Concepts * **ratingEngineRevisionId**: The rating engine revision whose config contains the presets — must already exist. * **revisionStrategy**: Controls how the revision is updated — `UpdateExistingRevision` modifies the specified revision in place. `CreateNewRevision` is not yet implemented. * **coverageTypeKey**: The string key of an existing coverage type (global or company-specific). Must exist in the `coverage_types` table. * **limits**: An object containing an array of named limit amounts and an optional `allowLimitEdits` flag controlling whether users can modify amounts on quotes. * **isDefault**: Whether this preset is the default for its coverage type. When creating a preset with `isDefault: true`, any existing default for the same coverage type within the revision config is automatically set to non-default. * **Settings fields**: Optional JSON configuration for deductibles, limits, retroactive dates, waiting periods, and prior/pending litigation dates. These are opaque blobs passed through to the rating engine. ## API Endpoints | Method | Endpoint | Description | | ------ | ------------------------------------------ | --------------------------------------------------------- | | GET | `/configuration/rating/presets` | List coverage limit presets from the revision config | | POST | `/configuration/rating/presets` | Create a new coverage limit preset in the revision config | | DELETE | `/configuration/rating/presets/{presetId}` | Remove a preset from the revision config | ## Permissions | Action | Permission | | ------------- | ---------------- | | List presets | `company:read` | | Create preset | `company:update` | | Delete preset | `company:update` | ## GET Response Properties The list endpoint returns `{ items }`. Each item has these properties: | Property | Type | Description | | ---------------------------------- | -------------- | -------------------------------------------------------- | | id | string (UUID) | Preset identifier | | coverageTypeKey | string | Coverage type key this preset belongs to | | setName | string | Display name for the preset | | isDefault | boolean | Whether this is the default preset for its coverage type | | limits | object | Limit definitions (see Limits Object below) | | defenseInsideLimit | string \| null | `"inside"` or `"outside"` | | deductible | number \| null | Deductible amount in dollars | | waitingPeriodSettings | object \| null | Waiting period configuration | | deductibleSettings | object \| null | Deductible default amount configuration | | limitSettings | object \| null | Limit default amounts configuration | | retroactiveDateSettings | object \| null | Retroactive date default amount configuration | | priorPendingLitigationDateSettings | object \| null | Prior/pending litigation date configuration | Unlike the table-based [Configuration Presets](/api-legacy-reference/configuration-presets/overview) endpoint, config-JSON presets do not have `createdAt`, `updatedAt`, or `retroactiveDate` fields. Sorting is by `setName` (default) or `coverageTypeKey` instead of timestamps. ## POST Request Properties | Property | Type | Required | Description | | ---------------------------------- | ------------- | -------- | --------------------------------------------------------- | | ratingEngineRevisionId | string (UUID) | Yes | Rating engine revision to add the preset to | | revisionStrategy | string | Yes | `"UpdateExistingRevision"` or `"CreateNewRevision"` (501) | | coverageTypeKey | string | Yes | Coverage type key (must exist) | | setName | string | Yes | Display name for the preset | | limits | object | Yes | Limit definitions (see below) | | isDefault | boolean | No | Whether this is the default preset (defaults to false) | | defenseInsideLimit | string | No | `"inside"` or `"outside"` | | deductible | number | No | Deductible amount in dollars | | waitingPeriodSettings | object | No | Waiting period configuration | | deductibleSettings | object | No | Deductible default amount configuration | | limitSettings | object | No | Limit default amounts configuration | | retroactiveDateSettings | object | No | Retroactive date default amount configuration | | priorPendingLitigationDateSettings | object | No | Prior/pending litigation date configuration | ### Limits Object | Property | Type | Required | Description | | ---------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------ | | limits | array | Yes | Array of limit definitions | | limits\[].id | string | Yes | Unique identifier for this limit | | limits\[].name | string | Yes | Display name (e.g., "Per Occurrence") | | limits\[].amount | number \| string | No | Limit amount — a number (e.g. 1000000) or a string (e.g. "100%", "-"). Omit when not applicable. | | allowLimitEdits | boolean | No | Whether users can edit limit amounts on quotes | # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/coverage-types/overview Create, manage, and query coverage types and their fields ## Overview Coverage types represent the lines of coverage a company offers, such as General Liability, Workers Compensation, or Auto. Each coverage type has a set of **fields** that determine what data can be recorded on events (claims and incidents) of that type. There are two kinds of coverage types: * **Global** coverage types (e.g., `general_liability`, `inland_marine`) are shared across all companies and cannot be created or deleted via the API. * **Company-specific** coverage types are created and owned by a single company. Use the Coverage Types API to list all available coverage types (global and company-specific), create company-specific coverage types, control which types are active for a company, discover which fields are available for each coverage type, or set the fields on company-specific coverage types. *** ## API Endpoints * **[List Coverage Types](/api-reference/coverage-types/list-coverage-types)** - List all coverage types (global and company-specific) with optional label filtering * **[Create Coverage Type](/api-reference/coverage-types/create-coverage-type)** - Create a new company-specific coverage type * **[Delete Coverage Type](/api-reference/coverage-types/delete-coverage-type)** - Permanently delete a company-specific coverage type * **[Set Enabled Coverage Types](/api-reference/coverage-types/set-enabled-coverage-types)** - Replace the company's enabled coverage types list * **[Get Coverage Type Fields](/api-reference/coverage-types/get-coverage-type-fields)** - Retrieve the fields associated with a coverage type * **[Set Coverage Type Fields](/api-reference/coverage-types/set-coverage-type-fields)** - Replace the fields on a company-specific coverage type *** ## Example: Create a Coverage Type ```json theme={null} POST /api/external/companies/{companyId}/coverage-types { "key": "vfs_general_liability", "label": "General Liability" } ``` Response: ```json theme={null} { "id": "vfs_general_liability" } ``` ## Example: Get Coverage Type Fields ```json theme={null} GET /api/external/companies/{companyId}/coverage-types/general_liability/fields { "coverageTypeId": "general_liability", "coverageTypeName": "General Liability", "fields": [ "reportDate", "eventDescription", "settlementDemand", "indemnityPaid", "alaeReserveAmount" ], "metadata": { "coverageTypeScope": "global", "fieldSources": ["database", "static"] } } ``` # Data Models Source: https://docs.aiinsurance.io/api-legacy-reference/data-models This section provides complete reference documentation for all data structures used in the Submissions and Quotes API. *** ## **Submission Object** | Field | Type | Description | | ---------------------------------------------------------------------- | ----------------- | --------------------------------- | | `id` | string (UUID) | Unique submission identifier | | `createdAt` | string (ISO 8601) | Submission creation timestamp | | `updatedAt` | string (ISO 8601) | Last update timestamp | | [`status`](/api-legacy-reference/data-models#submission-status-values) | string | Current submission status | | [`type`](/api-legacy-reference/data-models#submission-types) | string | Type of submission | | `number` | string | Human-readable submission number | | `primaryInsuredName` | string | Name of the primary insured party | | `applicationId` | string (UUID) | Associated application identifier | | `name` | string | Submission name/description | *** ## **Quote Object (Lightweight)** Returned by the **List Quote Info** endpoint (`GET /api/external/companies/{companyId}/quotes-info`). This lightweight representation includes essential fields only for efficient listing and searching. | Field | Type | Description | | ----------------------------------------------------------------- | --------------------------- | -------------------------------------------------- | | `id` | string (UUID) | Unique quote identifier | | `number` | string | Human-readable quote number (format: Q########-##) | | [`status`](/api-legacy-reference/data-models#quote-status-values) | enum | Current quote status | | `createdAt` | string (ISO 8601) | Quote creation timestamp | | `updatedAt` | string (ISO 8601, optional) | Last update timestamp | | `description` | string (optional) | Quote description from policy info | | `policyId` | string (UUID, optional) | Associated policy identifier (if bound) | | `policyCurrency` | string (optional) | Policy currency code (e.g., "USD", "CAD") | | `grandTotal` | number (optional) | Total premium amount including taxes and fees | *** ## **Quote Object (Full)** Returned by the **List Quotes** (`GET /api/external/companies/{companyId}/quotes`) and **Get Quote** (`GET /api/external/companies/{companyId}/quotes/{quoteId}`) endpoints. This complete representation includes all quote data, coverages, and billing information. | Field | Type | Description | | ----------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------- | | `id` | string (UUID) | Unique quote identifier | | `number` | string | Human-readable quote number | | `wizardType` | enum | Quote workflow type: `quote`, `endorsement`, `renewal`, `forms`, `cancellation` | | [`status`](/api-legacy-reference/data-models#quote-status-values) | enum | Current quote status | | `submissionId` | string (UUID) | Associated submission identifier | | `applicationId` | string (UUID, optional) | Associated application identifier | | `policyId` | string (UUID, optional) | Associated policy identifier (if bound) | | `data` | object | Complete quote data including policy info, coverages, insureds, and billing | | `previewData` | object (optional) | Rating preview data with premium breakdowns | | `billingEmail` | string (optional) | Email address for billing communications | See the **Get Quote** endpoint for the complete QuoteDetail schema with all nested fields. *** ## **ImportPolicy Object** | Field | Type | Description | | --------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- | | `policyNumber` | string | Customer facing policy identifier | | `policyStartDate` | string (ISO 8601) | Date policy begins | | `policyEndDate` | string (ISO 8601) | Date policy ends | | [`policyType`](/api-legacy-reference/data-models#policy-type-options) | enum | A single letter "C", "O", etc. (see below) | | `ratingData` | object | All policy-level rating data (see [config tutorial](/api-legacy-reference/submissions/overview#ratingenginefields)) | | `billingPeriod` | enum | "doNotSendBill", "annual", "quarterly", "monthly" | | `renewingPolicyNumber` | string (optional) | If a renewal, the number of the policy being renewed | | `policyCompanyEntityFields` | object | All non-rating policy-level data (see [config tutorial](/api-legacy-reference/submissions/overview#nonratingfields)) | | `brokerName` | string (optional) | The name of the broker/agent | | `brokerageName` | string (optional) | The name of the brokerage/agency | | `brokerCommission` | number (optional) | A percentage (e.g. 12.3 means 12.3%) | *** ## **ImportPolicyCoverage Object** ```json theme={null} { "coverageTypeId": enum, "deductible": number (in dollars, optional), "retroactibveDate": string (ISO 8601, optional), "priorOrPendingLitigationDate": string (ISO 8601, optional), "defenseInsideLimit": "inside" or "outside" (optional), "presetId": enum (optional), "limits": [{ "limitName": string, "amount": number | string }], "endorsements": { [insuredId]: { "deductible": number, (in dollars, optional) "retroactiveDate": string, // (ISO 8601, optional) "priorOrPendingLitigationDate": string (ISO 8601, optional), "limits": [{ "limitName": string, "amount": number | string }], "presetId": enum (optional) } } } ``` *** ## **ImportInsured Object** | Field | Type | Description | | ---------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------- | | `insuredName` | string | The name of the insured, used to identify in the system | | `joinDate` | string (ISO 8601) | Date coverage begins for insured | | `terminationDate` | string (ISO 8601) | Date coverage ends for insured | | `policyInsuredType` | enum | "primary", "additional", "named", or "related" | | `entityType` | enum | The type of covered exposure | | `applicationData` | object | All insured-level rating data | | `insuredCompanyEntityFields` | object | All non-rating insured-level data (see [config tutorial](/api-legacy-reference/submissions/overview#nonratingfields)) | *** ## **Policy Type Options** | Value | Description | | ----- | -------------------------------------------- | | `C` | Claims Made | | `N` | Claims Made "Nose" (Prior Acts) | | `T` | Claims Made "Tail" (Reporting Endorsement) | | `O` | Occurrence | | `P` | Claims Paid | | `S` | Slot Coverage - Claims Made | | `Q` | Slot Coverage "Tail" (Reporting Endorsement) | | `R` | Slot Coverage - Occurrence | *** ## **Submission Status Values** | Value | Description | | -------------- | ---------------------------------------- | | `draft` | Submission is being prepared | | `submitted` | Submission has been submitted for review | | `under_review` | Submission is being reviewed | | `quoted` | Quote has been generated | | `bound` | Policy has been bound | | `declined` | Submission was declined | *** ## **Submission Types** | Value | Description | | -------------- | --------------------------------------------------------------------------------------------------------------- | | `new_business` | A submission that will create a new policy | | `renewal` | Submission that will create a new policy from an existing one. This new policy can contain updated information. | | `endorsement` | Submission that will update an existing policy | *** ## **Quote Status Values** | Value | Description | | ------------------- | ------------------------------------------- | | `in_progress` | Quote is being created | | `complete` | Quote is complete and ready for review | | `sent` | Quote has been sent to the client | | `accepted` | Quote has been accepted by the client | | `bound` | Quote has been bound to a policy | | `cancelled` | Quote was cancelled | | `archived` | Quote has been archived | | `applied_to_policy` | Quote changes have been applied to a policy | *** ## Field Types | Type | Description | Usage in Submission | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | | `InputField` | A field that takes a value of type `string` or `number`, based on the `fields.type` value | `"key" : "some string"` or `"key" : 555` | | `DateField` | A field that takes a value of type `string` in the format `YYYY-MM-DD` | `"key" : "2025-10-03"` | | `SelectField` or `RadioSelect` | A field that takes a value of type `string` or `number`, based on the `value` property of `fields.options` | `"key" : "some option"`, where `fields.options:[{"value":"some option"},...]` | | `MultiSelectField` | A field that takes a value of type `string`, based on the `value` properties of `fields.options`. | `"key" : "some option 1, some option 2"`, where `fields.options:[{"value":"some option 1"}, {"value":"some option 2"},...]` | | `GroupField` | A field that takes a value of type `array`. This `array` is made of objects, whose keys are found in `fields.subFields`. Each field in `fields.subFields` is a type of `Field` | `"key" : [{"subKey": "value"},...]` | *** ## JSON Schema Format Types Configuration endpoints (like [GET /quotes/configuration](/api-reference/quotes/get-quotes-configuration)) return JSON Schema definitions for custom data fields. The `format` property indicates the semantic type of values: | Format | Type | Description | Example Value | | ---------- | -------- | -------------------------- | ---------------------------------- | | `date` | `string` | ISO 8601 date (YYYY-MM-DD) | `"2025-01-15"` | | `email` | `string` | Email address | `"user@example.com"` | | `phone` | `string` | Phone number | `"+1-555-123-4567"` | | `currency` | `number` | Currency amount (simple) | `1500` | | `currency` | `object` | Currency amount with code | `{ "code": "USD", "value": 1500 }` | | `percent` | `string` | Percentage value | `"15.5"` | | `address` | `string` | Physical address | `"123 Main St, ..."` | ### Currency Fields There are two types of currency fields: 1. **Simple currency** (`type: "number", format: "currency"`): A plain numeric amount. The currency code is typically derived from the policy's currency setting. ```json theme={null} { "annualPremium": 1500 } ``` 2. **Currency with code** (`type: "object", format: "currency"`): An object containing both the currency code and value. Used when the currency may differ from the policy default. ```json theme={null} { "foreignExpense": { "code": "EUR", "value": 2500 } } ``` These formats are used across all configuration endpoints (quotes, events, etc.) and follow [JSON Schema format semantics](https://json-schema.org/understanding-json-schema/reference/string#format). *** ## **Exposure-Level Rating** **Exposure-level rating** is a method of calculating insurance premiums where each individual item or entity covered under a policy (called an "exposure") is rated independently based on its specific characteristics and risk factors. ### How Exposure-Level Rating Works In exposure-level rating, each exposure within a policy is evaluated separately: 1. **Individual Assessment**: Each exposure (e.g., a building, vehicle, healthcare provider, or other entity type) is assessed based on its own unique characteristics, such as: * Physical attributes (size, construction type, location) * Operational details (usage patterns, safety features) * Risk factors specific to that exposure 2. **Independent Premium Calculation**: A premium is calculated for each exposure individually using exposure-specific rating questions and modifier factors. 3. **Aggregation**: The individual exposure premiums are then summed together to form the total exposure-level premium for the policy. 4. **Policy-Level Adjustments**: After exposure-level rating is complete, policy-level modification factors are applied to the aggregated total. ### Exposure-Level vs. Policy-Level Rating * **Exposure-Level Rating**: Evaluates individual entities (exposures) within a policy. Each exposure has its own set of rating questions and modifier factors. Examples include rating a specific doctor's malpractice risk or a particular building's property risk. * **Policy-Level Rating**: Evaluates the policy as a whole, applying factors that affect the entire policy regardless of individual exposures. Examples include organizational risk factors, program-level discounts, or overall policy terms. ### Example Consider a medical malpractice policy covering a hospital with multiple doctors: * **Exposure-Level Rating**: Each doctor (exposure) is rated individually based on: * Their medical specialty * Geographic location * Years of experience * Malpractice history * **Policy-Level Rating**: The policy as a whole is evaluated based on: * Hospital-wide risk management programs * Overall claims history * Negotiated risk agreements The final premium combines both exposure-level and policy-level calculations. For more information about how exposure-level rating fits into the overall data model, see [Understanding the AI Insurance Model](/getting-started/intro-to-aiinsurance/understanding-the-ai-insurance-model#2-exposure-level-rating-data). # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/defendants/overview Defendants represent parties named in a lawsuit. They are sub-resources of lawsuits, which are themselves sub-resources of events. The Defendants API allows you to create, retrieve, update, and delete defendant information for a specific lawsuit. **Key Concepts:** * Defendants belong to a lawsuit, accessed via the event path: `/events/{eventId}/lawsuit/defendants` * Each defendant is either an insured (linked via `insuredId`) or a non-insured party (identified by `nonInsuredName`) — exactly one must be set * Defendants can optionally be linked to an attorney and/or law firm * Deleting a defendant is a soft delete — the record is preserved but no longer returned by GET or LIST *** ## API Endpoints * **[List Defendants](/api-reference/defendants/list-defendants)** - Retrieve paginated list of defendants for a lawsuit * **[Create Defendant](/api-reference/defendants/create-defendant)** - Create a defendant for a lawsuit * **[Get Defendant](/api-reference/defendants/get-defendant)** - Retrieve a single defendant by ID * **[Update Defendant](/api-reference/defendants/update-defendant)** - Update a defendant (send null to clear fields) * **[Delete Defendant](/api-reference/defendants/delete-defendant)** - Soft delete a defendant *** ## Nullable Fields The following fields may be `null` in the response: | Field | When null | | ---------------- | -------------------------------------- | | `insuredId` | Defendant is a non-insured party | | `nonInsuredName` | Defendant is an insured | | `phoneNumber` | Phone number not provided | | `email` | Email not provided | | `attorneyId` | No attorney assigned | | `lawFirmId` | No law firm assigned | | `createdAt` | Timestamp not tracked (legacy records) | | `updatedAt` | Defendant has never been updated | *** ## Filtering and Sorting ### Filter Parameters | Parameter | Type | Description | | ------------ | --------------- | ----------------------------------- | | `id` | string or array | Filter by specific defendant ID(s) | | `filterText` | string | Text search across defendant fields | ### Sorting Parameters | Parameter | Type | Default | Description | | --------------- | ------ | ----------- | ------------------------------------------- | | `sortBy` | string | `createdAt` | Field to sort by (`createdAt`, `updatedAt`) | | `sortDirection` | string | `desc` | Sort direction (`asc` or `desc`) | ### Pagination | Parameter | Type | Default | Description | | --------- | ------- | ------- | ----------------------------------- | | `page` | integer | 1 | Page number (1-based, page size 50) | **Response includes:** * `items` - Array of defendants for the current page * `totalCount` - Total number of matching defendants across all pages *** ## Permissions Access to defendants requires the appropriate permissions based on your API key: | Operation | Required Permission | | ---------------- | ---------------------- | | List Defendants | `company.event:export` | | Create Defendant | `company.event:export` | | Get Defendant | `company.event:export` | | Update Defendant | `company.event:export` | | Delete Defendant | `company.event:export` | *** ## Example Response ```json theme={null} { "items": [ { "id": "550e8400-e29b-41d4-a716-446655440001", "companyId": "660e8400-e29b-41d4-a716-446655440000", "lawsuitId": "770e8400-e29b-41d4-a716-446655440000", "insuredId": null, "nonInsuredName": "John Doe", "phoneNumber": "+1-555-123-4567", "email": "john@example.com", "attorneyId": "880e8400-e29b-41d4-a716-446655440000", "lawFirmId": "990e8400-e29b-41d4-a716-446655440000", "createdAt": "2026-02-15T10:30:00.000Z", "updatedAt": "2026-02-16T14:20:00.000Z" } ], "totalCount": 1 } ``` *** # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/event-financials/overview The Event Financials API allows you to manage financial transactions and reserves for events (claims and incidents). This includes creating payments, tracking reserves, and viewing financial totals across events. **Key Concepts:** * **Transactions**: Financial records associated with events (payments, invoices) * **Reserves**: Expected costs set aside for future payments * **Transaction Types**: Categories like `indemnity_invoice` (loss payments) and `alae_invoice` (allocated loss adjustment expenses) * **Amounts in cents**: Most endpoints return amounts in cents (multiply by 100 from dollars) *** ## API Endpoints ### Transaction Management * **[List Event Transactions](/api-reference/event-financials/list-event-transactions)** - Get paginated list of transactions for an event * **[Get Event Transaction](/api-reference/event-financials/get-event-transaction)** - Get a single transaction with line items * **[Create Event Transaction](/api-reference/event-financials/create-event-transaction)** - Create a new payment or invoice * **[Void Event Transaction](/api-reference/event-financials/void-event-transaction)** - Void an existing transaction * **[Get Event Transaction Totals](/api-reference/event-financials/get-event-transaction-totals)** - Get transaction totals by category for an event ### Reserves & Totals * **[Get Event Reserves](/api-reference/event-financials/get-event-reserves)** - Get reserve amounts by category for an event * **[Update Expected Totals](/api-reference/event-financials/update-expected-totals)** - Update expected total (reserves) for a category * **[List Expected Total Timeline](/api-reference/event-financials/list-expected-total-timeline)** - Get chronological timeline of reserve changes * **[List Financial Totals](/api-reference/event-financials/list-event-financial-totals)** - Get financial totals across all events by transaction type *** ## Transaction Types Transaction types are configurable per company. Common built-in types include: | Type | Description | | ------------------- | ---------------------------------- | | `indemnity_invoice` | Loss payments (indemnity) | | `alae_invoice` | Allocated Loss Adjustment Expenses | Use the [GET /transaction-categories](/api-reference/transaction-categories/list-transaction-categories) endpoint to see all available transaction types for your company. ### Itemized vs Non-Itemized Transaction types can be either: * **Non-itemized**: Single amount per transaction (e.g., `indemnity_invoice`) * **Itemized**: Multiple line items per transaction (e.g., `alae_invoice`) When creating transactions, use the appropriate field: * Non-itemized: `amount` field (required), `lineItems` forbidden * Itemized: `lineItems` array (required), `amount` forbidden *** ## Transaction Status | Status | Description | | ---------- | ---------------------------------------- | | `owed` | Payment is pending/due | | `paid` | Payment has been made | | `approved` | Transaction is approved but not yet paid | | `void` | Transaction has been voided | *** ## Amount Conventions **Important:** Different endpoints use different units: | Endpoint | Unit | | ------------------------- | ----------- | | GET transactions | Cents | | GET reserves | Cents | | GET totals | Cents | | POST transactions | Cents | | **PATCH expected-totals** | **Dollars** | The PATCH expected-totals endpoint uses dollars for historical compatibility. *** ## Reserves vs Expected Totals * **Expected Total**: The anticipated total cost for a category (set by user/adjuster) * **Reserves**: Calculated as `expectedTotal - paid - owed` * **Owed**: Total amount of pending transactions * **Paid**: Total amount of completed transactions Example: ``` Expected Total: $15,000 Paid: $5,000 Owed: $2,000 Reserves: $8,000 (15000 - 5000 - 2000) ``` *** ## Permissions | Operation | Permission | | ---------------------------- | -------------------------------------------------- | | List/Get Transactions | `company.event:export` | | Create Transactions | `company.payment:create` | | Void Transaction | `company.payment:update` | | Get Transaction Totals | `company.payment:read` | | Get Reserves | `company.payment:read` | | Update Expected Totals | `company.claim:update` / `company.incident:update` | | List Expected Total Timeline | `company.payment:read` | | List Financial Totals | `company.payment:read` | *** ## Example: Creating a Payment ```json theme={null} // POST /events/{eventId}/financials/transactions { "transactionType": "indemnity_invoice", "transactionDate": "2025-01-15", "amount": 500000, "payeeId": "550e8400-e29b-41d4-a716-446655440050", "description": "Initial claim payment", "status": "paid", "paidDate": "2025-01-20" } ``` Response: ```json theme={null} { "id": "550e8400-e29b-41d4-a716-446655440010" } ``` *** ## Example: Voiding a Transaction ```json theme={null} // PATCH /events/{eventId}/financials/transactions/{transactionId} { "status": "void", "voidReason": "Duplicate invoice" } ``` Response returns the full transaction detail with `status: "void"` and the provided `voidReason`. *** ## Example: Updating Reserves ```json theme={null} // PATCH /events/{eventId}/financials/expected-totals { "type": "claim", "categoryId": "indemnity_invoice", "expectedTotal": 15000 } ``` Response: ```json theme={null} { "eventId": "550e8400-e29b-41d4-a716-446655440001", "categoryId": "indemnity_invoice", "expectedTotal": 15000, "reserves": 10000 } ``` The `type` field (claim/incident) is required for permission resolution. The event type must match the value provided. *** ## Nullable Fields | Field | When null | | --------------- | ------------------------------------ | | `payeeId` | No payee associated with transaction | | `invoiceNumber` | No invoice number assigned | | `invoiceDate` | No invoice date set | | `dueDate` | No due date set | | `paidDate` | Transaction is not paid | | `description` | No description provided | | `voidReason` | Transaction is not voided | | `reserves` | Category doesn't support reserves | | `updatedAt` | Transaction has never been updated | # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/events/overview Events represent claims and incidents in AI Insurance. The Events API allows you to programmatically create, read, update, and delete event information, including custom entity data specific to your company's configuration. **Key Concepts:** * Events come in two types: **claims** and **incidents** * Events can have **open** or **closed** status * Events must have one or more **insureds** (required) * Events can optionally be associated with a **policy** * Events contain **custom entity data** (`data` field) with field keys mapped to values *** ## API Endpoints * **[List Events](/api-reference/events/list-events)** - Retrieve paginated list of events with filtering and sorting * **[Get Event](/api-reference/events/get-event)** - Retrieve a single event by ID * **[Create Event](/api-reference/events/create-event)** - Create a new claim or incident * **[Update Event](/api-reference/events/update-event)** - Update an existing event * **[Delete Event](/api-reference/events/delete-event)** - Soft delete an event * **[Get Events Configuration](/api-reference/events/get-events-configuration)** - Retrieve JSON Schema for event custom fields *** ## Event Types Events can be one of two types: | Type | Description | | ---------- | ----------------------------------------------- | | `claim` | Insurance claim filed against a policy | | `incident` | Incident or occurrence that may lead to a claim | *** ## Event Status Events can have one of two statuses: | Status | Description | | -------- | ----------------------------------- | | `open` | Event is active and being processed | | `closed` | Event has been resolved and closed | *** ## Associated Insureds Events are associated with one or more insureds via the `insuredIds` field. By default, the API returns an array of insured IDs: ```json theme={null} { "insuredIds": [ "550e8400-e29b-41d4-a716-446655440200", "550e8400-e29b-41d4-a716-446655440201" ] } ``` When using `GET /events/{eventId}`, you can request expanded insured details with `expand=insureds`: ```json theme={null} { "insureds": [ { "id": "550e8400-e29b-41d4-a716-446655440200", "name": "John Smith", "entityType": "individual", "email": "john.smith@example.com", "phoneNumber": "+1-555-123-4567", "billingEmail": null } ] } ``` *** ## Custom Entity Data The `data` field contains custom entity data specific to each company's configuration. This allows you to store and retrieve company-specific information about events. ### Field Keys vs Field IDs **Important:** The `data` field uses **field keys** (human-readable names like "eventDescription") instead of field IDs (UUIDs). ```json theme={null} { "data": { "eventDescription": "Vehicle accident at intersection", "claimAmount": "50000", "adjusterId": "ADJ-12345" } } ``` ### When is `data` null? The `data` field returns: * **`null`** - When no custom entity data exists for the event * **`{ ... }`** - An object with field key-value pairs when custom data exists ### Field Configuration Custom entity data fields are configured per company in AI Insurance. The available fields and their keys depend on your company's setup. To see which fields are available for events, use the [Get Events Configuration](/api-reference/events/get-events-configuration) endpoint. The response includes: * **`data`** — a standard JSON Schema (draft 2020-12) describing all possible fields * **`fieldCoverageTypeMappings`** — maps each field key to `"all"` (applies to all events) or an array of coverage type IDs * **`companyCoverageTypes`** — the list of coverage types enabled for your company ```json theme={null} { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventDescription": { "type": "string", "title": "Event Description" }, "claimAmount": { "type": "number", "title": "Claim Amount", "format": "currency" }, "adjusterId": { "type": "string", "title": "Adjuster ID" } } }, "fieldCoverageTypeMappings": { "eventDescription": "all", "claimAmount": "all", "adjusterId": ["general_liability", "workers_comp"] }, "companyCoverageTypes": ["general_liability", "workers_comp", "auto"] } ``` A field mapped to `"all"` applies to every event. A field mapped to an array of coverage type IDs only applies to events of those coverage types. If a field's coverage type list matches every ID in `companyCoverageTypes`, it effectively applies to all events today — but won't automatically extend to new coverage types added in the future. See [JSON Schema Format Types](/api-legacy-reference/data-models#json-schema-format-types) for the list of supported `format` values. *** ## Nullable Fields The following fields may be `null` in the response: | Field | When null | | ----------- | ------------------------------------------ | | `policyId` | Event is not associated with a policy | | `createdBy` | Creator was not tracked | | `updatedAt` | Event has never been updated | | `data` | No custom entity data exists for the event | *** ## Filtering and Sorting List endpoints support comprehensive filtering and sorting options: ### Filter Parameters | Parameter | Type | Description | | ------------ | --------------- | ------------------------------------------ | | `type` | string or array | Filter by event type (`claim`, `incident`) | | `status` | string or array | Filter by status (`open`, `closed`) | | `policyId` | string | Filter by associated policy ID (UUID) | | `filterText` | string | Text search across event fields | ### Sorting Parameters | Parameter | Type | Default | Description | | --------------- | ------ | ----------- | ---------------------------------------------------------- | | `sortBy` | string | `createdAt` | Field to sort by (`createdAt`, `updatedAt`, `referenceId`) | | `sortDirection` | string | `desc` | Sort direction (`asc` or `desc`) | ### Pagination | Parameter | Type | Default | Description | | --------- | ------- | ------- | ----------------------------------- | | `page` | integer | 1 | Page number (1-based, page size 50) | **Response includes:** * `items` - Array of events for the current page * `totalCount` - Total number of matching events across all pages *** ## Deleting Events with Financial Transactions By default, events with **paid** or **processing** financial transactions cannot be deleted. This protects financial data integrity. If you need to delete such an event, you can set `force: true` in the DELETE request body: ```json theme={null} { "requestorEmail": "user@example.com", "type": "claim", "force": true } ``` **Use `force: true` with caution.** Force deleting an event with financial transactions will **orphan** those financial records. The transactions will remain in the system but will no longer be linked to an event. This action cannot be undone. If you attempt to delete an event with financial transactions without `force: true`, the API will return an error message indicating how many transactions are blocking deletion. *** ## Permissions Access to events requires the appropriate permissions based on your API key. Permissions are event-type specific: | Operation | Claims Permission | Incidents Permission | | ----------------- | ---------------------- | ------------------------- | | List Events | `company.claim:read` | `company.incident:read` | | Get Event | `company.claim:read` | `company.incident:read` | | Create Event | `company.claim:create` | `company.incident:create` | | Update Event | `claim:update` | `incident:update` | | Delete Event | `company.claim:delete` | `company.incident:delete` | | Get Configuration | `company.event:read` | `company.event:read` | **Note:** Update permissions use a slightly different format (`claim:update` vs `company.claim:update`). *** ## Example Response ```json theme={null} { "items": [ { "id": "550e8400-e29b-41d4-a716-446655440001", "companyId": "550e8400-e29b-41d4-a716-446655440000", "type": "claim", "status": "open", "referenceId": "CLM-2025-001", "coverageTypeId": "general_liability", "policyId": "550e8400-e29b-41d4-a716-446655440100", "insuredIds": [ "550e8400-e29b-41d4-a716-446655440200", "550e8400-e29b-41d4-a716-446655440201" ], "createdAt": "2025-01-15T10:30:00.000Z", "createdBy": "google-oauth2|123456789", "updatedAt": "2025-01-16T14:20:00.000Z", "data": { "eventDescription": "Vehicle accident at intersection", "claimAmount": "50000", "dateOfLoss": "2025-01-10" } } ], "totalCount": 42 } ``` *** # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/export-presets/overview List the export presets saved in a company ## Overview An export preset is a named, ordered list of export column keys that one user saved for one entity type (for example `event`, `insured`, `policy` or `quote`). `GET /api/external/companies/{companyId}/export-presets` returns every preset in the company, including presets saved by other users. Results are not paginated and are ordered by `entityType`, then `name`. Preset names are not unique, so two presets with the same name can both appear. ## Filtering | Parameter | Description | | ------------ | ---------------------------------------------------------------- | | `entityType` | Optional. Return only presets whose `entityType` matches exactly | ## Permissions | Endpoint | Method | Permission | | ---------------------------------------------------- | ------ | ---------------------------- | | `/api/external/companies/{companyId}/export-presets` | GET | `company.export_preset:read` | ## Example Response ```json theme={null} { "items": [ { "id": "7a6b5c4d-3e2f-4a1b-8c9d-0e1f2a3b4c5d", "entityType": "policy", "name": "Renewals", "fieldKeys": ["policyNumber", "policyEndDate", "premium"], "owner": { "id": "auth0|64f1a2b3c4d5e6f7a8b9c0d2", "name": "John Doe", "email": "john.doe@example.com" } } ], "totalCount": 1 } ``` `owner` is `null` when the preset has no owner. `entityType` and `name` can also be `null`, and `fieldKeys` is empty, for presets that were saved without those values. # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/exposure-types/overview Manage exposure type definitions for your company ## Overview The Exposure Types API lets you manage the categories of insured entities (exposure types) available to a company. Exposure types define what kinds of exposures can be created — for example, "Franchise Truck Dealer", "Auto", or "Company". Each exposure type has a unique `key` (used as a programmatic identifier) and a `label` (displayed in the UI). ## API Endpoints | Method | Endpoint | Description | | ------ | ---------------------------------- | ----------------------------------------------------- | | GET | `/exposure-types` | List all exposure types with optional label filtering | | POST | `/exposure-types` | Create a new exposure type | | DELETE | `/exposure-types/{exposureTypeId}` | Delete an exposure type | ## Permissions | Action | Permission | | -------------------- | ---------------- | | List exposure types | `company:read` | | Create exposure type | `company:update` | | Delete exposure type | `company:update` | ## Request Properties | Property | Type | Required | Description | | -------- | ------ | -------- | -------------------------------------------------------------------------- | | `value` | string | Yes | Unique identifier for the exposure type (e.g., `"franchise_truck_dealer"`) | | `label` | string | Yes | Human-readable display name (e.g., `"Franchise Truck Dealer"`) | ## Example ```bash theme={null} curl -X POST \ https://app.aiinsurance.io/api/external/companies/{companyId}/exposure-types \ -H "Authorization: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "value": "franchise_truck_dealer", "label": "Franchise Truck Dealer" }' ``` Response: ```json theme={null} { "id": "550e8400-e29b-41d4-a716-446655440003" } ``` # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/exposure/overview The Exposures API allows you to manage exposure entities for your company. Exposures represent the individuals or organizations that are covered by insurance policies. **Key Concepts:** * Exposures are entities (individuals or organizations) covered by insurance policies * Each exposure has a **name** and **entityType** that classify them * Exposures can be associated with policies and events * Deleting an exposure performs a soft delete (the record is marked as deleted but retained) *** ## API Endpoints * **[List Exposures](/api-reference/exposures/list-exposures)** - Retrieve paginated list of exposures with filtering and sorting * **[Get Exposure](/api-reference/exposures/get-exposure)** - Retrieve a single exposure by ID * **[Create Exposure](/api-reference/exposures/create-exposure)** - Create a new exposure * **[Update Exposure](/api-reference/exposures/update-exposure)** - Update an existing exposure * **[Delete Exposure](/api-reference/exposures/delete-exposure)** - Soft delete an exposure by ID *** ## Exposure Fields | Field | Type | Required | Description | | ----------------- | -------- | -------- | -------------------------------------------------------------- | | `id` | uuid | - | Exposure identifier (returned in responses) | | `name` | string | Yes | Name of the exposure | | `entityType` | string | Yes | Entity type (e.g., "individual", "organization", "dealership") | | `email` | string | No | Exposure email address | | `phoneNumber` | string | No | Exposure phone number | | `billingEmail` | string | No | Billing email address | | `defaultBrokerId` | uuid | No | Default broker ID for this exposure | | `policyIds` | uuid\[] | - | IDs of associated policies (returned in list responses) | | `createdAt` | datetime | - | When the exposure was created | *** ## Filtering and Sorting (List) ### Filter Parameters | Parameter | Type | Description | | ------------ | --------------- | --------------------------------------- | | `id` | uuid or uuid\[] | Filter by exposure ID (single or array) | | `entityType` | string | Filter by entity type | | `filterText` | string | Text search across exposure name | ### Sorting Parameters | Parameter | Type | Default | Description | | --------------- | ------ | ----------- | ---------------------------------------------------- | | `sortBy` | string | `createdAt` | Field to sort by (`createdAt`, `name`, `entityType`) | | `sortDirection` | string | `desc` | Sort direction (`asc` or `desc`) | *** ## Permissions Access to exposures requires the appropriate permissions based on your API key: | Operation | Required Permission | | --------------- | ------------------------ | | List Exposures | `company.insured:read` | | Get Exposure | `company.insured:read` | | Create Exposure | `company.insured:create` | | Update Exposure | `insured:update` | | Delete Exposure | `insured:delete` | *** ## Example List Response ```json theme={null} { "items": [ { "id": "550e8400-e29b-41d4-a716-446655440200", "name": "John Smith", "entityType": "individual", "policyIds": ["550e8400-e29b-41d4-a716-446655440100"], "createdAt": "2025-01-15T10:30:00.000Z" } ], "totalCount": 1 } ``` ## Example Create Request ```json theme={null} { "name": "Acme Manufacturing GmbH", "entityType": "organization" } ``` ## Example Create Response ```json theme={null} { "id": "550e8400-e29b-41d4-a716-446655440003" } ``` ## Example Update Request ```json theme={null} { "name": "John Smith Jr.", "email": "john.smith@example.com" } ``` ## Example Update Response ```json theme={null} { "id": "550e8400-e29b-41d4-a716-446655440200", "companyId": "550e8400-e29b-41d4-a716-446655440000", "name": "John Smith Jr.", "entityType": "individual", "phoneNumber": null, "email": "john.smith@example.com", "billingEmail": null, "defaultBrokerId": null, "createdAt": "2025-01-15T10:30:00.000Z", "createdBy": "google-oauth2|123456789", "updatedAt": "2025-01-20T14:00:00.000Z", "updatedBy": "google-oauth2|987654321" } ``` ## Example Delete Response ```json theme={null} { "id": "550e8400-e29b-41d4-a716-446655440002", "deleted": true } ``` *** # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/lawsuits/overview Lawsuits represent legal proceedings associated with insurance events. Each event can have at most one lawsuit. The Lawsuits API allows you to create, retrieve, update, and delete lawsuit information for a specific event. **Key Concepts:** * A lawsuit is a 1:1 sub-resource of an event — each event has at most one lawsuit * Lawsuits are accessed via the event path: `/events/{eventId}/lawsuit` * There is no list endpoint — use the GET endpoint to retrieve the single lawsuit for an event * Creating a lawsuit when one already exists returns `409 Conflict` * Deleting a lawsuit is a soft delete — the record is preserved but no longer returned by GET *** ## API Endpoints * **[Create Lawsuit](/api-reference/lawsuits/create-lawsuit)** - Create a lawsuit for an event (409 if one exists) * **[Get Lawsuit](/api-reference/lawsuits/get-lawsuit)** - Retrieve the lawsuit for an event * **[Update Lawsuit](/api-reference/lawsuits/update-lawsuit)** - Update the lawsuit for an event * **[Delete Lawsuit](/api-reference/lawsuits/delete-lawsuit)** - Soft delete the lawsuit for an event *** ## Nullable Fields The following fields may be `null` in the response: | Field | When null | | ------------------------------- | -------------------------------------- | | `caseNumber` | Case number not assigned | | `caseName` | Case name not provided | | `lawsuitFiledDate` | Filing date not recorded | | `suitServedDate` | Service date not recorded | | `trialDate` | Trial date not scheduled | | `venueName` | Venue not specified | | `venueAddress` | Venue address not provided | | `judgeName` | Judge not assigned | | `plaintiffs` | No plaintiffs recorded | | `plaintiffAttorneyId` | No plaintiff attorney assigned | | `plaintiffLawFirmId` | No plaintiff law firm assigned | | `plaintiffAddress` | Plaintiff address not provided | | `settlementDemand` | No settlement demand recorded | | `settlementType` | Settlement type not set | | `arbitrationInvolved` | Arbitration status not recorded | | `dateDefenseCounselAdded` | Defense counsel date not recorded | | `expertDefense` | No defense expert assigned | | `expertPlaintiff` | No plaintiff expert assigned | | `declaratoryJudgementFiledDate` | No declaratory judgement filed | | `createdAt` | Timestamp not tracked (legacy records) | | `updatedAt` | Lawsuit has never been updated | *** ## Permissions Access to lawsuits requires the appropriate permissions based on your API key: | Operation | Required Permission | | -------------- | ---------------------- | | Create Lawsuit | `company.event:export` | | Get Lawsuit | `company.event:export` | | Update Lawsuit | `company.event:export` | | Delete Lawsuit | `company.event:export` | *** ## Example Response ```json theme={null} { "id": "550e8400-e29b-41d4-a716-446655440001", "companyId": "660e8400-e29b-41d4-a716-446655440000", "eventId": "770e8400-e29b-41d4-a716-446655440000", "caseNumber": "CASE-2026-001", "caseName": "Smith v. Jones Insurance Co.", "lawsuitFiledDate": "2026-01-10T00:00:00.000Z", "suitServedDate": "2026-01-15T00:00:00.000Z", "trialDate": "2026-06-01T00:00:00.000Z", "venueName": "District Court of Springfield", "venueAddress": { "value": "100 Court St, Springfield, IL 62701" }, "judgeName": "Hon. Sarah Williams", "plaintiffs": ["John Smith", "Mary Smith"], "plaintiffAttorneyId": "880e8400-e29b-41d4-a716-446655440000", "plaintiffLawFirmId": "990e8400-e29b-41d4-a716-446655440000", "plaintiffAddress": null, "settlementDemand": "250000", "settlementType": "N", "arbitrationInvolved": "No", "dateDefenseCounselAdded": "2026-01-20T00:00:00.000Z", "expertDefense": "Dr. Expert Defense", "expertPlaintiff": "Dr. Expert Plaintiff", "declaratoryJudgementFiledDate": null, "createdAt": "2026-01-10T10:30:00.000Z", "updatedAt": "2026-02-01T14:20:00.000Z" } ``` *** # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/notes/overview Notes allow you to attach comments and documentation to entities (events, policies, and insureds (exposures)) in AI Insurance. The Notes API supports creating, listing, retrieving, and deleting notes programmatically. **Key Concepts:** * Notes are attached to a specific entity (event, policy, or insured) * Notes can be **privileged** (restricted visibility) or standard * Notes support **author override** for historical imports and on-behalf-of scenarios *** ## API Endpoints * **[List Notes](/api-reference/notes/list-notes)** - Retrieve notes for an entity * **[Create Note](/api-reference/notes/create-note)** - Create a new note * **[Get Note](/api-reference/notes/get-note)** - Retrieve a specific note * **[Delete Note](/api-reference/notes/delete-note)** - Delete a note (soft delete) *** ## Author Override When creating notes via the API, you can specify who the note author should be. This is useful for: * **Historical imports** - Migrating notes from legacy systems with original author names * **On-behalf-of creation** - Creating notes attributed to a specific user ### Author Fields | Field | Type | Description | | ------------ | ------ | ------------------------------------------------------------------------- | | `authorId` | string | ID of an existing user in the system. Use when the author has an account. | | `authorName` | string | Free-text author name. Use for external authors or historical imports. | `authorId` and `authorName` are **mutually exclusive**. Provide one or the other, not both. ### How Author is Determined When creating a note: 1. **If `authorId` is provided** - The note is linked to that user. The user must exist in the system. 2. **If `authorName` is provided** - The name is stored directly (no user lookup). Use for external authors. 3. **If neither is provided** - The note has no specific author assigned. ### Response: Author Display When retrieving notes, the response includes both `author` (user details) and `authorName` (display string): | Response Field | Type | Description | | -------------- | -------------- | -------------------------------------------------------------------------- | | `author` | object or null | User details (`id`, `name`, `email`) if linked to a user, otherwise `null` | | `authorName` | string | Display name using fallback: user's name → stored authorName → "UNKNOWN" | Always use `authorName` for display purposes. It provides a consistent display string regardless of how the author was specified. ### Examples **Creating a note with an existing user as author:** ```json theme={null} { "text": "Note created on behalf of another user.", "authorId": "google-oauth2|123456789" } ``` **Creating a note with an external author name:** ```json theme={null} { "text": "Historical note imported from legacy system.", "authorName": "Jane Doe (External)", "createdAt": "2024-06-15T14:30:00.000Z" } ``` **Response with linked user:** ```json theme={null} { "id": "550e8400-e29b-41d4-a716-446655440003", "entityId": "550e8400-e29b-41d4-a716-446655440001", "entityType": "events", "text": "Adjuster contacted claimant.", "author": { "id": "google-oauth2|123456789", "name": "John Smith", "email": "john@example.com" }, "authorName": "John Smith", "isPrivileged": false, "createdAt": "2025-01-15T10:30:00.000Z", "updatedAt": null } ``` **Response with external author (no linked user):** ```json theme={null} { "id": "550e8400-e29b-41d4-a716-446655440004", "entityId": "550e8400-e29b-41d4-a716-446655440001", "entityType": "events", "text": "Historical note from legacy system.", "author": null, "authorName": "Jane Doe (External)", "isPrivileged": false, "createdAt": "2024-06-01T14:00:00.000Z", "updatedAt": null } ``` *** ## Privileged Notes Notes can be marked as **privileged** to restrict their visibility. Privileged notes are only visible to users with the `privileged_notes:read` permission (typically carrier admins and managers). **Creating a privileged note:** ```json theme={null} { "text": "Internal investigation notes - do not share with claimant.", "isPrivileged": true } ``` To create a privileged note, the requestor must have `privileged_notes:read` permission. The API will return an error if the requestor lacks this permission. *** ## Entity Types Notes can be attached to three entity types: | Entity Type | Permission Required | Example Use Case | | ----------- | --------------------------- | ----------------------------------------------- | | `events` | `claim.notes:read/update` | Claim investigation notes, adjuster comments | | `policies` | `policy.notes:read/update` | Policy documentation, underwriting notes | | `insureds` | `insured.notes:read/update` | Customer communication logs, verification notes | *** ## Pagination and Sorting List endpoints support pagination and sorting: | Parameter | Type | Default | Description | | --------------- | ------- | ----------- | --------------------------------------------- | | `page` | integer | 1 | Page number (1-based) | | `sortBy` | string | `createdAt` | Field to sort by (`createdAt` or `updatedAt`) | | `sortDirection` | string | `desc` | Sort direction (`asc` or `desc`) | **Response includes:** * `items` - Array of notes for the current page * `totalCount` - Total number of matching notes *** # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/overview ## Overview Welcome to the AI Insurance External API documentation. This API allows you to programmatically manage your insurance operations, including submissions, quotes, policies, and more. **Current API Resources:** * **Submissions** - Create and manage insurance submissions * **Quotes** - Generate and retrieve quote information * **Notes** - Attach comments and documentation to entities * **Configuration** - Access your company's rating fields and coverage types **Coming Soon:** * Policies * Events * Insureds * Financials *** ## Getting Started ### Base URL All API endpoints are relative to your AI Insurance instance base URL: ``` https://app.aiinsurance.io ``` ### Route Prefix All legacy API endpoints are served under the `/api/external/` path prefix. V1 API endpoints use a separate `/api/v1/external/` prefix — see the [V1 API Reference](/api-v1-reference/overview). ### Authentication All API requests require authentication using an API key. Include your API key in the request headers: ```bash theme={null} Authorization: YOUR-API-KEY ``` To generate an API key, see [Authentication](/api-legacy-reference/authentication). *** ## API Resources ### Submissions Create and manage insurance submissions with complete policy and insured information. * **[List Submissions](/api-reference/submissions/list-submissions)** - Retrieve submissions for your company * **[Create Submission](/api-reference/submissions/create-submission)** - Create a new submission * **[Update Submission](/api-reference/submissions/update-submission)** - Update an existing submission * **[Overview](/api-legacy-reference/submissions/overview)** - Detailed guide on working with submissions ### Quotes Generate and retrieve quote information for submissions. * **List Quotes** (`GET /api/external/companies/{companyId}/quotes`) - Retrieve complete quote details with all nested data * **List Quote Info** (`GET /api/external/companies/{companyId}/quotes-info`) - Retrieve lightweight quote information (faster) * **Get Quote** (`GET /api/external/companies/{companyId}/quotes/{quoteId}`) - Get detailed quote information by ID See the Quotes section in the sidebar for interactive API documentation. ### Configuration Access your company's configuration including rating fields, coverage types, and entity types. * **[Get Configuration](/api-legacy-reference/configuration)** - Retrieve company configuration *** ## Reference Documentation ### Data Models Complete reference for all data structures used in the API: * **[Submission Object](/api-legacy-reference/data-models#submission-object)** - Submission response structure * **[Quote Object (Lightweight)](/api-legacy-reference/data-models#quote-object-lightweight)** - Lightweight quote representation * **[Quote Object (Full)](/api-legacy-reference/data-models#quote-object-full)** - Complete quote structure * **[ImportPolicy](/api-legacy-reference/data-models#importpolicy-object)** - Policy information for submissions * **[ImportPolicyCoverage](/api-legacy-reference/data-models#importpolicycoverage-object)** - Coverage data * **[ImportInsured](/api-legacy-reference/data-models#importinsured-object)** - Insured party information See [Data Models](/api-legacy-reference/data-models) for complete reference. *** ## Quick Start Example Here's a simple example to create a submission: ```bash theme={null} curl -X POST \ "https://app.aiinsurance.io/api/external/companies//submissions" \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "name": "My First Submission", "type": "new_business", "policy": { "policyNumber": "POL-001", "policyType": "O", "policyStartDate": "2024-01-01", "policyEndDate": "2025-01-01" } }' ``` See the [Submissions Guide](/api-legacy-reference/submissions/overview) for detailed examples and tutorials. *** ## 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 (e.g., creating several submissions as part of a batch import), 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 * The value is stored in the `external_api_audit_log` table (indexed for efficient querying) * Use any string value that helps you identify related requests (e.g., UUID, timestamp, job ID) ### Example: Including batchId ```bash theme={null} # Create multiple submissions with the same batchId for correlation BATCH_ID="import-2024-01-15-abc123" curl -X POST \ "https://app.aiinsurance.io/api/external/companies//submissions" \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "batchId": "'"$BATCH_ID"'", "name": "Submission 1", "type": "new_business", "policy": { "policyNumber": "POL-001", "policyType": "O", "policyStartDate": "2024-01-01", "policyEndDate": "2025-01-01" } }' curl -X POST \ "https://app.aiinsurance.io/api/external/companies//submissions" \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "batchId": "'"$BATCH_ID"'", "name": "Submission 2", "type": "new_business", "policy": { "policyNumber": "POL-002", "policyType": "O", "policyStartDate": "2024-01-01", "policyEndDate": "2025-01-01" } }' ``` This makes it easy to later query the audit log for all API calls associated with a specific batch operation. # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/payees/overview Payees are entities that receive payments, such as law firms, experts, vendors, and other third parties. The Payees API allows you to programmatically create, read, update, and delete payee information within your company. **Key Concepts:** * Payees represent external entities that receive payments from insurance operations * Each payee has a **type** (lawFirm, expert, vendor, other, financingCompany) * Law firm payees can specify a **law firm type** (defense or plaintiff) * Payees can have bank information for payment processing * Only "saved" payees (isSaved: true) are returned by the API. A non-saved payee is one that was created via a UI flow but for which no transaction was ever completed. *** ## API Endpoints * **[List Payees](/api-reference/payees/list-payees)** - Retrieve paginated list of payees with filtering and sorting * **[Get Payee](/api-reference/payees/get-payee)** - Retrieve a single payee by ID * **[Create Payee](/api-reference/payees/create-payee)** - Create a new payee * **[Update Payee](/api-reference/payees/update-payee)** - Update an existing payee * **[Delete Payee](/api-reference/payees/delete-payee)** - Soft delete a payee *** ## Payee Types | Type | Description | | ------------------ | ------------------------------------------- | | `lawFirm` | Law firm (can specify defense or plaintiff) | | `expert` | Expert witness or consultant | | `vendor` | Third-party vendor or service provider | | `other` | Other type of payee | | `financingCompany` | Financing or premium finance company | *** ## Law Firm Types When `payeeType` is `lawFirm`, you can specify the `lawFirmType`: | Type | Description | | ----------- | ---------------------------------------- | | `defense` | Defense counsel representing the insured | | `plaintiff` | Plaintiff counsel (opposing party) | *** ## Structured Address The `addressStructured` field contains a detailed address object with the following fields: | Field | Type | Description | | -------------- | ------ | ---------------------------------------- | | `streetNumber` | string | Street number | | `streetName` | string | Street name | | `city` | string | City name | | `state` | object | State with `short` and `long` properties | | `postalCode` | string | ZIP or postal code | | `country` | string | Country name or code | | `county` | string | County name | | `neighborhood` | string | Neighborhood name | | `sublocality` | string | Sublocality or district | | `timezone` | string | Timezone identifier | | `location` | object | Geographic coordinates (`lat`, `lng`) | *** ## Bank Information The `bankInfo` field contains payment information: | Field | Type | Description | | ------------------- | ---------------- | ------------------- | | `bankAccountNumber` | string or number | Bank account number | | `bankRoutingNumber` | string or number | Bank routing number | *** ## Nullable Fields The following fields may be `null` in the response: | Field | When null | | ------------------- | -------------------------------------- | | `email` | Email not provided | | `alternateEmails` | No alternate emails provided | | `phoneNumber` | Phone number not provided | | `description` | Description not provided | | `address` | Unstructured address not provided | | `addressStructured` | Structured address not provided | | `lawFirmType` | Payee is not a law firm | | `bankInfo` | Bank information not provided | | `taxIdNumber` | Tax ID not provided | | `externalPayee` | No external system reference | | `createdAt` | Timestamp not tracked (legacy records) | | `createdBy` | Created by system or unknown user | | `updatedAt` | Payee has never been updated | | `updatedBy` | Never updated or updated by system | *** ## Filtering and Sorting List endpoints support comprehensive filtering and sorting options: ### Filter Parameters | Parameter | Type | Description | | ------------ | --------------- | ------------------------------ | | `id` | string or array | Filter by specific payee ID(s) | | `payeeType` | string | Filter by payee type | | `filterText` | string | Text search across payee name | ### Sorting Parameters | Parameter | Type | Default | Description | | --------------- | ------ | ----------- | ------------------------------------------------------------------------- | | `sortBy` | string | `createdAt` | Field to sort by (`createdAt`, `updatedAt`, `name`, `email`, `payeeType`) | | `sortDirection` | string | `desc` | Sort direction (`asc` or `desc`) | ### Pagination | Parameter | Type | Default | Description | | --------- | ------- | ------- | ----------------------------------- | | `page` | integer | 1 | Page number (1-based, page size 50) | **Response includes:** * `items` - Array of payees for the current page * `totalCount` - Total number of matching payees across all pages *** ## Permissions Access to payees requires the appropriate permissions based on your API key: | Operation | Required Permission | | ------------ | ---------------------- | | List Payees | `company.payee:read` | | Get Payee | `company.payee:read` | | Create Payee | `company.payee:create` | | Update Payee | `company.payee:create` | | Delete Payee | `company.payee:create` | *** ## Example Response ```json theme={null} { "items": [ { "id": "550e8400-e29b-41d4-a716-446655440001", "companyId": "660e8400-e29b-41d4-a716-446655440000", "name": "Smith & Associates Law Firm", "payeeType": "lawFirm", "email": "contact@smithlaw.com", "alternateEmails": ["billing@smithlaw.com"], "phoneNumber": "+1-555-123-4567", "description": "Defense law firm specializing in insurance litigation", "address": "123 Legal Plaza, Suite 500, New York, NY 10001", "addressStructured": { "streetNumber": "123", "streetName": "Legal Plaza", "city": "New York", "state": { "short": "NY", "long": "New York" }, "postalCode": "10001", "country": "US" }, "lawFirmType": "defense", "bankInfo": { "bankAccountNumber": "****1234", "bankRoutingNumber": "****5678" }, "taxIdNumber": "12-3456789", "externalPayee": null, "createdAt": "2025-01-15T10:30:00.000Z", "createdBy": "880e8400-e29b-41d4-a716-446655440000", "updatedAt": "2025-01-16T14:20:00.000Z", "updatedBy": "880e8400-e29b-41d4-a716-446655440000" } ], "totalCount": 42 } ``` *** # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/policies/overview The Policies API allows you to manage policies for your company. Policies represent the insurance contracts that have been issued. **Key Concepts:** * Policies are insurance contracts issued to insureds * Each policy has a **number**, **primary insured**, and effective dates * Policies are divided into **segments** when exposures change mid-term * Policies can be created directly for historical imports, or via the quote→bind flow * Results are paginated with a fixed page size of 50 *** ## API Endpoints * **[List Policies](/api-reference/policies/list-policies)** - Retrieve paginated list of policies with filtering and sorting * **[Get Policy](/api-reference/policies/get-policy)** - Retrieve detailed policy information including segments, coverages, and rating inputs * **[Create Policy](/api-reference/policies/create-policy)** - Create a policy directly (for historical imports) * **[Delete Policy](/api-reference/policies/delete-policy)** - Soft delete a policy by ID *** ## Policy Segments When exposures (insureds) are added, removed, or modified mid-term, policies are automatically divided into **segments**. Each segment represents a period where policy data is constant. **Example:** A policy running from Jan 1 to Dec 31 has one exposure. On June 1, a second exposure is added. The policy will have two segments: * **Segment 1:** Jan 1 - May 31 (one exposure) * **Segment 2:** Jun 1 - Dec 31 (two exposures) Each segment includes: * Date range (`start`, `end`) * Status (`bound`, `quoted`, `cancelled`) * Premium and base premium totals * Full coverage details with limits * Exposure-level rating inputs showing how premiums were calculated *** ## Time Travel (Historical Views) The Get Policy endpoint supports the `asOf` query parameter to retrieve the policy state as it existed at a specific point in time: ``` GET /api/external/companies/{companyId}/policies/{policyId}?asOf=2024-06-15T10:00:00Z ``` This is useful for: * **Auditing:** Understanding the policy state at a specific date * **Reporting:** Generating historical reports * **Debugging:** Seeing how the policy looked before endorsements *** ## Creating Policies The Create Policy endpoint is primarily designed for **historical imports** where policies need to be created without going through the standard quote→bind wizard flow. **Workflow:** 1. Create insureds first via `POST /insureds` 2. (Optional) Create broker via `POST /brokers` if policy has a broker 3. Create the policy with insured and broker references via `POST /policies` 4. The endpoint automatically creates insured snapshots with the provided `ratingInfo` ### Required Fields | Field | Type | Description | | --------------- | ------ | ----------------------------------------------------- | | `referenceId` | string | Policy number (must be unique per company) | | `startsAtDate` | date | Policy effective start date (YYYY-MM-DD) | | `endsAtDate` | date | Policy effective end date (YYYY-MM-DD) | | `type` | string | Policy type (C, N, T, O, P, S, Q, R, A) | | `billingPeriod` | string | Billing frequency (annual, quarterly, monthly, etc.) | | `exposures` | array | At least one exposure with exactly one role "primary" | | `coverages` | array | At least one coverage with valid coverageTypeId | ### Optional Fields | Field | Type | Description | | ------------------ | ------ | ------------------------------------------------- | | `coverageTimezone` | string | IANA timezone (defaults to company default) | | `description` | string | Policy description | | `premium` | number | Premium in cents (overrides rating calculation) | | `brokerId` | uuid | ID of existing broker (use `POST /brokers` first) | ### Policy Types | Code | Description | | ---- | ----------------------------------- | | C | Claims Made | | N | New Claims Made | | T | Tail | | O | Occurrence | | P | Occurrence + Claims Made | | S | Split (Half Claims Made/Occurrence) | | Q | Quota Share | | R | Occurrence + Claims Made + Tail | | A | Claims Made (Alternative) | *** ## Policy Fields (List Response) | Field | Type | Description | | ------------------ | --------- | ---------------------------------------- | | `id` | uuid | Policy identifier | | `companyId` | uuid | Company identifier | | `number` | string | Policy number | | `createdAt` | datetime | When the policy was created (ISO 8601) | | `primaryInsuredId` | uuid/null | ID of the primary insured on this policy | *** ## Policy Fields (Get Response) The Get Policy endpoint returns detailed information including all list fields plus: | Field | Type | Description | | ------------------------- | ------------- | -------------------------------------------------- | | `policyId` | uuid | Policy identifier (same as `id`) | | `policyNumber` | string/null | Policy number (same as `referenceId`) | | `referenceId` | string/null | Policy reference ID | | `startsAtDate` | date/null | Policy effective start date | | `endsAtDate` | date/null | Policy effective end date | | `status` | string | Current policy status (see below) | | `termStart` | date/null | Policy term start date | | `termEnd` | date/null | Policy term end date | | `sourceTransactionId` | uuid/null | Transaction that created/modified the policy | | `effectiveTimestamp` | datetime/null | When current state became effective | | `segments` | array | Policy segments with coverage and exposure details | | `type` | string/null | Policy type code (C, N, T, O, etc.) | | `description` | string/null | Policy description | | `coverageTimezone` | string/null | IANA timezone for coverage dates | | `currencyCode` | string/null | ISO 4217 currency code (e.g., "USD") | | `prevPolicyId` | uuid/null | ID of previous policy (for renewal chains) | | `cancelledAt` | datetime/null | Timestamp when policy was cancelled | | `brokerId` | string/null | ID of the broker associated with this policy | | `recipientName` | string/null | Name of the policy recipient | | `recipientEmail` | string/null | Email of the policy recipient | | `primaryInsuredName` | string/null | Name of the primary insured | | `cancellationReason` | string/null | Reason for policy cancellation | | `cancellationExplanation` | string/null | Additional cancellation explanation | ### Policy Status Values | Status | Description | | --------------------- | ---------------------------------------- | | `active` | Policy is currently in effect | | `not_started` | Policy start date is in the future | | `expired` | Policy end date is in the past | | `pending_signature` | Awaiting policyholder signature | | `pending_payment` | Awaiting payment | | `pending_actions` | Awaiting both signature and payment | | `pending_renewal` | Within 60 days of renewal date | | `renewal_in_progress` | Renewal submission created but not bound | | `renewed` | Policy has been renewed | | `cancelled` | Policy has been cancelled | ### Segment Fields Each segment in the `segments` array contains: | Field | Type | Description | | ------------- | ----------- | -------------------------------------------------- | | `start` | date | Segment start date | | `end` | date | Segment end date | | `status` | string | Segment status (`bound`, `quoted`, `cancelled`) | | `premium` | number/null | Total premium for segment (cents) | | `basePremium` | number/null | Base premium before adjustments (cents) | | `coverages` | array | Coverages active during this segment | | `exposures` | array | Exposures with premium breakdown and rating inputs | ### Exposure Fields Each exposure in a segment contains: | Field | Type | Description | | -------------- | ----------- | ---------------------------------------------------------- | | `exposureId` | uuid | Exposure (insured) identifier | | `exposureType` | string/null | Type of exposure (e.g., "company", "distribution\_center") | | `premium` | number/null | Premium for this exposure (cents) | | `basePremium` | number/null | Base premium before adjustments (cents) | | `ratingInputs` | object/null | Rating factors by coverage type (see below) | ### Rating Inputs Structure The `ratingInputs` object is keyed by coverage type ID. Each coverage contains rating factor objects with: | Field | Type | Description | | ----------------- | ------------ | ------------------------------ | | `fieldName` | string | Human-readable factor name | | `adjustedPremium` | number | Premium after factor applied | | `multiplier` | number/array | Multiplier value(s) | | `value` | number/array | Base value(s) used | | `days` | integer | Days for pro-rata calculations | | `base` | integer | Base days (typically 365) | *** ## Filtering and Sorting ### Filter Parameters | Parameter | Type | Description | | ------------------ | ------ | ------------------------------------------------- | | `primaryInsuredId` | uuid | Filter by primary insured ID | | `filterText` | string | Text search across policy number and other fields | ### Sorting Parameters | Parameter | Type | Default | Description | | --------------- | ------ | ----------- | ----------------------------------------------------------------------------------- | | `sortBy` | string | `createdAt` | Field to sort by (`createdAt`, `updatedAt`, `number`, `startsAtDate`, `endsAtDate`) | | `sortDirection` | string | `desc` | Sort direction (`asc` or `desc`) | ### Pagination | Parameter | Type | Default | Description | | --------- | ------- | ------- | ----------------------------------- | | `page` | integer | 1 | Page number (1-based, page size 50) | **Response includes:** * `items` - Array of policies for the current page * `totalCount` - Total number of matching policies across all pages *** ## Permissions Access to policies requires the appropriate permissions based on your API key: | Operation | Required Permission | | ------------- | ----------------------- | | List Policies | `company.policy:read` | | Get Policy | `company.policy:read` | | Create Policy | `company.policy:create` | | Delete Policy | `policy:delete` | *** ## Example: Create Policy Request ```json theme={null} { "referenceId": "POL-2025-001", "startsAtDate": "2025-01-01", "endsAtDate": "2026-01-01", "type": "C", "billingPeriod": "annual", "exposures": [ { "insuredId": "550e8400-e29b-41d4-a716-446655440200", "role": "primary", "joinDate": "2025-01-01", "terminationDate": "2026-01-01", "ratingInfo": { "revenue": 5000000, "employees": 25 } } ], "coverages": [ { "coverageTypeId": "550e8400-e29b-41d4-a716-446655440300" } ] } ``` **Response:** `201 Created` ```json theme={null} { "id": "550e8400-e29b-41d4-a716-446655440100" } ``` *** ## Example: List Policies Response ```json theme={null} { "items": [ { "id": "550e8400-e29b-41d4-a716-446655440100", "companyId": "550e8400-e29b-41d4-a716-446655440000", "number": "POL-2025-001", "createdAt": "2025-01-15T10:30:00.000Z", "primaryInsuredId": "550e8400-e29b-41d4-a716-446655440200" }, { "id": "550e8400-e29b-41d4-a716-446655440101", "companyId": "550e8400-e29b-41d4-a716-446655440000", "number": "POL-2025-002", "createdAt": "2025-01-16T14:20:00.000Z", "primaryInsuredId": "550e8400-e29b-41d4-a716-446655440201" } ], "totalCount": 42 } ``` *** ## Example: Get Policy Response ```json theme={null} { "id": "84f9b186-08fc-408a-8f8c-d739e161c423", "policyId": "84f9b186-08fc-408a-8f8c-d739e161c423", "companyId": "7626bc64-e937-4f52-bb4a-05848bd09860", "referenceId": "POL-2025-001", "policyNumber": "POL-2025-001", "createdAt": "2025-01-19T14:58:29.000+00:00", "primaryInsuredId": "c018b789-d235-4597-bf2e-8c308465b890", "primaryInsuredName": "Acme Corporation", "startsAtDate": "2025-01-19", "endsAtDate": "2026-01-19", "status": "active", "termStart": "2025-01-19", "termEnd": "2026-01-19", "sourceTransactionId": "61b8357e-f92c-404e-825c-63432974c8a1", "effectiveTimestamp": "2025-01-19T15:01:45.000+00:00", "type": "C", "description": "Professional Liability Policy", "coverageTimezone": "America/New_York", "currencyCode": "USD", "prevPolicyId": null, "cancelledAt": null, "brokerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "recipientName": "John Smith", "recipientEmail": "john.smith@acme.com", "cancellationReason": null, "cancellationExplanation": null, "segments": [ { "start": "2025-01-19", "end": "2025-05-18", "status": "bound", "premium": 293016, "basePremium": 328490, "coverages": [ { "id": "d4d4b369-4b4c-4240-bb32-cfce31be99d7", "coverageTypeId": "bodily_injury_and_property_damage", "coverageTypeName": "Bodily Injury and Property Damage", "deductible": 25000, "defenseInsideLimit": "outside", "limits": [ { "id": "716bf78a-f714-4904-89b6-053b4e7793b7", "name": "Each Occurrence", "amount": 1000000 } ] } ], "exposures": [ { "exposureId": "c018b789-d235-4597-bf2e-8c308465b890", "exposureType": "company", "premium": 146508, "basePremium": 164245, "ratingInputs": { "bodily_injury_and_property_damage": { "bipdBaseRate": { "fieldName": "BIPD Base Rate", "multiplier": 46350, "adjustedPremium": 46350 }, "deductibleMultiplier": { "fieldName": "Deductible Multiplier", "multiplier": 0.7, "adjustedPremium": 32445 } } } } ] } ] } ``` *** # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/quotes/overview Quotes represent insurance pricing proposals in AI Insurance. The Quotes API allows you to programmatically create, read, and delete quotes, including policy information and custom data specific to your company's configuration. **Key Concepts:** * Quotes are associated with a **submission** * Quotes progress through various **statuses** from creation to binding * Quotes contain **policy information** (`policyInfo`) with coverage details and custom data * When bound, quotes become **policies** *** ## API Endpoints * **[List Quotes](/api-reference/quotes/list-quotes)** - Retrieve paginated list of quotes with filtering and sorting * **[Create Quote](/api-reference/quotes/create-quote)** - Create a new quote * **[List Quote Info](/api-reference/quotes/list-quote-info)** - Retrieve lightweight quote information (faster for dashboards) * **[Get Quote](/api-reference/quotes/get-quote)** - Retrieve a single quote by ID with full details * **[Delete Quote](/api-reference/quotes/delete-quote)** - Soft delete a quote * **[Get Quotes Configuration](/api-reference/quotes/get-quotes-configuration)** - Retrieve JSON Schema for quote custom fields *** ## Quote Status Quotes progress through the following statuses: | Status | Description | | ------------------- | ---------------------------------------------- | | `in_progress` | Quote is being prepared | | `complete` | Quote is complete and ready to send | | `sent` | Quote has been sent to the applicant | | `accepted` | Quote has been accepted by the applicant | | `bound` | Quote has been bound and converted to a policy | | `cancelled` | Quote has been cancelled | | `archived` | Quote has been archived | | `applied_to_policy` | Quote has been applied to an existing policy | *** ## Policy Information Quotes contain a `policyInfo` object with policy-level details: ```json theme={null} { "policyInfo": { "policyNumber": "POL-2025-001", "policyStartDate": "2025-01-01T00:00:00.000Z", "policyEndDate": "2026-01-01T00:00:00.000Z", "data": { "policyDescription": "General Liability Coverage", "specialConditions": "Standard terms apply" } } } ``` ### Custom Data The `policyInfo.data` field contains custom data specific to your company's configuration. This allows you to store and retrieve company-specific information about quotes and policies. **Important:** The `data` field uses **field keys** (human-readable names) instead of field IDs (UUIDs). ### Field Configuration Custom data fields are configured per company in AI Insurance. To see which fields are available for quotes, use the [Get Quotes Configuration](/api-reference/quotes/get-quotes-configuration) endpoint. The response structure mirrors the quote request shape, making it clear where each schema applies: ```json theme={null} { "policyInfo": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "policyDescription": { "type": "string", "title": "Policy Description" }, "effectiveDate": { "type": "string", "title": "Effective Date", "format": "date" }, "contactEmail": { "type": "string", "title": "Contact Email", "format": "email" }, "coverageTerritory": { "type": "string", "title": "Coverage Territory", "enum": ["domestic", "worldwide", "north_america"] } } } } } ``` The `policyInfo.data` schema is a standard JSON Schema (draft 2020-12) that you can use directly with validation libraries like Ajv or Zod. See [JSON Schema Format Types](/api-legacy-reference/data-models#json-schema-format-types) for the list of supported `format` values. *** ## Filtering and Sorting List endpoints support comprehensive filtering and sorting options: ### Filter Parameters | Parameter | Type | Description | | --------------- | --------------- | -------------------------------------------- | | `submissionId` | string | Filter by submission ID (UUID) | | `applicationId` | string | Filter by application ID (UUID) | | `status` | string or array | Filter by quote status | | `filterText` | string | Text search across quote fields | | `dateFrom` | string | Filter quotes created on or after this date | | `dateTo` | string | Filter quotes created on or before this date | ### Sorting Parameters | Parameter | Type | Default | Description | | --------------- | ------ | ----------- | --------------------------------------------------------------- | | `sortBy` | string | `createdAt` | Field to sort by (`createdAt`, `updatedAt`, `status`, `number`) | | `sortDirection` | string | `desc` | Sort direction (`asc` or `desc`) | ### Pagination | Parameter | Type | Default | Description | | --------- | ------- | ------- | ----------------------------------- | | `page` | integer | 1 | Page number (1-based, page size 50) | **Response includes:** * `items` - Array of quotes for the current page * `totalCount` - Total number of matching quotes across all pages *** ## Permissions Access to quotes requires the appropriate permissions based on your API key: | Operation | Required Permission | | ----------------- | ---------------------- | | List Quotes | `company.quote:read` | | Get Quote | `company.quote:read` | | Create Quote | `company.quote:create` | | Delete Quote | `company.quote:delete` | | Get Configuration | `company.quote:read` | *** ## Example Response ```json theme={null} { "items": [ { "id": "550e8400-e29b-41d4-a716-446655440002", "number": "Q00000001-01", "status": "complete", "submissionId": "550e8400-e29b-41d4-a716-446655440001", "createdAt": "2025-01-15T10:30:00.000Z", "description": "General Liability Coverage", "policyCurrency": "USD", "grandTotal": 2700.00, "policyInfo": { "policyNumber": "POL-2025-001", "policyStartDate": "2025-01-01T00:00:00.000Z", "policyEndDate": "2026-01-01T00:00:00.000Z", "data": { "policyDescription": "General Liability Coverage", "specialConditions": "Standard terms apply" } } } ], "totalCount": 15 } ``` *** # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/smart-tags/overview Retrieve smart tags for categorizing and labeling entities ## Overview Smart tags are customizable labels that can be applied to entities within the system. They provide a flexible way to categorize, filter, and organize data according to your business needs. Each smart tag includes: * **tagName**: A unique identifier for the tag (used programmatically) * **tagDisplayName**: A human-readable display name * **tagDescription**: Optional description explaining the tag's purpose * **tagCategories**: Array of category strings for grouping related tags * **tagData**: Flexible JSON object for storing additional metadata ## Use Cases Smart tags can be used to: * Categorize policies by coverage type or risk profile * Label insureds by segment or acquisition channel * Mark events by severity or handling priority * Group entities for reporting and analytics ## Permissions * **Read**: Requires `company:read` permission ## Example Response ```json theme={null} { "items": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "companyId": "123e4567-e89b-12d3-a456-426614174000", "tagName": "high_value_account", "tagDisplayName": "High Value Account", "tagDescription": "Accounts with annual premium over $100k", "tagCategories": ["account_tier", "priority"], "tagData": { "type": "account_classification" }, "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z" } ], "totalCount": 1 } ``` # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/submissions/overview Submissions are containers for quotes in AI Insurance. The Submissions API allows you to programmatically create, read, update, and delete submissions. **Key Concepts:** * Submissions are containers for **quotes** - create a submission first, then add quotes via the [Quotes API](/api-legacy-reference/quotes/overview) * Submissions progress through various **statuses** from creation to binding * Submissions have a **type** indicating if it's new business, renewal, endorsement, or cancellation * For renewals, submissions can reference the **renewing policy** via `renewingPolicyId` *** ## API Endpoints * **[List Submissions](/api-reference/submissions/list-submissions)** - Retrieve paginated list of submissions with filtering and sorting * **[Create Submission](/api-reference/submissions/create-submission)** - Create a new submission * **[Get Submission](/api-reference/submissions/get-submission)** - Retrieve a single submission by ID * **[Update Submission](/api-reference/submissions/update-submission)** - Update an existing submission * **[Delete Submission](/api-reference/submissions/delete-submission)** - Soft delete a submission * **[Attach Files to Submission](/api-reference/submissions/attach-files-to-submission)** - Attach one or more PDF files to a submission * **[Get Submission Loss History](/api-reference/submissions/get-submission-loss-history)** - Retrieve the loss history entries on a submission * **[Set Submission Loss History](/api-reference/submissions/set-submission-loss-history)** - Replace the loss history entries on a submission * **[Add Submission Loss History Entries](/api-reference/submissions/add-submission-loss-history-entries)** - Append entries to the loss history on a submission *** ## Submission Status Submissions progress through the following statuses: | Status | Description | | ------------------- | ---------------------------------------------- | | `in_progress` | Submission is being prepared | | `submitted` | Submission has been submitted for review | | `quote_in_progress` | Quote is being prepared | | `quoted` | Quote has been generated | | `bound` | Quote has been bound and converted to a policy | | `declined` | Submission was declined | | `expired` | Submission has expired | | `cancelled` | Submission was cancelled | *** ## Submission Type When creating a submission via the API, use these type values: | API Type | Description | | --------------- | ------------------------------------- | | `quote` | New business submission | | `renewal` | Renewal of an existing policy | | `endorsement` | Mid-term change to an existing policy | | `cancellation` | Cancellation of an existing policy | | `reinstatement` | Reinstatement of a cancelled policy | Use `quote` as the type for new business submissions. The API maps this to `new_business` internally. *** ## Submission Workflow ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Create │────▶│ Add Quotes │────▶│ Bind Quote │ │ Submission │ │ (Quotes API) │ │ (Creates │ │ │ │ │ │ Policy) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` 1. **Create Submission** - Use `POST /submissions` to create a new submission 2. **Add Quotes** - Use the [Quotes API](/api-legacy-reference/quotes/overview) to add quotes to the submission 3. **Bind Quote** - When a quote is bound, it becomes a policy *** ## Associated Quotes When using `GET /submissions/{submissionId}`, submissions include a `quoteIds` array by default: ```json theme={null} { "quoteIds": [ "660e8400-e29b-41d4-a716-446655440001", "660e8400-e29b-41d4-a716-446655440002" ] } ``` You can request expanded quote details with `expand=quotes`: ```json theme={null} { "quotes": [ { "id": "660e8400-e29b-41d4-a716-446655440001", "number": "Q00000001-01", "status": "complete", "submissionId": "550e8400-e29b-41d4-a716-446655440001", "applicationId": null, "policyId": null, "description": "General Liability Coverage", "policyCurrency": "USD", "grandTotal": 2500.00, "createdAt": "2024-01-15T11:00:00.000Z", "updatedAt": "2024-01-15T12:00:00.000Z" } ] } ``` *** ## List vs Get Response The **List Submissions** endpoint returns minimal fields for performance: | Field | List | Get | | ---------------------- | ---- | --- | | `id` | ✓ | ✓ | | `companyId` | | ✓ | | `number` | ✓ | ✓ | | `name` | ✓ | ✓ | | `status` | ✓ | ✓ | | `type` | ✓ | ✓ | | `primaryInsuredName` | ✓ | ✓ | | `applicationId` | ✓ | ✓ | | `renewingPolicyId` | | ✓ | | `renewingPolicyNumber` | | ✓ | | `declineReason` | | ✓ | | `quoteIds` | | ✓ | | `createdAt` | ✓ | ✓ | | `updatedAt` | ✓ | ✓ | | `closedAt` | | ✓ | | `boundAt` | | ✓ | *** ## Nullable Fields The following fields may be `null` in the response: | Field | When null | | ---------------------- | ------------------------------------ | | `name` | Submission name not set | | `primaryInsuredName` | No primary insured on the submission | | `applicationId` | Application not linked | | `renewingPolicyId` | Not a renewal or policy not linked | | `renewingPolicyNumber` | Not a renewal or policy not linked | | `declineReason` | Submission not declined | | `updatedAt` | Submission has never been updated | | `closedAt` | Submission not closed | | `boundAt` | Submission not bound | *** ## Filtering and Sorting List endpoints support comprehensive filtering and sorting options: ### Filter Parameters | Parameter | Type | Description | | ------------ | --------------- | ------------------------------------ | | `status` | string or array | Filter by submission status | | `type` | string or array | Filter by submission type | | `filterText` | string | Text search across submission fields | ### Sorting Parameters | Parameter | Type | Default | Description | | --------------- | ------ | ----------- | ----------------------------------------------------------------- | | `sortBy` | string | `createdAt` | Field to sort by (`createdAt`, `updatedAt`, `primaryInsuredName`) | | `sortDirection` | string | `desc` | Sort direction (`asc` or `desc`) | ### Pagination | Parameter | Type | Default | Description | | --------- | ------- | ------- | ----------------------------------- | | `page` | integer | 1 | Page number (1-based, page size 50) | **Response includes:** * `items` - Array of submissions for the current page * `totalCount` - Total number of matching submissions across all pages *** ## Deleting Submissions Submissions with associated quotes cannot be deleted. You must delete all quotes first using the [Quotes API](/api-legacy-reference/quotes/overview) before deleting the submission. *** ## Permissions Access to submissions requires the appropriate permissions based on your API key: | Operation | Required Permission | | -------------------------- | --------------------------- | | List Submissions | `company.submission:read` | | Get Submission | `company.submission:read` | | Create Submission | `company.submission:create` | | Update Submission | `company.submission:update` | | Delete Submission | `company.submission:delete` | | Attach Files to Submission | `submission.file:create` | | Set Loss History | `submission:update` | | Add Loss History Entries | `submission:update` | *** ## Example List Response ```json theme={null} { "items": [ { "id": "550e8400-e29b-41d4-a716-446655440001", "number": "SUB-2024-001", "name": "Acme Corp Submission", "status": "quoted", "type": "new_business", "primaryInsuredName": "Acme Corporation", "applicationId": "550e8400-e29b-41d4-a716-446655440010", "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-16T14:20:00.000Z" } ], "totalCount": 150 } ``` *** ## Example Get Response ```json theme={null} { "id": "550e8400-e29b-41d4-a716-446655440001", "companyId": "660e8400-e29b-41d4-a716-446655440000", "number": "SUB-2024-001", "name": "Acme Corp Submission", "status": "quoted", "type": "new_business", "primaryInsuredName": "Acme Corporation", "applicationId": "550e8400-e29b-41d4-a716-446655440010", "renewingPolicyId": null, "renewingPolicyNumber": null, "declineReason": null, "quoteIds": [ "660e8400-e29b-41d4-a716-446655440001", "660e8400-e29b-41d4-a716-446655440002" ], "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-16T14:20:00.000Z", "closedAt": null, "boundAt": null } ``` *** # Overview Source: https://docs.aiinsurance.io/api-legacy-reference/transaction-categories/overview Retrieve available transaction categories for financial transactions ## Overview Transaction categories define the types of financial transactions that can be recorded in the system. Each category specifies: * **Direction**: Whether the transaction is a Payable (money going out) or Receivable (money coming in) * **Scopes**: Which entity types (policies or events) the category applies to, and which payee types are supported * **Line Item Categories**: Subcategories for itemized transactions * **Reserves Support**: Whether the category supports reserve tracking (for event-related categories) ## Transaction Direction | Direction | Description | | ------------ | ------------------------------------------------ | | `Payable` | Money owed by the company (expenses, claims) | | `Receivable` | Money owed to the company (premiums, recoveries) | ## Transaction Scopes Each category has one or more scopes that define where it can be used: * **Entity Type**: Either `policy` or `event` * **Supported Payee Types**: Which payee types can receive payments for this category (for payable categories) ### Supported Payee Types | Type | Description | | ----------- | ------------------------------------------------- | | `insured` | The policyholder/insured party | | `payee` | A general payee (law firm, expert, vendor, etc.) | | `brokerage` | A brokerage that receives commissions or payments | ## Line Item Categories Some transaction categories support line items (itemized breakdowns). These categories have `isItemized: true` and include a `lineItemCategories` array with subcategories. Each line item category has: * `categoryId`: Unique identifier for the line item category * `name`: Display name * `parentTransactionCategoryId`: Reference to the parent transaction category ## Permissions * **Read**: Requires `externalApi:read` permission ## Example Response ```json theme={null} { "items": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "categoryId": "alae_invoice", "name": "ALAE", "lineItemCategories": [ { "categoryId": "attorney_fees_expenses", "name": "Attorney Fees Expenses", "parentTransactionCategoryId": "alae_invoice" }, { "categoryId": "expert_fees_expenses", "name": "Expert Fees Expenses", "parentTransactionCategoryId": "alae_invoice" } ], "isItemized": true, "direction": "Payable", "scopes": [ { "entityType": "event", "supportedPayeeTypes": ["payee"] } ], "supportsReserves": true }, { "id": "550e8400-e29b-41d4-a716-446655440001", "categoryId": "policy_invoice", "name": "Policy Invoice", "lineItemCategories": [], "isItemized": true, "direction": "Receivable", "scopes": [ { "entityType": "policy", "supportedPayeeTypes": ["insured", "brokerage", "payee"] } ], "supportsReserves": false } ], "totalCount": 2 } ``` # Resolve Address Source: https://docs.aiinsurance.io/api-reference/address/resolve-address /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/resolve-address Geocodes a freeform address string and returns the structured subfields (`street`, `city`, `state`, `county`, `country`, `zipCode`) in the shape Field Model V1 rating expects. Intended as a pre-flight utility: integrators call this before constructing create/update payloads so addresses include all required pieces (especially `county`, which is required for rating but often missing from upstream systems). Writes are not auto-enriched — this endpoint is read-only. **Strict response contract.** If geocoding succeeds but any required subfield cannot be determined, the endpoint returns a `400` with a distinct `problemCode` rather than a partial address. Integrators can branch on the `problemCode` to know which field was missing. `zipCode` is always returned as a string with leading zeros preserved (e.g. `"02140"`). **Required permission:** `company:read` # List Assignees Source: https://docs.aiinsurance.io/api-reference/assignees/list-assignees /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/{entityType}/{entityId}/assignees Returns the list of users assigned to a specific entity. **Required permission:** Permission depends on entity type: - `policies` → `company.policy:read` - `submissions` → `company.submission:read` - `insureds` → `company.insured:read` - `events` → `company.claim:read` # Set Assignees Source: https://docs.aiinsurance.io/api-reference/assignees/set-assignees /openapi/generated-external-api.yaml put /api/external/companies/{companyId}/{entityType}/{entityId}/assignees Sets the assignees for a specific entity. This is a full replacement — the provided list of user IDs completely replaces any existing assignees. Pass an empty array to remove all assignees. Previously removed assignees are soft-deleted (preserved for audit history) and can be re-assigned. **Required permission:** Permission depends on entity type: - `policies` → `policy:update` - `submissions` → `submission:update` - `insureds` → `insured:update` - `events` → `claim:update` # Create Attorney Source: https://docs.aiinsurance.io/api-reference/attorneys/create-attorney /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/attorneys Creates a new attorney. **Required fields:** - `name` - Attorney name **Optional fields:** - `email` - Attorney email address - `phoneNumber` - Phone number - `lawFirmId` - Associated law firm payee ID (must reference an existing payee) **Required permission:** `company.attorney:create` # Delete Attorney Source: https://docs.aiinsurance.io/api-reference/attorneys/delete-attorney /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/attorneys/{attorneyId} Soft deletes an attorney by setting deletedAt and deletedBy timestamps. The attorney will no longer be returned in list or get operations. **Required permission:** `company.attorney:delete` # Get Attorney Source: https://docs.aiinsurance.io/api-reference/attorneys/get-attorney /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/attorneys/{attorneyId} Returns a single attorney by ID. **Required permission:** `company.attorney:read` # List Attorneys Source: https://docs.aiinsurance.io/api-reference/attorneys/list-attorneys /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/attorneys Returns a paginated list of attorneys for the company. Attorneys represent legal professionals that can be associated with lawsuits as plaintiff or defense counsel. Filter by ID or search text, and sort by various fields. **Required permission:** `company.attorney:read` # Update Attorney Source: https://docs.aiinsurance.io/api-reference/attorneys/update-attorney /openapi/generated-external-api.yaml patch /api/external/companies/{companyId}/attorneys/{attorneyId} Updates an existing attorney. Only send fields you want to change. Send `null` for nullable fields to clear them. **Optional update fields:** - `name` - Update attorney name - `email` - Update email address (send null to clear) - `phoneNumber` - Update phone number (send null to clear) - `lawFirmId` - Update law firm association (send null to clear) **Required permission:** `company.attorney:update` # Bind Quote Source: https://docs.aiinsurance.io/api-reference/basic-policies/bind-quote /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/quotes/{quoteId}/bind Binds a Field Model V1 quote, creating a Basic Policy. The quote must not already be bound. On success, returns the newly created policy ID, policy number, and any bind errors encountered during the process. Bind errors are non-fatal warnings — the policy is still created. **Required permission:** `company.quote:create` # Create Basic Policy Source: https://docs.aiinsurance.io/api-reference/basic-policies/create-basic-policy /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/policies Creates a new basic policy. The request body is a flat object of company-configured fields plus a nested `exposures` array. Each exposure's `id` (and the top-level `primaryInsured`) must reference an existing exposure record — create exposures first via the [Exposures API](/api-v1-reference/exposures/overview). Additional company-configured fields (custom text, number, option-set, or object fields) may be included alongside the required fields below. **Required permission:** `company.policy:create` # Delete Basic Policy Source: https://docs.aiinsurance.io/api-reference/basic-policies/delete-basic-policy /openapi/generated-external-api.yaml delete /api/v1/external/companies/{companyId}/policies/{policyId} Soft-deletes a basic policy. **Required permission:** `policy:delete` # Get Basic Policy Source: https://docs.aiinsurance.io/api-reference/basic-policies/get-basic-policy /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/{policyId} Returns a single basic policy by ID, with the flat `fieldModelV1Data` object including the nested `exposures` array. **Required permission:** `company.policy:read` # List Basic Policies Source: https://docs.aiinsurance.io/api-reference/basic-policies/list-basic-policies /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies Returns a paginated list of basic policies for the company. **Filtering:** - `id` — one or more policy UUIDs. - `policyNumberFilterText` — case-insensitive substring match against `policyNumber` only. It does not search any other field. Prefer `filters` for anything beyond a policy-number substring search. - `filters` — zero or more structured per-field filters (`FieldModelV1ListFilter[]`) applied against any FMV1 field or system column (`createdAt`, `updatedAt`, `createdBy`, `updatedBy`). Combined with AND semantics. **Sorting:** `sortBy` accepts `createdAt`, `updatedAt`, or `number` (default `createdAt`). `sortDirection` accepts `asc` or `desc` (default `desc`). **Pagination:** page size is server-controlled. Pass `page` as a 1-based page number to iterate. **Required permission:** `company.policy:read` # Create Brokerage Source: https://docs.aiinsurance.io/api-reference/brokerages/create-brokerage /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/brokerages Creates a new brokerage. **Required fields:** - `name` - Brokerage name - `commissionPaymentMethod` - How commissions are handled **Optional fields:** - `niprBrokerageNumber` - NIPR brokerage number - `email` - Brokerage email address - `addressStructured` - Structured address object - `phone` - Phone number - `defaultCommissionPercentage` - Default commission percentage **Required permission:** `company.brokerage:create` # Delete Brokerage Source: https://docs.aiinsurance.io/api-reference/brokerages/delete-brokerage /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/brokerages/{brokerageId} Soft deletes a brokerage by setting deletedAt and deletedBy timestamps. The brokerage will no longer be returned in list or get operations. **Required permission:** `brokerage:update` # Get Brokerage Source: https://docs.aiinsurance.io/api-reference/brokerages/get-brokerage /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/brokerages/{brokerageId} Returns a single brokerage by ID. **Required permission:** `company.brokerage:read` # List Brokerages Source: https://docs.aiinsurance.io/api-reference/brokerages/list-brokerages /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/brokerages Returns a paginated list of brokerages for the company. Brokerages represent insurance agencies or brokers that distribute policies. Filter by ID or search text, and sort by various fields. **Required permission:** `company.brokerage:read` # Update Brokerage Source: https://docs.aiinsurance.io/api-reference/brokerages/update-brokerage /openapi/generated-external-api.yaml patch /api/external/companies/{companyId}/brokerages/{brokerageId} Updates an existing brokerage. Only send fields you want to change. **Optional update fields:** - `name` - Update brokerage name - `commissionPaymentMethod` - Update commission handling method - `niprBrokerageNumber` - Update NIPR number - `email` - Update email address - `addressStructured` - Update address - `phone` - Update phone number - `defaultCommissionPercentage` - Update default commission **Required permission:** `company.brokerage:create` # Create Broker Source: https://docs.aiinsurance.io/api-reference/brokers/create-broker /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/brokers Creates a new broker associated with an existing brokerage. **Required fields:** - `brokerageId` - ID of an existing brokerage (use GET /brokerages to find valid IDs) - `name` - Broker name **Optional fields:** - `email` - Broker email address - `defaultCommissionPercentage` - Default commission percentage (0-100) - `addressStructured` - Structured address object - `phone` - Primary phone number - `workPhone` - Work phone number - `producerNumber` - Producer number/identifier **Required permission:** `company.broker:create` # Delete Broker Source: https://docs.aiinsurance.io/api-reference/brokers/delete-broker /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/brokers/{brokerId} Soft deletes a broker by setting deletedAt and deletedBy timestamps. The broker will no longer be returned in list or get operations. **Note:** This operation will fail if the broker is associated with any policies, drafts, or insureds. **Required permission:** `company.broker:create` # Get Broker Source: https://docs.aiinsurance.io/api-reference/brokers/get-broker /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/brokers/{brokerId} Returns a single broker by ID. **Required permission:** `broker:read` # List Brokers Source: https://docs.aiinsurance.io/api-reference/brokers/list-brokers /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/brokers Returns a paginated list of brokers for the company. Brokers are individual agents associated with brokerages. Filter by broker ID, brokerage ID, or search text, and sort by various fields. **Required permission:** `company.broker:read` # Update Broker Source: https://docs.aiinsurance.io/api-reference/brokers/update-broker /openapi/generated-external-api.yaml patch /api/external/companies/{companyId}/brokers/{brokerId} Updates an existing broker. Only send fields you want to change. **Optional update fields:** - `name` - Update broker name - `email` - Update email address (send null to clear) - `defaultCommissionPercentage` - Update default commission (0-100) - `addressStructured` - Update address - `phone` - Update phone number - `workPhone` - Update work phone number - `producerNumber` - Update producer number - `brokerageId` - Update associated brokerage - `createdAt` - Update creation timestamp **Required permission:** `broker:update` # Create Folder Source: https://docs.aiinsurance.io/api-reference/company-files/create-folder /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/folders Creates a new folder in the company file system. Optionally nest the folder under an existing parent by providing `parentFolderId`. Omit it (or leave it out) to create a root-level folder. **Required permission:** `company.file:create` # Delete File Source: https://docs.aiinsurance.io/api-reference/company-files/delete-file /openapi/generated-external-api.yaml delete /api/v1/external/companies/{companyId}/files/{fileId} Soft-deletes a file. The file is no longer returned by list endpoints and its content can no longer be downloaded. **Required permission:** `company.file:delete` # Delete Folder Source: https://docs.aiinsurance.io/api-reference/company-files/delete-folder /openapi/generated-external-api.yaml delete /api/v1/external/companies/{companyId}/folders/{folderId} Soft-deletes a folder and all of its contents recursively (subfolders and files). Deleted items are no longer returned by list endpoints. **Required permission:** `company.file:delete` # Download File Content Source: https://docs.aiinsurance.io/api-reference/company-files/download-file-content /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/files/{fileId}/content Streams the binary content of a file. The response `Content-Type` is set to the file's MIME type (or `application/octet-stream` if unknown), and `Content-Disposition` is set to `attachment` with the file name. **Required permission:** `company.file:read` # Get File Metadata Source: https://docs.aiinsurance.io/api-reference/company-files/get-file-metadata /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/files/{fileId} Returns metadata for a single file. Does not return the file content — use the [Download File Content](#tag/Company-Files/GET/api/v1/external/companies/{companyId}/files/{fileId}/content) endpoint to stream the binary content. **Required permission:** `company.file:read` # List Folder Contents Source: https://docs.aiinsurance.io/api-reference/company-files/list-folder-contents /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/folders/{folderId} Returns a paginated list of items (files and subfolders) inside the specified folder. Each item has a `contentType` discriminator (`file` or `folder`). **Sorting:** `createdAt` (default) **Required permission:** `company.file:read` # List Folder Tree Source: https://docs.aiinsurance.io/api-reference/company-files/list-folder-tree /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/folders Returns a flat, paginated list of all folders in the company. Each folder includes a `parentFolderId` so consumers can reconstruct the hierarchy client-side. **Sorting:** `createdAt` (default), `name` **Required permission:** `company.file:read` # Rename or Move File Source: https://docs.aiinsurance.io/api-reference/company-files/rename-or-move-file /openapi/generated-external-api.yaml patch /api/v1/external/companies/{companyId}/files/{fileId} Renames a file, moves it to a different folder, or both. Send only the fields you want to change. Set `folderId` to a folder ID to move the file into that folder, or to `null` to remove it from its current folder (move to root). **Required permission:** `company.file:update` # Rename or Move Folder Source: https://docs.aiinsurance.io/api-reference/company-files/rename-or-move-folder /openapi/generated-external-api.yaml patch /api/v1/external/companies/{companyId}/folders/{folderId} Renames a folder, moves it to a different parent, or both. Send only the fields you want to change. Set `parentFolderId` to a folder ID to move the folder, or to `null` to move it to the root level. **Required permission:** `company.file:update` # Upload File Source: https://docs.aiinsurance.io/api-reference/company-files/upload-file /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/files Uploads a file to the company file system. The request body must be `multipart/form-data`. Optionally place the file inside a folder by providing `folderId`. Omit it to upload to the root level (no folder). **Required permission:** `company.file:create` # Create Configuration Field Source: https://docs.aiinsurance.io/api-reference/configuration-fields/create-configuration-field /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/configuration/fields Creates a new configuration field and associates it with the specified entity type. **Allowed entity names:** `events`, `insureds`, `policies` **Allowed field class names:** `InputField`, `SelectField`, `DateField`, `RadioSelect`, `ExportResolvedField` The field key cannot be `companyId` (reserved). **Required permission:** `company:update` # Delete Configuration Field Source: https://docs.aiinsurance.io/api-reference/configuration-fields/delete-configuration-field /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/configuration/fields/{fieldId} Deletes a configuration field by ID. The field must be an entity field (events, insureds, or policies) — rating fields cannot be deleted through this endpoint. The field definition and its entity association are permanently deleted. **Required permission:** `company:update` # List Configuration Fields Source: https://docs.aiinsurance.io/api-reference/configuration-fields/list-configuration-fields /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/configuration/fields Returns a paginated list of configuration fields for the company. Only returns entity fields (events, insureds, policies) — rating fields are managed through separate endpoints. **Filtering:** - `id` - Filter by field ID (single UUID or array) - `entityName` - Filter by entity type (events, insureds, policies) **Sorting:** - `createdAt` (default), `updatedAt` **Required permission:** `company:read` # Create Configuration Preset Source: https://docs.aiinsurance.io/api-reference/configuration-presets/create-configuration-preset /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/configuration/presets Creates a new coverage limit preset for the company. The preset is stored directly in the `coverage_limit_presets` table. The `coverageTypeKey` must reference an existing coverage type (global or company-specific). If the coverage type does not exist, a 404 is returned. If `isDefault` is `true`, any existing default preset for the same coverage type is automatically set to non-default. Only one preset per coverage type can be the default at a time. **Required permission:** `company:update` # Delete Configuration Preset Source: https://docs.aiinsurance.io/api-reference/configuration-presets/delete-configuration-preset /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/configuration/presets/{presetId} Soft-deletes a coverage limit preset by ID. The preset is marked as deleted and will no longer appear in list results, but is not physically removed from the database. **Required permission:** `company:update` # List Configuration Presets Source: https://docs.aiinsurance.io/api-reference/configuration-presets/list-configuration-presets /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/configuration/presets Returns a paginated list of coverage limit presets for the company. **Filtering:** - `coverageTypeKey` - Filter by coverage type (exact match) - `id` - Filter by preset ID (single UUID or array) **Sorting:** - `createdAt` (default), `updatedAt` **Required permission:** `company:read` # Create Configuration Rating Field Source: https://docs.aiinsurance.io/api-reference/configuration-rating-fields/create-configuration-rating-field /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/configuration/rating/fields Creates a new rating input field and associates it with the specified entity type and rating engine revision. The field definition is stored in `company_fields`, an association is created in `application_fields`, and the field is added to the rating engine revision's `config.applicationFields` array. **Allowed field class names:** `AddressField`, `DateField`, `GroupField`, `InputField`, `LocalCurrency`, `MultiSelectField`, `SelectField`, `StaticField` The field key cannot be `companyId` (reserved). **Required permission:** `company:update` # Delete Configuration Rating Field Source: https://docs.aiinsurance.io/api-reference/configuration-rating-fields/delete-configuration-rating-field /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/configuration/rating/fields/{fieldId} Deletes a rating input field by ID. The field definition, its application field association, and its entry in the rating engine revision's `config.applicationFields` are all permanently removed. **Required permission:** `company:update` # List Configuration Rating Fields Source: https://docs.aiinsurance.io/api-reference/configuration-rating-fields/list-configuration-rating-fields /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/configuration/rating/fields Returns a paginated list of rating input fields for the company. Only returns rating fields — entity fields (events, insureds, policies) are managed through `/configuration/fields` endpoints. **Filtering:** - `id` - Filter by field ID (single UUID or array) - `entityType` - Filter by entity type (e.g., "policies", "dealership") **Sorting:** - `createdAt` (default), `updatedAt` **Required permission:** `company:read` # Reorder Configuration Rating Fields Source: https://docs.aiinsurance.io/api-reference/configuration-rating-fields/reorder-configuration-rating-fields /openapi/generated-external-api.yaml put /api/external/companies/{companyId}/configuration/rating/fields/rank Reorders the rating input fields for a single `(companyId, entityType)` tuple by rewriting `application_fields.rank`. The array index of each field id in the request becomes its new `rank` (lower renders first, `null` renders last). This endpoint updates the UI rendering order only — it does **not** modify rating engine revisions (`rating_engine_revisions.config`). **Semantics — full set required:** The provided `fieldIds` must exactly match the set of rating fields currently defined for this `entityType`. Partial reorders, duplicate ids, unknown ids, and missing ids are all rejected. **Required permission:** `company:update` # Create Rating Revision Form Logic Source: https://docs.aiinsurance.io/api-reference/configuration-rating-form-logic/create-rating-revision-form-logic /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/configuration/rating/form-logic Creates a new form-logic rule in the rating engine revision's config JSON (`rating_engine_revisions.config.policyFormLogicConfigs`). Rules determine which forms are attached to policies or quotes based on a `shouldAdd` expression evaluated during rating. The `ratingEngineRevisionId` must reference an existing, non-deleted revision owned by this company. **Required permission:** `company:update` # Delete Rating Revision Form Logic Source: https://docs.aiinsurance.io/api-reference/configuration-rating-form-logic/delete-rating-revision-form-logic /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/configuration/rating/form-logic/{formLogicId} Removes a form-logic rule from the rating engine revision's config JSON by ID. The rule is permanently removed from the `policyFormLogicConfigs` array in the revision's config. The `ratingEngineRevisionId` must reference an existing, non-deleted revision owned by this company. **Required permission:** `company:update` # List Rating Revision Form Logic Source: https://docs.aiinsurance.io/api-reference/configuration-rating-form-logic/list-rating-revision-form-logic /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/configuration/rating/form-logic Returns all form-logic rules from a rating engine revision's config JSON (`config.policyFormLogicConfigs`). Rules are returned as a flat list with no pagination. **Filtering:** - `ruleName` - Filter by rule name (exact match, non-empty) - `id` - Filter by rule ID (single UUID or array) **Sorting:** - `ruleName` (default), `rank` - Default direction: ascending - Ties are broken by `id` ascending (or descending when `sortDirection=desc`) **Required permission:** `company:read` # Create Configuration Rating Output Source: https://docs.aiinsurance.io/api-reference/configuration-rating-outputs/create-configuration-rating-output /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/configuration/rating/outputs Creates a new rating output field (entity name: `rating_engine_display`) and an associated smart tag with the naming convention `AII{key}PrimaryInsured`. The field definition is stored in `company_fields`, an association is created in `company_entity_fields`, and a smart tag is created in `smart_tags`. **Allowed field class names:** `InputField` The field key cannot be `companyId` (reserved) and must be alphanumeric (`[A-Za-z0-9]+`) since the smart tag name is derived from it. **Required permission:** `company:update` # Delete Configuration Rating Output Source: https://docs.aiinsurance.io/api-reference/configuration-rating-outputs/delete-configuration-rating-output /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/configuration/rating/outputs/{fieldId} Deletes a rating output field by ID. The field definition, its `company_entity_fields` association, and its associated smart tag are all removed. The field and association are permanently deleted; the smart tag is soft-deleted (`deleted_at` is set). **Required permission:** `company:update` # List Configuration Rating Outputs Source: https://docs.aiinsurance.io/api-reference/configuration-rating-outputs/list-configuration-rating-outputs /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/configuration/rating/outputs Returns a paginated list of rating output fields (`rating_engine_display`) for the company. **Filtering:** - `id` - Filter by field ID (single UUID or array) **Sorting:** - `createdAt` (default), `updatedAt` **Required permission:** `company:read` # Create Rating Revision Preset Source: https://docs.aiinsurance.io/api-reference/configuration-rating-presets/create-rating-revision-preset /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/configuration/rating/presets Creates a new coverage limit preset in the rating engine revision's config JSON. This endpoint is for **rating-engine companies** — presets are stored in `rating_engine_revisions.config.coverageLimitPresets`, not in the `coverage_limit_presets` table. For non-rating-engine companies, use `POST /configuration/presets` instead. The `coverageTypeKey` must reference an existing coverage type (global or company-specific). If the coverage type does not exist, a 404 is returned. If `isDefault` is `true`, any existing default preset for the same coverage type within the revision's config is automatically set to non-default. **Required permission:** `company:update` # Delete Rating Revision Preset Source: https://docs.aiinsurance.io/api-reference/configuration-rating-presets/delete-rating-revision-preset /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/configuration/rating/presets/{presetId} Removes a coverage limit preset from the rating engine revision's config JSON by ID. The preset is permanently removed from the `coverageLimitPresets` array in the revision's config. This endpoint is for **rating-engine companies** — presets are stored in `rating_engine_revisions.config.coverageLimitPresets`, not in the `coverage_limit_presets` table. For non-rating-engine companies, use `DELETE /configuration/presets/{presetId}` instead. **Required permission:** `company:update` # List Rating Revision Presets Source: https://docs.aiinsurance.io/api-reference/configuration-rating-presets/list-rating-revision-presets /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/configuration/rating/presets Returns all coverage limit presets from a rating engine revision's config JSON (`config.coverageLimitPresets`). This endpoint is for **rating-engine companies**. For non-rating-engine companies, use `GET /configuration/presets` instead. **Filtering:** - `coverageTypeKey` - Filter by coverage type (exact match) - `id` - Filter by preset ID (single UUID or array) **Sorting:** - `setName` (default), `coverageTypeKey` - Default direction: ascending **Required permission:** `company:read` # Create Coverage Type Source: https://docs.aiinsurance.io/api-reference/coverage-types/create-coverage-type /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/coverage-types Creates a new company-specific coverage type. The coverage type is inserted into the `coverage_types` table with `company_identifier` set to the company ID. This endpoint only creates the coverage type row — it does **not** enable it. To control which coverage types are active for a company, use the Set Enabled Coverage Types endpoint. The `key` is a caller-provided string (not a UUID), typically following the convention `{shortName}_{snake_case_name}` (e.g., `vfs_general_liability`). **Required permission:** `company:update` # Delete Coverage Type Source: https://docs.aiinsurance.io/api-reference/coverage-types/delete-coverage-type /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/coverage-types/{coverageTypeId} Permanently deletes a company-specific coverage type. Global coverage types cannot be deleted. Before deletion, the coverage type must be: - **Not enabled** — remove it from the enabled list first using the Set Enabled Coverage Types endpoint - **Not referenced by fields** — remove field associations first using the Set Coverage Type Fields endpoint **Required permission:** `company:update` # Get Coverage Type Fields Source: https://docs.aiinsurance.io/api-reference/coverage-types/get-coverage-type-fields /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/coverage-types/{coverageTypeId}/fields Returns the list of field keys associated with a given coverage type. Fields are sourced from both the database (`entity_type_fields` table) and static configuration, then merged and deduplicated. The returned field keys are human-readable strings (e.g., "reportDate") that match the keys used in event `data` objects. **Required permission:** `company.event:export` # List Coverage Types Source: https://docs.aiinsurance.io/api-reference/coverage-types/list-coverage-types /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/coverage-types Returns all coverage types available to the company, including both global types and company-specific types. Results are sorted alphabetically by key. **Filtering:** - `label` - Filter by label (case-insensitive substring match) **Required permission:** `company:read` # Set Coverage Type Fields Source: https://docs.aiinsurance.io/api-reference/coverage-types/set-coverage-type-fields /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/coverage-types/{coverageTypeId}/fields Sets the fields associated with a company-specific coverage type. This is a **replace** operation — the provided field list completely replaces all existing fields for the coverage type. Pass an empty array to remove all fields. Duplicate field keys in the request are automatically deduplicated. Only company-specific coverage types can be modified. Attempting to modify a global (shared) coverage type returns a 403 error. **Required permission:** `company:update` # Set Enabled Coverage Types Source: https://docs.aiinsurance.io/api-reference/coverage-types/set-enabled-coverage-types /openapi/generated-external-api.yaml put /api/external/companies/{companyId}/coverage-types/enabled Replaces the company's enabled coverage types list wholesale. The provided `coverageTypeKeys` array becomes the new complete list of enabled coverage types for the company. Each key must refer to an existing coverage type that is either: - A **global** coverage type (e.g., `general_liability`, `inland_marine`) - A **company-specific** coverage type owned by this company Duplicate keys in the request are automatically deduplicated. At least one key must be provided. Coverage types that belong to other companies are treated as not found to avoid leaking information about other companies' configurations. **Required permission:** `company:update` # Create Defendant Source: https://docs.aiinsurance.io/api-reference/defendants/create-defendant /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/events/{eventId}/lawsuit/defendants Creates a defendant for a lawsuit. A lawsuit must exist for the given event. Each defendant must have either an `insuredId` or a `nonInsuredName` (not both). **Required permission:** `company.event:export` # Delete Defendant Source: https://docs.aiinsurance.io/api-reference/defendants/delete-defendant /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/events/{eventId}/lawsuit/defendants/{defendantId} Soft-deletes a defendant. The defendant will no longer be returned by GET or LIST requests. **Required permission:** `company.event:export` # Get Defendant Source: https://docs.aiinsurance.io/api-reference/defendants/get-defendant /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/events/{eventId}/lawsuit/defendants/{defendantId} Returns a single defendant by ID. The defendant must belong to the lawsuit associated with the given event. **Required permission:** `company.event:export` # List Defendants Source: https://docs.aiinsurance.io/api-reference/defendants/list-defendants /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/events/{eventId}/lawsuit/defendants Returns a paginated list of defendants for a lawsuit. Defendants are sub-resources of lawsuits. A lawsuit must exist for the given event. Each defendant is either an insured (linked via `insuredId`) or a non-insured party (identified by `nonInsuredName`). **Required permission:** `company.event:export` # Update Defendant Source: https://docs.aiinsurance.io/api-reference/defendants/update-defendant /openapi/generated-external-api.yaml patch /api/external/companies/{companyId}/events/{eventId}/lawsuit/defendants/{defendantId} Updates a defendant. Only provided fields are updated. Send `null` for a field to clear its value. Omit a field to preserve its existing value. **Required permission:** `company.event:export` # Create Event Transaction Source: https://docs.aiinsurance.io/api-reference/event-financials/create-event-transaction /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/events/{eventId}/financials/transactions Creates a new financial transaction for an event. **Transaction Types:** - **Non-itemized types** (e.g., `indemnity_invoice`): Require `amount` field, `lineItems` is forbidden - **Itemized types** (e.g., `alae_invoice`): Require `lineItems` array, `amount` is forbidden Use the [GET /transaction-categories](/api-reference/transaction-categories/list-transaction-categories) endpoint to see available transaction types and whether they are itemized. **Note:** This endpoint does NOT automatically update reserves. Use [PATCH /events/{eventId}/financials/expected-totals](/api-reference/event-financials/update-expected-totals) to update reserves. **Required permission:** `company.payment:create` # Delete Event Transaction Source: https://docs.aiinsurance.io/api-reference/event-financials/delete-event-transaction /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/events/{eventId}/financials/transactions/{transactionId} Permanently soft-deletes a financial transaction. Unlike voiding, deletion is for transactions that should not have existed at all. Sets `deletedAt` and `deletedBy` on the transaction and recalculates reserves. **Required permission:** `company.payment:update` # Get Event Reserves Source: https://docs.aiinsurance.io/api-reference/event-financials/get-event-reserves /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/events/{eventId}/financials/reserves Returns reserve information for all transaction categories on an event. Each category includes: - `reserves`: Current reserve amount (null if category doesn't support reserves) - `owed`: Total amount owed - `paid`: Total amount paid - `expectedTotal`: Expected total amount **All amounts are in cents.** **Required permission:** `company.payment:read` # Get Event Transaction Source: https://docs.aiinsurance.io/api-reference/event-financials/get-event-transaction /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/events/{eventId}/financials/transactions/{transactionId} Returns a single financial transaction by ID, including line items (itemizations). **Required permission:** `company.event:export` # Get Event Transaction Totals Source: https://docs.aiinsurance.io/api-reference/event-financials/get-event-transaction-totals /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/events/{eventId}/financials/transactions/totals Returns transaction totals for all expense categories on a specific event. Each category includes: - `categoryId`: The transaction category identifier - `reserves`: Current reserve amount (null if category doesn't support reserves) - `owed`: Total amount owed - `paid`: Total amount paid - `expectedTotal`: Expected total amount **All amounts are in cents.** **Required permission:** `company.payment:read` # List Event Financial Totals Source: https://docs.aiinsurance.io/api-reference/event-financials/list-event-financial-totals /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/events/financials/{transactionType}/totals Returns a paginated list of all events with their financial totals for a specific transaction type. Each event item includes: - `hasCategoryTransactions`: Whether the event has any transactions of the specified type - Financial totals (reserves, owed, paid, expectedTotal) - null if no transactions exist **All amounts are in cents.** **Note:** Sorting is limited to `createdAt` only. Computed financial values cannot be sorted. **Required permission:** `company.payment:read` # List Event Transactions Source: https://docs.aiinsurance.io/api-reference/event-financials/list-event-transactions /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/events/{eventId}/financials/transactions Returns a paginated list of financial transactions for a specific event. Supports filtering by transaction type, status, payee, and text search. **Required permission:** `company.event:export` # List Expected Total Timeline Source: https://docs.aiinsurance.io/api-reference/event-financials/list-expected-total-timeline /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/events/financials/expected-totals/timeline Returns a chronological timeline of expected total (reserve) changes for specified events. Each entry represents a point in time when reserves were updated, including: - The expected total at that moment - Who made the change - Which transaction category was affected Use this to audit reserve history or build reserve trend visualizations. **All amounts are in cents.** **Required permission:** `company.payment:read` # Update Expected Totals Source: https://docs.aiinsurance.io/api-reference/event-financials/update-expected-totals /openapi/generated-external-api.yaml patch /api/external/companies/{companyId}/events/{eventId}/financials/expected-totals Updates the expected total for a transaction category on an event. This endpoint is used to set or update reserve amounts for categories that support reserves. **Important:** Amounts are in **dollars** (not cents) for this endpoint. **Required permission:** `company.claim:update` or `company.incident:update` (depending on event type) # Void Event Transaction Source: https://docs.aiinsurance.io/api-reference/event-financials/void-event-transaction /openapi/generated-external-api.yaml patch /api/external/companies/{companyId}/events/{eventId}/financials/transactions/{transactionId} Voids a financial transaction. Once voided, a transaction cannot be modified further. Optionally provide a custom void reason. **Required permission:** `company.payment:update` # Create Event Source: https://docs.aiinsurance.io/api-reference/events/create-event /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/events Creates a new event (claim or incident). **Required fields:** - `type` - Event type (`claim` or `incident`) - `coverageTypeId` - Coverage type identifier - `insuredIds` - At least one insured must be associated **Optional fields:** - `status` - Defaults to `open` if not provided - `policyId` - Associate with a policy - `data` - Custom entity data as key-value pairs **Required permission:** `company.claim:create` or `company.incident:create` (depending on type) # Delete Event Source: https://docs.aiinsurance.io/api-reference/events/delete-event /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/events/{eventId} Soft deletes an event by setting deletedAt and deletedBy timestamps. The event will no longer be returned in list or get operations. **Financial Transaction Protection:** By default, events with paid or processing financial transactions cannot be deleted. This protects financial data integrity. If you need to delete such an event, set `force: true` in the request body. **⚠️ WARNING:** Using `force: true` will orphan the associated financial records. Only use this option if you understand the implications. **Required fields in request body:** - `type` - Event type (required for permission resolution) **Optional fields:** - `force` - Set to `true` to delete events with paid/processing transactions (use with caution) **Required permission:** `company.claim:delete` or `company.incident:delete` (depending on type) # Get Event Source: https://docs.aiinsurance.io/api-reference/events/get-event /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/events/{eventId} Returns a single event by ID. Use `expand=insureds` to include full insured details instead of just IDs. **Required permission:** `company.claim:read` or `company.incident:read` (depending on event type) # Get Events Configuration Source: https://docs.aiinsurance.io/api-reference/events/get-events-configuration /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/events/configuration Returns a JSON Schema describing the custom fields available for the `data` object when creating or updating events, along with mappings that indicate which fields apply to which coverage types. The `data` schema is a standard JSON Schema (draft 2020-12) that can be used directly with validation libraries like Ajv or Zod. The `fieldCoverageTypeMappings` object maps each field key to either `"all"` (field applies to all events) or an array of coverage type IDs. Every key in `data.properties` has a corresponding entry in this mapping. **Required permission:** `company.event:read` # List Events Source: https://docs.aiinsurance.io/api-reference/events/list-events /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/events Returns a paginated list of events (claims and incidents) for the company. Events represent insurance claims and incidents. Each event includes: - Basic event information (type, status, reference ID) - Associated policy and insured references - Custom entity data specific to your company's configuration The `data` field contains custom entity data with **field keys** (not field IDs) mapped to values. Returns `null` when no custom data exists for the event. **Required permission:** `company.claim:read` or `company.incident:read` (depending on event type filter) # Update Event Source: https://docs.aiinsurance.io/api-reference/events/update-event /openapi/generated-external-api.yaml patch /api/external/companies/{companyId}/events/{eventId} Updates an existing event. Only send fields you want to change. **Required fields in request body:** - `type` - Event type (required for permission resolution) **Optional update fields:** - `status` - Update event status - `coverageTypeId` - Update coverage type - `policyId` - Update associated policy (use `null` to remove) - `insuredIds` - Replace associated insureds - `data` - Update custom entity data (merged with existing) **Required permission:** `claim:update` or `incident:update` (depending on type in request body) # List Export Presets Source: https://docs.aiinsurance.io/api-reference/export-presets/list-export-presets /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/export-presets Returns every export preset saved by any user of the company. An export preset is a named, ordered list of export column keys that one user saved for one entity type. Use the optional `entityType` query parameter to return only presets for one entity type. Results are not paginated: every matching preset is returned, ordered by `entityType`, then `name`. Preset names are not unique, so two presets with the same name may both be returned. **Required permission:** `company.export_preset:read` # Create Exposure Type Source: https://docs.aiinsurance.io/api-reference/exposure-types/create-exposure-type /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/exposure-types Creates a new exposure type for the company and adds it to the company's enabled exposure types. Exposure types define the categories of insured entities a company can manage (e.g., "Franchise Truck Dealer", "Auto", "Company"). The `value` must be unique within the company. Attempting to create a duplicate value returns a validation error. **Required permission:** `company:update` # Delete Exposure Type Source: https://docs.aiinsurance.io/api-reference/exposure-types/delete-exposure-type /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/exposure-types/{exposureTypeId} Permanently deletes a company-specific exposure type and removes it from the company's enabled exposure types. Before deletion, the exposure type must not be referenced by any insureds. If insureds exist with this exposure type, the request returns 409. **Required permission:** `company:update` # List Exposure Types Source: https://docs.aiinsurance.io/api-reference/exposure-types/list-exposure-types /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/exposure-types Returns all exposure types configured for the company. Results are sorted alphabetically by key. **Filtering:** - `label` - Filter by label (case-insensitive substring match) **Required permission:** `company:read` # Create Exposure Source: https://docs.aiinsurance.io/api-reference/exposures/create-exposure /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/exposures Creates a new exposure for the company. **Required fields:** - `name` - Name of the exposure - `entityType` - Entity type (e.g., "individual", "organization", "dealership") **Required permission:** `company.insured:create` # Delete Exposure Source: https://docs.aiinsurance.io/api-reference/exposures/delete-exposure /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/exposures/{exposureId} Soft deletes an exposure by ID. The exposure will be marked as deleted and will no longer appear in list operations. **Required permission:** `insured:delete` # Get Exposure Source: https://docs.aiinsurance.io/api-reference/exposures/get-exposure /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/exposures/{exposureId} Returns a single exposure by ID. **Required permission:** `company.insured:read` # List Exposures Source: https://docs.aiinsurance.io/api-reference/exposures/list-exposures /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/exposures Returns a paginated list of exposures for the company. **Filtering:** - `id` - Filter by exposure ID (single or array) - `entityType` - Filter by entity type - `filterText` - Text search across exposure name **Sorting:** - `createdAt` (default), `name`, `entityType` **Required permission:** `company.insured:read` # Update Exposure Source: https://docs.aiinsurance.io/api-reference/exposures/update-exposure /openapi/generated-external-api.yaml patch /api/external/companies/{companyId}/exposures/{exposureId} Updates an existing exposure. All fields are optional - only send fields being changed. Does NOT allow updating entityType or applicationData (rating data). **Required permission:** `insured:update` # Download Bordereau CSV Source: https://docs.aiinsurance.io/api-reference/field-model-bordereau/download-bordereau-csv /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/bordereau/download Downloads the bordereau report as a CSV file. Returns the same transaction-level premium data as the [List Bordereau Rows](/api-reference/field-model/bordereau/list) endpoint, serialized as RFC 4180 CSV with a `Content-Disposition: attachment` header. The CSV includes fixed columns (Policy Number, Insured Name, Transaction Action, Policy Version, Effective Date, Transaction Timestamp, Policy Start Date, Policy End Date, Created At, Created By, Policy Premium, Policy Premium Change) plus any additional columns specified via the `additionalColumns` parameter. Default limit is 50,000 rows (maximum 50,000). **Required permission:** `company.policy:read` # Export Bordereau to Google Sheets Source: https://docs.aiinsurance.io/api-reference/field-model-bordereau/export-bordereau-to-google-sheets /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/policies/bordereau/export Exports the bordereau report to a Google Sheets spreadsheet. Writes the same transaction-level premium data as the [List Bordereau Rows](/api-reference/field-model/bordereau/list) endpoint into a Google Sheets tab. Provide either `spreadsheetId` (to write into an existing spreadsheet) or `folderId` (to create a new spreadsheet in that Google Drive folder). When using `folderId`, the spreadsheet name defaults to `"{companyShortName}-bordereau-export {UTC timestamp}"` unless overridden via `spreadsheetName`. The caller must supply a `googleOAuthToken` with write access to the target spreadsheet or folder. Default limit is 50,000 rows (maximum 50,000). **Required permission:** `company.policy:read` # List Bordereau Rows Source: https://docs.aiinsurance.io/api-reference/field-model-bordereau/list-bordereau-rows /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/bordereau Returns a paginated, flat list of transaction-level premium rows (a "bordereau"). Each row represents one policy transaction and includes fixed columns (policy number, insured name, action, dates, premium, premium change) plus optional dynamic columns resolved from FullTerm custom object fields. Use `periodStart` and `periodEnd` to scope the report to transactions whose `transactionTimestamp` falls within the half-open interval `[periodStart, periodEnd)`. Use `actions` to filter by transaction type (e.g. only NEW_BUSINESS and ENDORSE). Use `additionalColumns` to transpose FullTerm custom object fields into extra columns. Each entry maps a dot-path into the segment's policy data to a named column header. **Required permission:** `company.policy:read` # Add Custom Object Relationship Source: https://docs.aiinsurance.io/api-reference/field-model-custom-objects/add-custom-object-relationship /openapi/generated-external-api.yaml put /api/v1/external/companies/{companyId}/custom-objects/{objectType}/{objectId}/relationships/{fieldRefId}/{targetId} Links a custom object to a target entity via a relationship field. Use the `fieldRefId` from the [Get Configuration](/api-reference/field-model/custom-objects/get-custom-object-configuration) endpoint. **Cardinality behavior:** - **one_to_one**: Replaces any existing link from this object *and* any existing link to the target. Each side can have at most one link. - **one_to_many**: Replaces any existing link from this object (the "one" side), but the target (the "many" side) can have multiple links. - **many_to_one**: Appends the link. The source (the "many" side) can have multiple links, but existing links to the target from other sources on the "one" side are replaced. - **many_to_many**: Appends the link. Both sides can have multiple links. If the exact same link already exists, the operation is idempotent and returns `created: false`. **Required permission:** `company.fmv1_custom_object:update` # Create Custom Object Source: https://docs.aiinsurance.io/api-reference/field-model-custom-objects/create-custom-object /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/custom-objects/{objectType} Creates a new custom object of the given type. The request body must include a `data` object where keys are field `referenceId`s defined in the type's configuration. Use the [Get Configuration](/api-reference/field-model/custom-objects/get-custom-object-configuration) endpoint to discover available fields. **Relationship fields are not accepted in `data`** — use the dedicated relationship management endpoints instead. **Required permission:** `company.fmv1_custom_object:create` # Delete Custom Object Source: https://docs.aiinsurance.io/api-reference/field-model-custom-objects/delete-custom-object /openapi/generated-external-api.yaml delete /api/v1/external/companies/{companyId}/custom-objects/{objectType}/{objectId} Deletes a custom object by ID. **Required permission:** `company.fmv1_custom_object:delete` # Get Custom Object Source: https://docs.aiinsurance.io/api-reference/field-model-custom-objects/get-custom-object /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/custom-objects/{objectType}/{objectId} Returns a single custom object by ID. The response includes both `data` (regular field values) and `relationships` (linked entity IDs). **Required permission:** `company.fmv1_custom_object:read` # Get Custom Object Configuration Source: https://docs.aiinsurance.io/api-reference/field-model-custom-objects/get-custom-object-configuration /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/custom-objects/{objectType}/configuration Returns the field configuration for a custom object type. The response includes: - **`data`**: A JSON Schema describing the regular fields available for create and update operations. - **`relationships`**: An array of relationship field metadata, each containing the `fieldRefId` to use with the relationship management endpoints. **Required permission:** `company.fmv1_custom_object:read` # List Custom Object Types Source: https://docs.aiinsurance.io/api-reference/field-model-custom-objects/list-custom-object-types /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/custom-objects Returns the list of custom object types configured for the company. Use the `type` value from the response as the `objectType` path parameter for all other custom object endpoints. **Required permission:** `company.fmv1_custom_object:read` # List Custom Objects Source: https://docs.aiinsurance.io/api-reference/field-model-custom-objects/list-custom-objects /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/custom-objects/{objectType} Returns a paginated list of custom objects for the given type. **Sorting:** `createdAt` (default), `updatedAt`, `displayName` **Required permission:** `company.fmv1_custom_object:read` # Remove Custom Object Relationship Source: https://docs.aiinsurance.io/api-reference/field-model-custom-objects/remove-custom-object-relationship /openapi/generated-external-api.yaml delete /api/v1/external/companies/{companyId}/custom-objects/{objectType}/{objectId}/relationships/{fieldRefId}/{targetId} Removes the link between a custom object and a target entity for the given relationship field. If the link does not exist, the operation is idempotent and returns `removed: false`. **Required permission:** `company.fmv1_custom_object:update` # Update Custom Object Source: https://docs.aiinsurance.io/api-reference/field-model-custom-objects/update-custom-object /openapi/generated-external-api.yaml put /api/v1/external/companies/{companyId}/custom-objects/{objectType}/{objectId} Updates a custom object's data fields. The request body must include a `data` object — this is a **full replacement** of the object's field data, not a merge. Include all fields you want the object to have after the update. **Relationship fields are not accepted in `data`** — use the dedicated relationship management endpoints instead. **Required permission:** `company.fmv1_custom_object:update` # Aggregate Earned Premium Source: https://docs.aiinsurance.io/api-reference/field-model-earned-premium/aggregate-earned-premium /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/aggregate/earned-premium Returns earned premium per day summed across all matching policies. No per-policy or per-transaction breakdown — just a daily time series and a grand total. Use `segmentScope` to control which policies are included based on segment date matching: - `"all"` — every policy - `{"asOf":"YYYY-MM-DD"}` — policies with segments active on that date - `{"fromDate":"YYYY-MM-DD","toDate":"YYYY-MM-DD"}` — policies with segments overlapping the date range Use `filters` to narrow results by field values in policy data. The earned premium date range is a half-open interval `[startDate, endDate)` and must not exceed 366 days. **Required permission:** `company.policy:read` # Get Earned Premium (Single Policy) Source: https://docs.aiinsurance.io/api-reference/field-model-earned-premium/get-earned-premium-single-policy /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/{policyId}/earned-premium Returns earned premium for a single policy over a date range. Each transaction on the policy produces a daily contribution (a fixed daily rate over its effective range), and the earned premium on any given day is the sum of all active contributions. Use the `detail` parameter to control response granularity: - `transactions` (default) — transaction-level totals only - `days` — adds a daily time series of net earned premium - `daysAndTransactions` — adds a daily time series with per-transaction contributions on each day The date range is a half-open interval `[startDate, endDate)` and must not exceed 366 days. Use `timeTravelBackToDate` to see earned premium as it would have been calculated at a prior point in time — only transactions created before that timestamp are included. **Required permission:** `company.policy:read` # List Earned Premium (Multi-Policy) Source: https://docs.aiinsurance.io/api-reference/field-model-earned-premium/list-earned-premium-multi-policy /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/list/earned-premium Returns earned premium for multiple policies, paginated by policy. Each item in the response has the same shape as the single-policy endpoint for the requested detail level. Use `segmentScope` to control which policies are included based on segment date matching: - `"all"` — every policy - `{"asOf":"YYYY-MM-DD"}` — policies with segments active on that date - `{"fromDate":"YYYY-MM-DD","toDate":"YYYY-MM-DD"}` — policies with segments overlapping the date range Use `filters` to narrow results by field values in policy data. The earned premium date range is a half-open interval `[startDate, endDate)` and must not exceed 366 days. **Required permission:** `company.policy:read` # List Event Financial Transactions Source: https://docs.aiinsurance.io/api-reference/field-model-event-financials/list-event-financial-transactions /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/events/{eventId}/financials/transactions Returns a paginated list of financial transactions for a specific event. Default sort is by `invoiceDate` descending (most recent first). **Required permission:** `company.event:read` # Create Event Source: https://docs.aiinsurance.io/api-reference/field-model-events/create-event /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/events Creates a new Field Model V1 event for the company. The request body is a flat JSON object where keys are field `referenceId`s defined in the company's field configuration. Use the [Get Configuration](/api-reference/field-model/events/overview) endpoint to discover available fields. **Required base fields:** `eventType`, `eventCoverageType`, `eventInsureds` (array of exposure IDs). **Optional base fields:** `eventStatus` (defaults to `Open`), `eventReferenceId` (auto-generated if omitted), `policyId` (mapped to the `eventPolicy` Join field inside `fieldModelV1Data`). **Date fields** must be submitted as objects: `{ "date": "YYYY-MM-DD", "timezone": "America/New_York" }` — plain date strings are not accepted. **Required permission:** `company.claim:create` or `company.incident:create` (determined by `eventType`) # Delete Event Source: https://docs.aiinsurance.io/api-reference/field-model-events/delete-event /openapi/generated-external-api.yaml delete /api/v1/external/companies/{companyId}/events/{eventId} Deletes a Field Model V1 event by ID. The `type` field is required in the request body for permission resolution. Use `force: true` to bypass financial transaction checks. **Required permission:** `company.claim:delete` or `company.incident:delete` (determined by `type`) # Get Event Source: https://docs.aiinsurance.io/api-reference/field-model-events/get-event /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/events/{eventId} Returns a single Field Model V1 event by ID. **Required permission:** `company.event:export` # Get Event Configuration Source: https://docs.aiinsurance.io/api-reference/field-model-events/get-event-configuration /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/events/configuration Returns a JSON Schema describing the fields available for creating or updating Field Model V1 events. The `fields` schema is a standard JSON Schema (draft 2020-12) that can be used directly with validation libraries like Ajv or Zod. The `required` array lists fields that must be provided when creating or updating an event. **Required permission:** `company.event:export` # List Events Source: https://docs.aiinsurance.io/api-reference/field-model-events/list-events /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/events Returns a paginated list of Field Model V1 events for the company. **Filtering:** - `type` - Filter by event type (`claim` or `incident`) - `status` - Filter by event status (`open` or `closed`) - `policyId` - Filter by associated policy ID - `filterText` - Text search across event fields **Sorting:** - `createdAt` (default), `updatedAt`, `referenceId` **Required permission:** `company.event:export` # Update Event Source: https://docs.aiinsurance.io/api-reference/field-model-events/update-event /openapi/generated-external-api.yaml put /api/v1/external/companies/{companyId}/events/{eventId} Updates a Field Model V1 event. The request body is a flat JSON object with field `referenceId`s as keys — the same shape as the create request. **This is a full replacement** of the event's field data, not a merge. Include all fields you want the event to have after the update. The `eventType` field is required in the body for permission resolution. **Required permission:** `claim:update` or `incident:update` (determined by `eventType`) # Update Expected Totals Source: https://docs.aiinsurance.io/api-reference/field-model-events/update-expected-totals /openapi/generated-external-api.yaml patch /api/v1/external/companies/{companyId}/events/{eventId}/financials/expected-totals Updates the expected total (reserve) for a transaction category on a Field Model V1 event. This endpoint is used to set or update reserve amounts for categories that support reserves. Unlike the legacy expected-totals endpoint, this endpoint resolves the event type from `fieldModelV1Data.eventType` rather than the internal `type` column. Use this endpoint for events created via the V1 API. **Important:** Amounts are in **dollars** (not cents) for this endpoint. **Required permission:** `claim:update` or `incident:update` (depending on event type) # Create Exposure Source: https://docs.aiinsurance.io/api-reference/field-model-exposures/create-exposure /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/exposures Creates a new Field Model V1 exposure for the company. The request body is a flat JSON object where keys are field `referenceId`s defined in the company's field configuration. Use the [Get Configuration](/api-reference/field-model/exposures/overview) endpoint to discover available fields. **Required fields:** `exposureName`, `exposureType` (and any fields marked required in your company's configuration). **Required permission:** `company.insured:create` # Delete Exposure Source: https://docs.aiinsurance.io/api-reference/field-model-exposures/delete-exposure /openapi/generated-external-api.yaml delete /api/v1/external/companies/{companyId}/exposures/{exposureId} Soft deletes a Field Model V1 exposure by ID. The exposure will be marked as deleted and will no longer appear in list operations. Exposures with associated policies, quotes, events, or transactions cannot be deleted. **Required permission:** `insured:delete` # Get Exposure Source: https://docs.aiinsurance.io/api-reference/field-model-exposures/get-exposure /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/exposures/{exposureId} Returns a single Field Model V1 exposure by ID. **Required permission:** `company.insured:read` # Get Exposure Configuration Source: https://docs.aiinsurance.io/api-reference/field-model-exposures/get-exposure-configuration /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/exposures/configuration Returns a JSON Schema describing the fields available for creating or updating Field Model V1 exposures. The `fields` schema is a standard JSON Schema (draft 2020-12) that can be used directly with validation libraries like Ajv or Zod. The `required` array lists fields that must be provided when creating or updating an exposure. **Required permission:** `company.insured:read` # List Exposures Source: https://docs.aiinsurance.io/api-reference/field-model-exposures/list-exposures /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/exposures Returns a paginated list of Field Model V1 exposures for the company. **Filtering:** - `id` - Filter by exposure ID (single or array) - `exposureType` - Filter by exposure type - `filterText` - Text search across exposure name **Sorting:** - `createdAt` (default), `updatedAt`, `exposureName`, `exposureType` **Required permission:** `company.insured:read` # Update Exposure Source: https://docs.aiinsurance.io/api-reference/field-model-exposures/update-exposure /openapi/generated-external-api.yaml put /api/v1/external/companies/{companyId}/exposures/{exposureId} Updates a Field Model V1 exposure. The request body is a flat JSON object with field `referenceId`s as keys — the same shape as the create request. **This is a full replacement** of the exposure's field data, not a merge. Include all fields you want the exposure to have after the update. **Required permission:** `insured:update` # Get Policies Configuration Source: https://docs.aiinsurance.io/api-reference/field-model-policies/get-policies-configuration /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/configuration Returns JSON Schemas describing the custom fields available for Field Model V1 policies. The response contains separate schemas for policy-level fields and exposure-level fields. Each schema is a standard JSON Schema (draft 2020-12) that can be used directly with validation libraries like Ajv or Zod. The `policy` schema covers policy-level custom fields (used in policy `fieldModelV1Data.policy` or segment `policy` objects). The `exposure` schema covers exposure-level custom fields. The `policy` schema excludes fields that are system-managed and not user-input: calculated (Jexl-derived) fields, server-populated fields (rating responses, billing, Google Drive ids, target rater), and policy lifecycle fields (`policyStatus`, `policyNumber`). **Required permission:** `company.policy:read` # Cancel Policy Transaction Source: https://docs.aiinsurance.io/api-reference/field-model-policy-transactions/cancel-policy-transaction /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/policies/{policyId}/transaction/cancel Cancels a policy as of a given date via a CANCEL transaction. The policy must be Active at the cancellation date. The action sets `policyStatus` to `cancelled` from the cancellation date through the end of the policy term and records a `policyEarlyTerminationDate` on `fullTermPolicyInfo`. Optional `fullTermDeltas` allow adjusting `fullTermPolicyBilling` fields (e.g. short-rate penalties, cancellation fees). Only `fullTermPolicyBilling`-prefixed paths are accepted — per-segment data and policy dates are not modifiable via cancel. Dates are not accepted on these deltas because they always span the full policy term; the server injects them. **Required permission:** `company.policy:update` # Delete Policy Transaction Source: https://docs.aiinsurance.io/api-reference/field-model-policy-transactions/delete-policy-transaction /openapi/generated-external-api.yaml delete /api/v1/external/companies/{companyId}/policies/{policyId}/transactions/{transactionId} Deletes the most recent transaction on a policy, rolling the policy back to its prior version. Only the most recent transaction (highest `policyVersion`) can be deleted — attempting to delete an older transaction returns a 400 error. After deletion, the policy state reverts to what it was before the deleted transaction was applied. If the only transaction (NEW_BUSINESS) is deleted, the policy has no remaining transactions. **Required permission:** `policy:delete` # Endorse Policy Transaction Source: https://docs.aiinsurance.io/api-reference/field-model-policy-transactions/endorse-policy-transaction /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/policies/{policyId}/transaction/endorse Applies an ENDORSE transaction to an existing policy. Endorsements modify policy state over specified date ranges using per-field deltas. Each delta targets a specific path within the policy data (e.g. `policy.annualPremium`, `policy.exposures`) and can Add, Remove, or Overwrite values. Deltas come in two flavors: - **`deltas`** — segmented deltas for per-segment fields. Each delta specifies a `startDate` / `endDate` within the policy term. - **`fullTermDeltas`** — deltas for cross-segment invariant fields (`fullTermPolicyBilling`, `fullTermPolicyInfo`, `fullTermPolicyRatingResponse`, `fullTermExposureRatingResponse`). These are applied uniformly across the entire policy term, so no dates are accepted — the server injects `policyStartDate` → `policyEndDate` automatically. Mixing the two is a validation error: `fullTerm*` paths in `deltas` are rejected, and non-`fullTerm*` paths in `fullTermDeltas` are rejected. At least one of the two arrays must be non-empty. The engine recomputes segments after applying all deltas — adjacent segments with identical data are automatically merged. The response includes the full set of resulting segments. **Required permission:** `company.policy:update` # Get Policy Transaction Source: https://docs.aiinsurance.io/api-reference/field-model-policy-transactions/get-policy-transaction /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/{policyId}/transactions/{transactionId} Returns a single policy transaction by ID, including its per-field deltas. Each delta describes a specific field change (add, remove, or overwrite) within a date range. Use this endpoint to inspect exactly what changed in a given transaction. **Required permission:** `company.policy:read` # Get Policy Version Source: https://docs.aiinsurance.io/api-reference/field-model-policy-transactions/get-policy-version /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/{policyId}/versions/{version} Returns a specific version of a policy with all its derived segments. Each segment contains the full policy state (policy-level fields and nested exposures) for a contiguous date range. The `fullTermPolicyInfo` and `fullTermPolicyBilling` fields are extracted from the segments for convenience — these are full-term invariant fields that are identical across all segments in a version. **Required permission:** `company.policy:read` # List Policies Source: https://docs.aiinsurance.io/api-reference/field-model-policy-transactions/list-policies /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/list Returns a paginated list of policies, resolving each policy to its latest version (or the latest version as of `timeTravelBackToDate`), then applying segment scope filters and field-level JSONB filters. **Example questions this endpoint answers:** - "Show me all current policies" — `segmentScope="all"`, no filters - "Current policies providing coverage on March 15" — `segmentScope={"asOf":"2025-03-15"}` - "Current policies providing coverage during Q1" — `segmentScope={"fromDate":"2025-01-01","toDate":"2025-03-31"}` - "What did the book of business look like on Jan 1?" — `timeTravelBackToDate=2025-01-01`, `segmentScope="all"` Use `segmentScope` to control which segments within each policy version participate in filtering: - `"all"` — every segment of the resolved version - `{"asOf":"2025-03-15"}` — point-in-time: segments where `startDate <= asOf <= endDate` - `{"fromDate":"2025-01-01","toDate":"2025-12-31"}` — date range: segments overlapping the window Use `timeTravelBackToDate` to see what the book of business looked like at a prior point in time. Each policy is resolved to the version that was latest at that timestamp. Use `detail=full` to include complete field data for the scope-matched segments in each result. Use `detail=summary` for lightweight responses with only matched segment date ranges. **Required permission:** `company.policy:read` # List Policy Transactions Source: https://docs.aiinsurance.io/api-reference/field-model-policy-transactions/list-policy-transactions /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/{policyId}/transactions Returns a paginated list of all transactions for a policy, ordered by `policyVersion`. Each transaction represents an immutable change set (new business, endorsement, cancellation, reinstatement, or renewal). Use this endpoint to see the full transaction history of a policy. For detailed per-field deltas, retrieve a single transaction via the Get Policy Transaction endpoint. **Related:** The Bordereau APIs provide a similar transaction-level view across all policies, with the ability to include additional columns for full-term policy fields. Use this endpoint when you need per-field deltas for a single policy; use the Bordereau APIs when you need a flat, reportable listing across policies. **Required permission:** `company.policy:read` # List Policy Versions Source: https://docs.aiinsurance.io/api-reference/field-model-policy-transactions/list-policy-versions /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/versions Lists policy versions across all policies. Unlike "List Policies" (which resolves each policy to one version), this endpoint returns every `(policy, version)` pair that matches the filters. A single policy can appear multiple times if multiple versions match. **Example questions this endpoint answers:** - "Find all policy versions where premium exceeded $100k" — `segmentScope="all"`, `filters` on premium field - "Which policy versions provided coverage on June 15?" — `segmentScope={"asOf":"2025-06-15"}` - "Find policies that ever matched a specific coverage type on a given date" — `segmentScope={"asOf":"..."}`, `filters` on coverage field Query parameters (`detail`, `segmentScope`, `filters`, pagination, sorting) work identically to the List Policies endpoint except that `timeTravelBackToDate` is not available — all versions are listed. **Required permission:** `company.policy:read` # List Single Policy Versions Source: https://docs.aiinsurance.io/api-reference/field-model-policy-transactions/list-single-policy-versions /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/{policyId}/versions Returns a paginated list of all versions for a single policy. Each version is a snapshot of the policy state produced by a transaction. Use this to see how a policy changed over time, or to find versions that match specific field criteria. **Example questions this endpoint answers:** - "Show me all versions of policy ABC" — `segmentScope="all"`, no filters - "Which versions of policy ABC had premium above $50k?" — `segmentScope="all"`, `filters` on premium field - "Which versions of policy ABC provided coverage on March 15?" — `segmentScope={"asOf":"2025-03-15"}` Query parameters (`detail`, `segmentScope`, `filters`, pagination, sorting) work identically to the List Policy Versions endpoint, scoped to a single policy. **Required permission:** `company.policy:read` # New Business Transaction Source: https://docs.aiinsurance.io/api-reference/field-model-policy-transactions/new-business-transaction /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/policies/transaction/new-business Creates a new policy via a NEW_BUSINESS transaction. This is the entry point for the transaction-based policy lifecycle. The transaction produces a single segment covering the full policy term. The request body contains the policy term dates and the initial policy state, including policy-level fields, full-term aggregates, and nested exposures. Exposures must reference existing exposure records by ID. **Required permission:** `company.policy:create` # Reinstate Policy Transaction Source: https://docs.aiinsurance.io/api-reference/field-model-policy-transactions/reinstate-policy-transaction /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/policies/{policyId}/transaction/reinstate Reinstates a previously cancelled policy as of a given date via a REINSTATE transaction. The policy must be Cancelled at the reinstatement date. The action sets `policyStatus` back to `active` from the reinstatement date through the end of the policy term and clears the `policyEarlyTerminationDate` on `fullTermPolicyInfo`. Optional `fullTermDeltas` allow adjusting `fullTermPolicyBilling` fields (e.g. reinstatement fees). Only `fullTermPolicyBilling`-prefixed paths are accepted — per-segment data and policy dates are not modifiable via reinstate. Dates are not accepted on these deltas because they always span the full policy term; the server injects them. **Required permission:** `company.policy:update` # Renew Policy Transaction Source: https://docs.aiinsurance.io/api-reference/field-model-policy-transactions/renew-policy-transaction /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/policies/transaction/renew Creates a new policy via a RENEW transaction, linking it to a previous policy. The new policy term must start on or after the previous policy's end date. The request body follows the same structure as NEW_BUSINESS — it contains the new policy term dates and the full initial policy state, including policy-level fields, full-term aggregates, and nested exposures. The transaction produces a new policy record with a single segment covering the full renewal term. **Required permission:** `company.policy:create` # Validate Policies (Batch) Source: https://docs.aiinsurance.io/api-reference/field-model-policy-validation/validate-policies-batch /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/validate Runs data consistency checks against multiple policies in a single request and returns paginated results. This is a read-only diagnostic endpoint — no data is modified. Three modes control which policies are validated (mutually exclusive): 1. **Explicit pairs** (`policyVersions`) — validate specific policy/version combinations. Pagination parameters are ignored. 2. **Time travel** (`timeTravelBackToDate`) — validate the latest version of each policy as of a historical point in time. Paginated via `limit`/`offset`. 3. **Default** (neither parameter) — validate the latest version of all policies in the company. Paginated via `limit`/`offset`. The same eight checks from the single-policy validation endpoint are available. Use the `checks` parameter to select a subset. ### Available checks | Check | Scope | What it validates | |-------|-------|-------------------| | `contiguity` | version | Segments form a contiguous date range with no gaps or overlaps | | `fullTermInvariance` | version | Billing and policy metadata fields are constant across all segments in a version | | `hashCorrectness` | version | Stored segment hash matches the computed hash of the segment data | | `noDuplicateSegments` | version | No adjacent segments have identical hashes | | `transactionSegmentExistence` | version | At least one segment exists for the version | | `versionSequentiality` | policy | Versions are sequential starting from 1 with no gaps | | `cancelEarnedPremium` | policy | Cancel transaction premium matches earned premium through the cancellation date | | `cancelReinstatePremium` | policy | Reinstate transaction premium matches the pre-cancel version premium | **Required permission:** `company.policy:read` # Validate Policy Source: https://docs.aiinsurance.io/api-reference/field-model-policy-validation/validate-policy /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/{policyId}/validate Runs data consistency checks against a single policy and returns detailed results. This is a read-only diagnostic endpoint — no data is modified. Eight checks are available, covering segment contiguity, hash correctness, version sequentiality, full-term invariance, duplicate detection, transaction-segment existence, and cancel/reinstate premium consistency. By default all checks run; use the `checks` parameter to select a subset. Checks are either **version-scoped** (run once per policy version) or **policy-scoped** (run once for the whole policy). A policy with 3 versions and all 8 checks enabled produces up to 18 results (5 version-scoped checks x 3 versions + 3 policy-scoped checks). Use the `version` parameter to validate a single version instead of all versions. ### Available checks | Check | Scope | What it validates | |-------|-------|-------------------| | `contiguity` | version | Segments form a contiguous date range with no gaps or overlaps | | `fullTermInvariance` | version | Billing and policy metadata fields are constant across all segments in a version | | `hashCorrectness` | version | Stored segment hash matches the computed hash of the segment data | | `noDuplicateSegments` | version | No adjacent segments have identical hashes | | `transactionSegmentExistence` | version | At least one segment exists for the version | | `versionSequentiality` | policy | Versions are sequential starting from 1 with no gaps | | `cancelEarnedPremium` | policy | Cancel transaction premium matches earned premium through the cancellation date | | `cancelReinstatePremium` | policy | Reinstate transaction premium matches the pre-cancel version premium | **Required permission:** `company.policy:read` # Create Quote Source: https://docs.aiinsurance.io/api-reference/field-model-quotes/create-quote /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/quotes Creates a new Field Model V1 quote. The `quote` and `exposures` fields contain custom field data where keys are field `referenceId`s defined in the company's field configuration. Use the [Configuration endpoint](/api-reference/field-model-quotes/get-quotes-configuration) to discover available fields. **Required fields in `quote`:** `policyStartDate`, `policyEndDate`, `policyType`, `policyTimeZone`. Fields like `policyNumber` and `policyEffectiveDate` are not required. **Lifecycle fields** (`quoteType`, `quoteStatus`, `quoteNumber`, `quoteBindErrors`, `quoteSubmissionId`) are system-managed and will be rejected with a 400 error if included in the request. **Required permission:** `company.quote:create` # Delete Quote Source: https://docs.aiinsurance.io/api-reference/field-model-quotes/delete-quote /openapi/generated-external-api.yaml delete /api/v1/external/companies/{companyId}/quotes/{quoteId} Soft-deletes a Field Model V1 quote. **Required permission:** `company.quote:delete` # Get Quote Source: https://docs.aiinsurance.io/api-reference/field-model-quotes/get-quote /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/quotes/{quoteId} Returns a single Field Model V1 quote by ID, including custom field data and exposures. **Required permission:** `company.quote:read` # Get Quotes Configuration Source: https://docs.aiinsurance.io/api-reference/field-model-quotes/get-quotes-configuration /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/quotes/configuration Returns JSON Schemas describing the custom fields available for Field Model V1 quotes. The response contains separate schemas for quote-level fields and exposure-level fields. Each schema is a standard JSON Schema (draft 2020-12) that can be used directly with validation libraries like Ajv or Zod. The `quote` schema covers fields used in the quote's `data` object. It excludes calculated fields, policy-only fields (policyNumber, policyStatus, policyCancelDate, etc.), server-populated fields (rating responses, google drive fields, etc.), and lifecycle fields. The `exposure` schema covers fields used in the `exposures[]` array. **Lifecycle fields** (`quoteType`, `quoteStatus`, `quoteNumber`, `quoteBindErrors`, `quoteSubmissionId`) are omitted from the configuration since they are system-managed. **Required permission:** `company.quote:read` # List Quotes Source: https://docs.aiinsurance.io/api-reference/field-model-quotes/list-quotes /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/quotes Returns a paginated list of Field Model V1 quotes for the company. **Filtering:** - `submissionId` — Filter by submission ID **Sorting:** - `createdAt` (default), `updatedAt` **Required permission:** `company.quote:read` # Send Quote Source: https://docs.aiinsurance.io/api-reference/field-model-quotes/send-quote /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/quotes/{quoteId}/send Sends a Field Model V1 quote, transitioning its status to "sent". **Required permission:** `company.quote:update` # Update Quote Source: https://docs.aiinsurance.io/api-reference/field-model-quotes/update-quote /openapi/generated-external-api.yaml put /api/v1/external/companies/{companyId}/quotes/{quoteId} Updates a Field Model V1 quote. This is a **full replacement** of the quote's custom field data and exposures. The `quote` object is merged with existing lifecycle fields (the system preserves `quoteType`, `quoteStatus`, `quoteNumber`, `quoteBindErrors`, `quoteSubmissionId`). The `exposures` array fully replaces the existing exposures. **Lifecycle fields** are rejected with a 400 error if included in the request body. **Required permission:** `company.quote:update` # Create Submission Source: https://docs.aiinsurance.io/api-reference/field-model-submissions/create-submission /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/submissions Creates a new Field Model V1 submission. The request body is a flat JSON object where keys are field `referenceId`s defined in the company's field configuration. Use the [Configuration endpoint](/api-reference/field-model/submissions/overview) to discover available fields. **Required field:** `submissionType` must be provided. **Lifecycle fields** (`submissionStatus`, `submissionNumber`, `submissionName`, `submissionPrimaryInsured`, `submissionBoundDate`, `submissionQuotes`) are system-managed. `submissionStatus` defaults to `inProgress` if not provided. **Required permission:** `company.submission:create` # Delete Submission Source: https://docs.aiinsurance.io/api-reference/field-model-submissions/delete-submission /openapi/generated-external-api.yaml delete /api/v1/external/companies/{companyId}/submissions/{submissionId} Soft-deletes a Field Model V1 submission. **Required permission:** `company.quote:delete` > Note: Uses `company.quote:delete` because `company.submission:delete` > does not exist yet. # Get Submission Source: https://docs.aiinsurance.io/api-reference/field-model-submissions/get-submission /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/submissions/{submissionId} Returns a single Field Model V1 submission by ID, including custom field data. **Required permission:** `company.submission:read` # Get Submissions Configuration Source: https://docs.aiinsurance.io/api-reference/field-model-submissions/get-submissions-configuration /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/submissions/configuration Returns a JSON Schema describing the custom fields available for Field Model V1 submissions. The schema can be used directly with validation libraries like Ajv or Zod. The schema excludes calculated fields, server-populated fields, and lifecycle fields (`submissionStatus`, `submissionType`, `submissionNumber`, `submissionName`, `submissionPrimaryInsured`, `submissionBoundDate`, `submissionQuotes`). **Required permission:** `company.submission:read` # List Submissions Source: https://docs.aiinsurance.io/api-reference/field-model-submissions/list-submissions /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/submissions Returns a paginated list of Field Model V1 submissions for the company. **Filtering:** - `submissionType` — Filter by submission type (single value or comma-separated) - `submissionStatus` — Filter by submission status (single value or comma-separated) - `filterText` — Text search across submission fields **Sorting:** - `createdAt` (default), `updatedAt`, `submissionNumber`, `submissionName`, `submissionStatus`, `submissionType` **Required permission:** `company.submission:read` # Update Submission Source: https://docs.aiinsurance.io/api-reference/field-model-submissions/update-submission /openapi/generated-external-api.yaml put /api/v1/external/companies/{companyId}/submissions/{submissionId} Updates a Field Model V1 submission. The request body is a flat JSON object where keys are field `referenceId`s. Fields not included in the request are preserved — this is a **merge**, not a full replacement. **Lifecycle fields** (`submissionStatus`, `submissionNumber`, `submissionName`, `submissionPrimaryInsured`, `submissionBoundDate`, `submissionQuotes`) are system-managed and will be rejected with a 400 error if included in the request body. **Required permission:** `company.quote:update` > Note: Uses `company.quote:update` because `company.submission:update` > does not exist yet. # Compare Configuration Source: https://docs.aiinsurance.io/api-reference/fmv1-configuration/compare-configuration /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/configuration/compare Compares an FMV1 configuration spreadsheet against the current database state and returns a diff summary. Each configuration category (field definitions, option sets, custom objects, etc.) includes counts of additions, updates, deletes, and unchanged items. Use this to preview what an import would change before applying it. The caller must provide their own Google OAuth2 access token with read permission on the target spreadsheet. **Required permission:** `company.configuration:export` This endpoint requires an API key created with the **FMV1_CONFIGURATION_MANAGER** role. See [Authentication](/api-reference/authentication) for how to create API keys with specific roles. # Export Configuration Source: https://docs.aiinsurance.io/api-reference/fmv1-configuration/export-configuration /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/configuration/export Exports the company's FMV1 configuration to an existing Google Spreadsheet. The spreadsheet is overwritten with the current configuration including field definitions, option sets, custom objects, card definitions, card sections, and field locations. The caller must provide their own Google OAuth2 access token with edit permission on the target spreadsheet. **Required permission:** `company.configuration:export` This endpoint requires an API key created with the **FMV1_CONFIGURATION_MANAGER** role. See [Authentication](/api-reference/authentication) for how to create API keys with specific roles. # Generate Configuration Spreadsheet Source: https://docs.aiinsurance.io/api-reference/fmv1-configuration/generate-configuration-spreadsheet /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/configuration/generate Creates a new Google Spreadsheet with the FMV1 configuration template structure. The spreadsheet contains all the required sheets, headers, and formatting but no data — it is a blank template ready to be filled in. The spreadsheet is created in the caller's Google Drive. **Required permission:** `company.configuration:export` This endpoint requires an API key created with the **FMV1_CONFIGURATION_MANAGER** role. See [Authentication](/api-reference/authentication) for how to create API keys with specific roles. # Import Configuration Source: https://docs.aiinsurance.io/api-reference/fmv1-configuration/import-configuration /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/configuration/import Imports FMV1 configuration from a Google Spreadsheet into the database. This runs the full pipeline: validate, parse, compare, and apply changes. If validation fails, no changes are applied and the response returns `success: false` with a `message` describing the failure. The caller must provide their own Google OAuth2 access token with read permission on the target spreadsheet. **Required permission:** `company.configuration:import` This endpoint modifies the company's FMV1 configuration. Changes take effect immediately and affect all users of the company. Use the **compare** endpoint first to preview changes. This endpoint requires an API key created with the **FMV1_CONFIGURATION_MANAGER** role. See [Authentication](/api-reference/authentication) for how to create API keys with specific roles. # Validate Configuration Spreadsheet Source: https://docs.aiinsurance.io/api-reference/fmv1-configuration/validate-configuration-spreadsheet /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/configuration/validate Validates the structure and data of an FMV1 configuration spreadsheet without applying any changes. Use this to check for errors before running an import. Returns a list of validation errors with details about the sheet, column, and row where each issue was found. The caller must provide their own Google OAuth2 access token with read permission on the target spreadsheet. **Required permission:** `company.configuration:export` This endpoint requires an API key created with the **FMV1_CONFIGURATION_MANAGER** role. See [Authentication](/api-reference/authentication) for how to create API keys with specific roles. # Create Lawsuit Source: https://docs.aiinsurance.io/api-reference/lawsuits/create-lawsuit /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/events/{eventId}/lawsuit Creates a lawsuit for an event. Each event can have at most one lawsuit. Returns 409 Conflict if a lawsuit already exists for the event. **Required permission:** `company.event:export` # Delete Lawsuit Source: https://docs.aiinsurance.io/api-reference/lawsuits/delete-lawsuit /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/events/{eventId}/lawsuit Soft-deletes the lawsuit for an event. The lawsuit will no longer be returned by GET requests. **Required permission:** `company.event:export` # Get Lawsuit Source: https://docs.aiinsurance.io/api-reference/lawsuits/get-lawsuit /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/events/{eventId}/lawsuit Returns the lawsuit associated with an event. Each event has at most one lawsuit. **Required permission:** `company.event:export` # Update Lawsuit Source: https://docs.aiinsurance.io/api-reference/lawsuits/update-lawsuit /openapi/generated-external-api.yaml patch /api/external/companies/{companyId}/events/{eventId}/lawsuit Updates the lawsuit for an event. Only provided fields are updated. Send `null` for a field to clear its value. Omit a field to preserve its existing value. **Required permission:** `company.event:export` # Create Note Source: https://docs.aiinsurance.io/api-reference/notes/create-note /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/{entityType}/{entityId}/notes Creates a new note attached to an event, policy, or insured. **Required permission:** Permission depends on entity type: - `events` → `claim.notes:update` - `policies` → `policy.notes:update` - `insureds` → `insured.notes:update` **Privileged notes:** If `isPrivileged` is true, the API key must also have `privileged_notes:read` permission. # Delete Note Source: https://docs.aiinsurance.io/api-reference/notes/delete-note /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/{entityType}/{entityId}/notes/{noteId} Soft deletes a note by setting deletedAt and deletedBy timestamps. The note will no longer be returned in list or get operations. **Required permission:** Permission depends on entity type: - `events` → `claim.notes:update` - `policies` → `policy.notes:update` - `insureds` → `insured.notes:update` # Get Note Source: https://docs.aiinsurance.io/api-reference/notes/get-note /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/{entityType}/{entityId}/notes/{noteId} Returns a single note by ID. **Required permission:** Permission depends on entity type: - `events` → `claim.notes:read` - `policies` → `policy.notes:read` - `insureds` → `insured.notes:read` **Privileged notes:** If the note is privileged, the API key must have `privileged_notes:read` permission to view it. # List Notes Source: https://docs.aiinsurance.io/api-reference/notes/list-notes /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/{entityType}/{entityId}/notes Returns a paginated list of notes for a specific entity. **Required permission:** Permission depends on entity type: - `events` → `claim.notes:read` - `policies` → `policy.notes:read` - `insureds` → `insured.notes:read` **Privileged notes:** Notes marked as privileged are automatically filtered out unless the API key has `privileged_notes:read` permission. # Create Payee Source: https://docs.aiinsurance.io/api-reference/payees/create-payee /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/payees Creates a new payee. **Required fields:** - `name` - Payee name - `payeeType` - Type of payee (lawFirm, expert, vendor, other, financingCompany) **Optional fields:** - `email` - Primary email address - `alternateEmails` - Additional email addresses - `phoneNumber` - Phone number - `description` - Description of the payee - `address` - Unstructured address string - `addressStructured` - Structured address object - `lawFirmType` - Type of law firm (defense, plaintiff) - only for lawFirm payeeType - `bankInfo` - Bank account information - `taxIdNumber` - Tax identification number **Required permission:** `company.payee:create` # Delete Payee Source: https://docs.aiinsurance.io/api-reference/payees/delete-payee /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/payees/{payeeId} Soft deletes a payee by setting deletedAt and deletedBy timestamps. The payee will no longer be returned in list or get operations. Deletion is blocked if the payee has associated transactions. **Required permission:** `company.payee:create` # Get Payee Source: https://docs.aiinsurance.io/api-reference/payees/get-payee /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/payees/{payeeId} Returns a single payee by ID. Returns 404 if the payee is not found, soft-deleted, or unsaved (isSaved: false). **Required permission:** `company.payee:read` # List Payees Source: https://docs.aiinsurance.io/api-reference/payees/list-payees /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/payees Returns a paginated list of payees for the company. Payees are entities that receive payments, such as law firms, experts, vendors, etc. Filter by payee type, ID, or search text, and sort by various fields. Only returns saved payees (isSaved: true). **Required permission:** `company.payee:read` # Update Payee Source: https://docs.aiinsurance.io/api-reference/payees/update-payee /openapi/generated-external-api.yaml patch /api/external/companies/{companyId}/payees/{payeeId} Updates an existing payee. Only send fields you want to change. **Optional update fields:** - `name` - Update payee name - `payeeType` - Update payee type - `email` - Update email address (send null to clear) - `alternateEmails` - Update alternate emails - `phoneNumber` - Update phone number - `description` - Update description - `address` - Update unstructured address - `addressStructured` - Update structured address - `lawFirmType` - Update law firm type - `bankInfo` - Update bank information - `taxIdNumber` - Update tax ID number - `externalPayee` - Update external payee reference - `createdAt` - Update creation timestamp (for imports) **Required permission:** `company.payee:create` # Create Policy Source: https://docs.aiinsurance.io/api-reference/policies/create-policy /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/policies Creates a new policy directly, primarily for historical imports where policies need to be created without going through the quote→bind wizard flow. **Workflow:** 1. Create insureds first via `POST /insureds` 2. Create the policy with insured references via this endpoint 3. The endpoint creates insured snapshots with the provided ratingInfo **Required fields:** - `referenceId` - Policy number (must be unique) - `startsAtDate`, `endsAtDate` - Coverage dates - `type` - Policy type (C, N, T, O, P, S, Q, R, A) - `billingPeriod` - Billing frequency - `exposures` - At least one exposure with exactly one having `role: "primary"` - `coverages` - At least one coverage with valid `coverageTypeId` **Required permission:** `company.policy:create` # Delete Policy Source: https://docs.aiinsurance.io/api-reference/policies/delete-policy /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/policies/{policyId} Soft deletes a policy by setting deletedAt and deletedBy timestamps. The policy will no longer be returned in list operations. **Important:** Policies with associated events (claims/incidents) cannot be deleted. You must delete all events first before deleting the policy. **Required permission:** `policy:delete` # Get Policy Source: https://docs.aiinsurance.io/api-reference/policies/get-policy /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/policies/{policyId} Retrieves detailed information about a specific policy, including its segments, coverages, exposures, and rating inputs. **Segments:** Policies are divided into segments when exposures are added, removed, or modified mid-term. Each segment represents a period where policy data is constant, with non-overlapping date ranges covering the full policy term. **Time Travel (asOf parameter):** Use the `asOf` query parameter to retrieve the policy state as it existed at a specific point in time. This is useful for auditing, reporting, or understanding how the policy looked before endorsements or modifications. **Required permission:** `company.policy:read` # List Policies Source: https://docs.aiinsurance.io/api-reference/policies/list-policies /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/policies Returns a paginated list of policies for the company. **Filtering:** - `primaryInsuredId` - Filter by primary insured ID - `filterText` - Text search across policy number and other fields **Sorting:** - `createdAt` (default), `updatedAt`, `number`, `startsAtDate`, `endsAtDate` **Required permission:** `company.policy:read` # List Policy Transactions Source: https://docs.aiinsurance.io/api-reference/policies/list-policy-transactions /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/policies/{policyId}/transactions Returns a paginated list of policy transactions (change sets) for a specific policy. Transactions represent the activity log/audit trail of changes made to the policy, including binds, endorsements, cancellations, reinstatements, and renewals. **Filtering:** - `type` - Filter by transaction type (bind, endorsement, cancellation, reinstatement, renewal) **Sorting:** - `processedAt` (default), `effectiveDate`, `type` **Required permission:** `company.policy:read` # Create Quote Source: https://docs.aiinsurance.io/api-reference/quotes/create-quote /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/quotes Creates a new quote for an existing submission. Only `submissionId` is required - all other fields are optional. The quote will be initialized with default values based on the submission type (new_business, renewal, endorsement, cancellation, or reinstatement). **Note:** The `applicant` field is not supported for external API. The concept of "applicant" (human who initiated an insurance application) doesn't apply to programmatic API calls. Use `recipients` to track who should receive the quote. **Required permission:** `company.quote:create` # Delete Quote Source: https://docs.aiinsurance.io/api-reference/quotes/delete-quote /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/quotes/{quoteId} Soft deletes a quote by setting deletedAt and deletedBy timestamps. The quote will no longer be returned in list or get operations. **Required permission:** `company.quote:delete` # Get Quote Source: https://docs.aiinsurance.io/api-reference/quotes/get-quote /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/quotes/{quoteId} Returns a single quote with all details. **Required permission:** `company.quote:read` # Get Quotes Configuration Source: https://docs.aiinsurance.io/api-reference/quotes/get-quotes-configuration /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/quotes/configuration Returns a JSON Schema describing the custom fields available for the `policyInfo.data` object when creating or updating quotes. The response is a standard JSON Schema (draft 2020-12) that can be used directly with validation libraries like Ajv or Zod. This enables clients to validate quote data before submission, reducing API errors. **Required permission:** `company.quote:read` # List Quote Info Source: https://docs.aiinsurance.io/api-reference/quotes/list-quote-info /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/quotes-info Returns lightweight quote information with essential fields only. Faster response than List Quotes - ideal for dashboards and lists. **Required permission:** `company.quote:read` # List Quotes Source: https://docs.aiinsurance.io/api-reference/quotes/list-quotes /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/quotes Returns complete Quote objects with all data fields, including nested quote data, preview data, coverages, and billing information. For lightweight quote information (faster response), use List Quote Info instead. **Required permission:** `company.quote:read` # Create Smart Tag Source: https://docs.aiinsurance.io/api-reference/smart-tags/create-smart-tag /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/smart-tags Creates a new smart tag for the company. **Required fields:** - `tagName` - Tag identifier (must match pattern /^AII[A-Za-z0-9]+$/) - `tagDisplayName` - Display name for the tag - `tagCategories` - Array of categories (e.g., ['quote', 'policy']) **Optional fields:** - `tagDescription` - Description of what the tag does - `tagData` - Custom smart tag configuration (see below) **Custom Smart Tag Types:** When creating a custom smart tag, specify the `type` field in `tagData`. Available types include: *Coverage & Premium Types:* - `coveragePremium` - Coverage premium amount - `coveragePremiumTax` - Coverage premium tax - `coveragePremiumPlusTax` - Coverage premium plus tax - `specificCoverageProperty` - Specific coverage property - `specificCoverageLimit` - Specific coverage limit *Policy Types:* - `policy` - Policy-level data - `policyLevelRatingOutput` - Policy-level rating outputs - `policyList` - List of policies - `policyTable` - Policy data table - `firstPolicyCoverage` - First policy coverage - `firstPolicyLimit` - First policy limit *Insured Types:* - `insuredsSchedule` - Schedule of insureds - `selectedInsured` - Selected insured data - `primaryInsured` - Primary insured information - `primaryInsuredCoverageRatingOutput` - Primary insured coverage rating output - `primaryInsuredCoverageRatingOutputTable` - Primary insured coverage rating output table - `insuredCoverageRatingOutputsTable` - Insured coverage ratings outputs table - `summedInsuredCoverageRatings` - Summed insured coverage ratings - `insuredClaimsTable` - Insured claims table *Other Types:* - `dynamic` - Dynamic field lookup (most flexible for custom fields) - `staticTable` - Static table data - `stateSpecificDisclosures` - State-specific disclosure text - `eventFinancialAmount` - Event financial amount **Allowed tagData fields:** - `type` - Smart tag type (required if using custom smart tags) - `fieldId` - Field identifier - `fieldKey` - Field key - `fieldLabel` - Field label - `fieldSection` - Field section - `entityType` - Entity type - `outputLabel` - Output label - `coverageKey` - Coverage key - `filters` - Filter conditions (array) - `columns` - Column definitions (array) **Required permission:** `company:update` # List Smart Tags Source: https://docs.aiinsurance.io/api-reference/smart-tags/list-smart-tags /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/smart-tags Returns a paginated list of smart tags for the company. **Filtering:** - `id` - Filter by smart tag ID (single or array) - `filterText` - Text search across tag name **Sorting:** - `createdAt` (default), `updatedAt`, `tagName`, `tagDisplayName` **Required permission:** `company:read` # Add Submission Loss History Entries Source: https://docs.aiinsurance.io/api-reference/submissions/add-submission-loss-history-entries /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/submissions/{submissionId}/loss-history Appends loss history entries to a submission without replacing existing ones. The new entries are added after any previously stored entries. For FMV1-enabled companies, adding entries automatically recomputes computed loss history aggregation fields on all quotes attached to the submission. The request must contain at least one entry — an empty array is rejected with a 400 error. Unknown fields are also rejected. **Required permission:** `submission:update` # Attach Files to Submission Source: https://docs.aiinsurance.io/api-reference/submissions/attach-files-to-submission /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/submissions/{submissionId}/files Attaches one or more files to an existing submission. The files appear in the submission's Files tab and are downloadable from there. The request body must be `multipart/form-data` with each file in a part named `file`. Repeat the same field name for multiple files. **Constraints:** - At least one file is required. - All files must be submitted in a single request. Files are not partially attached on validation failure — either every file lands or none do. **Required permission:** `submission.file:create` # Create Submission Source: https://docs.aiinsurance.io/api-reference/submissions/create-submission /openapi/generated-external-api.yaml post /api/external/companies/{companyId}/submissions Creates a new submission. Submissions are containers for quotes. Create a submission first, then add quotes via the Quotes API. **Required fields:** - `type` - Submission type (quote, renewal, endorsement, cancellation, reinstatement) **Optional fields:** - `renewingPolicyId` - Policy ID being renewed (for renewal submissions) **Note:** Use `quote` as the type for new business submissions. **Required permission:** `company.submission:create` # Delete Submission Source: https://docs.aiinsurance.io/api-reference/submissions/delete-submission /openapi/generated-external-api.yaml delete /api/external/companies/{companyId}/submissions/{submissionId} Soft deletes a submission by setting deletedAt and deletedBy timestamps. The submission will no longer be returned in list or get operations. **Important:** Submissions with associated quotes cannot be deleted. You must delete all quotes first before deleting the submission. **Required permission:** `company.submission:delete` # Get Submission Source: https://docs.aiinsurance.io/api-reference/submissions/get-submission /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/submissions/{submissionId} Returns a single submission by ID. By default, returns `quoteIds` as an array of quote IDs. Use `expand=quotes` to include full quote details. **Required permission:** `company.submission:read` # Get Submission Loss History Source: https://docs.aiinsurance.io/api-reference/submissions/get-submission-loss-history /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/submissions/{submissionId}/loss-history Returns the loss history entries stored on a submission. When no loss history has been set, returns an empty array. **Required permission:** `company.submission:read` # List Submissions Source: https://docs.aiinsurance.io/api-reference/submissions/list-submissions /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/submissions Returns a paginated list of submissions for the company. Filter by status, type, or search text. **Required permission:** `company.submission:read` # Set Submission Loss History Source: https://docs.aiinsurance.io/api-reference/submissions/set-submission-loss-history /openapi/generated-external-api.yaml put /api/external/companies/{companyId}/submissions/{submissionId}/loss-history Replaces the entire loss history on a submission. The request body contains an array of loss history entries — any previously stored entries are overwritten. Unknown fields are rejected with a 400 error. For FMV1-enabled companies, setting loss history automatically recomputes computed loss history aggregation fields on all quotes attached to the submission. **Required permission:** `submission:update` # Update Submission Source: https://docs.aiinsurance.io/api-reference/submissions/update-submission /openapi/generated-external-api.yaml patch /api/external/companies/{companyId}/submissions/{submissionId} Updates an existing submission. Only send fields you want to change (PATCH semantics). **Optional update fields:** - `name` - Update submission name (send null to clear) - `status` - Update submission status - `type` - Update submission type - `renewingPolicyId` - Update renewing policy (send null to clear) - `declineReason` - Update decline reason (send null to clear) **Note:** The `renewingPolicyId` must reference an existing, non-deleted policy. **Required permission:** `company.submission:update` # List Transaction Categories Source: https://docs.aiinsurance.io/api-reference/transaction-categories/list-transaction-categories /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/transaction-categories Returns a list of transaction categories available for the company. Transaction categories define the types of financial transactions that can be created, such as indemnity payments, defense costs, expert fees, etc. Each category includes: - **Direction**: Whether it's Payable (company pays out) or Receivable (company receives) - **Scopes**: Where the category can be used (policy or event level) and which payee types - **Line items**: Sub-categories for itemized transactions - **Reserves support**: Whether the category supports reserve amounts Returns company-specific custom categories if configured, otherwise returns the built-in default categories. **Required permission:** `company:read` # Resolve Address Source: https://docs.aiinsurance.io/api-v1-reference/address-tools/resolve-address Geocode a freeform address string into the FMV1 Address object-primitive shape — including county. `GET /api/external/companies/{companyId}/resolve-address?address=` Pre-flight utility for FMV1 integrators. Geocodes a freeform address string and returns the structured sub-fields (`street`, `city`, `state`, `county`, `country`, `zipCode`) in the shape FMV1 rating expects. Most often used to derive `county` when upstream data does not include it. The endpoint is **read-only** — writes are not enriched automatically. Call this before constructing your create/update payload. *** ## Why this exists FMV1 enforces [strict completeness on `Address` object-primitive values](/api-v1-reference/object-primitives/overview#address): if any sub-field is missing, the write is rejected. `county` is the sub-field most often missing from upstream sources. This endpoint fills that gap. *** ## Request | Parameter | In | Required | Description | | ----------- | ----- | -------- | ---------------------------------------------------------------------------------------------- | | `companyId` | path | yes | Your company UUID | | `address` | query | yes | Freeform address string. Must be non-empty and non-blank (whitespace-only values are rejected) | ```bash theme={null} curl -G "https://app.aiinsurance.io/api/external/companies//resolve-address" \ -H "Authorization: " \ --data-urlencode "address=350 5th Ave, New York, NY" ``` **Required permission:** `company:read` *** ## Response — `200 OK` Returns the [`Address` object primitive](/api-v1-reference/object-primitives/overview#address) — all six sub-fields populated. ```json theme={null} { "street": "350 5th Avenue", "city": "New York", "state": "NY", "county": "New York County", "country": "United States", "zipCode": "10001" } ``` `zipCode` is always returned as a string with leading zeros preserved (e.g. `"02140"`). The response shape is identical to the FMV1 `Address` sub-object — paste the response straight into a create/update payload's address field. *** ## Failure behavior If geocoding succeeds but any required sub-field cannot be determined, the endpoint returns `400` with a distinct `problemCode` — partial addresses are **never** returned as success. Branch on `problemCode` to know which sub-field was the problem. | HTTP | `problemCode` | Meaning | | ---- | ----------------------- | ---------------------------------------------------------------------------------------------- | | 400 | `BlankString` | Input was empty or whitespace-only | | 400 | `AddressNotFound` | Geocoder returned no results — provide a more specific input | | 400 | `AddressMissingStreet` | No street number/route in the result | | 400 | `AddressMissingCity` | No locality / postal town / sublocality in the result | | 400 | `AddressMissingState` | No `administrative_area_level_1` in the result | | 400 | `AddressMissingCounty` | No `administrative_area_level_2` in the result — most common cause is an under-specified input | | 400 | `AddressMissingCountry` | No country in the result | | 400 | `AddressMissingZipCode` | No postal code in the result | | 502 | `GeocodingFailed` | Upstream geocoder is unreachable or returned an error — retry after a short delay | ```json theme={null} { "error": { "code": "AddressMissingCounty", "message": "Resolved address is missing a county. Provide a more specific address that includes a county." } } ``` *** ## Related * [Object Primitives → Address](/api-v1-reference/object-primitives/overview#address) — full sub-field reference. * [V1 API Changelog](/api-v1-reference/changelog) — strict `Address` validation was rolled out on 2026-04-28. # Generating API Keys Source: https://docs.aiinsurance.io/api-v1-reference/authentication ## How to Generate API Keys API keys allow you to programmatically access your AI Insurance data and integrate with external systems. This guide shows you how to generate API keys from your company settings. ## Step-by-Step Instructions ### Step 1: Access Company Settings 1. Log into your AI Insurance account at [https://app.aiinsurance.io](https://app.aiinsurance.io) 2. In the left sidebar, find and click on your company name (e.g., "Demo Insurance Inc.") 3. This will open the company settings page ### Step 2: Navigate to API Keys 1. In the company settings, look for the navigation bar 2. Click on the **"API Keys"** tab 3. Once you're on the **API Keys** page, you will see: * A table of any existing API keys * A button to create a new API key * Your **Company ID** at the bottom of the page (this ID is required in most API requests) Find api key ### Step 3: Create Your API Key 1. Click the purple **"+ Create New API Key"** button 2. You'll be prompted to enter: * **Key Name**: A descriptive name for your API key (e.g., "Production Integration", "Testing API") * **Description**: Optional description of what this key will be used for add key ### Step 4: Save Your API Key 1. After creating the key, you'll receive your API key 2. **Store it securely** - API keys grant access to your company's data **Authentication Header Format** When making API requests, include your API key in the Authorization header: ``` Authorization: YOUR-API-KEY ``` **Correct:** ```bash theme={null} -H "Authorization: abc123xyz789" ``` **Incorrect:** ```bash theme={null} -H "Authorization: Bearer abc123xyz789" ❌ -H "X-API-Key: abc123xyz789" ❌ ``` *** ## Using Your API Key Now that you have your API key, you can use it to access the AI Insurance V1 API. ### Example: Using Your API Key ```bash theme={null} curl -X GET \ "https://app.aiinsurance.io/api/v1/external/companies/YOUR-COMPANY-ID/exposures" \ -H "Authorization: YOUR-API-KEY" ``` # API Changelog Source: https://docs.aiinsurance.io/api-v1-reference/changelog ## V1 API Changelog Track changes, additions, and deprecations to the V1 API. *** ### 2026-05-15 #### New: Company Files API (folders + files) Added 10 endpoints for managing company-level folders and files: **Folders:** `POST`, `GET`, `GET /{folderId}`, `PATCH /{folderId}`, `DELETE /{folderId}` under `/api/v1/external/companies/{companyId}/folders` **Files:** `POST` (multipart upload), `GET /{fileId}`, `GET /{fileId}/content` (binary download), `PATCH /{fileId}`, `DELETE /{fileId}` under `/api/v1/external/companies/{companyId}/files` Key capabilities: * Create nested folder hierarchies with `parentFolderId` * Upload files via `multipart/form-data`, optionally placing them in a folder * Stream binary file content with correct `Content-Type` and `Content-Disposition` headers * Rename and move files/folders (including moving to root by setting parent to `null`) * Recursive soft-delete of folders (deletes all contents) All endpoints use `company.file:{action}` permissions. See the [Company Files overview](/api-v1-reference/company-files/overview) for details. These are company-level file endpoints only. Entity-scoped file endpoints (attached to exposures, policies, events) are planned for a future release. *** ### 2026-05-07 #### New endpoint: Update Expected Totals for V1 events Added `PATCH /api/v1/external/companies/{companyId}/events/{eventId}/financials/expected-totals` for Field Model V1 events. The legacy expected-totals endpoint at `/api/external/...` relies on an internal `type` column that is always `null` for V1-created events, causing a `TypeMismatch` error. This new endpoint resolves the event type from `fieldModelV1Data.eventType` instead. The request body is identical to the legacy endpoint (`type`, `categoryId`, `expectedTotal`, optional `asOfDate`). The `type` field is still required for permission routing. *** ### 2026-05-01 #### Event→Policy relationship migrated to `eventPolicy` Join field (additive) Event responses now surface the associated policy in two places: the existing top-level `policyId` and the new `eventPolicy` key inside `fieldModelV1Data`. Both reflect the same value — `policyId` stays at the top level for backwards compatibility, while `eventPolicy` is the underlying `Join: Policy` field where the value is stored. **What changed:** * `GET /api/v1/external/companies/{companyId}/events` and `/events/{eventId}` responses include `eventPolicy` inside `fieldModelV1Data` alongside the pre-existing top-level `policyId`. No fields were removed. * `POST` and `PUT` event endpoints continue to accept `policyId` as a top-level request param. The server maps it to `fieldModelV1Data.eventPolicy` internally; clients that already submit `policyId` need no changes. * `policyId` is no longer stored on a dedicated `events.policy_id` column on the FMV1 read/write paths — it now lives in `fieldModelV1Data.eventPolicy`, consistent with how `eventInsureds` was migrated previously. The external API contract is unchanged for existing integrators. This is a non-breaking change. Integrators can ignore `eventPolicy` and continue using `policyId`, or migrate to reading the value from `fieldModelV1Data.eventPolicy` to align with the rest of the field model. *** #### `Address.zipCode` must be a JSON string (breaking) `Address` object-primitive writes that send `zipCode` as a JSON number are now rejected with `400` and `problemCode: "InvalidAddressZipCode"`. Previously, numeric ZIPs were accepted by the API but silently lost their leading zeros — `02140` parses as `2140`, corrupting the stored address. **Affected endpoints:** every FMV1 create/update endpoint that can carry an `Address` value (top-level field or nested inside a custom object), including all exposure, event, quote, basic-policy, segmented-policy-transaction, and custom-object writes. **What to send:** quote ZIP codes in your payload — `"zipCode": "02140"`, never `"zipCode": 02140`. The [Address sub-field reference](/api-v1-reference/object-primitives/overview#address) and the [`Fmv1Address` OpenAPI schema](/api-v1-reference/object-primitives/overview#address) both call this out explicitly. **Why this is most likely to bite:** * **Spreadsheets** (Excel / Google Sheets) auto-coerce ZIP-shaped cells to numbers — export as text or wrap in `=TEXT(...)` before serializing. * **OpenAPI clients / codegen** that infer the `zipCode` JSON type from a sample value rather than the schema (which has always been `type: string`). * **LLM-generated requests** that "helpfully" unquote numeric-looking strings. The geocoded shape returned by [`GET /resolve-address`](/api-v1-reference/address-tools/resolve-address) already returns `zipCode` as a string — paste responses straight into your write payload and you avoid this failure. *** ### 2026-04-29 #### Documentation: Object Primitives + Address Tools * New [Object Primitives reference page](/api-v1-reference/object-primitives/overview) documenting the five FMV1 built-in object shapes (`Address`, `CoverageLimit`, `Currency`, `Date`, `QuoteBindError`) — sub-field tables, JSON examples, the strict-completeness rule, and List cardinality. * New [Resolve Address](/api-v1-reference/address-tools/resolve-address) endpoint page surfacing the V1-relevant pre-flight utility for deriving a complete `Address` (including `county`) from a freeform input string. The endpoint itself was added on 2026-04-27 under the legacy URL — this page exposes it to V1 integrators directly. * OpenAPI spec now exports reusable `Fmv1Address`, `Fmv1CoverageLimit`, `Fmv1Currency`, `Fmv1Date`, and `Fmv1QuoteBindError` schemas under `components.schemas` for client-codegen consumers. Schemas mark every sub-field as `required`. *** ### 2026-04-28 #### Strict object-primitive sub-field validation (breaking) When a request body for an FMV1 create/update endpoint includes an object-primitive value (`Address`, `CoverageLimit`, `Currency`, `Date`, `QuoteBindError`), every declared sub-field must now be present and non-empty. Affected endpoints: * `POST/PATCH /api/v1/external/companies/{companyId}/exposures` and `/exposures/{id}` * `POST/PATCH /api/v1/external/companies/{companyId}/events` and `/events/{id}` * `POST/PATCH /api/v1/external/companies/{companyId}/quotes` and `/quotes/{id}` * `POST /api/v1/external/companies/{companyId}/policies` (Basic Policies) * All segmented policy transaction endpoints (`new-business`, `endorse`, `renew`) * `POST/PATCH /api/v1/external/companies/{companyId}/custom-objects/{objectType}` and `/{objectId}` **What changed:** * A `null`, `undefined`, or empty-string (`""`) sub-field on a present object-primitive value now returns `400` with `Field '' is missing required sub-field ''`. Previously, partial object primitives were silently accepted and surfaced as confusing rating errors downstream. The most common case is `Address` without `county` — call `GET /api/external/companies/{companyId}/resolve-address` first if upstream data lacks county. * Numeric `0` (e.g. `Currency.value: 0`) and Boolean `false` are still valid — the rule only treats `null` / `undefined` / `""` as missing. * **Whitespace-only strings (e.g. `" "`) are NOT treated as missing** by this validator. A consumer sending `county: " "` will pass this check; downstream rating may still reject it. Trim/normalize sub-field strings client-side before submitting. * Custom-object sub-fields keep their existing `requiredCondition` rules unchanged. * Omitting the parent object-primitive field entirely is unchanged — the strict rule only fires when the parent value is provided. *** ### 2026-04-20 * **Bind Quote** — documented under Basic Policies: `POST /api/v1/external/companies/{companyId}/quotes/{quoteId}/bind`. Binds a Field Model V1 quote to create a Basic Policy. Returns `{ policyId, policyNumber, bindErrors }`. Requires `company.quote:create`. *** ### 2026-04-17 * **Basic Policies API** — introduced as a simplified CRUD alternative to the transaction-based Policy API at `GET/POST /api/v1/external/companies/{companyId}/policies` and `GET/DELETE /api/v1/external/companies/{companyId}/policies/{policyId}`. Request body is a flat field-model object with nested `exposures`. See the [Basic Policies overview](/api-v1-reference/policies/basic-overview). * **List Basic Policies** supports `id`, `policyNumberFilterText` (substring match on `policyNumber` only), and `filters` (structured per-field `FieldModelV1ListFilter[]` against any FMV1 field or system column, combined with AND). * Removed the "Deprecated" group from the V1 docs. The previous CRUD endpoint shape (`{ referenceId, startsAtDate, endsAtDate, segments: [...] }`) is no longer documented; use the new flat-shape Basic Policies API instead. # Overview Source: https://docs.aiinsurance.io/api-v1-reference/company-files/overview Manage company-level folders and files via the API The Company Files API lets you create a folder hierarchy, upload files, and organize them into folders — all at the company level. These endpoints manage **company-level** files and folders only. Entity-scoped file endpoints (attached to exposures, policies, events, etc.) are planned for a future release. ## Key Concepts * **Folder** — a named container that can hold files and other folders. Folders form a tree via `parentFolderId` (null = root). * **File** — a binary object with metadata (name, MIME type, category). Files can optionally live inside a folder. * **Folder contents** — the `GET /folders/{folderId}` endpoint returns a mixed list of files and subfolders, discriminated by the `contentType` field (`file` or `folder`). * **Soft delete** — both file and folder deletes are soft (the record is marked as deleted). Deleting a folder recursively soft-deletes all contents. ## API Endpoints ### Folders | Method | Endpoint | Description | | ------ | ------------------------ | ----------------------------------------- | | POST | `/v1/folders` | Create a folder | | GET | `/v1/folders` | List all folders (flat, paginated) | | GET | `/v1/folders/{folderId}` | List folder contents (files + subfolders) | | PATCH | `/v1/folders/{folderId}` | Rename or move a folder | | DELETE | `/v1/folders/{folderId}` | Soft-delete folder (recursive) | ### Files | Method | Endpoint | Description | | ------ | ---------------------------- | ------------------------------------- | | POST | `/v1/files` | Upload a file (multipart) | | GET | `/v1/files/{fileId}` | Get file metadata | | GET | `/v1/files/{fileId}/content` | Download file content (binary stream) | | PATCH | `/v1/files/{fileId}` | Rename or move a file | | DELETE | `/v1/files/{fileId}` | Soft-delete a file | ## Permissions | Operation | Permission | | -------------------------------------------------------------- | --------------------- | | List folders, List folder contents, Get file, Download content | `company.file:read` | | Create folder, Upload file | `company.file:create` | | Rename/move folder, Rename/move file | `company.file:update` | | Delete folder, Delete file | `company.file:delete` | ## Workflow Example A typical integration creates a folder structure, uploads files into it, then retrieves them later. **1. Create a folder** ```bash theme={null} curl -X POST https://app.aiinsurance.io/api/v1/external/companies/{companyId}/folders \ -H "Authorization: YOUR-API-KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Claims Documents"}' # → {"id": "folder-uuid"} ``` **2. Upload a file into the folder** ```bash theme={null} curl -X POST https://app.aiinsurance.io/api/v1/external/companies/{companyId}/files \ -H "Authorization: YOUR-API-KEY" \ -F "file=@claim-report.pdf" \ -F "fileName=claim-report.pdf" \ -F "mimeType=application/pdf" \ -F "folderId=folder-uuid" # → {"id": "file-uuid", "name": "claim-report.pdf", ...} ``` **3. List folder contents** ```bash theme={null} curl https://app.aiinsurance.io/api/v1/external/companies/{companyId}/folders/folder-uuid \ -H "Authorization: YOUR-API-KEY" # → {"items": [{"contentId": "file-uuid", "contentType": "file", ...}], "totalCount": 1} ``` **4. Download the file** ```bash theme={null} curl https://app.aiinsurance.io/api/v1/external/companies/{companyId}/files/file-uuid/content \ -H "Authorization: YOUR-API-KEY" \ -o claim-report.pdf ``` # Overview Source: https://docs.aiinsurance.io/api-v1-reference/configuration/overview The FMV1 Configuration API provides endpoints for exporting, validating, comparing, and importing company configuration via Google Spreadsheets. This is the programmatic interface to the onboarding spreadsheet pipeline. ## Authentication These endpoints require an API key created with the **FMV1\_CONFIGURATION\_MANAGER** role. Standard API keys (e.g., those with `CARRIER_ADMIN`) will not have the required permissions. To create an API key with this role, go to **Settings > API Keys** and select the **FMV1 Configuration Manager** role when generating the key. ## Google OAuth Token All endpoints require the caller to provide a `googleOAuthToken` — a Google OAuth2 access token with permission to read from (or write to) the target spreadsheet. The server does not use its own Google credentials for these operations. You can obtain a token via Google's OAuth2 flow with the `https://www.googleapis.com/auth/spreadsheets` scope. *** ## Workflow The typical round-trip workflow is: 1. **Generate** — Create a new blank configuration spreadsheet template (or use **Export** to populate an existing one with current config) 2. Edit the spreadsheet manually 3. **Validate** — Check the spreadsheet for structural or data errors 4. **Compare** — Preview what changes the import would apply 5. **Import** — Apply the changes from the spreadsheet to the database *** ## API Endpoints * **[Generate Spreadsheet](/api-reference/fmv1-configuration/generate-configuration-spreadsheet)** — Create a blank configuration template spreadsheet * **[Export Configuration](/api-reference/fmv1-configuration/export-configuration)** — Write current config to an existing spreadsheet * **[Validate Configuration](/api-reference/fmv1-configuration/validate-configuration-spreadsheet)** — Check spreadsheet for errors * **[Compare Configuration](/api-reference/fmv1-configuration/compare-configuration)** — Diff spreadsheet against database * **[Import Configuration](/api-reference/fmv1-configuration/import-configuration)** — Apply spreadsheet changes to database *** ## Permissions | Operation | Required Permission | | --------- | ------------------------------ | | Generate | `company.configuration:export` | | Export | `company.configuration:export` | | Validate | `company.configuration:export` | | Compare | `company.configuration:export` | | Import | `company.configuration:import` | *** ## Configuration Categories The compare endpoint returns change counts for each category: | Category | Description | | ------------------ | -------------------------------------------------- | | `fieldDefinitions` | Field definitions (name, type, reference ID, etc.) | | `optionSets` | Option set values for dropdown fields | | `customObjects` | Custom object type definitions | | `cardDefinitions` | UI card layout definitions | | `cardSections` | Sections within cards | | `fieldLocations` | Where fields appear on cards | *** ## Smart Tag Configuration Walkthrough