List Single Policy Versions

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

import requests

url = "https://app.aiinsurance.io/api/v1/external/companies/{companyId}/policies/{policyId}/versions"

headers = {"Authorization": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://app.aiinsurance.io/api/v1/external/companies/{companyId}/policies/{policyId}/versions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.aiinsurance.io/api/v1/external/companies/{companyId}/policies/{policyId}/versions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.aiinsurance.io/api/v1/external/companies/{companyId}/policies/{policyId}/versions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://app.aiinsurance.io/api/v1/external/companies/{companyId}/policies/{policyId}/versions")
  .header("Authorization", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.aiinsurance.io/api/v1/external/companies/{companyId}/policies/{policyId}/versions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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
}

Transactions

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

GET

api

external

companies

{companyId}

policies

{policyId}

versions

List Single Policy Versions

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

import requests

url = "https://app.aiinsurance.io/api/v1/external/companies/{companyId}/policies/{policyId}/versions"

headers = {"Authorization": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://app.aiinsurance.io/api/v1/external/companies/{companyId}/policies/{policyId}/versions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.aiinsurance.io/api/v1/external/companies/{companyId}/policies/{policyId}/versions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.aiinsurance.io/api/v1/external/companies/{companyId}/policies/{policyId}/versions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://app.aiinsurance.io/api/v1/external/companies/{companyId}/policies/{policyId}/versions")
  .header("Authorization", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.aiinsurance.io/api/v1/external/companies/{companyId}/policies/{policyId}/versions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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
}

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

page

integer

default:1

Page number (1-based, default 1, page size 50)

Required range: x >= 1

detail

enum<string>

required

Detail level. summary returns lightweight results with matched segment date ranges. full includes complete field data for each scope-matched segment.

Available options:

summary,

full

segmentScope

string

required

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

filters

string

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.

sortBy

enum<string>

Field to sort results by

Available options:

policyId,

createdAt,

versionCreatedAt

sortDirection

enum<string>

default:desc

Sort direction (default desc)

Available options:

asc,

desc

Response

Paginated list of policy versions

Paginated list of policy results.

items

object[]

required

Show child attributes

totalCount

integer

required

Total number of matching results across all pages

Get Policy Version List Policy Transactions

⌘I

Getting Started

Exposures

Events

Event Financials

Policies

Submissions

Quotes

Rating

Custom Objects

Configuration Management

Basic Policies

Company Files

Document Generation

Submission Parsing

Address Tools

Reference

List Single Policy Versions

Authorizations

Path Parameters

Query Parameters

Response