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

# Get Transaction

> Retrieve a single transaction by ID

Returns a single transaction by its unique identifier. Both the parent policy and the transaction must belong to the authenticated upstream entity.

## Path Parameters

| Parameter           | Type   | Required | Description                                               |
| ------------------- | ------ | -------- | --------------------------------------------------------- |
| **`policyId`**      | string | Yes      | Unique identifier of the parent policy (MongoDB ObjectId) |
| **`transactionId`** | string | Yes      | Unique identifier of the transaction (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": "6650a1b2c3d4e5f6a7b8c9d1",
    "policyId": "6650a1b2c3d4e5f6a7b8c9d0",
    "policyNumber": "POL-2025-001",
    "policyTransactionType": "new",
    "policyTransactionDate": "2025-01-15T00:00:00.000Z",
    "riskStateCode": "CA",
    "entityMatchStatus": "user confirmed",
    "matchedAgents": [
      {
        "agentId": "6650a1b2c3d4e5f6a7b8c9d2",
        "matchSource": "user",
        "matchConfidence": 1,
        "matchedAt": "2025-01-15T10:30:00.000Z"
      }
    ],
    "agentMatchStatus": "user confirmed",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:31:45.000Z"
  },
  "timestamp": "2025-01-15T10:31:50.000Z"
}
```

## Error Scenarios

### Bad Request (400)

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

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

### Transaction Not Found (404)

Returned when the transaction does not exist under the policy, or belongs to a different upstream entity.

```json theme={null}
{
  "statusCode": 404,
  "errorType": "not_found",
  "errorMessage": ["Transaction 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/v2.json GET /v2/upstream/policies/{policyId}/transactions/{transactionId}
openapi: 3.0.0
info:
  title: Turris Public API
  description: API for managing insurance compliance data
  version: 2.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:
  /v2/upstream/policies/{policyId}/transactions/{transactionId}:
    get:
      tags:
        - upstream/policies
      operationId: PoliciesV2Controller_getTransaction_v2
      parameters:
        - name: policyId
          required: true
          in: path
          description: Unique identifier of the parent policy
          schema:
            example: 6650a1b2c3d4e5f6a7b8c9d0
            type: string
        - name: transactionId
          required: true
          in: path
          description: Unique identifier of the transaction
          schema:
            example: 6650a1b2c3d4e5f6a7b8c9d1
            type: string
      responses:
        '200':
          description: Transaction details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PolicyTransactionResponse'
                  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 path parameter 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: Transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
components:
  schemas:
    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
    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
    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

- [Update Transaction](/api-reference/v2/policy-transactions/update-transaction.md)
- [List Transactions](/api-reference/v2/policy-transactions/list-transactions.md)
- [Create Transaction](/api-reference/v2/policy-transactions/create-transaction.md)