New Business Transaction

Creates a new policy via a NEW_BUSINESS transaction. This is the entry point for the transaction-based policy lifecycle. The transaction produces a single segment covering the full policy term.

The request body contains the policy term dates and the initial policy state, including policy-level fields, full-term aggregates, and nested exposures. Exposures must reference existing exposure records by ID.

Required permission: company.policy:create

POST /api/v1/external/companies/{companyId}/policies/transaction/new-business

New Business Transaction

cURL

curl --request POST \
  --url https://app.aiinsurance.io/api/v1/external/companies/{companyId}/policies/transaction/new-business \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "policyStartDate": "2025-01-01",
  "policyEndDate": "2026-01-01",
  "fieldModelV1Data": {
    "policy": {
      "annualPremium": 85000,
      "fullTermPolicyInfo": {
        "policyStatus": "Active",
        "policyStartDate": {
          "year": 2025,
          "month": 1,
          "day": 1,
          "timezone": "America/New_York"
        },
        "policyEndDate": {
          "year": 2026,
          "month": 1,
          "day": 1,
          "timezone": "America/New_York"
        },
        "primaryInsuredId": "550e8400-e29b-41d4-a716-446655440010"
      },
      "fullTermPolicyBilling": {
        "policyPremium": 85000,
        "policyTaxes": 0,
        "policyFees": 500,
        "policyGrandTotal": 85500
      },
      "exposures": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440010",
          "exposureType": "MedicalFacility",
          "bedCount": 120
        }
      ]
    }
  }
}
'

201

success

{
  "policyId": "550e8400-e29b-41d4-a716-446655440001",
  "policyVersion": 1,
  "transactionId": "550e8400-e29b-41d4-a716-446655440002",
  "startDate": "2025-01-01",
  "endDate": "2026-01-01",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "fullTermPolicyInfo": {
    "policyStatus": "Active",
    "policyStartDate": {
      "year": 2025,
      "month": 1,
      "day": 1,
      "timezone": "America/New_York"
    },
    "policyEndDate": {
      "year": 2026,
      "month": 1,
      "day": 1,
      "timezone": "America/New_York"
    },
    "primaryInsuredId": "550e8400-e29b-41d4-a716-446655440010"
  },
  "fullTermPolicyBilling": {
    "policyPremium": 85000,
    "policyTaxes": 0,
    "policyFees": 500,
    "policyGrandTotal": 85500
  },
  "segments": [
    {
      "startDate": "2025-01-01",
      "endDate": "2026-01-01",
      "fieldModelV1Data": {
        "policy": {
          "annualPremium": 85000,
          "fullTermPolicyInfo": {
            "policyStatus": "Active",
            "policyStartDate": {
              "year": 2025,
              "month": 1,
              "day": 1,
              "timezone": "America/New_York"
            },
            "policyEndDate": {
              "year": 2026,
              "month": 1,
              "day": 1,
              "timezone": "America/New_York"
            },
            "primaryInsuredId": "550e8400-e29b-41d4-a716-446655440010"
          },
          "fullTermPolicyBilling": {
            "policyPremium": 85000,
            "policyTaxes": 0,
            "policyFees": 500,
            "policyGrandTotal": 85500
          },
          "exposures": [
            {
              "id": "550e8400-e29b-41d4-a716-446655440010",
              "exposureType": "MedicalFacility",
              "bedCount": 120
            }
          ]
        }
      }
    }
  ]
}

Authorizations

Authorization · string · header · required

API key authentication. Include your API key in the Authorization header.

Path Parameters

companyId · string<uuid> · required

Company identifier

Body

application/json

policyStartDate · string<date> · required

Policy term start date in ISO 8601 format. Must be before policyEndDate. The day/month/year must match fullTermPolicyInfo.policyStartDate.

Accepts a plain date (2025-01-01) or a full timestamp with UTC offset (2025-01-01T00:00:00-05:00). Only standard-time (non-DST) offsets are accepted:

Timezone	Accepted offset
America/New_York	-05:00 (EST)
America/Los_Angeles	-08:00 (PST)

Daylight-saving offsets (-04:00 EDT, -07:00 PDT) are not accepted. These are the only two timezones currently supported.

policyEndDate · string<date> · required

Policy term end date in ISO 8601 format. Must be after policyStartDate. The day/month/year must match fullTermPolicyInfo.policyEndDate.

Accepts a plain date (2026-01-01) or a full timestamp with UTC offset. Only standard-time offsets are accepted — see policyStartDate for the mapping.

fieldModelV1Data · object · required

Container for policy state. Must contain a policy object with all policy-level fields and optional nested exposures.

Custom fields within the policy and each exposure are validated against your company's field configuration. Unknown fields are rejected, required fields must be present, and values must match their configured types (including option set membership).

Show child attributes

transactionTimestamp · string<date-time>

When the business decision was made. Defaults to the current time if omitted. Set explicitly for imports (e.g., aligning to a bordereau booking date).

Response

201

application/json

Policy created successfully

Response returned by policy transaction endpoints. Contains the policy version produced by the transaction, including all derived segments.

policyId · string<uuid> · required

Policy identifier

policyVersion · integer · required

Sequential version number produced by this transaction

transactionId · string<uuid> · required

Identifier of the transaction that produced this version

startDate · string<date> · required

Policy term start date (ISO 8601)

endDate · string<date> · required

Policy term end date (ISO 8601)

createdAt · string<date-time> · required

When the transaction was created (ISO 8601)

segments · object[] · required

Derived segments for this policy version. Each segment represents a maximal contiguous date range where policy state is identical. Adjacent segments with identical data are automatically merged.

Show child attributes

fullTermPolicyInfo · object

Full-term policy information. Contains policy status, term dates, and primary insured reference.

fullTermPolicyBilling · object

Full-term billing aggregates. Contains premium, taxes, fees, and grand total for the full policy term.