> ## Documentation Index > Fetch the complete documentation index at: https://docs.go.aiinsurance.io/llms.txt > Use this file to discover all available pages before exploring further. # 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` ## OpenAPI ````yaml /openapi/generated-external-api.yaml get /api/v1/companies/{companyId}/policies/list openapi: 3.0.3 info: title: AI Insurance External API description: External API for AI Insurance platform version: 1.0.0 contact: email: support@aiinsurance.io servers: - url: https://go.aiinsurance.io description: Production security: - ApiKeyAuth: [] paths: /api/v1/companies/{companyId}/policies/list: get: tags: - Field Model Policy Transactions summary: List Policies description: > 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` operationId: listPoliciesTransactionModel parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/page' - name: detail in: query required: true schema: type: string enum: - summary - full description: > Detail level. `summary` returns lightweight results with matched segment date ranges. `full` includes complete field data for each scope-matched segment. - name: segmentScope in: query required: false schema: type: string default: '"all"' description: > JSON-encoded segment scope filter. Controls which segments within each resolved version participate in filtering. Optional — defaults to `"all"` when omitted. Values: - `"all"` — every segment - `{"asOf":"YYYY-MM-DD"}` — point-in-time - `{"fromDate":"YYYY-MM-DD","toDate":"YYYY-MM-DD"}` — date range examples: all: summary: All segments value: '"all"' asOf: summary: Point-in-time value: '{"asOf":"2025-06-15"}' range: summary: Date range value: '{"fromDate":"2025-01-01","toDate":"2025-06-30"}' - name: filters in: query schema: type: string description: > JSON-encoded array of field filters. Each filter targets a field in the segment's `data` object 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. examples: textFilter: summary: Text field filter value: >- [{"fieldReferenceId":"policyNumber","fieldType":"text","operator":"matches","value":"POL-001"}] numberFilter: summary: Number field filter value: >- [{"fieldReferenceId":"annualPremium","fieldType":"number","operator":"greaterThan","value":50000}] - name: timeTravelBackToDate in: query schema: type: string format: date description: > 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. - name: sortBy in: query schema: type: string enum: - policyId - createdAt - versionCreatedAt description: Field to sort results by - name: sortDirection in: query schema: type: string enum: - asc - desc default: desc description: Sort direction (default `desc`) responses: '200': description: Paginated list of policies content: application/json: schema: $ref: '#/components/schemas/PolicyListResponse' examples: summaryMode: summary: Summary detail level value: 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' policyStartDate: year: 2025 month: 1 day: 1 timezone: America/New_York policyEndDate: year: 2026 month: 1 day: 1 timezone: America/New_York fullTermPricingInfo: premium: 102000 taxes: 0 fees: 500 brokerCommission: 0 programCommission: 0 pricingComponents: - label: Policy Premium group: Policy Invoice kind: Premium earningBasis: null value: 102000 - label: Policy Fee group: Policy Invoice kind: Fees earningBasis: null value: 500 matchedSegments: - startDate: '2025-01-01' endDate: '2025-06-01' - startDate: '2025-06-01' endDate: '2026-01-01' totalCount: 1 fullMode: summary: Full detail level (includes segments) value: 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: 1 versionCreatedAt: '2025-01-15T10:30:00.000Z' policyStartDate: year: 2025 month: 1 day: 1 timezone: America/New_York policyEndDate: year: 2026 month: 1 day: 1 timezone: America/New_York fullTermPricingInfo: premium: 85000 taxes: 0 fees: 500 brokerCommission: 0 programCommission: 0 pricingComponents: - label: Policy Premium group: Policy Invoice kind: Premium earningBasis: null value: 85000 - label: Policy Fee group: Policy Invoice kind: Fees earningBasis: null value: 500 matchedSegments: - startDate: '2025-01-01' endDate: '2026-01-01' segments: - startDate: '2025-01-01' endDate: '2026-01-01' data: policyStatus: active annualPremium: 85000 fullTermPricingInfo: premium: 85000 taxes: 0 fees: 500 brokerCommission: 0 programCommission: 0 pricingComponents: - label: Policy Premium group: Policy Invoice kind: Premium earningBasis: null value: 85000 - label: Policy Fee group: Policy Invoice kind: Fees earningBasis: null value: 500 exposures: - id: 550e8400-e29b-41d4-a716-446655440010 exposureType: MedicalFacility bedCount: 120 totalCount: 1 '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidSegmentScope: summary: Invalid JSON in segmentScope value: error: code: INVALID_REQUEST message: segmentScope must be valid JSON invalidFilters: summary: Invalid JSON in filters value: error: code: INVALID_REQUEST message: filters must be valid JSON '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier page: name: page in: query schema: type: integer minimum: 1 default: 1 description: Page number (1-based, default 1). schemas: PolicyListResponse: type: object description: > Paginated list of policy results. **Why this differs from the entity list shape.** A non-policy entity list (`GET /entities/{entityType}`) returns flat items, each a single `{ id, fieldModelV1Data, … }` record. A policy list item instead carries a `summary` object (and, with `detail=full`, a `segments` array) — it has no single top-level field-data blob. This is **by design**: a Policy is a *segmented* entity assembled from immutable transactions, so its field data lives per-segment rather than in one flat record. The `summary` gives the policy-level view (id, full-term info, matched segment date ranges) and `segments` carries the per-segment `data` object when requested. required: - items - totalCount properties: items: type: array items: $ref: '#/components/schemas/PolicyTransactionListItem' totalCount: type: integer description: Total number of matching results across all pages ErrorResponse: type: object description: Standard error response for all external API endpoints required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code example: VALIDATION_ERROR message: type: string description: Human-readable error message example: 'submissionId: Required field is missing' userMessages: type: array description: >- Clean, verbatim-displayable messages — one entry per failure, free of error-code tags, field paths, and internal noise. Suitable for showing to end users as-is. items: type: string example: - Exposures of type 'company' require an address details: type: array description: Additional details for validation errors (field-level errors) items: type: object properties: field: type: string description: The field that caused the error example: submissionId message: type: string description: Description of the field error example: Required field is missing PolicyTransactionListItem: type: object description: > A policy list result. Always contains a `summary` object. When `detail=full`, also contains a `segments` array with complete field data for the scope-matched segments. required: - summary properties: summary: $ref: '#/components/schemas/PolicyListItemSummary' segments: type: array description: > Segments matching the `segmentScope` filter, with complete field data. Only present when `detail=full`. The `matchedSegments` array in `summary` contains date ranges only; this array adds the full `data` object for each segment. items: $ref: '#/components/schemas/PolicyTransactionSegmentResponse' PolicyListItemSummary: type: object description: | Summary fields for a policy list item. Always present in list responses. required: - id - policyId - companyId - createdAt - policyVersion - versionCreatedAt - matchedSegments properties: id: type: string format: uuid description: Transaction ID that produced this version policyId: type: string format: uuid description: Policy identifier companyId: type: string format: uuid description: Company identifier createdAt: type: string format: date-time description: When the policy was originally created (ISO 8601) policyVersion: type: integer description: Sequential version number versionCreatedAt: type: string format: date-time description: When this version was created (ISO 8601) primaryInsuredName: type: string nullable: true description: > Plain-text primary-insured name, read from the policy's own `primaryInsuredName` field — the source of truth for the primary insured. Reported as of the end of the segment window the query matched, so an unscoped query on a policy whose insured changed mid-term returns the later name. Null only when the matched segments carry no policy data. primaryInsuredId: type: string nullable: true description: | Id of the entity behind `primaryInsuredName`. Null when the policy's configuration does not populate it. policyNumber: type: string nullable: true description: > The policy number, read from the policy's own `policyNumber` field — the source of truth, invariant across the whole term. Null if no matched segments contain policy info. policyStartDate: type: object nullable: true description: > Policy term start date as the structured date object, read from the policy's own `policyStartDate` field — the source of truth, invariant across the whole term. Unrelated to `matchedSegments`, which reports the ISO ranges your `segmentScope` matched. Null if no matched segments contain policy info. allOf: - $ref: '#/components/schemas/Fmv1Date' policyEndDate: type: object nullable: true description: > Policy term end date as the structured date object, read from the policy's own `policyEndDate` field — the source of truth, invariant across the whole term. Null if no matched segments contain policy info. allOf: - $ref: '#/components/schemas/Fmv1Date' fullTermPricingInfo: type: object nullable: true description: | The policy's full-term pricing contract: `pricingComponents` (each `{label, group, kind, value[, earningBasis]}`) plus the five server-computed, read-only rollups (`premium`, `taxes`, `fees`, `brokerCommission`, `programCommission` — each the sum of its kind's components). Null if no matched segments contain pricing data. additionalProperties: true matchedSegments: type: array description: > Segments that matched the `segmentScope` filter. Contains only date ranges, not full segment data. Use `detail=full` to get complete segment data. items: type: object required: - startDate - endDate properties: startDate: type: string format: date description: Segment start date (ISO 8601) endDate: type: string format: date description: Segment end date (ISO 8601) PolicyTransactionSegmentResponse: type: object description: > A derived policy segment representing a date range where policy state is identical. Contains the full policy data (policy-level fields and nested exposures) for this period. required: - startDate - endDate - data properties: startDate: type: string format: date description: Segment start date (ISO 8601) endDate: type: string format: date description: Segment end date (ISO 8601) data: type: object description: > Policy state for this segment: the policy-level fields and their nested exposure containers, at the top level of this object. Before 2026-08-05 this member was named `fieldModelV1Data` and wrapped the same fields in an extra `policy` key. Read `data.policyNumber` where you read `fieldModelV1Data.policy.policyNumber`. additionalProperties: true Fmv1Date: type: object description: > Field Model V1 object primitive representing a calendar date with an explicit timezone. `day`, `month`, and `year` are required when this object is provided in a write payload; `timezone` is optional. Partial date components are rejected with `400`. **Two accepted input shapes** — the API canonicalizes both into the internal `{ day, month, year, timezone }` form before storage: * `{ date: "YYYY-MM-DD", timezone: "America/New_York" }` — ISO form * `{ day, month, year, timezone }` — DMY form (returned in responses) Day, month, and year are 1-based integers. `timezone` is an IANA tz database identifier (e.g. "America/New_York", "UTC"). required: - day - month - year properties: day: type: integer minimum: 1 maximum: 31 description: Day of month, 1-based (1-31) month: type: integer minimum: 1 maximum: 12 description: Month, 1-based (1=January, 12=December) year: type: integer description: Four-digit calendar year (e.g. 2026) timezone: type: string description: IANA timezone identifier (e.g. "America/New_York", "UTC") responses: Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: Missing API key value: error: code: AuthenticationError message: API key authentication required userMessages: - API key authentication required invalidApiKey: summary: >- Invalid API key (e.g. unknown key, or a Bearer token used instead of an API key) value: error: code: AuthenticationError message: Invalid API key userMessages: - Invalid API key Forbidden: description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientPermissions: summary: Insufficient permissions value: error: code: AuthorizationError message: User is not authorized to perform the requested action userMessages: - User is not authorized to perform the requested action companyMismatch: summary: A valid API key naming another company in the URL value: error: code: AuthorizationError message: API key is not scoped to the requested company userMessages: - API key is not scoped to the requested company InternalServerError: description: Internal Server Error - Unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: Unexpected server error value: error: code: UncaughtActionError message: Uncaught error occurred in userMessages: - An unexpected error occurred. Please try again later. securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: >- API key authentication. Send your raw API key as the `Authorization` header value with NO scheme prefix — `Authorization: YOUR-API-KEY`. Do NOT prefix it with `Bearer ` or `ApiKey `, and do not use an `X-API-Key` header; those are not accepted. ````