> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.aiinsurance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Replace Event Open/Close History

> Replaces an event's **whole** open/close-history log with the one you send,
then derives the event's status from it, in one atomic call: the stored log
is discarded wholesale, `eventStatus` and **Close Date** are set from the
new log's final entry (`close` → `closed` with that entry's
`effectiveOnDate`; `open`/`reopen` → `open` with no close date).

**This is the path for historical imports and history corrections.** An
already-closed historical claim is created open and then closed by this
call (or resolved at create time by supplying `eventOpenCloseHistory`);
a log that was loaded wrong is fixed by sending the corrected one. For
day-to-day lifecycle changes use
[Close Event](/api-reference/event-lifecycle/close-event) and
[Re-open Event](/api-reference/event-lifecycle/re-open-event), which append
to the log instead of replacing it.

**Every entry sub-field is yours to supply** — including `actionTakenDate`,
the date the action was taken. A historical log carries the true dates;
nothing is server-stamped here.

**The log must be well-formed.** It must be non-empty, its first entry's
action must be `open`, actions must strictly alternate `close`/`reopen`
after that (a claim cannot close twice in a row, or re-open while open),
and `effectiveOnDate`s must be non-decreasing in the order the entries are
listed. A malformed log returns `400`.

**Restricted field.** If your company's configuration gives
`eventOpenCloseHistory` a `writePermission`, this call also requires that
field write group (`event.field-<value>`), exactly as a generic event
update naming the field would. A key without it receives `403` with error
code `field-write-permission-required`. Close Event and Re-open Event are
not affected: they append one server-built entry rather than letting you
author the log.

**Required permission:** `event.edit`




## OpenAPI

````yaml /openapi/generated-external-api.yaml put /api/v1/companies/{companyId}/events/{eventId}/open-close-history
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://go.aiinsurance.io
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /api/v1/companies/{companyId}/events/{eventId}/open-close-history:
    put:
      tags:
        - Event Lifecycle
      summary: Replace Event Open/Close History
      description: >
        Replaces an event's **whole** open/close-history log with the one you
        send,

        then derives the event's status from it, in one atomic call: the stored
        log

        is discarded wholesale, `eventStatus` and **Close Date** are set from
        the

        new log's final entry (`close` → `closed` with that entry's

        `effectiveOnDate`; `open`/`reopen` → `open` with no close date).


        **This is the path for historical imports and history corrections.** An

        already-closed historical claim is created open and then closed by this

        call (or resolved at create time by supplying `eventOpenCloseHistory`);

        a log that was loaded wrong is fixed by sending the corrected one. For

        day-to-day lifecycle changes use

        [Close Event](/api-reference/event-lifecycle/close-event) and

        [Re-open Event](/api-reference/event-lifecycle/re-open-event), which
        append

        to the log instead of replacing it.


        **Every entry sub-field is yours to supply** — including
        `actionTakenDate`,

        the date the action was taken. A historical log carries the true dates;

        nothing is server-stamped here.


        **The log must be well-formed.** It must be non-empty, its first entry's

        action must be `open`, actions must strictly alternate `close`/`reopen`

        after that (a claim cannot close twice in a row, or re-open while open),

        and `effectiveOnDate`s must be non-decreasing in the order the entries
        are

        listed. A malformed log returns `400`.


        **Restricted field.** If your company's configuration gives

        `eventOpenCloseHistory` a `writePermission`, this call also requires
        that

        field write group (`event.field-<value>`), exactly as a generic event

        update naming the field would. A key without it receives `403` with
        error

        code `field-write-permission-required`. Close Event and Re-open Event
        are

        not affected: they append one server-built entry rather than letting you

        author the log.


        **Required permission:** `event.edit`
      operationId: replaceEventOpenCloseHistory
      parameters:
        - $ref: '#/components/parameters/companyId'
        - $ref: '#/components/parameters/eventIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - eventOpenCloseHistory
              properties:
                eventOpenCloseHistory:
                  type: array
                  minItems: 1
                  description: |
                    The complete replacement log, in the order the actions
                    happened: `open` first, then alternating `close`/`reopen`.
                  items:
                    type: object
                    required:
                      - action
                      - effectiveOnDate
                      - actionTakenDate
                    properties:
                      action:
                        type: string
                        enum:
                          - open
                          - close
                          - reopen
                        description: The lifecycle action this entry records.
                      effectiveOnDate:
                        $ref: '#/components/schemas/Fmv1Date'
                      actionTakenDate:
                        $ref: '#/components/schemas/Fmv1Date'
            examples:
              closedHistoricalClaim:
                summary: >-
                  A historical claim that opened, closed, re-opened, and closed
                  again
                value:
                  eventOpenCloseHistory:
                    - action: open
                      effectiveOnDate:
                        date: '2020-01-15'
                        timezone: America/New_York
                      actionTakenDate:
                        date: '2020-01-15'
                        timezone: America/New_York
                    - action: close
                      effectiveOnDate:
                        date: '2020-06-01'
                        timezone: America/New_York
                      actionTakenDate:
                        date: '2020-06-03'
                        timezone: America/New_York
                    - action: reopen
                      effectiveOnDate:
                        date: '2021-02-10'
                        timezone: America/New_York
                      actionTakenDate:
                        date: '2021-02-10'
                        timezone: America/New_York
                    - action: close
                      effectiveOnDate:
                        date: '2021-08-20'
                        timezone: America/New_York
                      actionTakenDate:
                        date: '2021-08-22'
                        timezone: America/New_York
      responses:
        '200':
          description: The log was replaced and the event's status derived from it.
          content:
            application/json:
              schema:
                type: object
                required:
                  - eventId
                  - eventStatus
                properties:
                  eventId:
                    type: string
                    format: uuid
                    description: The event whose log was replaced.
                  eventStatus:
                    type: string
                    enum:
                      - open
                      - closed
                    description: >
                      The status the new log's final entry dictates: `closed`
                      when

                      it is a `close`, `open` otherwise.
              examples:
                closed:
                  summary: The log ends in a close
                  value:
                    eventId: 550e8400-e29b-41d4-a716-446655440020
                    eventStatus: closed
        '400':
          description: >
            The log is malformed: empty, first entry not `open`, actions not

            strictly alternating `close`/`reopen`, `effectiveOnDate`s
            decreasing,

            or an entry missing one of its three sub-fields; or a date is not a

            real calendar day, outside the 1900-2200 window, names an
            unsupported

            `timezone`, or uses the retired `{ day, month, year }` spelling; or

            `eventId` is not a UUID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No event with the given id exists for this company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    companyId:
      name: companyId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Company identifier
    eventIdPath:
      name: eventId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Event (claim or incident) identifier
  schemas:
    Fmv1Date:
      type: object
      description: >
        Field Model V1 `Date` value: a calendar day pinned to an IANA time zone
        —

        the day a person wrote on the policy, not an instant.


        `date` is the day as `YYYY-MM-DD` and must name a real calendar day

        (`2026-02-30` is rejected with `400`). `timezone` is an IANA tz database

        identifier (e.g. `America/New_York`, `UTC`); an unknown zone is rejected

        with `400`. On a write `timezone` may be omitted, in which case it
        defaults

        to `America/New_York`. Every value the API returns carries both members.


        This is the one Date shape the API accepts, stores and returns, for
        every

        field typed `Date` — entity fields, policy term dates, custom-object

        sub-fields, embedded exposure items and the event lifecycle dates alike.
        The

        retired `{ day, month, year, timezone }` spelling is refused with `400`

        (see the API changelog, 2026-09-08). The policy endorsement `deltas`
        channel

        additionally requires both members stated, because it stores each value

        exactly as sent (2026-09-04).
      required:
        - date
      additionalProperties: false
      properties:
        date:
          type: string
          format: date
          description: The calendar day as `YYYY-MM-DD`, zero-padded.
          example: '2026-03-15'
        timezone:
          type: string
          description: >
            IANA time zone identifier the day is anchored in (e.g.
            "America/New_York",

            "UTC"). Optional on a write (defaults to `America/New_York`); always

            present in a response.
          example: America/New_York
    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'
            userMessages:
              type: array
              description: >-
                Clean, verbatim-displayable messages — one entry per failure,
                free of error-code tags, field paths, and internal noise.
                Suitable for showing to end users as-is.
              items:
                type: string
              example:
                - Exposures of type 'company' require an address
            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
                  code:
                    type: string
                    description: Stable problem code for this individual validation failure
                    example: BLANK_LIST_ELEMENT
                  reason:
                    type: string
                    description: Stable reason the value violates its canonical contract
                    example: blank-list-element
                  expected:
                    type: string
                    description: The expected canonical value contract
                    example: nonblank trimmed string
                  message:
                    type: string
                    description: Description of the field error
                    example: Required field is missing
  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: AuthenticationError
                  message: API key authentication required
                  userMessages:
                    - API key authentication required
            invalidApiKey:
              summary: >-
                Invalid API key (e.g. unknown key, or a Bearer token used
                instead of an API key)
              value:
                error:
                  code: AuthenticationError
                  message: Invalid API key
                  userMessages:
                    - Invalid API key
    Forbidden:
      description: Forbidden - Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            insufficientPermissions:
              summary: Insufficient permissions
              value:
                error:
                  code: AuthorizationError
                  message: User is not authorized to perform the requested action
                  userMessages:
                    - User is not authorized to perform the requested action
            companyMismatch:
              summary: A valid API key naming another company in the URL
              value:
                error:
                  code: AuthorizationError
                  message: API key is not scoped to the requested company
                  userMessages:
                    - API key is not scoped to the requested company
    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: UncaughtActionError
                  message: Uncaught error occurred in <actionName>
                  userMessages:
                    - An unexpected error occurred. Please try again later.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key authentication. Send your raw API key as the `Authorization`
        header value with NO scheme prefix — `Authorization: YOUR-API-KEY`. Do
        NOT prefix it with `Bearer ` or `ApiKey `, and do not use an `X-API-Key`
        header; those are not accepted.

````