> ## Documentation Index > Fetch the complete documentation index at: https://docs.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/external/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://app.aiinsurance.io description: Production security: - ApiKeyAuth: [] paths: /api/v1/external/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: true schema: type: string description: > 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 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 `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. 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' 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 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' 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: 85000 policyTaxes: 0 policyFees: 500 policyGrandTotal: 85500 matchedSegments: - startDate: '2025-01-01' endDate: '2026-01-01' segments: - startDate: '2025-01-01' endDate: '2026-01-01' fieldModelV1Data: policy: annualPremium: 85000 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: 85000 policyTaxes: 0 policyFees: 500 policyGrandTotal: 85500 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, page size 50) schemas: PolicyListResponse: type: object description: Paginated list of policy results. 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' 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 `fieldModelV1Data` 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) fullTermPolicyBilling: type: object nullable: true description: | Full-term billing aggregates (premium, taxes, fees, grand total). Null if no matched segments contain billing data. additionalProperties: true fullTermPolicyInfo: type: object nullable: true description: | Full-term policy information (status, term dates, primary insured). Null if no matched segments contain policy info. 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 - fieldModelV1Data properties: startDate: type: string format: date description: Segment start date (ISO 8601) endDate: type: string format: date description: Segment end date (ISO 8601) fieldModelV1Data: type: object description: > Policy state for this segment. Contains a `policy` key with policy-level fields and a nested `exposures` array. properties: policy: type: object description: Policy-level fields and nested exposures for this segment. additionalProperties: true additionalProperties: true 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: UNAUTHORIZED message: Authorization header is required bearerTokenNotAllowed: summary: Bearer token used instead of API key value: error: code: UNAUTHORIZED message: External API endpoints require API key authentication Forbidden: description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientPermissions: summary: Insufficient permissions value: error: code: FORBIDDEN message: Insufficient permissions to perform this action 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: INTERNAL_ERROR message: An unexpected error occurred. Please try again later. securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: >- API key authentication. Include your API key in the Authorization header. ````