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

GET /api/external/companies/{companyId}/policies/{policyId}

Get Policy

cURL

curl --request GET \
  --url https://app.aiinsurance.io/api/external/companies/{companyId}/policies/{policyId} \
  --header 'Authorization: <api-key>'

200

success

{
  "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": "[e-mail]",
  "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
              }
            }
          }
        }
      ]
    }
  ]
}

Authorizations

Authorization · string · header · required

API key authentication. Include your API key in the Authorization header.

Path Parameters

companyId · string<uuid> · required

Company identifier

policyId · string<uuid> · required

Policy identifier

Query Parameters

asOf · string<date-time>

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"

Response

200

application/json

Policy details retrieved successfully

Detailed policy information returned from the get endpoint

id · string<uuid>

Policy identifier

policyId · string<uuid>

Policy identifier (same as id, for convenience)

companyId · string<uuid>

Company identifier

referenceId · string | null

Policy reference ID (same as policyNumber)

policyNumber · string | null

Policy number

createdAt · string<date-time> | null

When the policy was created (ISO 8601)

primaryInsuredId · string<uuid> | null

ID of the primary insured on this policy

startsAtDate · string<date> | null

Policy effective start date (YYYY-MM-DD)

endsAtDate · string<date> | null

Policy effective end date (YYYY-MM-DD)

status · enum<string>

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

Available options: active, not_started, expired, pending_signature, pending_payment, pending_actions, pending_renewal, renewal_in_progress, renewed, cancelled, inactive, unknown

termStart · string<date> | null

Policy term start date (YYYY-MM-DD)

termEnd · string<date> | null

Policy term end date (YYYY-MM-DD)

sourceTransactionId · string<uuid> | null

ID of the transaction that created or last modified the policy

effectiveTimestamp · string<date-time> | null

Timestamp when the current policy state became effective (ISO 8601)

segments · object[]

Policy segments with coverage and exposure details. Each segment represents a period where policy data is constant.

Show child attributes

type · string | null

Policy type code (e.g., "C" for Claims Made, "O" for Occurrence)

brokerId · string | null

ID of the broker associated with this policy

recipientName · string | null

Name of the policy recipient

recipientEmail · string | null

Email of the policy recipient