Upload Policy File - Turris Public API

Upload a policy data file for asynchronous processing. The file headers are validated synchronously — if validation passes, the file is uploaded to storage and a worker job is queued for ingestion. Returns an uploadId that you can poll via Get Upload Status.

Workflow

Upload your file

Send a POST /v1/policies/upload request with your CSV or Excel file as multipart/form-data. The response includes an uploadId with status QUEUED.

Poll for status

Call GET /v1/policies/uploads/{uploadId} every 3-5 seconds. The status will move from QUEUED to PROCESSING as a worker picks up the file.

Handle the result

Stop polling once the status reaches a terminal state: COMPLETED, COMPLETED_WITH_FAILURES, or FAILED. Check the errors array for any row-level failures. Once complete, retrieve your policies via List Policies or Get Policy.

File Requirements

Constraint	Value
Formats	CSV (`.csv`), Excel (`.xlsx`)
Max size	10 MB
Content-Type	`multipart/form-data`
Form field name	`file`

Column Headers

Column headers in your file must exactly match the supported field names listed below. Unrecognized headers are rejected immediately with a 400 response.

Required Columns

These columns must be present in every upload:

Column Header	Description
`policyNumber`	Unique identifier that groups transactions into a single policy
`riskStateCode`	US state code (e.g., `CA`, `TX`, `NY`)
`policyTransactionType`	Transaction lifecycle stage: `New`, `Renewal`, `Endorsement`, `Cancellation`, or `Audit`
`policyTransactionDate`	Date the transaction was processed (e.g., `2025-01-15` or `01/15/2025`)

Agency Identifier (at least one required)

At least one of these columns must be present for entity matching:

Column Header	Description
`agencyName`	Name of the agency — used for AI-powered matching
`agencyNpn`	National Producer Number — most reliable identifier
`agencyFein`	Federal Employer Identification Number

Optional Columns

Column Header	Description
`agencyLicenseNumber`	State insurance license number of the agency
`agencyLicensedStateCode`	State where the agency license was issued
`agentName`	Name of the individual agent
`agentNpn`	NPN of the individual agent
`agentLicenseNumber`	State license number of the agent
`agentLicensedState`	State where the agent license was issued
`insuredEntityName`	Name of the insured party
`carrierName`	Insurance carrier name
`lineOfBusiness`	Line of business (e.g., `Commercial Lines`, `Property & Casualty`)
`productName`	Product name for product matching
`productCode`	Product code (alternative to product name)
`producerName`	Producing agent name
`producerCode`	Producer identifier code
`effectiveDate`	Policy effective date
`expiryDate`	Policy expiration date
`premiumAmountInUSD`	Premium amount in USD
`aggregateCoverageInUSD`	Aggregate coverage limit
`coveragePerClaimInUSD`	Per-claim coverage limit
`filingNumber`	Filing number
`slaNumber`	SLA number
`externalBillingId`	External billing identifier from the upstream entity billing system
`licenseNumber`	License number
`npn`	NPN
`upstreamEntityName`	Upstream entity name

Success Response

All successful responses are wrapped in the standard response envelope. See Request/Response Conventions.

{
  "statusCode": 201,
  "data": {
    "uploadId": "6650a1b2c3d4e5f6a7b8c9d0",
    "status": "QUEUED"
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Field	Type	Description
`uploadId`	string	MongoDB ObjectId — use this to poll Get Upload Status
`status`	string	Always `QUEUED` on successful upload

Error Scenarios

Unsupported File Format (400)

Returned when the file is not CSV or XLSX.

{
  "statusCode": 400,
  "errorType": "validation_error",
  "errorMessage": ["Only CSV and XLSX files are allowed"],
  "requestId": "dev-abc123",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Unsupported Column Headers (400)

Returned when any column header doesn’t match a supported field name.

{
  "statusCode": 400,
  "errorType": "validation_error",
  "errorMessage": [
    "Unsupported column headers. Column headers must exactly match the supported field names."
  ],
  "details": {
    "supportedFields": [
      "policyNumber", "riskStateCode", "policyTransactionType", "policyTransactionDate",
      "insuredEntityName", "carrierName", "effectiveDate", "expiryDate",
      "premiumAmountInUSD", "aggregateCoverageInUSD", "coveragePerClaimInUSD",
      "lineOfBusiness", "licenseNumber", "npn", "producerName", "producerCode",
      "productName", "productCode", "filingNumber", "slaNumber", "externalBillingId", "upstreamEntityName",
      "agencyName", "agencyNpn", "agencyFein", "agencyLicenseNumber",
      "agencyLicensedStateCode", "agentName", "agentNpn", "agentLicenseNumber",
      "agentLicensedState"
    ]
  },
  "requestId": "dev-abc123",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Missing Required Columns (400)

Returned when one or more required columns are absent.

{
  "statusCode": 400,
  "errorType": "validation_error",
  "errorMessage": ["Missing required columns: riskStateCode, policyTransactionDate"],
  "details": {
    "supportedFields": [
      "policyNumber", "riskStateCode", "policyTransactionType", "policyTransactionDate",
      "insuredEntityName", "carrierName", "effectiveDate", "expiryDate",
      "premiumAmountInUSD", "aggregateCoverageInUSD", "coveragePerClaimInUSD",
      "lineOfBusiness", "licenseNumber", "npn", "producerName", "producerCode",
      "productName", "productCode", "filingNumber", "slaNumber", "externalBillingId", "upstreamEntityName",
      "agencyName", "agencyNpn", "agencyFein", "agencyLicenseNumber",
      "agencyLicensedStateCode", "agentName", "agentNpn", "agentLicenseNumber",
      "agentLicensedState"
    ]
  },
  "requestId": "dev-abc123",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Missing Agency Identifier (400)

Returned when none of agencyName, agencyNpn, or agencyFein columns are present.

{
  "statusCode": 400,
  "errorType": "validation_error",
  "errorMessage": [
    "At least one agency identifier column is required: agencyName, agencyNpn, agencyFein"
  ],
  "details": {
    "supportedFields": [
      "policyNumber", "riskStateCode", "policyTransactionType", "policyTransactionDate",
      "insuredEntityName", "carrierName", "effectiveDate", "expiryDate",
      "premiumAmountInUSD", "aggregateCoverageInUSD", "coveragePerClaimInUSD",
      "lineOfBusiness", "licenseNumber", "npn", "producerName", "producerCode",
      "productName", "productCode", "filingNumber", "slaNumber", "externalBillingId", "upstreamEntityName",
      "agencyName", "agencyNpn", "agencyFein", "agencyLicenseNumber",
      "agencyLicensedStateCode", "agentName", "agentNpn", "agentLicenseNumber",
      "agentLicensedState"
    ]
  },
  "requestId": "dev-abc123",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

No File Uploaded (400)

{
  "statusCode": 400,
  "errorType": "validation_error",
  "errorMessage": ["No file uploaded"],
  "requestId": "dev-abc123",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

File Too Large (413)

Files exceeding 10 MB are rejected by the server before reaching the handler.

Unauthorized (401)

Missing or invalid authentication token. See Authentication.

Idempotency

This endpoint supports idempotency. If you include an idempotency-key header, duplicate requests within 1 hour return the original response without reprocessing. See Idempotency.

Multi-Transaction Policies

Multiple rows sharing the same policyNumber are grouped into a single policy with multiple transactions. For example, a CSV with:

policyNumber	policyTransactionType	policyTransactionDate
POL-001	New	2025-01-15
POL-001	Endorsement	2025-03-20
POL-001	Renewal	2025-06-01

Creates 1 policy with 3 transactions. The policy’s currentStatus is automatically resolved from its transaction history.

Headers

idempotency-key

string

UUID to ensure idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

x-idempotency-key

string

Alternative UUID header for idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

multipart/form-data

file

required

Response

File upload initiated — returns uploadId for polling status

data

object

required

Show child attributes

requestId

string

required

Unique request identifier

Example:

"dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8"

timestamp

string

required

Response timestamp

Example:

"2025-11-12T20:49:03.293Z"

​Workflow

​File Requirements

​Column Headers

​Required Columns

​Agency Identifier (at least one required)

​Optional Columns

​Success Response

​Error Scenarios

​Unsupported File Format (400)

​Unsupported Column Headers (400)

​Missing Required Columns (400)

​Missing Agency Identifier (400)

​No File Uploaded (400)

​File Too Large (413)

​Unauthorized (401)

​Idempotency

​Multi-Transaction Policies

Headers

Body

Response

Workflow

File Requirements

Column Headers

Required Columns

Agency Identifier (at least one required)

Optional Columns

Success Response

Error Scenarios

Unsupported File Format (400)

Unsupported Column Headers (400)

Missing Required Columns (400)

Missing Agency Identifier (400)

No File Uploaded (400)

File Too Large (413)

Unauthorized (401)

Idempotency

Multi-Transaction Policies