> ## 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 Single Policy 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` ## OpenAPI ````yaml /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/{policyId}/versions 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/{policyId}/versions: get: tags: - Field Model Policy Transactions summary: List Single Policy Versions description: > 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` operationId: listSinglePolicyVersions parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/policyIdPath' - $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 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. - 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 policy versions content: application/json: schema: $ref: '#/components/schemas/PolicyListResponse' examples: versionHistory: summary: Three versions of a policy value: items: - summary: id: 550e8400-e29b-41d4-a716-446655440004 policyId: 550e8400-e29b-41d4-a716-446655440001 companyId: 550e8400-e29b-41d4-a716-446655440099 createdAt: '2025-01-15T10:30:00.000Z' policyVersion: 3 versionCreatedAt: '2025-03-10T09:00:00.000Z' fullTermPolicyInfo: policyStatus: Active fullTermPolicyBilling: policyPremium: 110000 policyTaxes: 0 policyFees: 500 policyGrandTotal: 110500 matchedSegments: - startDate: '2025-01-01' endDate: '2025-06-01' - startDate: '2025-06-01' endDate: '2025-09-01' - startDate: '2025-09-01' endDate: '2026-01-01' - summary: id: 550e8400-e29b-41d4-a716-446655440003 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 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' - 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 fullTermPolicyBilling: policyPremium: 85000 policyTaxes: 0 policyFees: 500 policyGrandTotal: 85500 matchedSegments: - startDate: '2025-01-01' endDate: '2026-01-01' totalCount: 3 '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 '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 policyIdPath: name: policyId in: path required: true schema: type: string format: uuid description: Policy 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. ````