> ## 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. # Validate Policy > Runs data consistency checks against a single policy and returns detailed results. This is a read-only diagnostic endpoint — no data is modified. Eight checks are available, covering segment contiguity, hash correctness, version sequentiality, full-term invariance, duplicate detection, transaction-segment existence, and cancel/reinstate premium consistency. By default all checks run; use the `checks` parameter to select a subset. Checks are either **version-scoped** (run once per policy version) or **policy-scoped** (run once for the whole policy). A policy with 3 versions and all 8 checks enabled produces up to 18 results (5 version-scoped checks x 3 versions + 3 policy-scoped checks). Use the `version` parameter to validate a single version instead of all versions. ### Available checks | Check | Scope | What it validates | |-------|-------|-------------------| | `contiguity` | version | Segments form a contiguous date range with no gaps or overlaps | | `fullTermInvariance` | version | Billing and policy metadata fields are constant across all segments in a version | | `hashCorrectness` | version | Stored segment hash matches the computed hash of the segment data | | `noDuplicateSegments` | version | No adjacent segments have identical hashes | | `transactionSegmentExistence` | version | At least one segment exists for the version | | `versionSequentiality` | policy | Versions are sequential starting from 1 with no gaps | | `cancelEarnedPremium` | policy | Cancel transaction premium matches earned premium through the cancellation date | | `cancelReinstatePremium` | policy | Reinstate transaction premium matches the pre-cancel version premium | **Required permission:** `company.policy:read` ## OpenAPI ````yaml /openapi/generated-external-api.yaml get /api/v1/external/companies/{companyId}/policies/{policyId}/validate 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}/validate: get: tags: - Field Model Policy Validation summary: Validate Policy description: > Runs data consistency checks against a single policy and returns detailed results. This is a read-only diagnostic endpoint — no data is modified. Eight checks are available, covering segment contiguity, hash correctness, version sequentiality, full-term invariance, duplicate detection, transaction-segment existence, and cancel/reinstate premium consistency. By default all checks run; use the `checks` parameter to select a subset. Checks are either **version-scoped** (run once per policy version) or **policy-scoped** (run once for the whole policy). A policy with 3 versions and all 8 checks enabled produces up to 18 results (5 version-scoped checks x 3 versions + 3 policy-scoped checks). Use the `version` parameter to validate a single version instead of all versions. ### Available checks | Check | Scope | What it validates | |-------|-------|-------------------| | `contiguity` | version | Segments form a contiguous date range with no gaps or overlaps | | `fullTermInvariance` | version | Billing and policy metadata fields are constant across all segments in a version | | `hashCorrectness` | version | Stored segment hash matches the computed hash of the segment data | | `noDuplicateSegments` | version | No adjacent segments have identical hashes | | `transactionSegmentExistence` | version | At least one segment exists for the version | | `versionSequentiality` | policy | Versions are sequential starting from 1 with no gaps | | `cancelEarnedPremium` | policy | Cancel transaction premium matches earned premium through the cancellation date | | `cancelReinstatePremium` | policy | Reinstate transaction premium matches the pre-cancel version premium | **Required permission:** `company.policy:read` operationId: validatePolicy parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/policyIdPath' - name: version in: query schema: type: integer minimum: 1 description: | Validate only this policy version. If omitted, all versions are validated. Version-scoped checks run only for the specified version; policy-scoped checks always run. - name: checks in: query schema: type: string description: | Comma-separated list of check names to run (e.g., `contiguity,hashCorrectness`). If omitted, all checks run. Unrecognized check names are silently ignored. If all provided names are unrecognized, all checks run (same as omitting the parameter). Check names are case-sensitive. responses: '200': description: Validation results for the policy content: application/json: schema: $ref: '#/components/schemas/PolicyValidationResponse' examples: allPassing: summary: All checks pass value: policyId: 550e8400-e29b-41d4-a716-446655440001 validatedAt: '2026-04-14T18:30:00.000Z' summary: totalChecks: 8 passed: 8 failed: 0 skipped: 0 results: - check: contiguity status: pass scope: version:1 - check: fullTermInvariance status: pass scope: version:1 - check: hashCorrectness status: pass scope: version:1 - check: noDuplicateSegments status: pass scope: version:1 - check: transactionSegmentExistence status: pass scope: version:1 - check: cancelEarnedPremium status: pass scope: policy - check: cancelReinstatePremium status: pass scope: policy - check: versionSequentiality status: pass scope: policy withFailure: summary: One check fails value: policyId: 550e8400-e29b-41d4-a716-446655440001 validatedAt: '2026-04-14T18:30:00.000Z' summary: totalChecks: 8 passed: 7 failed: 1 skipped: 0 results: - check: contiguity status: fail scope: version:2 message: >- Segments for version 2 are not contiguous: gap between 2025-06-01 and 2025-07-01 - check: fullTermInvariance status: pass scope: version:2 - check: hashCorrectness status: pass scope: version:2 - check: noDuplicateSegments status: pass scope: version:2 - check: transactionSegmentExistence status: pass scope: version:2 - check: cancelEarnedPremium status: pass scope: policy - check: cancelReinstatePremium status: pass scope: policy - check: versionSequentiality status: pass scope: policy filteredChecks: summary: Subset of checks requested value: policyId: 550e8400-e29b-41d4-a716-446655440001 validatedAt: '2026-04-14T18:30:00.000Z' summary: totalChecks: 8 passed: 2 failed: 0 skipped: 6 results: - check: contiguity status: pass scope: version:1 - check: fullTermInvariance status: skipped scope: version:1 - check: hashCorrectness status: skipped scope: version:1 - check: noDuplicateSegments status: skipped scope: version:1 - check: transactionSegmentExistence status: skipped scope: version:1 - check: cancelEarnedPremium status: skipped scope: policy - check: cancelReinstatePremium status: skipped scope: policy - check: versionSequentiality status: pass scope: policy '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: Policy or version not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: policyNotFound: summary: Policy not found value: error: code: NOT_FOUND message: Policy 550e8400-e29b-41d4-a716-446655440001 not found versionNotFound: summary: Specified version not found value: error: code: NOT_FOUND message: >- Policy 550e8400-e29b-41d4-a716-446655440001 version 5 not found '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 schemas: PolicyValidationResponse: type: object description: > Validation results for a single policy, including a summary of pass/fail/skip counts and the individual check results. required: - policyId - validatedAt - summary - results properties: policyId: type: string format: uuid description: The policy that was validated validatedAt: type: string format: date-time description: ISO 8601 timestamp of when the validation was performed summary: $ref: '#/components/schemas/PolicyValidationSummary' results: type: array description: > Individual check results. Contains one entry per check per scope (version-scoped checks produce one result per version). items: $ref: '#/components/schemas/PolicyValidationCheckResult' 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 PolicyValidationSummary: type: object description: > Aggregate counts of check results for a single policy. A policy with multiple versions will have more results than the number of check types, because version-scoped checks run once per version. required: - totalChecks - passed - failed - skipped properties: totalChecks: type: integer description: > Total number of check results (passed + failed + skipped). This can exceed 8 (the number of check types) because version-scoped checks run once per version. example: 18 passed: type: integer description: Number of checks that passed example: 17 failed: type: integer description: Number of checks that failed example: 1 skipped: type: integer description: > Number of checks that were skipped because the `checks` query parameter excluded them example: 0 PolicyValidationCheckResult: type: object description: > Result of a single validation check against a policy or policy version. Each check evaluates a specific data consistency invariant. required: - check - status - scope properties: check: type: string description: > Name of the validation check. See the `checks` query parameter for the full list of available check names. enum: - cancelEarnedPremium - cancelReinstatePremium - contiguity - fullTermInvariance - hashCorrectness - noDuplicateSegments - transactionSegmentExistence - versionSequentiality example: contiguity status: type: string description: > Outcome of the check: `pass` if the invariant holds, `fail` if a violation was detected, or `skipped` if the check was excluded by the `checks` filter. enum: - pass - fail - skipped example: pass scope: type: string description: > Context in which the check ran. Version-scoped checks use the format `version:N` (e.g., `version:1`). Policy-scoped checks use `policy`. example: version:1 message: type: string description: | Explanation of the failure. Only present when `status` is `fail`. example: >- Segments for version 2 are not contiguous: gap between 2025-06-01 and 2025-07-01 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. ````