> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turrisfi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Policies
> Retrieve all policies belonging to the authenticated upstream entity
Returns all policies associated with your upstream entity. Soft-deleted policies are excluded automatically. Results can be filtered by policy number, status, or risk state.
## Query Parameters
| Parameter | Type | Required | Description |
| ------------------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| **`policyNumber`** | string | No | Filter by exact policy number (e.g., `POL-2025-001`) |
| **`currentStatus`** | string | No | Filter by policy status: `bound`, `active`, `expired`, `cancelled`, or `non renewed` |
| **`riskStateCode`** | string | No | Filter by US state code (e.g., `CA`, `TX`, `NY`) |
## Filtering Examples
```bash theme={null}
# By status
GET /v1/policies?currentStatus=active
# By state
GET /v1/policies?riskStateCode=CA
# Combined filters
GET /v1/policies?currentStatus=active&riskStateCode=TX
# By exact policy number
GET /v1/policies?policyNumber=POL-2025-001
```
## Response Shape
All successful responses are wrapped in the standard response envelope. See [Request/Response Conventions](/guides/request-response).
```json theme={null}
{
"statusCode": 200,
"data": [
{
"_id": "6650a1b2c3d4e5f6a7b8c9d0",
"policyNumber": "POL-2025-001",
"currentStatus": "active",
"riskStateCode": "CA",
"agencyName": "Premier Insurance Agency",
"agencyNpn": "12345678",
"agencyFein": "12-3456789",
"agentName": "John Smith",
"agentNpn": "87654321",
"carrierName": "National Insurance Co",
"lineOfBusiness": "Commercial Lines",
"productName": "General Liability",
"insuredEntityName": "Acme Corp",
"effectiveDate": "2025-01-15T00:00:00.000Z",
"expiryDate": "2026-01-15T00:00:00.000Z",
"premiumAmountInUSD": 5000,
"aggregateCoverageInUSD": 1000000,
"coveragePerClaimInUSD": 500000,
"entityMatchStatus": "auto matched",
"productMatchStatus": "unmatched",
"transactionCount": 3,
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:31:45.000Z"
}
],
"timestamp": "2025-01-15T10:31:50.000Z"
}
```
### Response Fields
#### Core Fields
| Field | Type | Description |
| --------------- | ------ | ---------------------------------------------------------------------------------- |
| `_id` | string | Unique policy identifier |
| `policyNumber` | string | Policy number that groups transactions into a single policy |
| `currentStatus` | string | Current policy status: `bound`, `active`, `expired`, `cancelled`, or `non renewed` |
| `riskStateCode` | string | US state code where the risk is located |
#### Agency & Agent Fields
| Field | Type | Description |
| ------------------------- | ------- | --------------------------------------------- |
| `agencyName` | string? | Agency name |
| `agencyNpn` | string? | Agency National Producer Number |
| `agencyFein` | string? | Agency Federal Employer Identification Number |
| `agencyLicenseNumber` | string? | Agency state license number |
| `agencyLicensedStateCode` | string? | State where the agency license was issued |
| `agentName` | string? | Individual agent name |
| `agentNpn` | string? | Agent National Producer Number |
| `agentLicenseNumber` | string? | Agent state license number |
| `agentLicensedState` | string? | State where the agent license was issued |
#### Insurance Details
| Field | Type | Description |
| ------------------- | ------- | ------------------------- |
| `insuredEntityName` | string? | Name of the insured party |
| `carrierName` | string? | Insurance carrier name |
| `lineOfBusiness` | string? | Line of business |
| `producerName` | string? | Producing agent name |
| `producerCode` | string? | Producer identifier code |
| `productName` | string? | Product name |
| `productCode` | string? | Product code |
#### Dates & Coverage
| Field | Type | Description |
| ------------------------ | ------- | --------------------------------- |
| `effectiveDate` | string? | Policy effective date (ISO 8601) |
| `expiryDate` | string? | Policy expiration date (ISO 8601) |
| `premiumAmountInUSD` | number? | Premium amount in USD |
| `aggregateCoverageInUSD` | number? | Aggregate coverage limit in USD |
| `coveragePerClaimInUSD` | number? | Per-claim coverage limit in USD |
#### Matching & Metadata
| Field | Type | Description |
| -------------------- | ------- | ----------------------------------------------- |
| `entityMatchStatus` | string | Agency/entity matching status (see table below) |
| `productMatchStatus` | string | Product matching status (see table below) |
| `transactionCount` | number | Number of transactions linked to this policy |
| `filingNumber` | string? | Filing number |
| `slaNumber` | string? | SLA number |
| `externalBillingId` | string? | External billing identifier |
| `licenseNumber` | string? | License number |
| `npn` | string? | National Producer Number |
| `createdAt` | string | ISO 8601 timestamp when the policy was created |
| `updatedAt` | string | ISO 8601 timestamp of the last update |
### Matching Status Values
| Field | Values | Meaning |
| -------------------- | -------------------------------------------------------------------- | --------------------------------------------------------- |
| `entityMatchStatus` | `unmatched`, `auto matched`, `user confirmed`, `manual review` | Whether the policy has been linked to a downstream entity |
| `productMatchStatus` | `unmatched`, `auto matched`, `user confirmed`, `needs clarification` | Whether the policy has been linked to a product |
Policies with `entityMatchStatus` of `"unmatched"` or `"manual review"` require attention in the Turris dashboard.
## Error Scenarios
### Bad Request (400)
Returned when a query parameter has an invalid value (e.g., an unsupported `currentStatus`).
```json theme={null}
{
"statusCode": 400,
"errorType": "validation_error",
"errorMessage": ["Invalid value for currentStatus"],
"requestId": "dev-abc123",
"timestamp": "2025-01-15T10:30:00.000Z"
}
```
### Unauthorized (401)
Missing or invalid authentication token. See [Authentication](/authentication).
## OpenAPI
````yaml openapi/v1.json GET /v1/policies
openapi: 3.0.0
info:
title: Turris Public API
description: API for managing insurance compliance data
version: 1.0.0
contact: {}
servers:
- url: https://public.api.live.turrisfi.com
description: Production
- url: https://public.api.sandbox.turrisfi.com
description: Sandbox
security: []
tags: []
paths:
/v1/policies:
get:
tags:
- policies
operationId: PoliciesController_listPolicies_v1
parameters:
- name: policyNumber
required: false
in: query
description: Filter by exact policy number
schema:
example: POL-2025-001
type: string
- name: currentStatus
required: false
in: query
description: Filter by current policy status
schema:
example: active
type: string
enum:
- bound
- active
- expired
- cancelled
- non renewed
- name: riskStateCode
required: false
in: query
description: Filter by US state code where risk is located
schema:
example: CA
type: string
responses:
'200':
description: List of policies belonging to the authenticated upstream entity
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/PublicPolicyResponse'
requestId:
type: string
description: Unique request identifier
example: dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8
timestamp:
type: string
description: Response timestamp
example: '2025-11-12T20:49:03.293Z'
required:
- data
- requestId
- timestamp
'400':
description: Invalid query parameter value
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
'401':
description: Invalid or missing auth token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
components:
schemas:
PublicPolicyResponse:
type: object
properties:
_id:
type: string
description: Unique policy identifier
example: 6650a1b2c3d4e5f6a7b8c9d0
policyNumber:
type: string
description: Policy number that groups transactions into a single policy
example: POL-2025-001
currentStatus:
type: string
description: Current policy status derived from transaction history
example: active
enum:
- bound
- active
- expired
- cancelled
- non renewed
riskStateCode:
type: string
description: US state code where the risk is located
example: CA
insuredEntityName:
type: string
description: Name of the insured party
example: Acme Corp
agencyName:
type: string
description: Agency name
example: Premier Insurance Agency
agencyNpn:
type: string
description: Agency National Producer Number
example: '12345678'
agencyFein:
type: string
description: Agency Federal Employer Identification Number
example: 12-3456789
agencyLicenseNumber:
type: string
description: Agency state license number
example: ABC-123456
agencyLicensedStateCode:
type: string
description: State where the agency license was issued
example: CA
agentName:
type: string
description: Individual agent name
example: John Smith
agentNpn:
type: string
description: Agent National Producer Number
example: '87654321'
agentLicenseNumber:
type: string
description: Agent state license number
example: LIC-789012
agentLicensedState:
type: string
description: State where the agent license was issued
example: TX
carrierName:
type: string
description: Insurance carrier name
example: National Insurance Co
lineOfBusiness:
type: string
description: Line of business
example: Commercial Lines
producerName:
type: string
description: Producing agent name
example: Jane Doe
producerCode:
type: string
description: Producer identifier code
example: PROD-001
productName:
type: string
description: Product name
example: General Liability
productCode:
type: string
description: Product code
example: GL-100
effectiveDate:
type: string
description: Policy effective date (ISO 8601)
example: '2025-01-15T00:00:00.000Z'
expiryDate:
type: string
description: Policy expiration date (ISO 8601)
example: '2026-01-15T00:00:00.000Z'
premiumAmountInUSD:
type: number
description: Premium amount in USD
example: 5000
aggregateCoverageInUSD:
type: number
description: Aggregate coverage limit in USD
example: 1000000
coveragePerClaimInUSD:
type: number
description: Per-claim coverage limit in USD
example: 500000
filingNumber:
type: string
description: Filing number
example: FIL-2025-001
slaNumber:
type: string
description: SLA number
example: SLA-2025-001
externalBillingId:
type: string
description: External billing identifier
example: BILL-2025-001
licenseNumber:
type: string
description: License number
example: LIC-001
npn:
type: string
description: National Producer Number
example: '11223344'
entityMatchStatus:
type: string
description: Agency/entity matching status
example: auto matched
enum:
- auto matched
- user confirmed
- manual review
- unmatched
productMatchStatus:
type: string
description: Product matching status
example: unmatched
enum:
- auto matched
- user confirmed
- needs clarification
- unmatched
transactionCount:
type: number
description: Number of transactions linked to this policy
example: 3
createdAt:
type: string
description: ISO 8601 timestamp when the policy was created
example: '2025-01-15T10:30:00.000Z'
updatedAt:
type: string
description: ISO 8601 timestamp of the last update
example: '2025-01-15T10:31:45.000Z'
required:
- _id
- policyNumber
- currentStatus
- riskStateCode
- entityMatchStatus
- productMatchStatus
- transactionCount
- createdAt
- updatedAt
ErrorResponseDto:
type: object
properties:
statusCode:
type: number
description: HTTP status code
requestId:
type: string
description: Unique request identifier for debugging
errorType:
type: string
description: Error type classification
errorMessage:
description: Array of error messages
type: array
items:
type: string
timestamp:
type: string
description: ISO timestamp when the error occurred
details:
type: object
description: Additional error context
required:
- statusCode
- requestId
- errorType
- errorMessage
- timestamp
````