Basic Policies Overview

Simple flat-shape CRUD for policies that don’t need transaction history

The Basic Policies API is a simplified way of managing policies in the app — flat-shape CRUD over policies with company-configured dynamic fields. Use it when you don’t need the temporal versioning, segments, or earned-premium calculations of the transaction-based Policy API.

Key Concepts:

• Fields are dynamically defined per company. Use the Configuration endpoint to discover available fields and their types.
• The request body for create is a flat JSON object where keys are field referenceIds (e.g., policyNumber, policyStartDate, policyType).
• Exposures are nested inline in the policy — each exposure is an object in the exposures array, with an id referencing an existing exposure record.
• Responses include a fieldModelV1Data object containing all field values plus the nested exposures array.

---

When to use Basic vs Transaction-Based Policies

Use case	API
Simple data ingestion, policies that won’t be modified after creation, no audit trail needed	Basic Policies
Endorsements, cancellations, reinstatements, renewals, earned-premium reporting, full audit trail	Transaction-Based Policies

Both APIs share the same underlying storage and configuration — they’re alternative write paths over the same policy records.

---

Configuration

Call GET /v1/policies/configuration to get a JSON Schema of the available policy and exposure fields for your company. The same endpoint drives both the Basic and the Transaction-Based Policy APIs — one configuration, shared across both.

---

API Endpoints

• Get Configuration — GET /v1/policies/configuration
• Create Policy — POST /v1/policies
• Bind Quote to Create Policy — POST /v1/quotes/{quoteId}/bind (creates a Basic Policy from an existing quote)
• List Policies — GET /v1/policies with filtering, sorting, pagination
• Get Policy — GET /v1/policies/{policyId}
• Delete Policy — DELETE /v1/policies/{policyId} (soft delete)

---

Permissions

Operation	Required Permission
Get Configuration	company.policy:read
List Policies	company.policy:read
Get Policy	company.policy:read
Create Policy	company.policy:create
Bind Quote	company.quote:create
Delete Policy	policy:delete

---

Filtering

Parameter	Type	Description
id	string or string[]	Filter by policy ID (single or array).
policyNumberFilterText	string	Case-insensitive substring match against policyNumber only. Does not search any other field.
filters	FieldModelV1ListFilter[]	Structured per-field filters against any FMV1 field or system column. Combined with AND semantics. See Filters below.

Filters: structured field matching

Each item in filters is an object with fieldReferenceId, fieldType, operator, and a value (plus valueTo for between operators and systemColumn for systemUser / systemDate). The set of operators and the shape of value depend on fieldType.

Supported field types and their operators:

fieldType	Operators	value shape
text	matches, contains, doesNotContain	string
optionSet	in	string[] (allowed option keys)
number	equals, greaterThan, lessThan, between	number (+ valueTo for between)
boolean	equals	boolean
date	on, before, after, between	{ year, month, day } (+ valueTo for between)
currency	equals, greaterThan, lessThan, between	number (+ valueTo for between)
address	contains	string (substring across street/city/state/zip)
join	in	string[] (allowed linked-entity IDs)
textList / numberList / addressList	listIncludes	one item value of the list element type
optionSetList	listIn, listAll, listExcludes	string[]
systemUser	in	string[] + systemColumn: "createdBy" | "updatedBy"
systemDate	on, before, after, between	{ year, month, day } + systemColumn: "createdAt" | "updatedAt"

Example: policies created after Jan 1 2026 whose policyStatus is active:

[
  {
    "fieldReferenceId": "policyStatus",
    "fieldType": "optionSet",
    "operator": "in",
    "value": ["active"]
  },
  {
    "fieldReferenceId": "createdAt",
    "fieldType": "systemDate",
    "operator": "after",
    "value": { "year": 2026, "month": 1, "day": 1 },
    "systemColumn": "createdAt"
  }
]

---

Sorting

Value	Description
createdAt	Sort by creation date (default)
updatedAt	Sort by last update date
number	Sort by policy number

Use the sortDirection parameter (asc or desc) to control sort order.

---

Example Create Request

Before creating a policy, create any exposures it references via the Exposures API — primaryInsured and each entry in exposures[].id must point to an existing exposure record.

{
  "policyNumber": "POL-2026-0001",
  "policyStartDate": { "date": "2026-01-01", "timezone": "America/New_York" },
  "policyEndDate": { "date": "2027-01-01", "timezone": "America/New_York" },
  "policyEffectiveDate": { "date": "2026-01-01", "timezone": "America/New_York" },
  "policyType": "generalLiability",
  "policyTimeZone": "America/New_York",
  "primaryInsured": "550e8400-e29b-41d4-a716-446655440010",
  "exposures": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "exposureName": "Acme Corporation",
      "exposureType": "business"
    }
  ]
}

Additional company-configured fields (custom text, number, option-set, or object fields defined in your FMV1 configuration) may be included alongside the standard fields above.

201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440001"
}

Example Get Response

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "companyId": "550e8400-e29b-41d4-a716-446655440000",
  "fieldModelV1Data": {
    "policyNumber": "POL-2026-0001",
    "policyStartDate": { "year": 2026, "month": 1, "day": 1, "timezone": "America/New_York" },
    "policyEndDate": { "year": 2027, "month": 1, "day": 1, "timezone": "America/New_York" },
    "policyEffectiveDate": { "year": 2026, "month": 1, "day": 1, "timezone": "America/New_York" },
    "policyType": "generalLiability",
    "policyTimeZone": "America/New_York",
    "primaryInsured": "550e8400-e29b-41d4-a716-446655440010",
    "exposures": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "exposureName": "Acme Corporation",
        "exposureType": "business"
      }
    ]
  },
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": null,
  "createdBy": "google-oauth2|123456789",
  "updatedBy": null
}

Date-typed fields (policyStartDate, policyEndDate, policyEffectiveDate) are canonicalized on write from the { date: "YYYY-MM-DD", timezone } input form to the internal { day, month, year, timezone } form shown in responses.