List Earned Premium (Multi-Policy)

Returns earned premium for multiple policies, paginated by policy. Each item in the response has the same shape as the single-policy endpoint for the requested detail level.

Use segmentScope to control which policies are included based on segment date matching:

• "all" — every policy
• {"asOf":"YYYY-MM-DD"} — policies with segments active on that date
• {"fromDate":"YYYY-MM-DD","toDate":"YYYY-MM-DD"} — policies with segments overlapping the date range

Use filters to narrow results by field values in policy data.

The earned premium date range is a half-open interval [startDate, endDate) and must not exceed 366 days.

Required permission: company.policy:read

GET /api/v1/external/companies/{companyId}/policies/list/earned-premium

List Earned Premium (Multi-Policy)

cURL

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

200

transactionsDetail

{
  "items": [
    {
      "policyId": "550e8400-e29b-41d4-a716-446655440001",
      "policyNumber": "POL-2025-001",
      "earnedPremiumTotal": 42465.75,
      "transactionTotals": [
        {
          "transactionId": "660e8400-e29b-41d4-a716-446655440001",
          "policyVersion": 1,
          "action": "NEW_BUSINESS",
          "totalContribution": 42465.75
        }
      ]
    },
    {
      "policyId": "550e8400-e29b-41d4-a716-446655440002",
      "policyNumber": "POL-2025-002",
      "earnedPremiumTotal": 28000,
      "transactionTotals": [
        {
          "transactionId": "660e8400-e29b-41d4-a716-446655440010",
          "policyVersion": 1,
          "action": "NEW_BUSINESS",
          "totalContribution": 25000
        },
        {
          "transactionId": "660e8400-e29b-41d4-a716-446655440011",
          "policyVersion": 2,
          "action": "ENDORSE",
          "totalContribution": 3000
        }
      ]
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 50,
    "total": 2
  }
}

Authorizations

Authorization · string · header · required

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

Path Parameters

companyId · string<uuid> · required

Company identifier

Query Parameters

startDate · string<date> · required

Start of the earned premium window (inclusive). ISO 8601 date (YYYY-MM-DD). Must be before or equal to endDate.

endDate · string<date> · required

End of the earned premium window (exclusive). ISO 8601 date (YYYY-MM-DD). The range [startDate, endDate) must not exceed 366 days.

detail · enum<string> · default: transactions

Response granularity per policy:

• transactions — transactionTotals only (default)
• days — adds days array with net earned premium per day
• daysAndTransactions — adds days array with per-transaction contributions on each day

Available options: transactions, days, daysAndTransactions

segmentScope · string · required

JSON-encoded segment scope filter. Controls which policies are included based on segment date matching. Values:

• "all" — every policy
• {"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 (text, number, boolean, date, currency, optionSet, address).

timeTravelBackToDate · string<date-time>

Only include transactions created before this timestamp (ISO 8601). Useful for auditing historical earned premium state.

limit · integer · default: 50

Maximum number of policies to return per page (default 50, max 200).

Required range: 1 <= x <= 200

offset · integer · default: 0

Number of policies to skip (0-based, default 0).

Required range: x >= 0

Response

200

application/json

Paginated list of per-policy earned premium

Paginated list of per-policy earned premium results.

items · object[] · required

Show child attributes

pagination · object · required

Show child attributes