Policies

cURL

curl --request GET \
  --url https://public.api.live.turrisfi.com/v2/upstream/policies \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://public.api.live.turrisfi.com/v2/upstream/policies', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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": "Example 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": "Jon 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",
      "uploadSource": "upstream entity"
    }
  ],
  "requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
  "timestamp": "2025-11-12T20:49:03.293Z"
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

GET

upstream

policies

cURL

curl --request GET \
  --url https://public.api.live.turrisfi.com/v2/upstream/policies \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://public.api.live.turrisfi.com/v2/upstream/policies', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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": "Example 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": "Jon 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",
      "uploadSource": "upstream entity"
    }
  ],
  "requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
  "timestamp": "2025-11-12T20:49:03.293Z"
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

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 /v2/upstream/policies?currentStatus=active

# By state
GET /v2/upstream/policies?riskStateCode=CA

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

# By exact policy number
GET /v2/upstream/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": "Example 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.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

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"

Start Here

Shared Endpoints

Products

Carriers

Agencies You Appoint

Contract Container Templates

Agents

Contacts

Market Contacts

Licenses

Appointments

Compliance Data Subscriptions

Compliance Status

File Documents

Policy Ingestion

Policy Transactions

Surplus Lines Filings

Diligent Effort

Webhooks

E&O/Cyber Compliance

Regulatory Actions

Tools

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)

Authorizations

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)

Authorizations

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)