> ## Documentation Index > Fetch the complete documentation index at: https://docs.aiinsurance.io/llms.txt > Use this file to discover all available pages before exploring further. # 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` ## OpenAPI ````yaml /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/policies/transaction/new-business openapi: 3.0.3 info: title: AI Insurance External API description: External API for AI Insurance platform version: 1.0.0 contact: email: support@aiinsurance.io servers: - url: https://app.aiinsurance.io description: Production security: - ApiKeyAuth: [] paths: /api/v1/external/companies/{companyId}/policies/transaction/new-business: post: tags: - Field Model Policy Transactions summary: New Business Transaction description: > 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` operationId: newBusinessPolicyTransaction parameters: - $ref: '#/components/parameters/companyId' requestBody: required: true content: application/json: schema: type: object required: - policyStartDate - policyEndDate - fieldModelV1Data properties: policyStartDate: type: string format: date description: > 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: type: string format: date description: > 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. transactionTimestamp: type: string format: date-time description: > 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). fieldModelV1Data: type: object required: - policy description: > 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). properties: policy: type: object description: > Policy-level fields. Must include `fullTermPolicyInfo` and `fullTermPolicyBilling`. May include a nested `exposures` array and any custom fields defined in your field configuration. required: - fullTermPolicyInfo - fullTermPolicyBilling properties: fullTermPolicyInfo: type: object description: Full-term policy information. required: - policyStatus - policyStartDate - policyEndDate - primaryInsuredId properties: policyStatus: type: string description: Policy status (e.g., "Active") policyStartDate: description: > Policy start date. Accepts either: - An ISO date string (e.g. `"2025-01-01"` or `"2025-01-01T00:00:00-05:00"`). Timezone is inferred from the UTC offset if present (`-05:00` → `America/New_York`, `-08:00` → `America/Los_Angeles`), otherwise defaults to `America/New_York`. Converted to structured format internally; the day/month/year must be consistent with the top-level `policyStartDate`. - A structured date object with explicit day/month/year/timezone fields. The components must match the top-level `policyStartDate`. oneOf: - type: string format: date - type: object required: - day - month - year - timezone properties: day: type: integer description: Day of month (1-31) month: type: integer description: Month (1-12) year: type: integer description: Four-digit year timezone: type: string enum: - America/New_York - America/Los_Angeles description: > IANA timezone name. Only two timezones are currently supported: `America/New_York` (standard time: `-05:00` EST) and `America/Los_Angeles` (standard time: `-08:00` PST). Only standard-time offsets are accepted in the top-level date; daylight-saving offsets are rejected. policyEndDate: description: > Policy end date. Accepts either: - An ISO date string. See `policyStartDate` for offset-to-timezone mapping. The day/month/year must be consistent with the top-level `policyEndDate`. - A structured date object with explicit day/month/year/timezone fields. oneOf: - type: string format: date - type: object required: - day - month - year - timezone properties: day: type: integer description: Day of month (1-31) month: type: integer description: Month (1-12) year: type: integer description: Four-digit year timezone: type: string enum: - America/New_York - America/Los_Angeles description: > IANA timezone name. Only two timezones are currently supported: `America/New_York` (standard time: `-05:00` EST) and `America/Los_Angeles` (standard time: `-08:00` PST). Only standard-time offsets are accepted in the top-level date; daylight-saving offsets are rejected. primaryInsuredId: type: string format: uuid description: >- Must match the `id` of one of the exposures when exposures are included. additionalProperties: true fullTermPolicyBilling: type: object description: Full-term billing aggregates. required: - policyPremium - policyTaxes - policyFees - policyGrandTotal properties: policyPremium: type: number description: Total premium for the full term policyTaxes: type: number description: Total taxes for the full term policyFees: type: number description: Total fees for the full term policyGrandTotal: type: number description: >- Grand total (premium + taxes + fees) for the full term additionalProperties: true exposures: type: array description: > Exposures to include on the policy. Each exposure must reference an existing exposure record by `id`. Create exposures first via the [Exposures API](/api-reference/field-model/exposures/overview). items: type: object required: - id properties: id: type: string format: uuid description: Existing exposure record ID exposureType: type: string description: >- Exposure type (must match a configured exposure type) additionalProperties: true additionalProperties: true examples: medicalFacility: summary: Medical facility policy value: 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 responses: '201': description: Policy created successfully content: application/json: schema: $ref: '#/components/schemas/PolicyTransactionVersionResponse' examples: success: summary: New business transaction response value: 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 '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidDateRange: summary: End date before start date value: error: code: InvalidDateRange message: policyEndDate must be after policyStartDate missingPolicyObject: summary: Missing policy object in fieldModelV1Data value: error: code: InvalidFieldModelV1Data message: fieldModelV1Data must contain a 'policy' object missingFullTermFields: summary: Missing required full-term fields value: error: code: InvalidFieldModelV1Data message: >- 'fullTermPolicyInfo' is required and must be an object; 'fullTermPolicyBilling' is required and must be an object dateConsistencyMismatch: summary: Structured date fields don't match top-level dates value: error: code: DateConsistencyError message: >- fullTermPolicyInfo.policyStartDate.month (6) does not match policyStartDate month (1) unsupportedTimezone: summary: Timezone not in allowlist value: error: code: DateConsistencyError message: >- 'fullTermPolicyInfo.policyStartDate.timezone' must be one of: America/New_York, America/Los_Angeles; got 'Europe/London' utcOffsetMismatch: summary: ISO UTC offset doesn't match structured timezone value: error: code: DateConsistencyError message: >- policyStartDate UTC offset (+00:00) is not consistent with fullTermPolicyInfo.policyStartDate.timezone (America/New_York); expected one of: -05:00 exposureNotFound: summary: Exposure ID does not exist value: error: code: InvalidFieldModelV1Data message: >- Exposure IDs not found: 550e8400-e29b-41d4-a716-446655440099 fieldConfigValidation: summary: Field value fails company configuration validation value: error: code: InvalidFieldModelV1Data message: >- Unknown field 'nonExistentField'; Field 'bedCount' expected number, got string '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier schemas: PolicyTransactionVersionResponse: type: object description: > Response returned by policy transaction endpoints. Contains the policy version produced by the transaction, including all derived segments. required: - policyId - policyVersion - transactionId - startDate - endDate - createdAt - segments properties: policyId: type: string format: uuid description: Policy identifier policyVersion: type: integer description: Sequential version number produced by this transaction transactionId: type: string format: uuid description: Identifier of the transaction that produced this version startDate: type: string format: date description: Policy term start date (ISO 8601) endDate: type: string format: date description: Policy term end date (ISO 8601) createdAt: type: string format: date-time description: When the transaction was created (ISO 8601) fullTermPolicyInfo: type: object nullable: true description: > Full-term policy information. Contains policy status, term dates, and primary insured reference. additionalProperties: true fullTermPolicyBilling: type: object nullable: true description: > Full-term billing aggregates. Contains premium, taxes, fees, and grand total for the full policy term. additionalProperties: true segments: type: array description: > 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. items: $ref: '#/components/schemas/PolicyTransactionSegmentResponse' ErrorResponse: type: object description: Standard error response for all external API endpoints required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code example: VALIDATION_ERROR message: type: string description: Human-readable error message example: 'submissionId: Required field is missing' details: type: array description: Additional details for validation errors (field-level errors) items: type: object properties: field: type: string description: The field that caused the error example: submissionId message: type: string description: Description of the field error example: Required field is missing PolicyTransactionSegmentResponse: type: object description: > A derived policy segment representing a date range where policy state is identical. Contains the full policy data (policy-level fields and nested exposures) for this period. required: - startDate - endDate - fieldModelV1Data properties: startDate: type: string format: date description: Segment start date (ISO 8601) endDate: type: string format: date description: Segment end date (ISO 8601) fieldModelV1Data: type: object description: > Policy state for this segment. Contains a `policy` key with policy-level fields and a nested `exposures` array. properties: policy: type: object description: Policy-level fields and nested exposures for this segment. additionalProperties: true additionalProperties: true responses: Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: Missing API key value: error: code: UNAUTHORIZED message: Authorization header is required bearerTokenNotAllowed: summary: Bearer token used instead of API key value: error: code: UNAUTHORIZED message: External API endpoints require API key authentication Forbidden: description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientPermissions: summary: Insufficient permissions value: error: code: FORBIDDEN message: Insufficient permissions to perform this action InternalServerError: description: Internal Server Error - Unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: Unexpected server error value: error: code: INTERNAL_ERROR message: An unexpected error occurred. Please try again later. securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: >- API key authentication. Include your API key in the Authorization header. ````