> ## 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. # Renew Policy Transaction > Creates a new policy via a RENEW transaction, linking it to a previous policy. The new policy term must start on or after the previous policy's end date. The request body follows the same structure as NEW_BUSINESS — it contains the new policy term dates and the full initial policy state, including policy-level fields, full-term aggregates, and nested exposures. The transaction produces a new policy record with a single segment covering the full renewal term. **Required permission:** `company.policy:create` ## OpenAPI ````yaml /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/policies/transaction/renew 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/renew: post: tags: - Field Model Policy Transactions summary: Renew Policy Transaction description: > Creates a new policy via a RENEW transaction, linking it to a previous policy. The new policy term must start on or after the previous policy's end date. The request body follows the same structure as NEW_BUSINESS — it contains the new policy term dates and the full initial policy state, including policy-level fields, full-term aggregates, and nested exposures. The transaction produces a new policy record with a single segment covering the full renewal term. **Required permission:** `company.policy:create` operationId: renewPolicyTransaction parameters: - $ref: '#/components/parameters/companyId' requestBody: required: true content: application/json: schema: type: object required: - previousPolicyId - newPolicyStartDate - newPolicyEndDate - fieldModelV1Data properties: previousPolicyId: type: string format: uuid description: > The ID of the policy being renewed. Must be an existing policy with at least one transaction. The new policy will be linked to this policy. newPolicyStartDate: type: string format: date description: > Renewal term start date in ISO 8601 format. Must be on or after the previous policy's end date. Must be before `newPolicyEndDate`. The day/month/year must match `fullTermPolicyInfo.policyStartDate`. Accepts a plain date (`2026-01-01`) or a full timestamp with UTC offset (`2026-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. newPolicyEndDate: type: string format: date description: > Renewal term end date in ISO 8601 format. Must be after `newPolicyStartDate`. The day/month/year must match `fullTermPolicyInfo.policyEndDate`. Accepts a plain date (`2027-01-01`) or a full timestamp with UTC offset. Only standard-time offsets are accepted — see `newPolicyStartDate` 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 renewal 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. `"2026-01-01"` or `"2026-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 `newPolicyStartDate`. - A structured date object with explicit day/month/year/timezone fields. The components must match the top-level `newPolicyStartDate`. 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). 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 `newPolicyEndDate`. - 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). 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 renewal 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: annualRenewal: summary: Annual policy renewal value: previousPolicyId: 550e8400-e29b-41d4-a716-446655440001 newPolicyStartDate: '2026-01-01' newPolicyEndDate: '2027-01-01' fieldModelV1Data: policy: annualPremium: 90000 fullTermPolicyInfo: policyStatus: Active policyStartDate: year: 2026 month: 1 day: 1 timezone: America/New_York policyEndDate: year: 2027 month: 1 day: 1 timezone: America/New_York primaryInsuredId: 550e8400-e29b-41d4-a716-446655440010 fullTermPolicyBilling: policyPremium: 90000 policyTaxes: 0 policyFees: 500 policyGrandTotal: 90500 exposures: - id: 550e8400-e29b-41d4-a716-446655440010 exposureType: MedicalFacility bedCount: 120 responses: '201': description: Renewal policy created successfully content: application/json: schema: $ref: '#/components/schemas/PolicyTransactionVersionResponse' examples: success: summary: Renewal transaction response value: policyId: 550e8400-e29b-41d4-a716-446655440060 policyVersion: 1 transactionId: 550e8400-e29b-41d4-a716-446655440061 startDate: '2026-01-01' endDate: '2027-01-01' createdAt: '2025-12-15T10:30:00.000Z' fullTermPolicyInfo: policyStatus: Active policyStartDate: year: 2026 month: 1 day: 1 timezone: America/New_York policyEndDate: year: 2027 month: 1 day: 1 timezone: America/New_York primaryInsuredId: 550e8400-e29b-41d4-a716-446655440010 fullTermPolicyBilling: policyPremium: 90000 policyTaxes: 0 policyFees: 500 policyGrandTotal: 90500 segments: - startDate: '2026-01-01' endDate: '2027-01-01' fieldModelV1Data: policy: annualPremium: 90000 fullTermPolicyInfo: policyStatus: Active policyStartDate: year: 2026 month: 1 day: 1 timezone: America/New_York policyEndDate: year: 2027 month: 1 day: 1 timezone: America/New_York primaryInsuredId: 550e8400-e29b-41d4-a716-446655440010 fullTermPolicyBilling: policyPremium: 90000 policyTaxes: 0 policyFees: 500 policyGrandTotal: 90500 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: newPolicyEndDate must be after newPolicyStartDate startDateBeforePreviousEnd: summary: Renewal starts before previous policy ends value: error: code: InvalidRequest message: >- newPolicyStartDate (2025-06-01) must be >= previous policy end date (2025-12-31) 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' 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' '404': description: Previous policy not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: previousPolicyNotFound: summary: Previous policy does not exist value: error: code: NOT_FOUND message: Policy 550e8400-e29b-41d4-a716-446655440099 not found '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. ````