Policies - Turris Public API

cURL

curl --request GET \
  --url https://public.api.live.turrisfi.com/v1/policies

{
  "data": [
    {
      "_id": "6650a1b2c3d4e5f6a7b8c9d0",
      "policyNumber": "POL-2025-001",
      "currentStatus": "active",
      "riskStateCode": "CA",
      "entityMatchStatus": "auto matched",
      "productMatchStatus": "unmatched",
      "transactionCount": 3,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:31:45.000Z",
      "insuredEntityName": "Acme Corp",
      "agencyName": "Premier Insurance Agency",
      "agencyNpn": "12345678",
      "agencyFein": "12-3456789",
      "agencyLicenseNumber": "ABC-123456",
      "agencyLicensedStateCode": "CA",
      "agentName": "John Smith",
      "agentNpn": "87654321",
      "agentLicenseNumber": "LIC-789012",
      "agentLicensedState": "TX",
      "carrierName": "National Insurance Co",
      "lineOfBusiness": "Commercial Lines",
      "producerName": "Jane Doe",
      "producerCode": "PROD-001",
      "productName": "General Liability",
      "productCode": "GL-100",
      "effectiveDate": "2025-01-15T00:00:00.000Z",
      "expiryDate": "2026-01-15T00:00:00.000Z",
      "premiumAmountInUSD": 5000,
      "aggregateCoverageInUSD": 1000000,
      "coveragePerClaimInUSD": 500000,
      "filingNumber": "FIL-2025-001",
      "slaNumber": "SLA-2025-001",
      "externalBillingId": "BILL-2025-001",
      "licenseNumber": "LIC-001",
      "npn": "11223344"
    }
  ],
  "requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
  "timestamp": "2025-11-12T20:49:03.293Z"
}

GET

policies

cURL

curl --request GET \
  --url https://public.api.live.turrisfi.com/v1/policies

{
  "data": [
    {
      "_id": "6650a1b2c3d4e5f6a7b8c9d0",
      "policyNumber": "POL-2025-001",
      "currentStatus": "active",
      "riskStateCode": "CA",
      "entityMatchStatus": "auto matched",
      "productMatchStatus": "unmatched",
      "transactionCount": 3,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:31:45.000Z",
      "insuredEntityName": "Acme Corp",
      "agencyName": "Premier Insurance Agency",
      "agencyNpn": "12345678",
      "agencyFein": "12-3456789",
      "agencyLicenseNumber": "ABC-123456",
      "agencyLicensedStateCode": "CA",
      "agentName": "John Smith",
      "agentNpn": "87654321",
      "agentLicenseNumber": "LIC-789012",
      "agentLicensedState": "TX",
      "carrierName": "National Insurance Co",
      "lineOfBusiness": "Commercial Lines",
      "producerName": "Jane Doe",
      "producerCode": "PROD-001",
      "productName": "General Liability",
      "productCode": "GL-100",
      "effectiveDate": "2025-01-15T00:00:00.000Z",
      "expiryDate": "2026-01-15T00:00:00.000Z",
      "premiumAmountInUSD": 5000,
      "aggregateCoverageInUSD": 1000000,
      "coveragePerClaimInUSD": 500000,
      "filingNumber": "FIL-2025-001",
      "slaNumber": "SLA-2025-001",
      "externalBillingId": "BILL-2025-001",
      "licenseNumber": "LIC-001",
      "npn": "11223344"
    }
  ],
  "requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
  "timestamp": "2025-11-12T20:49:03.293Z"
}

Returns all policies associated with your upstream entity. Soft-deleted policies are excluded automatically. Results can be filtered by policy number, status, or risk state.

Query Parameters

Parameter	Type	Required	Description
`policyNumber`	string	No	Filter by exact policy number (e.g., `POL-2025-001`)
`currentStatus`	string	No	Filter by policy status: `bound`, `active`, `expired`, `cancelled`, or `non renewed`
`riskStateCode`	string	No	Filter by US state code (e.g., `CA`, `TX`, `NY`)

Filtering Examples

# By status
GET /v1/policies?currentStatus=active

# By state
GET /v1/policies?riskStateCode=CA

# Combined filters
GET /v1/policies?currentStatus=active&riskStateCode=TX

# By exact policy number
GET /v1/policies?policyNumber=POL-2025-001

Response Shape

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

{
  "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",
      "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

Core Fields

Field	Type	Description
`_id`	string	Unique policy identifier
`policyNumber`	string	Policy number that groups transactions into a single policy
`currentStatus`	string	Current policy status: `bound`, `active`, `expired`, `cancelled`, or `non renewed`
`riskStateCode`	string	US state code where the risk is located

Agency & Agent Fields

Field	Type	Description
`agencyName`	string?	Agency name
`agencyNpn`	string?	Agency National Producer Number
`agencyFein`	string?	Agency Federal Employer Identification Number
`agencyLicenseNumber`	string?	Agency state license number
`agencyLicensedStateCode`	string?	State where the agency license was issued
`agentName`	string?	Individual agent name
`agentNpn`	string?	Agent National Producer Number
`agentLicenseNumber`	string?	Agent state license number
`agentLicensedState`	string?	State where the agent license was issued

Insurance Details

Field	Type	Description
`insuredEntityName`	string?	Name of the insured party
`carrierName`	string?	Insurance carrier name
`lineOfBusiness`	string?	Line of business
`producerName`	string?	Producing agent name
`producerCode`	string?	Producer identifier code
`productName`	string?	Product name
`productCode`	string?	Product code

Dates & Coverage

Field	Type	Description
`effectiveDate`	string?	Policy effective date (ISO 8601)
`expiryDate`	string?	Policy expiration date (ISO 8601)
`premiumAmountInUSD`	number?	Premium amount in USD
`aggregateCoverageInUSD`	number?	Aggregate coverage limit in USD
`coveragePerClaimInUSD`	number?	Per-claim coverage limit in USD

Matching & Metadata

Field	Type	Description
`entityMatchStatus`	string	Agency/entity matching status (see table below)
`productMatchStatus`	string	Product matching status (see table below)
`transactionCount`	number	Number of transactions linked to this policy
`filingNumber`	string?	Filing number
`slaNumber`	string?	SLA number
`externalBillingId`	string?	External billing identifier
`licenseNumber`	string?	License number
`npn`	string?	National Producer Number
`createdAt`	string	ISO 8601 timestamp when the policy was created
`updatedAt`	string	ISO 8601 timestamp of the last update

Matching Status Values

Field	Values	Meaning
`entityMatchStatus`	`unmatched`, `auto matched`, `user confirmed`, `manual review`	Whether the policy has been linked to a downstream entity
`productMatchStatus`	`unmatched`, `auto matched`, `user confirmed`, `needs clarification`	Whether the policy has been linked to a product

Policies with entityMatchStatus of "unmatched" or "manual review" require attention in the Turris dashboard.

Error Scenarios

Bad Request (400)

Returned when a query parameter has an invalid value (e.g., an unsupported currentStatus).

{
  "statusCode": 400,
  "errorType": "validation_error",
  "errorMessage": ["Invalid value for currentStatus"],
  "requestId": "dev-abc123",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Unauthorized (401)

Missing or invalid authentication token. See Authentication.

Query Parameters

policyNumber

string

Filter by exact policy number

Example:

"POL-2025-001"

currentStatus

enum<string>

Filter by current policy status

Available options:

bound,

active,

expired,

cancelled,

non renewed

Example:

"active"

riskStateCode

string

Filter by US state code where risk is located

Example:

"CA"

Response

List of policies belonging to the authenticated upstream entity

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"

Policy Get E&O/Cyber Compliance

⌘I

​Query Parameters

​Filtering Examples

​Response Shape

​Response Fields

​Core Fields

​Agency & Agent Fields

​Insurance Details

​Dates & Coverage

​Matching & Metadata

​Matching Status Values

​Error Scenarios

​Bad Request (400)

​Unauthorized (401)

Query Parameters

Response

Query Parameters

Filtering Examples

Response Shape

Response Fields

Core Fields

Agency & Agent Fields

Insurance Details

Dates & Coverage

Matching & Metadata

Matching Status Values

Error Scenarios

Bad Request (400)

Unauthorized (401)