> ## 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. # Close Event > Closes an event (a claim or an incident) as of a date you choose, in one atomic call: the event's status becomes `closed`, its **Close Date** is stamped with the date you send, and a `close` entry is appended to the event's open/close-history log. **Use this instead of setting `eventStatus`.** A `PATCH` to `/entities/event/{entityId}` that changes `eventStatus` is rejected with a `409` (`GuardedStatusFieldWrite`). The status and the log have to move together — the lifecycle dates a claim reports (opened on, previously closed on, re-opened on) are derived from that log, so a status change that skipped it would silently misreport them. Creating an event with an explicit `eventStatus` is unaffected: a historical import still loads closed claims directly. **`effectiveOnDate` is the date the closure TAKES EFFECT** — typically the day the adjuster closed the file, which may be earlier than today. The date you *acted* is recorded separately by the platform and is not settable. **The log cannot run backwards.** `effectiveOnDate` must be on or after the last entry already in the event's log; an earlier date returns `409` (`EventLifecycleDateOutOfOrder`), and the message names the date it has to clear. The same day as the previous entry is allowed. In practice this means an event cannot be closed before the day it was opened. **Required permission:** `company.claim:create` ## OpenAPI ````yaml /openapi/generated-external-api.yaml post /api/v1/companies/{companyId}/events/{eventId}/close 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}/close: post: tags: - Event Lifecycle summary: Close Event description: > Closes an event (a claim or an incident) as of a date you choose, in one atomic call: the event's status becomes `closed`, its **Close Date** is stamped with the date you send, and a `close` entry is appended to the event's open/close-history log. **Use this instead of setting `eventStatus`.** A `PATCH` to `/entities/event/{entityId}` that changes `eventStatus` is rejected with a `409` (`GuardedStatusFieldWrite`). The status and the log have to move together — the lifecycle dates a claim reports (opened on, previously closed on, re-opened on) are derived from that log, so a status change that skipped it would silently misreport them. Creating an event with an explicit `eventStatus` is unaffected: a historical import still loads closed claims directly. **`effectiveOnDate` is the date the closure TAKES EFFECT** — typically the day the adjuster closed the file, which may be earlier than today. The date you *acted* is recorded separately by the platform and is not settable. **The log cannot run backwards.** `effectiveOnDate` must be on or after the last entry already in the event's log; an earlier date returns `409` (`EventLifecycleDateOutOfOrder`), and the message names the date it has to clear. The same day as the previous entry is allowed. In practice this means an event cannot be closed before the day it was opened. **Required permission:** `company.claim:create` operationId: closeEvent parameters: - $ref: '#/components/parameters/companyId' - $ref: '#/components/parameters/eventIdPath' requestBody: required: true content: application/json: schema: type: object required: - effectiveOnDate properties: effectiveOnDate: $ref: '#/components/schemas/EventLifecycleDate' examples: closeOnDate: summary: Close the claim effective 5 August 2026 value: effectiveOnDate: year: 2026 month: 8 day: 5 responses: '200': description: The event was closed. content: application/json: schema: type: object required: - eventId - eventStatus properties: eventId: type: string format: uuid description: The event that was closed. eventStatus: type: string enum: - closed description: The event's status after the call. examples: closed: summary: Event closed value: eventId: 550e8400-e29b-41d4-a716-446655440020 eventStatus: closed '400': description: > `effectiveOnDate` is missing, incomplete, outside the 1900-2200 window, or not a real calendar day; 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' '409': description: > The event cannot be closed: it is already `closed` (`EventAlreadyClosed`), or `effectiveOnDate` is earlier than the last entry in its open/close-history log (`EventLifecycleDateOutOfOrder`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: alreadyClosed: summary: Event is already closed value: error: code: EventAlreadyClosed message: >- Event 550e8400-e29b-41d4-a716-446655440020 is already closed userMessages: - >- Event 550e8400-e29b-41d4-a716-446655440020 is already closed dateOutOfOrder: summary: The close date precedes the last lifecycle entry value: error: code: EventLifecycleDateOutOfOrder message: >- Event 550e8400-e29b-41d4-a716-446655440020 cannot record a lifecycle action effective 2026-02-15: it is earlier than the last entry in the open/close-history log (2026-03-01) userMessages: - >- Event 550e8400-e29b-41d4-a716-446655440020 cannot record a lifecycle action effective 2026-02-15: it is earlier than the last entry in the open/close-history log (2026-03-01) '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: EventLifecycleDate: type: object description: > The calendar day a lifecycle action takes effect. Deliberately narrower than [Fmv1Date](/api-reference/object-primitives/date): a lifecycle action records a wall-clock DAY, so there is no `timezone` and no ISO `{ date: "YYYY-MM-DD" }` alternative — send `year`, `month` and `day`. Any other key is ignored. The date must be a real calendar day (`2026-02-31` is rejected) and fall between the years 1900 and 2200. required: - year - month - day properties: year: type: integer minimum: 1900 maximum: 2200 description: Four-digit calendar year (e.g. 2026) month: type: integer minimum: 1 maximum: 12 description: Month, 1-based (1=January, 12=December) day: type: integer minimum: 1 maximum: 31 description: Day of month, 1-based (1-31) 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 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 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. ````