Skip to main content
POST
cURL
Creates one transaction under an existing policy. The policyNumber is inherited from the parent policy. Only policyTransactionDate and riskStateCode are required. policyTransactionType defaults to bound when omitted.

Path Parameters

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.
Use uniqueTransactionId to give the transaction a stable, caller-supplied id that disambiguates otherwise-identical transactions during deduplication.

Response Shape

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

Error Scenarios

Bad Request (400)

Returned when policyId is malformed or the body fails validation.

Parent Policy Not Found (404)

Returned when policyId does not exist or belongs to a different upstream entity.

Duplicate Transaction (409)

Returned when a transaction with these details already exists under the policy.

Agent Assignment Rejected (422)

Returned when agentIds is supplied without a confirmed agency, or an agent is not available to the matched agency.

Unauthorized (401)

Missing or invalid authentication token. See Authentication.

Idempotency

This endpoint supports idempotency. If you include an idempotency-key header, duplicate requests within 1 hour return the original response without creating a second transaction. See Idempotency.

Headers

idempotency-key
string

UUID to ensure idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

x-idempotency-key
string

Alternative UUID header for idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

Path Parameters

policyId
string
required

Unique identifier of the parent policy

Example:

"6650a1b2c3d4e5f6a7b8c9d0"

Body

application/json
policyTransactionDate
string
required

Transaction date (ISO 8601)

Example:

"2025-01-15T00:00:00.000Z"

riskStateCode
string
required

US state code where the risk is located

Example:

"CA"

policyTransactionType
enum<string>

Transaction type. Defaults to "bound" when omitted.

Available options:
new,
renewal,
endorsement,
cancellation,
audit,
reinstatement,
bound
Example:

"new"

uniqueTransactionId
string

Caller-supplied stable id disambiguating otherwise-identical transactions during dedup.

Example:

"ext-txn-001"

insuredEntityName
string

Name of the insured party

Example:

"Example Corp"

agencyName
string

Agency name

Example:

"Premier Insurance Agency"

carrierName
string

Insurance carrier name

Example:

"National Insurance Co"

effectiveDate
string

Effective date (ISO 8601)

Example:

"2025-01-15T00:00:00.000Z"

expiryDate
string

Expiration date (ISO 8601)

Example:

"2026-01-15T00:00:00.000Z"

premiumAmountInUSD
number

Premium amount in USD

Example:

5000

aggregateCoverageInUSD
number

Aggregate coverage limit in USD

Example:

1000000

coveragePerClaimInUSD
number

Per-claim coverage limit in USD

Example:

500000

lineOfBusiness
string

Line of business

Example:

"Commercial Lines"

licenseNumber
string

License number

Example:

"LIC-001"

npn
string

National Producer Number

Example:

"11223344"

producerName
string

Producing agent name

Example:

"Jon Doe"

producerCode
string

Producer identifier code

Example:

"PROD-001"

productName
string

Product name

Example:

"General Liability"

productCode
string

Product code

Example:

"GL-100"

filingNumber
string

Filing number

Example:

"FIL-2025-001"

slaNumber
string

SLA number

Example:

"SLA-2025-001"

externalBillingId
string

External billing identifier

Example:

"BILL-2025-001"

agencyNpn
string

Agency National Producer Number

Example:

"12345678"

agencyFein
string

Agency Federal Employer Identification Number

Example:

"12-3456789"

agencyLicenseNumber
string

Agency state license number

Example:

"ABC-123456"

agencyLicensedStateCode
string

State where the agency license was issued

Example:

"CA"

agentName
string

Individual agent name

Example:

"John Smith"

agentNpn
string

Agent National Producer Number

Example:

"87654321"

agentLicenseNumber
string

Agent state license number

Example:

"LIC-789012"

agentLicensedState
string

State where the agent license was issued

Example:

"TX"

agentIds
string[]

Agent association - agent ids (agent._id from GET /agents) to assign. Requires a confirmed agency.

Example:

Response

Transaction created

data
object
required
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"