curl --request POST \
--url https://public.api.live.turrisfi.com/v2/upstream/policies/{policyId}/transactions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"policyTransactionDate": "2025-01-15T00:00:00.000Z",
"riskStateCode": "CA",
"policyTransactionType": "new",
"uniqueTransactionId": "ext-txn-001",
"insuredEntityName": "Example Corp",
"agencyName": "Premier Insurance Agency",
"carrierName": "National Insurance Co",
"effectiveDate": "2025-01-15T00:00:00.000Z",
"expiryDate": "2026-01-15T00:00:00.000Z",
"premiumAmountInUSD": 5000,
"aggregateCoverageInUSD": 1000000,
"coveragePerClaimInUSD": 500000,
"lineOfBusiness": "Commercial Lines",
"licenseNumber": "LIC-001",
"npn": "11223344",
"producerName": "Jon Doe",
"producerCode": "PROD-001",
"productName": "General Liability",
"productCode": "GL-100",
"filingNumber": "FIL-2025-001",
"slaNumber": "SLA-2025-001",
"externalBillingId": "BILL-2025-001",
"agencyNpn": "12345678",
"agencyFein": "12-3456789",
"agencyLicenseNumber": "ABC-123456",
"agencyLicensedStateCode": "CA",
"agentName": "John Smith",
"agentNpn": "87654321",
"agentLicenseNumber": "LIC-789012",
"agentLicensedState": "TX",
"agentIds": [
"6650a1b2c3d4e5f6a7b8c9d0"
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
policyTransactionDate: '2025-01-15T00:00:00.000Z',
riskStateCode: 'CA',
policyTransactionType: 'new',
uniqueTransactionId: 'ext-txn-001',
insuredEntityName: 'Example Corp',
agencyName: 'Premier Insurance Agency',
carrierName: 'National Insurance Co',
effectiveDate: '2025-01-15T00:00:00.000Z',
expiryDate: '2026-01-15T00:00:00.000Z',
premiumAmountInUSD: 5000,
aggregateCoverageInUSD: 1000000,
coveragePerClaimInUSD: 500000,
lineOfBusiness: 'Commercial Lines',
licenseNumber: 'LIC-001',
npn: '11223344',
producerName: 'Jon Doe',
producerCode: 'PROD-001',
productName: 'General Liability',
productCode: 'GL-100',
filingNumber: 'FIL-2025-001',
slaNumber: 'SLA-2025-001',
externalBillingId: 'BILL-2025-001',
agencyNpn: '12345678',
agencyFein: '12-3456789',
agencyLicenseNumber: 'ABC-123456',
agencyLicensedStateCode: 'CA',
agentName: 'John Smith',
agentNpn: '87654321',
agentLicenseNumber: 'LIC-789012',
agentLicensedState: 'TX',
agentIds: ['6650a1b2c3d4e5f6a7b8c9d0']
})
};
fetch('https://public.api.live.turrisfi.com/v2/upstream/policies/{policyId}/transactions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://public.api.live.turrisfi.com/v2/upstream/policies/{policyId}/transactions"
payload = {
"policyTransactionDate": "2025-01-15T00:00:00.000Z",
"riskStateCode": "CA",
"policyTransactionType": "new",
"uniqueTransactionId": "ext-txn-001",
"insuredEntityName": "Example Corp",
"agencyName": "Premier Insurance Agency",
"carrierName": "National Insurance Co",
"effectiveDate": "2025-01-15T00:00:00.000Z",
"expiryDate": "2026-01-15T00:00:00.000Z",
"premiumAmountInUSD": 5000,
"aggregateCoverageInUSD": 1000000,
"coveragePerClaimInUSD": 500000,
"lineOfBusiness": "Commercial Lines",
"licenseNumber": "LIC-001",
"npn": "11223344",
"producerName": "Jon Doe",
"producerCode": "PROD-001",
"productName": "General Liability",
"productCode": "GL-100",
"filingNumber": "FIL-2025-001",
"slaNumber": "SLA-2025-001",
"externalBillingId": "BILL-2025-001",
"agencyNpn": "12345678",
"agencyFein": "12-3456789",
"agencyLicenseNumber": "ABC-123456",
"agencyLicensedStateCode": "CA",
"agentName": "John Smith",
"agentNpn": "87654321",
"agentLicenseNumber": "LIC-789012",
"agentLicensedState": "TX",
"agentIds": ["6650a1b2c3d4e5f6a7b8c9d0"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"data": {
"_id": "6650a1b2c3d4e5f6a7b8c9d0",
"policyId": "6650a1b2c3d4e5f6a7b8c9d1",
"upstreamEntityId": "6650a1b2c3d4e5f6a7b8c9d0",
"policyNumber": "POL-2025-001",
"policyTransactionType": "new",
"policyTransactionDate": "2025-01-15T00:00:00.000Z",
"riskStateCode": "CA",
"entityMatchStatus": "unmatched",
"matchedAgents": [
{
"agentId": "6650a1b2c3d4e5f6a7b8c9d0",
"matchSource": "user",
"matchConfidence": 1,
"matchedAt": "2025-01-15T10:30:00.000Z"
}
],
"agentMatchStatus": "user confirmed",
"transactionFingerprint": "a1b2c3...",
"columnMappingId": "6650a1b2c3d4e5f6a7b8c9d0",
"entityId": "6650a1b2c3d4e5f6a7b8c9d0",
"entityModel": "UpstreamEntity",
"isDeleted": false,
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:31:45.000Z",
"insuredEntityName": "Example Corp",
"agencyName": "Premier Insurance Agency",
"carrierName": "National Insurance Co",
"effectiveDate": "2025-01-15T00:00:00.000Z",
"expiryDate": "2026-01-15T00:00:00.000Z",
"premiumAmountInUSD": 5000,
"aggregateCoverageInUSD": 1000000,
"coveragePerClaimInUSD": 500000,
"lineOfBusiness": "Commercial Lines",
"licenseNumber": "LIC-001",
"npn": "11223344",
"producerName": "Jon Doe",
"producerCode": "PROD-001",
"productName": "General Liability",
"productCode": "GL-100",
"filingNumber": "FIL-2025-001",
"slaNumber": "SLA-2025-001",
"externalBillingId": "BILL-2025-001",
"uniqueTransactionId": "ext-txn-001",
"agencyNpn": "12345678",
"agencyFein": "12-3456789",
"agencyLicenseNumber": "ABC-123456",
"agencyLicensedStateCode": "CA",
"agentName": "John Smith",
"agentNpn": "87654321",
"agentLicenseNumber": "LIC-789012",
"agentLicensedState": "TX",
"downstreamEntityId": "6650a1b2c3d4e5f6a7b8c9d0",
"upstreamDownstreamAssociationId": "6650a1b2c3d4e5f6a7b8c9d1",
"entityMatchConfidence": 1,
"dedupResult": "new"
},
"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": {}
}{
"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": {}
}Create Transaction
Create a transaction under an existing policy
curl --request POST \
--url https://public.api.live.turrisfi.com/v2/upstream/policies/{policyId}/transactions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"policyTransactionDate": "2025-01-15T00:00:00.000Z",
"riskStateCode": "CA",
"policyTransactionType": "new",
"uniqueTransactionId": "ext-txn-001",
"insuredEntityName": "Example Corp",
"agencyName": "Premier Insurance Agency",
"carrierName": "National Insurance Co",
"effectiveDate": "2025-01-15T00:00:00.000Z",
"expiryDate": "2026-01-15T00:00:00.000Z",
"premiumAmountInUSD": 5000,
"aggregateCoverageInUSD": 1000000,
"coveragePerClaimInUSD": 500000,
"lineOfBusiness": "Commercial Lines",
"licenseNumber": "LIC-001",
"npn": "11223344",
"producerName": "Jon Doe",
"producerCode": "PROD-001",
"productName": "General Liability",
"productCode": "GL-100",
"filingNumber": "FIL-2025-001",
"slaNumber": "SLA-2025-001",
"externalBillingId": "BILL-2025-001",
"agencyNpn": "12345678",
"agencyFein": "12-3456789",
"agencyLicenseNumber": "ABC-123456",
"agencyLicensedStateCode": "CA",
"agentName": "John Smith",
"agentNpn": "87654321",
"agentLicenseNumber": "LIC-789012",
"agentLicensedState": "TX",
"agentIds": [
"6650a1b2c3d4e5f6a7b8c9d0"
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
policyTransactionDate: '2025-01-15T00:00:00.000Z',
riskStateCode: 'CA',
policyTransactionType: 'new',
uniqueTransactionId: 'ext-txn-001',
insuredEntityName: 'Example Corp',
agencyName: 'Premier Insurance Agency',
carrierName: 'National Insurance Co',
effectiveDate: '2025-01-15T00:00:00.000Z',
expiryDate: '2026-01-15T00:00:00.000Z',
premiumAmountInUSD: 5000,
aggregateCoverageInUSD: 1000000,
coveragePerClaimInUSD: 500000,
lineOfBusiness: 'Commercial Lines',
licenseNumber: 'LIC-001',
npn: '11223344',
producerName: 'Jon Doe',
producerCode: 'PROD-001',
productName: 'General Liability',
productCode: 'GL-100',
filingNumber: 'FIL-2025-001',
slaNumber: 'SLA-2025-001',
externalBillingId: 'BILL-2025-001',
agencyNpn: '12345678',
agencyFein: '12-3456789',
agencyLicenseNumber: 'ABC-123456',
agencyLicensedStateCode: 'CA',
agentName: 'John Smith',
agentNpn: '87654321',
agentLicenseNumber: 'LIC-789012',
agentLicensedState: 'TX',
agentIds: ['6650a1b2c3d4e5f6a7b8c9d0']
})
};
fetch('https://public.api.live.turrisfi.com/v2/upstream/policies/{policyId}/transactions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://public.api.live.turrisfi.com/v2/upstream/policies/{policyId}/transactions"
payload = {
"policyTransactionDate": "2025-01-15T00:00:00.000Z",
"riskStateCode": "CA",
"policyTransactionType": "new",
"uniqueTransactionId": "ext-txn-001",
"insuredEntityName": "Example Corp",
"agencyName": "Premier Insurance Agency",
"carrierName": "National Insurance Co",
"effectiveDate": "2025-01-15T00:00:00.000Z",
"expiryDate": "2026-01-15T00:00:00.000Z",
"premiumAmountInUSD": 5000,
"aggregateCoverageInUSD": 1000000,
"coveragePerClaimInUSD": 500000,
"lineOfBusiness": "Commercial Lines",
"licenseNumber": "LIC-001",
"npn": "11223344",
"producerName": "Jon Doe",
"producerCode": "PROD-001",
"productName": "General Liability",
"productCode": "GL-100",
"filingNumber": "FIL-2025-001",
"slaNumber": "SLA-2025-001",
"externalBillingId": "BILL-2025-001",
"agencyNpn": "12345678",
"agencyFein": "12-3456789",
"agencyLicenseNumber": "ABC-123456",
"agencyLicensedStateCode": "CA",
"agentName": "John Smith",
"agentNpn": "87654321",
"agentLicenseNumber": "LIC-789012",
"agentLicensedState": "TX",
"agentIds": ["6650a1b2c3d4e5f6a7b8c9d0"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"data": {
"_id": "6650a1b2c3d4e5f6a7b8c9d0",
"policyId": "6650a1b2c3d4e5f6a7b8c9d1",
"upstreamEntityId": "6650a1b2c3d4e5f6a7b8c9d0",
"policyNumber": "POL-2025-001",
"policyTransactionType": "new",
"policyTransactionDate": "2025-01-15T00:00:00.000Z",
"riskStateCode": "CA",
"entityMatchStatus": "unmatched",
"matchedAgents": [
{
"agentId": "6650a1b2c3d4e5f6a7b8c9d0",
"matchSource": "user",
"matchConfidence": 1,
"matchedAt": "2025-01-15T10:30:00.000Z"
}
],
"agentMatchStatus": "user confirmed",
"transactionFingerprint": "a1b2c3...",
"columnMappingId": "6650a1b2c3d4e5f6a7b8c9d0",
"entityId": "6650a1b2c3d4e5f6a7b8c9d0",
"entityModel": "UpstreamEntity",
"isDeleted": false,
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:31:45.000Z",
"insuredEntityName": "Example Corp",
"agencyName": "Premier Insurance Agency",
"carrierName": "National Insurance Co",
"effectiveDate": "2025-01-15T00:00:00.000Z",
"expiryDate": "2026-01-15T00:00:00.000Z",
"premiumAmountInUSD": 5000,
"aggregateCoverageInUSD": 1000000,
"coveragePerClaimInUSD": 500000,
"lineOfBusiness": "Commercial Lines",
"licenseNumber": "LIC-001",
"npn": "11223344",
"producerName": "Jon Doe",
"producerCode": "PROD-001",
"productName": "General Liability",
"productCode": "GL-100",
"filingNumber": "FIL-2025-001",
"slaNumber": "SLA-2025-001",
"externalBillingId": "BILL-2025-001",
"uniqueTransactionId": "ext-txn-001",
"agencyNpn": "12345678",
"agencyFein": "12-3456789",
"agencyLicenseNumber": "ABC-123456",
"agencyLicensedStateCode": "CA",
"agentName": "John Smith",
"agentNpn": "87654321",
"agentLicenseNumber": "LIC-789012",
"agentLicensedState": "TX",
"downstreamEntityId": "6650a1b2c3d4e5f6a7b8c9d0",
"upstreamDownstreamAssociationId": "6650a1b2c3d4e5f6a7b8c9d1",
"entityMatchConfidence": 1,
"dedupResult": "new"
},
"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": {}
}{
"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": {}
}policyNumber is inherited from the parent policy. Only policyTransactionDate and riskStateCode are required. policyTransactionType defaults to bound when omitted.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
policyId | string | Yes | Unique identifier of the parent policy (MongoDB ObjectId) |
Agent Assignment
agentIds (agent _id values from List Agents) is only valid when the parent policy has a confirmed agency match. Each agent must be available to the matched agency, otherwise the request fails with 422.
uniqueTransactionId to give the transaction a stable, caller-supplied id that disambiguates otherwise-identical transactions during deduplication.Response Shape
{
"statusCode": 201,
"data": {
"_id": "6650a1b2c3d4e5f6a7b8c9d1",
"policyId": "6650a1b2c3d4e5f6a7b8c9d0",
"policyNumber": "POL-2025-001",
"policyTransactionType": "new",
"policyTransactionDate": "2025-01-15T00:00:00.000Z",
"riskStateCode": "CA",
"entityMatchStatus": "unmatched",
"matchedAgents": [],
"agentMatchStatus": "unmatched",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:30:00.000Z"
},
"timestamp": "2025-01-15T10:30:00.000Z"
}
Error Scenarios
Bad Request (400)
Returned whenpolicyId is malformed or the body fails validation.
{
"statusCode": 400,
"errorType": "validation_error",
"errorMessage": ["policyTransactionDate must be a valid ISO 8601 date string"],
"requestId": "dev-abc123",
"timestamp": "2025-01-15T10:30:00.000Z"
}
Parent Policy Not Found (404)
Returned whenpolicyId does not exist or belongs to a different upstream entity.
{
"statusCode": 404,
"errorType": "not_found",
"errorMessage": ["Policy not found"],
"requestId": "dev-abc123",
"timestamp": "2025-01-15T10:30:00.000Z"
}
Duplicate Transaction (409)
Returned when a transaction with these details already exists under the policy.{
"statusCode": 409,
"errorType": "conflict",
"errorMessage": ["A transaction with these details already exists"],
"requestId": "dev-abc123",
"timestamp": "2025-01-15T10:30:00.000Z"
}
Agent Assignment Rejected (422)
Returned whenagentIds is supplied without a confirmed agency, or an agent is not available to the matched agency.
{
"statusCode": 422,
"errorType": "unprocessable_entity",
"errorMessage": ["Agents can only be assigned when the policy has a confirmed agency"],
"requestId": "dev-abc123",
"timestamp": "2025-01-15T10:30:00.000Z"
}
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 transaction. See Idempotency.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
UUID to ensure idempotent request processing
"550e8400-e29b-41d4-a716-446655440000"
Alternative UUID header for idempotent request processing
"550e8400-e29b-41d4-a716-446655440000"
Path Parameters
Unique identifier of the parent policy
"6650a1b2c3d4e5f6a7b8c9d0"
Body
Transaction date (ISO 8601)
"2025-01-15T00:00:00.000Z"
US state code where the risk is located
"CA"
Transaction type. Defaults to "bound" when omitted.
new, renewal, endorsement, cancellation, audit, reinstatement, bound "new"
Caller-supplied stable id disambiguating otherwise-identical transactions during dedup.
"ext-txn-001"
Name of the insured party
"Example Corp"
Agency name
"Premier Insurance Agency"
Insurance carrier name
"National Insurance Co"
Effective date (ISO 8601)
"2025-01-15T00:00:00.000Z"
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
"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"
Agent association - agent ids (agent._id from GET /agents) to assign. Requires a confirmed agency.
["6650a1b2c3d4e5f6a7b8c9d0"]
Was this page helpful?