> ## 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.
# Uploading Status
> Check the processing status of a file upload
Poll this endpoint to track the progress of a file upload initiated via [Upload Policy File](/api-reference/v1/policies/upload-policy-file). Returns the current processing status, record counts, and any errors encountered during ingestion.
## Polling Strategy
**Recommended interval:** Poll every **3-5 seconds** while `status` is `QUEUED` or `PROCESSING`. Stop polling once the status reaches a terminal state (`COMPLETED`, `COMPLETED_WITH_FAILURES`, `FAILED`, or `CANCELLED`) or a paused state (`NEEDS_CLARIFICATION`).
Upload received, waiting for a worker to pick it up.
Worker is actively parsing the file and creating policies and transactions.
Processing ends with one of: `COMPLETED`, `COMPLETED_WITH_FAILURES`, `FAILED`, or `CANCELLED`. The status `NEEDS_CLARIFICATION` means processing is paused awaiting user input. Stop polling and inspect the response.
## Status Values
| Status | Terminal? | Description |
| ------------------------- | --------- | ---------------------------------------------------------------------- |
| `QUEUED` | No | Upload received, waiting for a worker to pick it up |
| `PROCESSING` | No | Worker is actively parsing the file and creating policies/transactions |
| `COMPLETED` | Yes | All rows processed successfully |
| `COMPLETED_WITH_FAILURES` | Yes | Processing finished but some rows failed — check `errors` array |
| `NEEDS_CLARIFICATION` | No | Processing paused — AI matching requires user input to continue |
| `FAILED` | Yes | Processing failed entirely |
| `CANCELLED` | Yes | Processing was cancelled |
## 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": {
"uploadId": "6650a1b2c3d4e5f6a7b8c9d0",
"status": "COMPLETED",
"totalRows": 1000,
"created": 851,
"updated": 149,
"failed": 0,
"errors": [],
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:31:45.000Z"
},
"timestamp": "2025-01-15T10:31:50.000Z"
}
```
### Response Fields
| Field | Type | Description |
| ----------- | ------ | ------------------------------------------------------------------------- |
| `uploadId` | string | The upload request ID |
| `status` | string | Current processing status (see table above) |
| `totalRows` | number | Total number of data rows in the uploaded file |
| `created` | number | Number of new policies created |
| `updated` | number | Number of existing policies updated (duplicate `policyNumber` re-uploads) |
| `failed` | number | Number of rows that failed processing |
| `errors` | array | Details about individual row failures (see below) |
| `createdAt` | string | ISO 8601 timestamp when the upload was initiated |
| `updatedAt` | string | ISO 8601 timestamp of the last status update |
### Error Object
Each entry in the `errors` array describes a single row failure:
| Field | Type | Description |
| -------------- | ------- | ------------------------------------------------ |
| `index` | number | Zero-based index of the failed row |
| `policyNumber` | string? | Policy number from the failed row (if available) |
| `error` | string | Human-readable error message |
## Example Responses
### In Progress
```json theme={null}
{
"statusCode": 200,
"data": {
"uploadId": "6650a1b2c3d4e5f6a7b8c9d0",
"status": "PROCESSING",
"totalRows": 1000,
"created": 342,
"updated": 58,
"failed": 0,
"errors": [],
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:45.000Z"
}
}
```
### Completed With Failures
```json theme={null}
{
"statusCode": 200,
"data": {
"uploadId": "6650a1b2c3d4e5f6a7b8c9d0",
"status": "COMPLETED_WITH_FAILURES",
"totalRows": 1000,
"created": 845,
"updated": 147,
"failed": 8,
"errors": [
{
"index": 0,
"policyNumber": "POL-2025-001",
"error": "Missing required field: riskStateCode"
},
{
"index": 47,
"policyNumber": "POL-2025-048",
"error": "Invalid date format for policyTransactionDate"
}
],
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:31:45.000Z"
}
}
```
## Error Scenarios
### Upload Not Found (404)
Returned when `uploadId` doesn't exist or belongs to a different upstream entity.
```json theme={null}
{
"statusCode": 404,
"errorType": "not_found",
"errorMessage": ["Upload 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/uploads/{uploadId}
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/uploads/{uploadId}:
get:
tags:
- policies
operationId: PoliciesController_getUploadStatus_v1
parameters:
- name: uploadId
required: true
in: path
description: ID of the upload request returned by POST /policies/upload
schema:
example: 6650a1b2c3d4e5f6a7b8c9d0
type: string
responses:
'200':
description: Upload processing status with record counts and errors
content:
application/json:
schema:
$ref: '#/components/schemas/PolicyUploadStatusResponse'
'400':
description: Invalid uploadId 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: Upload not found or belongs to a different upstream entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
components:
schemas:
PolicyUploadStatusResponse:
type: object
properties:
uploadId:
type: string
description: ID of the upload request
example: 6650a1b2c3d4e5f6a7b8c9d0
status:
type: string
description: Current processing status
example: COMPLETED
enum:
- QUEUED
- PROCESSING
- COMPLETED
- COMPLETED_WITH_FAILURES
- NEEDS_CLARIFICATION
- CANCELLED
- FAILED
totalRows:
type: number
description: Total number of data rows in the uploaded file
example: 1000
created:
type: number
description: Number of new policies created
example: 851
updated:
type: number
description: >-
Number of existing policies updated (duplicate policyNumber
re-uploads)
example: 149
failed:
type: number
description: Number of rows that failed processing
example: 0
errors:
description: Details about individual row failures
type: array
items:
$ref: '#/components/schemas/BatchPolicyIngestionErrorResponse'
createdAt:
type: string
description: ISO 8601 timestamp when the upload was initiated
example: '2025-01-15T10:30:00.000Z'
updatedAt:
type: string
description: ISO 8601 timestamp of the last status update
example: '2025-01-15T10:31:45.000Z'
required:
- uploadId
- status
- totalRows
- created
- updated
- failed
- errors
- 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
BatchPolicyIngestionErrorResponse:
type: object
properties:
index:
type: number
description: Zero-based index of the failed row in the uploaded file
example: 47
policyNumber:
type: string
description: Policy number from the failed row (if available)
example: POL-2025-001
error:
type: string
description: Human-readable error message
example: 'Missing required field: riskStateCode'
required:
- index
- error
````