> ## 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.

# Policy

> Retrieve a single policy by ID

Returns a single policy by its unique identifier. The policy must belong to the authenticated upstream entity.

## Path Parameters

| Parameter      | Type   | Required | Description                                        |
| -------------- | ------ | -------- | -------------------------------------------------- |
| **`policyId`** | string | Yes      | Unique identifier of the policy (MongoDB ObjectId) |

## Response Shape

<Note>
  All successful responses are wrapped in the standard response envelope. See [Request/Response Conventions](/guides/request-response).
</Note>

```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",
    "producerName": "Jane Doe",
    "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

The response object contains the same fields as each item in [List Policies](/api-reference/v1/policies/list-policies). See that page for the full field reference, including matching status values.

## Error Scenarios

### Bad Request (400)

Returned when `policyId` is not a valid MongoDB ObjectId format.

```json theme={null}
{
  "statusCode": 400,
  "errorType": "validation_error",
  "errorMessage": ["policyId must be a mongodb id"],
  "requestId": "dev-abc123",
  "timestamp": "2025-01-15T10:30:00.000Z"
}
```

### Policy Not Found (404)

Returned when `policyId` doesn't exist or belongs to a different upstream entity.

```json theme={null}
{
  "statusCode": 404,
  "errorType": "not_found",
  "errorMessage": ["Policy not found"],
  "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/{policyId}
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/{policyId}:
    get:
      tags:
        - policies
      operationId: PoliciesController_getPolicy_v1
      parameters:
        - name: policyId
          required: true
          in: path
          description: Unique identifier of the policy
          schema:
            example: 6650a1b2c3d4e5f6a7b8c9d0
            type: string
      responses:
        '200':
          description: Policy details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $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 policyId format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '401':
          description: Invalid or missing auth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '404':
          description: Policy not found or belongs to a different upstream entity
          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

````