List Policies

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

GET /api/v1/external/companies/{companyId}/policies/list

List Policies

cURL

curl --request GET \
  --url https://app.aiinsurance.io/api/v1/external/companies/{companyId}/policies/list \
  --header 'Authorization: <api-key>'

200

summaryMode

{
  "items": [
    {
      "summary": {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "policyId": "550e8400-e29b-41d4-a716-446655440001",
        "companyId": "550e8400-e29b-41d4-a716-446655440099",
        "createdAt": "2025-01-15T10:30:00.000Z",
        "policyVersion": 2,
        "versionCreatedAt": "2025-02-01T14:00:00.000Z",
        "fullTermPolicyInfo": {
          "policyStatus": "Active",
          "policyStartDate": {
            "year": 2025,
            "month": 1,
            "day": 1,
            "timezone": "America/New_York"
          },
          "policyEndDate": {
            "year": 2026,
            "month": 1,
            "day": 1,
            "timezone": "America/New_York"
          },
          "primaryInsuredId": "550e8400-e29b-41d4-a716-446655440010"
        },
        "fullTermPolicyBilling": {
          "policyPremium": 102000,
          "policyTaxes": 0,
          "policyFees": 500,
          "policyGrandTotal": 102500
        },
        "matchedSegments": [
          {
            "startDate": "2025-01-01",
            "endDate": "2025-06-01"
          },
          {
            "startDate": "2025-06-01",
            "endDate": "2026-01-01"
          }
        ]
      }
    }
  ],
  "totalCount": 1
}

Authorizations

Authorization · string · header · required

API key authentication. Include your API key in the Authorization header.

Path Parameters

companyId · string<uuid> · required

Company identifier

Query Parameters

page · integer · default: 1

Page number (1-based, default 1, page size 50)

Required range: x >= 1

detail · enum<string> · required

Detail level. summary returns lightweight results with matched segment date ranges. full includes complete field data for each scope-matched segment.

Available options: summary, full

segmentScope · string · required

JSON-encoded segment scope filter. Controls which segments within each resolved version participate in filtering. Values:

• "all" — every segment
• {"asOf":"YYYY-MM-DD"} — point-in-time
• {"fromDate":"YYYY-MM-DD","toDate":"YYYY-MM-DD"} — date range

filters · string

JSON-encoded array of field filters. Each filter targets a field in the segment's fieldModelV1Data and supports type-specific operators. Supported field types: text, number, boolean, date, currency, optionSet, address, join, textList, numberList, optionSetList, addressList.

List-cardinality types support operators: listIncludes (textList, numberList, addressList), listIn, listAll, listExcludes (optionSetList). The join type supports the in operator.

See the Configuration API for available field reference IDs.

timeTravelBackToDate · string<date>

Resolve each policy to the version that was latest at this date. Useful for reconstructing the book of business as it was known at a prior point in time.

sortBy · enum<string>

Field to sort results by

Available options: policyId, createdAt, versionCreatedAt

sortDirection · enum<string> · default: desc

Sort direction (default desc)

Available options: asc, desc

Response

200

application/json

Paginated list of policies

Paginated list of policy results.

items · object[] · required

Show child attributes

totalCount · integer · required

Total number of matching results across all pages