> ## 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. # Get Policy > Retrieves detailed information about a specific policy, including its segments, coverages, exposures, and rating inputs. **Segments:** Policies are divided into segments when exposures are added, removed, or modified mid-term. Each segment represents a period where policy data is constant, with non-overlapping date ranges covering the full policy term. **Time Travel (asOf parameter):** Use the `asOf` query parameter to retrieve the policy state as it existed at a specific point in time. This is useful for auditing, reporting, or understanding how the policy looked before endorsements or modifications. **Required permission:** `company.policy:read` ## OpenAPI ````yaml /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/policies/{policyId} 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/external/companies/{companyId}/policies/{policyId}: get: tags: - Policies summary: Get Policy description: > Retrieves detailed information about a specific policy, including its segments, coverages, exposures, and rating inputs. **Segments:** Policies are divided into segments when exposures are added, removed, or modified mid-term. Each segment represents a period where policy data is constant, with non-overlapping date ranges covering the full policy term. **Time Travel (asOf parameter):** Use the `asOf` query parameter to retrieve the policy state as it existed at a specific point in time. This is useful for auditing, reporting, or understanding how the policy looked before endorsements or modifications. **Required permission:** `company.policy:read` operationId: getPolicy parameters: - $ref: '#/components/parameters/companyId' - name: policyId in: path required: true schema: type: string format: uuid description: Policy identifier - name: asOf in: query required: false schema: type: string format: date-time description: > Retrieve the policy state as it existed at this timestamp (ISO 8601 format). If omitted, returns the current policy state. Example: "2024-06-15T10:00:00Z" responses: '200': description: Policy details retrieved successfully content: application/json: schema: $ref: '#/components/schemas/PolicyDetail' examples: success: summary: Policy with segments and exposures value: id: 84f9b186-08fc-408a-8f8c-d739e161c423 policyId: 84f9b186-08fc-408a-8f8c-d739e161c423 companyId: 7626bc64-e937-4f52-bb4a-05848bd09860 referenceId: POL-2025-001 policyNumber: POL-2025-001 createdAt: '2025-01-19T14:58:29.000+00:00' primaryInsuredId: c018b789-d235-4597-bf2e-8c308465b890 startsAtDate: '2025-01-19' endsAtDate: '2026-01-19' status: active termStart: '2025-01-19' termEnd: '2026-01-19' sourceTransactionId: 61b8357e-f92c-404e-825c-63432974c8a1 effectiveTimestamp: '2025-01-19T15:01:45.000+00:00' brokerId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 recipientName: John Smith recipientEmail: john.smith@acme.com segments: - start: '2025-01-19' end: '2025-05-18' status: bound premium: 293016 basePremium: 328490 coverages: - id: d4d4b369-4b4c-4240-bb32-cfce31be99d7 coverageTypeId: bodily_injury_and_property_damage coverageTypeName: Bodily Injury and Property Damage deductible: 25000 defenseInsideLimit: outside limits: - id: 716bf78a-f714-4904-89b6-053b4e7793b7 name: Each Occurrence amount: 1000000 exposures: - exposureId: c018b789-d235-4597-bf2e-8c308465b890 exposureType: company premium: 146508 basePremium: 164245 ratingInputs: bodily_injury_and_property_damage: bipdBaseRate: fieldName: BIPD Base Rate multiplier: 46350 adjustedPremium: 46350 deductibleMultiplier: fieldName: Deductible Multiplier multiplier: 0.7 adjustedPremium: 32445 - start: '2025-05-19' end: '2026-01-19' status: bound premium: 98341 basePremium: 110246.64 coverages: - id: d4d4b369-4b4c-4240-bb32-cfce31be99d7 coverageTypeId: bodily_injury_and_property_damage coverageTypeName: Bodily Injury and Property Damage deductible: 25000 defenseInsideLimit: outside limits: - id: 716bf78a-f714-4904-89b6-053b4e7793b7 name: Each Occurrence amount: 1000000 exposures: - exposureId: cee398b5-1569-42a0-90bb-5eda3fdd067b exposureType: manufacturing_contracting_facility premium: 98341 basePremium: 110246.64 ratingInputs: bodily_injury_and_property_damage: activeRate: base: 365 days: 245 fieldName: Coverage Length Active Rate multiplier: 0.6712328767123288 adjustedPremium: 21778.15 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: Policy not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: policyNotFound: summary: Policy not found value: error: code: NOT_FOUND message: Policy not found '500': $ref: '#/components/responses/InternalServerError' components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier schemas: PolicyDetail: type: object description: Detailed policy information returned from the get endpoint properties: id: type: string format: uuid description: Policy identifier policyId: type: string format: uuid description: Policy identifier (same as id, for convenience) companyId: type: string format: uuid description: Company identifier referenceId: type: string nullable: true description: Policy reference ID (same as policyNumber) policyNumber: type: string nullable: true description: Policy number createdAt: type: string format: date-time nullable: true description: When the policy was created (ISO 8601) primaryInsuredId: type: string format: uuid nullable: true description: ID of the primary insured on this policy startsAtDate: type: string format: date nullable: true description: Policy effective start date (YYYY-MM-DD) endsAtDate: type: string format: date nullable: true description: Policy effective end date (YYYY-MM-DD) status: $ref: '#/components/schemas/PolicyStatus' termStart: type: string format: date nullable: true description: Policy term start date (YYYY-MM-DD) termEnd: type: string format: date nullable: true description: Policy term end date (YYYY-MM-DD) sourceTransactionId: type: string format: uuid nullable: true description: ID of the transaction that created or last modified the policy effectiveTimestamp: type: string format: date-time nullable: true description: Timestamp when the current policy state became effective (ISO 8601) segments: type: array items: $ref: '#/components/schemas/PolicySegment' description: | Policy segments with coverage and exposure details. Each segment represents a period where policy data is constant. type: type: string nullable: true description: Policy type code (e.g., "C" for Claims Made, "O" for Occurrence) brokerId: type: string nullable: true description: ID of the broker associated with this policy recipientName: type: string nullable: true description: Name of the policy recipient recipientEmail: type: string nullable: true description: Email of the policy recipient 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 PolicyStatus: type: string description: | Current status of the policy: - `active` - Policy is currently in effect - `not_started` - Policy start date is in the future - `expired` - Policy end date is in the past - `pending_signature` - Awaiting policyholder signature - `pending_payment` - Awaiting payment - `pending_actions` - Awaiting both signature and payment - `pending_renewal` - Within 60 days of renewal date - `renewal_in_progress` - Renewal submission created but not bound - `renewed` - Policy has been renewed - `cancelled` - Policy has been cancelled enum: - active - not_started - expired - pending_signature - pending_payment - pending_actions - pending_renewal - renewal_in_progress - renewed - cancelled - inactive - unknown PolicySegment: type: object description: > A policy segment representing a period where policy data is constant. When exposures are added, removed, or modified mid-term, the policy is split into segments with non-overlapping date ranges. properties: start: type: string format: date description: Segment start date (YYYY-MM-DD) end: type: string format: date description: Segment end date (YYYY-MM-DD) status: $ref: '#/components/schemas/SegmentStatus' premium: type: number nullable: true description: Total premium for this segment in dollars basePremium: type: number nullable: true description: Base premium for this segment before adjustments in dollars coverages: type: array items: $ref: '#/components/schemas/PolicyCoverage' description: Coverages active during this segment exposures: type: array items: $ref: '#/components/schemas/PolicyExposure' description: >- Exposures (insureds) active during this segment with their rating details SegmentStatus: type: string description: Status of a policy segment enum: - bound - quoted - cancelled PolicyCoverage: type: object description: Coverage details within a policy segment properties: id: type: string format: uuid description: Coverage identifier coverageTypeId: type: string description: Coverage type identifier (e.g., "bodily_injury_and_property_damage") coverageTypeName: type: string description: Human-readable coverage type name deductible: type: number nullable: true description: Deductible amount in cents defenseInsideLimit: type: string nullable: true description: >- Whether defense costs are inside or outside the limit ("inside" or "outside") limits: type: array items: $ref: '#/components/schemas/PolicyCoverageLimit' description: Coverage limits PolicyExposure: type: object description: >- Exposure (insured) data within a policy segment, including rating details properties: exposureId: type: string format: uuid description: Exposure (insured) identifier exposureType: type: string nullable: true description: >- Type of exposure (e.g., "company", "distribution_center", "manufacturing_contracting_facility") premium: type: number nullable: true description: Premium for this exposure in cents basePremium: type: number nullable: true description: Base premium before adjustments in dollars ratingInputs: type: object nullable: true description: > Rating inputs organized by coverage type ID. Each key is a coverage type ID, and the value is an object with rating factor keys and their details. additionalProperties: type: object additionalProperties: $ref: '#/components/schemas/RatingFactor' PolicyCoverageLimit: type: object description: A coverage limit with its amount properties: id: type: string format: uuid description: Limit identifier name: type: string description: Name of the limit (e.g., "Each Occurrence", "Aggregate") amount: type: number description: Limit amount in cents RatingFactor: type: object description: A rating factor that was applied during premium calculation properties: fieldName: type: string description: Human-readable name of the rating factor adjustedPremium: type: number description: Premium after this factor was applied multiplier: oneOf: - type: number - type: array items: type: number description: Multiplier value(s) applied value: oneOf: - type: number - type: array items: type: number description: Base value(s) used in calculation days: type: integer description: Number of days (for pro-rata calculations) base: type: integer description: Base number of days (typically 365) message: type: string description: Optional message about the factor 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. ````