> ## 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.
# Update Policy
> Partially update a policy by ID
Updates an existing policy. Every field is optional and only supplied fields change. The policy must belong to the authenticated upstream entity.
## Path Parameters
| Parameter | Type | Required | Description |
| -------------- | ------ | -------- | -------------------------------------------------- |
| **`policyId`** | string | Yes | Unique identifier of the policy (MongoDB ObjectId) |
## Association Fields Are Set-or-Clear
| Value | Effect |
| ------ | -------------------------------------------------------------------------------- |
| An id | Links the association and stamps the corresponding match status `user confirmed` |
| `null` | Clears the association and resets the corresponding match status to `unmatched` |
`productId` and `downstreamEntityAssociationId` follow this rule. Omitting a field leaves the existing association untouched.
## Response Shape
All successful responses are wrapped in the standard response envelope. See [Request/Response Conventions](/guides/request-response).
The response is the full policy object, identical in shape to [Create Policy](/api-reference/v1/policies/create-policy).
## Error Scenarios
### Bad Request (400)
Returned when `policyId` is malformed or the body fails validation.
```json theme={null}
{
"statusCode": 400,
"errorType": "validation_error",
"errorMessage": ["policyId must be a mongodb id"],
"requestId": "dev-abc123",
"timestamp": "2025-01-15T10:30:00.000Z"
}
```
### Not Found (404)
Returned when the policy, or a supplied `productId` or `downstreamEntityAssociationId`, does not exist for your upstream entity.
```json theme={null}
{
"statusCode": 404,
"errorType": "not_found",
"errorMessage": ["Policy 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 PATCH /v1/policies/{policyId}
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/{policyId}:
patch:
tags:
- policies
operationId: PoliciesController_updatePolicy_v1
parameters:
- name: policyId
required: true
in: path
description: Unique identifier of the policy
schema:
example: 6650a1b2c3d4e5f6a7b8c9d0
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePolicyDto'
responses:
'200':
description: Updated policy
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/PolicyApiResponse'
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 request body or policyId 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: Policy, product, or agency association not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
components:
schemas:
UpdatePolicyDto:
type: object
properties:
currentStatus:
type: string
description: Lifecycle status override
example: active
enum:
- bound
- active
- expired
- cancelled
- non renewed
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: Policy effective date (ISO 8601)
example: '2025-01-15T00:00:00.000Z'
expiryDate:
type: string
description: Policy 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
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
productId:
type: string
description: >-
Product association. Pass an id to (re)link, or null to clear the
product match.
example: 6650a1b2c3d4e5f6a7b8c9d0
nullable: true
downstreamEntityAssociationId:
type: string
description: >-
Agency association (downstreamEntityAssociationId from GET
/downstream-entity-associations). Pass an id to (re)link, or null to
clear the agency match.
example: 6650a1b2c3d4e5f6a7b8c9d0
nullable: true
PolicyApiResponse:
type: object
properties:
_id:
type: string
description: Unique policy identifier
example: 6650a1b2c3d4e5f6a7b8c9d0
upstreamEntityId:
type: string
description: Owning upstream entity id
example: 6650a1b2c3d4e5f6a7b8c9d0
policyNumber:
type: string
description: Policy number
example: POL-2025-001
currentStatus:
type: string
description: Current lifecycle status
example: bound
enum:
- bound
- active
- expired
- cancelled
- non renewed
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: Policy effective date (ISO 8601)
example: '2025-01-15T00:00:00.000Z'
expiryDate:
type: string
description: Policy 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
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
riskStateCode:
type: string
description: US state code where the risk is located
example: CA
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: user confirmed
enum:
- auto matched
- user confirmed
- manual review
- unmatched
entityMatchConfidence:
type: number
description: Entity match confidence (0-1)
example: 1
productId:
type: string
description: Matched product id
example: 6650a1b2c3d4e5f6a7b8c9d0
productMatchStatus:
type: string
description: Product matching status
example: unmatched
enum:
- auto matched
- user confirmed
- needs clarification
- unmatched
productMatchConfidence:
type: number
description: Product match confidence (0-1)
example: 1
matchedDownstreamEntities:
description: Confirmed matched downstream entities
type: array
items:
$ref: '#/components/schemas/PolicyMatchedDownstreamEntityResponse'
latestTransactionId:
type: string
description: Id of the most recent transaction
example: 6650a1b2c3d4e5f6a7b8c9d0
transactionCount:
type: number
description: Number of transactions linked to this policy
example: 3
uploadSource:
type: string
description: Origin channel of the policy
example: public api
enum:
- upstream entity
- enterprise
- public api
- downstream entity
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 policy 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
- upstreamEntityId
- policyNumber
- currentStatus
- riskStateCode
- entityMatchStatus
- productMatchStatus
- matchedDownstreamEntities
- transactionCount
- 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
PolicyMatchedDownstreamEntityResponse:
type: object
properties:
downstreamEntityId:
type: string
description: Matched downstream entity (agency) id
example: 6650a1b2c3d4e5f6a7b8c9d0
upstreamDownstreamAssociationId:
type: string
description: Upstream-downstream association id backing the match
example: 6650a1b2c3d4e5f6a7b8c9d1
matchSource:
type: string
description: Origin of the match
example: user
enum:
- ai
- user
matchConfidence:
type: number
description: Match confidence (0-1)
example: 1
matchedAt:
type: string
description: ISO 8601 timestamp when the match was recorded
example: '2025-01-15T10:30:00.000Z'
required:
- downstreamEntityId
- upstreamDownstreamAssociationId
- matchSource
````
## Related topics
- [Create Policy](/api-reference/v1/policies/create-policy.md)
- [Update Transaction](/api-reference/v1/policy-transactions/update-transaction.md)
- [Policies](/api-reference/v1/policies/list-policies.md)