> ## 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. # List Transactions > List transactions for a policy, paginated Returns the transactions linked to a policy, paginated. The policy must belong to the authenticated upstream entity. ## Path Parameters | Parameter | Type | Required | Description | | -------------- | ------ | -------- | --------------------------------------------------------- | | **`policyId`** | string | Yes | Unique identifier of the parent policy (MongoDB ObjectId) | ## Query Parameters | Parameter | Type | Required | Description | | ----------- | ------ | -------- | -------------------------------------- | | **`page`** | number | No | 1-based page number. Defaults to `1` | | **`limit`** | number | No | Page size, max `100`. Defaults to `50` | ## 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": { "transactions": [ { "_id": "6650a1b2c3d4e5f6a7b8c9d1", "policyId": "6650a1b2c3d4e5f6a7b8c9d0", "policyNumber": "POL-2025-001", "policyTransactionType": "new", "policyTransactionDate": "2025-01-15T00:00:00.000Z", "riskStateCode": "CA", "entityMatchStatus": "user confirmed", "matchedAgents": [], "agentMatchStatus": "unmatched", "createdAt": "2025-01-15T10:30:00.000Z", "updatedAt": "2025-01-15T10:30:00.000Z" } ], "total": 1, "page": 1, "limit": 50, "totalPages": 1 }, "timestamp": "2025-01-15T10:31:50.000Z" } ``` ### Response Fields | Field | Type | Description | | -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `transactions` | array | Transactions on the current page (see [Get Transaction](/api-reference/v1/policy-transactions/get-transaction) for the item shape) | | `total` | number | Total transactions matching the query | | `page` | number | 1-based page number | | `limit` | number | Page size | | `totalPages` | number | Total number of pages | ## Error Scenarios ### Bad Request (400) Returned when `policyId` is malformed or a query parameter is out of range. ```json theme={null} { "statusCode": 400, "errorType": "validation_error", "errorMessage": ["limit must not be greater than 100"], "requestId": "dev-abc123", "timestamp": "2025-01-15T10:30:00.000Z" } ``` ### Parent Policy Not Found (404) Returned when `policyId` does not 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}/transactions 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}/transactions: get: tags: - policies operationId: PoliciesController_listTransactions_v1 parameters: - name: policyId required: true in: path description: Unique identifier of the parent policy schema: example: 6650a1b2c3d4e5f6a7b8c9d0 type: string - name: page required: false in: query description: 1-based page number schema: default: 1 example: 1 type: number - name: limit required: false in: query description: Page size (max 100) schema: default: 50 example: 50 type: number responses: '200': description: Paginated transactions for the policy content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PaginatedPolicyTransactionsResponse' 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 parameters or 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: Parent policy not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponseDto' components: schemas: PaginatedPolicyTransactionsResponse: type: object properties: transactions: description: Transactions on the current page type: array items: $ref: '#/components/schemas/PolicyTransactionResponse' total: type: number description: Total transactions matching the query example: 42 page: type: number description: 1-based page number example: 1 limit: type: number description: Page size example: 50 totalPages: type: number description: Total number of pages example: 1 required: - transactions - total - page - limit - totalPages ErrorResponseDto: type: object properties: statusCode: type: number description: HTTP status code requestId: type: string description: Unique request identifier for debugging errorType: type: string description: >- Machine-readable error classification. Branch on this rather than on `errorMessage`, which is prose and may change. Authentication failures returned by our identity provider are forwarded verbatim, so a 401 can carry a code outside this list; treat an unrecognised value as a generic failure of its HTTP status. enum: - conflict - contact_not_authorized - document_exceeds_page_limit - downstream_entity_member_exists - duplicate_external_id_error - duplicate_member_email - duplicate_producer_code_error - forbidden - gateway_timeout - inactive_email - internal_server_error - invalid_email - invalid_email_for_invites - invalid_organization_category - invalid_organization_slug - invalid_phone_number - invalid_token - invite_limit_reached - jwt_invalid - m2m_client_not_found - not_found - organization_already_exists - organization_slug_already_used - payment_required - producer_agreement_required - product_feature_subscription_required - service_unavailable - session_authorization_error - some_custom_error_string - throttled - too_many_requests - unauthorized - unauthorized_client - unexpected_400_stytch_error - unexpected_403_stytch_error - unexpected_404_stytch_error - unexpected_error - unexpected_stytch_error - unprocessable_entity - validation_error example: validation_error 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 PolicyTransactionResponse: type: object properties: _id: type: string description: Unique transaction identifier example: 6650a1b2c3d4e5f6a7b8c9d0 policyId: type: string description: Parent policy id example: 6650a1b2c3d4e5f6a7b8c9d1 upstreamEntityId: type: string description: Owning upstream entity id example: 6650a1b2c3d4e5f6a7b8c9d0 policyNumber: type: string description: Policy number (inherited from the parent) example: POL-2025-001 policyTransactionType: type: string description: Transaction type example: new enum: - new - renewal - endorsement - cancellation - audit - reinstatement - bound policyTransactionDate: type: string description: Transaction date (ISO 8601) example: '2025-01-15T00:00:00.000Z' riskStateCode: type: string description: US state code where the risk is located example: CA insuredEntityName: type: string description: Name of the insured party example: Example Corp agencyName: type: string description: Agency name example: Premier Insurance Agency carrierName: type: string description: Insurance carrier name example: National Insurance Co effectiveDate: type: string description: Effective date (ISO 8601) example: '2025-01-15T00:00:00.000Z' expiryDate: type: string description: 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 lineOfBusiness: type: string description: Line of business example: Commercial Lines licenseNumber: type: string description: License number example: LIC-001 npn: type: string description: National Producer Number example: '11223344' producerName: type: string description: Producing agent name example: Jon 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 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 uniqueTransactionId: type: string description: Caller-supplied stable dedup id example: ext-txn-001 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 downstreamEntityId: type: string description: Resolved matched downstream entity (agency) id example: 6650a1b2c3d4e5f6a7b8c9d0 upstreamDownstreamAssociationId: type: string description: Resolved agency association id example: 6650a1b2c3d4e5f6a7b8c9d1 entityMatchStatus: type: string description: Agency/entity matching status example: unmatched enum: - auto matched - user confirmed - manual review - unmatched entityMatchConfidence: type: number description: Entity match confidence (0-1) example: 1 matchedAgents: description: Assigned agents type: array items: $ref: '#/components/schemas/PolicyTransactionMatchedAgentResponse' agentMatchStatus: type: string description: Agent matching status example: user confirmed enum: - auto matched - user confirmed - unmatched dedupResult: type: string description: Deduplication result example: new enum: - new - update - unchanged transactionFingerprint: type: string description: Stable identity hash used for duplicate detection example: a1b2c3... columnMappingId: type: string description: Column-mapping sentinel id example: 6650a1b2c3d4e5f6a7b8c9d0 entityId: type: string description: Owner entity id example: 6650a1b2c3d4e5f6a7b8c9d0 entityModel: type: string description: Owner entity model example: UpstreamEntity enum: - UpstreamEntity - DownstreamEntity - EnterpriseUpstreamEntity - EnterpriseDownstreamEntity - Agent - Admin - turris_ops isDeleted: type: boolean description: Soft-delete flag example: false createdAt: type: string description: ISO 8601 timestamp when the transaction 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 - policyId - upstreamEntityId - policyNumber - policyTransactionType - policyTransactionDate - riskStateCode - entityMatchStatus - matchedAgents - agentMatchStatus - transactionFingerprint - columnMappingId - entityId - entityModel - isDeleted - createdAt - updatedAt PolicyTransactionMatchedAgentResponse: type: object properties: agentId: type: string description: Assigned agent id example: 6650a1b2c3d4e5f6a7b8c9d0 matchSource: type: string description: Origin of the agent assignment example: user enum: - ai - user matchConfidence: type: number description: Match confidence (0-1) example: 1 matchedAt: type: string description: ISO 8601 timestamp when the agent was assigned example: '2025-01-15T10:30:00.000Z' required: - agentId - matchSource ```` ## Related topics - [Pagination, Filtering, and Sorting](/guides/pagination.md) - [Create Transaction](/api-reference/v1/policy-transactions/create-transaction.md) - [Delete Transaction](/api-reference/v1/policy-transactions/delete-transaction.md)