Create Policy
Create a single policy declaratively
policyNumber and riskStateCode are required. Everything else is optional and can be added later with Update Policy.
currentStatus values (bound, active, expired, cancelled, non renewed) are all lifecycle states after binding, so there is no quote or pre-bind state. policyNumber is required because it is the grouping key that ties transactions together, not because Turris re-checks that the policy is bound.Descriptive fields and association ids
Most fields on this endpoint are descriptive: the raw values your system already holds, stored verbatim on the policy record. Two fields are different.downstreamEntityAssociationId and productId are association ids, meaning Turris record ids that create a hard link between the policy and an entity you already have in Turris.
The distinction matters because compliance work runs on the links, not on the strings. Turris can only check whether an agency was licensed and appointed in the risk state on the effective date once the policy is linked to a specific downstream entity association. An agency name on its own is text.
You can supply either kind, or both. They do different jobs.
Identifying the agency
downstreamEntityAssociationId from List Associations. It resolves internally to the downstream entity and the upstream/downstream association pair.
Send the id when you have it. It is exact, immediate, and immune to spelling drift. If your system stores a Turris association id against each agency, send it on every create.
Send the descriptive fields when you do not. A policy created without an association id is stored with entityMatchStatus = unmatched, and a later matching run resolves it against your downstream entity roster in this order:
- A previously confirmed mapping for that normalized agency name
producerCodeagencyNpn, then the genericnpnagencyFeinagencyLicenseNumbercombined withagencyLicensedStateCode- Exact agency name against legal name or DBA
- Normalized agency name, ignoring suffixes such as Inc, LLC, Ltd, Corp
Identifying the product
The same split applies.productId from List Products. If your upstream entity has exactly one product, matching assigns it automatically after the agency match and no product matching is needed.
Carrier and agent fields
carrierName, agentName, agentNpn, agentLicenseNumber, agentLicensedState, producerName, lineOfBusiness, insuredEntityName, filingNumber, slaNumber and externalBillingId are all descriptive. There is no carrier association id on this endpoint. Agent fields feed agent matching during a matching run but are never required at create time.
Creating a policy before you have every detail
No descriptive field is required, so a partial create is a supported flow rather than a workaround. A common pattern is to create the policy as soon as the policy number and risk state are known, then PATCH in premium, coverage limits, product and agency details as they land. GetpolicyNumber and riskStateCode right at create time. They are the two required fields, and they are also the two Update Policy does not accept, so neither can be changed afterwards. createInitialTransaction is likewise create-only; attach later transactions with Create Transaction instead.
Every other field on this endpoint can be set later through PATCH, and passing null for an association id clears it and resets that match status to unmatched.
currentStatus defaults to bound and is recomputed from transactions once any are attached. See Create Transaction.Creating the initial transaction
By default the policy is created transaction-less (transactionCount = 0). Set createInitialTransaction to true to atomically create the policy’s first transaction alongside it in one operation. The transaction is inferred, not supplied:
true, transactionCount becomes 1, latestTransactionId points at the new transaction, and currentStatus is derived from that transaction rather than the request body. Both writes commit together; either one failing rolls back the whole request. Defaults to false when omitted, leaving the create behavior unchanged.
Response Shape
Error Scenarios
Bad Request (400)
Returned when the body fails validation (missingpolicyNumber or riskStateCode, invalid enum value, or malformed association id).
Association Not Found (404)
Returned when a suppliedproductId or downstreamEntityAssociationId does not exist for your upstream entity.
Duplicate Policy (409)
Returned when a policy with the samepolicyNumber already exists for your upstream entity.
Unauthorized (401)
Missing or invalid authentication token. See Authentication.Idempotency
This endpoint supports idempotency. If you include anidempotency-key header, duplicate requests within 1 hour return the original response without creating a second policy. See Idempotency.Headers
UUID to ensure idempotent request processing
"550e8400-e29b-41d4-a716-446655440000"
Alternative UUID header for idempotent request processing
"550e8400-e29b-41d4-a716-446655440000"
Body
Policy number that groups transactions into a single policy
"POL-2025-001"
US state code where the risk is located
"CA"
Initial lifecycle status. Recomputed from transactions once any are attached; defaults to "bound".
bound, active, expired, cancelled, non renewed "bound"
Name of the insured party
"Example Corp"
Agency name as your system holds it. Stored verbatim and used as the primary matching signal when downstreamEntityAssociationId is not supplied. Send both when you have the association id: the id creates the link, this field stays the human-readable label.
"Premier Insurance Agency"
Insurance carrier name
"National Insurance Co"
Policy effective date (ISO 8601)
"2025-01-15T00:00:00.000Z"
Policy expiration date (ISO 8601)
"2026-01-15T00:00:00.000Z"
Premium amount in USD
5000
Aggregate coverage limit in USD
1000000
Per-claim coverage limit in USD
500000
Line of business
"Commercial Lines"
License number
"LIC-001"
National Producer Number
"11223344"
Producing agent name
"Jon Doe"
Producer identifier code
"PROD-001"
Product name as your system holds it. Stored verbatim and used as a matching signal against your product catalogue when productId is not supplied.
"General Liability"
Product code
"GL-100"
Filing number
"FIL-2025-001"
SLA number
"SLA-2025-001"
External billing identifier
"BILL-2025-001"
Agency National Producer Number
"12345678"
Agency Federal Employer Identification Number
"12-3456789"
Agency state license number
"ABC-123456"
State where the agency license was issued
"CA"
Individual agent name
"John Smith"
Agent National Producer Number
"87654321"
Agent state license number
"LIC-789012"
State where the agent license was issued
"TX"
Product association. Stamps productMatchStatus = "user confirmed" when supplied.
"6650a1b2c3d4e5f6a7b8c9d0"
Agency association - the downstreamEntityAssociationId from GET /downstream-entity-associations. Resolved to upstreamDownstreamAssociationId + downstreamEntityId; stamps entityMatchStatus = "user confirmed".
"6650a1b2c3d4e5f6a7b8c9d0"
When true, atomically create the policy first transaction alongside the policy. The initial transaction is inferred as type "new", dated effectiveDate (or today when absent), and inherits the policy descriptive and confirmed-agency fields. transactionCount becomes 1 and currentStatus is derived from that transaction. Defaults to false.
true