> ## 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. # Retry Import > Fixes a failed import by running a stored row again with corrected `transformations` or `guards`, without sending the data again. It applies to rows stored by Import Entity (`createFmv1Import`); rows stored by Import Rows (`ingestFmv1ImportRows`), and attempts made by an import job, are run again by queueing another job with Queue Import Job (`queueFmv1ImportJob`). Find the failed row or attempt with List Import Attempts (`listFmv1ImportAttempts`). Retries a stored import row: fixes a failed import with new transformations or guards, without sending the data again. Name the row by `importRowId`, to retry it with the transformations and guards you send, or by `importAttemptId`, to retry that attempt's row with the attempt's own. The retry reads the row's `data` and entity type, then runs the steps of Import Entity after the row is stored: the **transformations** turn `data.` into an entity, the **guards** run against it, and the entity is **created**, or **updated** when the transformed entity carries an `id`. A row that already created its entity creates another unless the transformations set `id`, such as with `LOOKUP`. A row cannot be retried as another entity type. Every retry of a row you can import answers `201` with the new **import attempt**, linked to the same row, whether or not the entity was written: check `importAttempt.writeResult`. Its `attemptBatch` is the request's. No row is stored. A malformed request is a `400`, and records nothing: both ids or neither, `transformations` or `guards` sent with an `importAttemptId`, an id that is not a UUID, a blank `attemptBatch`, a body key this endpoint does not take, or any query parameter. There is no `Idempotency-Key`: sending the same retry twice records two attempts, and may write twice. **Required permission:** `.import` for the stored row's entity type, such as `submission.import` to retry a Submission row. The row's type is known only once it is read, so a caller holding no import permission is a `403`, and a row or attempt of a type you cannot import is a `404`, the same as an id that exists nowhere. ## OpenAPI ````yaml /openapi/generated-external-api.yaml post /api/v1/companies/{companyId}/imports/retry 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}/imports/retry: post: tags: - Imports summary: Retry Import description: > Fixes a failed import by running a stored row again with corrected `transformations` or `guards`, without sending the data again. It applies to rows stored by Import Entity (`createFmv1Import`); rows stored by Import Rows (`ingestFmv1ImportRows`), and attempts made by an import job, are run again by queueing another job with Queue Import Job (`queueFmv1ImportJob`). Find the failed row or attempt with List Import Attempts (`listFmv1ImportAttempts`). Retries a stored import row: fixes a failed import with new transformations or guards, without sending the data again. Name the row by `importRowId`, to retry it with the transformations and guards you send, or by `importAttemptId`, to retry that attempt's row with the attempt's own. The retry reads the row's `data` and entity type, then runs the steps of Import Entity after the row is stored: the **transformations** turn `data.` into an entity, the **guards** run against it, and the entity is **created**, or **updated** when the transformed entity carries an `id`. A row that already created its entity creates another unless the transformations set `id`, such as with `LOOKUP`. A row cannot be retried as another entity type. Every retry of a row you can import answers `201` with the new **import attempt**, linked to the same row, whether or not the entity was written: check `importAttempt.writeResult`. Its `attemptBatch` is the request's. No row is stored. A malformed request is a `400`, and records nothing: both ids or neither, `transformations` or `guards` sent with an `importAttemptId`, an id that is not a UUID, a blank `attemptBatch`, a body key this endpoint does not take, or any query parameter. There is no `Idempotency-Key`: sending the same retry twice records two attempts, and may write twice. **Required permission:** `.import` for the stored row's entity type, such as `submission.import` to retry a Submission row. The row's type is known only once it is read, so a caller holding no import permission is a `403`, and a row or attempt of a type you cannot import is a `404`, the same as an id that exists nowhere. operationId: retryFmv1Import parameters: - $ref: '#/components/parameters/companyId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RetryImportRequest' examples: retryRowWithNewTransformations: summary: Retry a row with new transformations value: importRowId: 9c5e1a3d-7f2b-4d8e-a6c4-1b9f3e7d2a58 transformations: locations: mapOver: submission.sites values: state: region attemptBatch: october-fix retryAttemptUnderNewBatch: summary: Retry an attempt as it ran, under another attempt batch description: > Reuses the attempt's transformations and guards, such as after the company's configuration or a referenced record has been fixed. value: importAttemptId: 2d6b9f3a-8e1c-4a7d-b2e9-6f4c1a8d3e57 attemptBatch: october-rerun fixWithLookup: summary: Fix a failed attempt by linking the record LOOKUP finds description: > The first attempt sent the employer's tax id where the field model takes the Organization's id, and the write was refused. The retry sets `employer` to the id of the one Organization with that tax id. value: importRowId: 6f2a9d4c-1e7b-4c3a-8b59-3d1e7f9a2c04 transformations: employer: 'LOOKUP(''Organization'', { taxId: source.employerTaxId })' attemptBatch: october-fix responses: '201': description: > A new attempt was recorded on the row. Whether the entity was written is the attempt's `writeResult`. content: application/json: schema: $ref: '#/components/schemas/ImportResponse' examples: retriedRow: summary: The retried row's entity was created value: importRowId: 9c5e1a3d-7f2b-4d8e-a6c4-1b9f3e7d2a58 importAttempt: id: 4a8d2f6c-3e1b-4b7a-9c05-6e2d8f1a3b97 importRowId: 9c5e1a3d-7f2b-4d8e-a6c4-1b9f3e7d2a58 entityType: Submission action: create attemptBatch: october-fix transformations: locations: mapOver: submission.sites values: state: region guards: [] transformationResult: status: ok entity: name: Acme Logistics sites: - region: CA locations: - state: CA guardResult: passed: true writeResult: status: ok entityId: 1f8d3b7a-6e2c-4a9d-8b51-4c7e2a9f3d06 created: true createdAt: '2026-10-23T16:12:40.318Z' updatedAt: '2026-10-23T16:12:40.702Z' retriedAttempt: summary: >- The attempt ran again with its own transformations and guards value: importRowId: 3a9f7c1e-2d6b-4e8a-9b45-7c1e3f9d2b60 importAttempt: id: 8b3e1d7f-5a2c-4f9e-a6d1-2c7b9e4f1a35 importRowId: 3a9f7c1e-2d6b-4e8a-9b45-7c1e3f9d2b60 entityType: Submission action: create attemptBatch: october-rerun transformations: {} guards: [] transformationResult: status: ok entity: submissionName: Acme Logistics effectiveDate: '2026-01-01' expirationDate: '2027-01-01' guardResult: passed: true writeResult: status: ok entityId: 7d2c9a4e-1f6b-4e3a-8c57-9b1e4d7a2f60 created: true createdAt: '2026-10-23T16:14:05.772Z' updatedAt: '2026-10-23T16:14:06.156Z' fixedWithLookup: summary: LOOKUP found the employer, and the person was created value: importRowId: 6f2a9d4c-1e7b-4c3a-8b59-3d1e7f9a2c04 importAttempt: id: 5c1e8a3f-9d4b-4a2e-b7f6-3a9d1c5e8b72 importRowId: 6f2a9d4c-1e7b-4c3a-8b59-3d1e7f9a2c04 entityType: Person action: create attemptBatch: october-fix transformations: employer: >- LOOKUP('Organization', { taxId: source.employerTaxId }) guards: [] transformationResult: status: ok entity: name: Pat Lee employer: 4b9e2d7a-1c5f-4a3e-8d62-9f1b3e7c2a85 guardResult: passed: true writeResult: status: ok entityId: 2e7b4d9a-6c1f-4a8e-b3d5-8f2a1c6e9b47 created: true createdAt: '2026-10-23T16:15:31.209Z' updatedAt: '2026-10-23T16:15:31.593Z' '400': description: > Bad Request — the request is malformed, and nothing was recorded: both ids or neither, `transformations` or `guards` beside an `importAttemptId`, an id that is not a UUID, a transformation or guard of the wrong shape, a blank `attemptBatch`, a body key this endpoint does not take (`entityType` included), or any query parameter. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notExactlyOneId: summary: Both ids, or neither value: error: code: VALIDATION_ERROR message: Send exactly one of importRowId or importAttemptId. userMessages: - Send exactly one of importRowId or importAttemptId. details: - message: Send exactly one of importRowId or importAttemptId. transformationsWithAttempt: summary: Transformations sent with an importAttemptId value: error: code: VALIDATION_ERROR message: >- transformations: A retry by importAttemptId reuses that attempt’s transformations and guards; send importRowId to retry with new ones. userMessages: - >- A retry by importAttemptId reuses that attempt’s transformations and guards; send importRowId to retry with new ones. details: - field: transformations message: >- A retry by importAttemptId reuses that attempt’s transformations and guards; send importRowId to retry with new ones. invalidImportRowId: summary: An import row id that is not a UUID value: error: code: INVALID_IMPORT_ROW_ID message: 'Invalid importRowId: must be a UUID.' userMessages: - 'Invalid importRowId: must be a UUID.' invalidImportAttemptId: summary: An import attempt id that is not a UUID value: error: code: INVALID_IMPORT_ATTEMPT_ID message: 'Invalid importAttemptId: must be a UUID.' userMessages: - 'Invalid importAttemptId: must be a UUID.' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: | No row or attempt with that id that you can import: unknown, another company's, or of an entity type you hold no import permission for. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: importRowNotFound: summary: Unknown import row id for this company value: error: code: IMPORT_ROW_NOT_FOUND message: >- Import row 9c5e1a3d-7f2b-4d8e-a6c4-1b9f3e7d2a58 not found importAttemptNotFound: summary: Unknown import attempt id for this company value: error: code: IMPORT_ATTEMPT_NOT_FOUND message: >- Import attempt 2d6b9f3a-8e1c-4a7d-b2e9-6f4c1a8d3e57 not found '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] - ApiKeyAuth: [] components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier schemas: RetryImportRequest: type: object description: > A new attempt on a stored import row. Name the row by exactly one of `importRowId` or `importAttemptId`: - **`importRowId`** retries the row with the `transformations` and `guards` you send (none of each when omitted, as on Import Entity). - **`importAttemptId`** retries that attempt's row with the attempt's own `transformations` and `guards`. Sending either alongside it is a `400`; retry by `importRowId` to change them. The data is the row's, as it was first sent, and so is the entity type: a row cannot be retried as another entity type. additionalProperties: false properties: importRowId: type: string format: uuid description: >- The import row to retry, from an Import Entity response or List Import Rows. importAttemptId: type: string format: uuid description: > An attempt whose row to retry, reusing its transformations and guards. transformations: allOf: - $ref: '#/components/schemas/ImportTransformations' description: > Only with `importRowId`; none when omitted. The same format as Import Entity's. guards: allOf: - $ref: '#/components/schemas/ImportGuards' description: > Only with `importRowId`; none when omitted. The same format as Import Entity's. attemptBatch: type: string nullable: true description: > Your key grouping this retry with others for later review, stored as the new attempt's `attemptBatch`. The row keeps its own `importBatch`, so List Import Attempts by `importBatch` still finds the retry. Omit it or send `null` for none; a blank key is refused. ImportResponse: type: object description: The stored import row's id and the attempt this request recorded. required: - importRowId - importAttempt properties: importRowId: type: string format: uuid description: > The import row storing `data` as sent. Read it with Get Import Row; a failed import is fixed by retrying this row, not by sending the data again. importAttempt: $ref: '#/components/schemas/ImportAttempt' 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 ImportTransformations: type: object description: > How `data.` becomes an entity in this company's field model: one entry per field reference id (camelCase). Each value is either a JEXL expression string that reads the data's top-level keys by name (`submission.name`, `broker.email`), or a mapping for a list of child objects: `{ "mapOver": "", "values": { "": "" } }`. Inside `values`, bare names and `me` are the current element, `parent` is the object holding the list and `root` is the whole `data`. A child value may itself be a mapping; its `mapOver` path reads the current scope (for example `me.locations`). A `{ "values": { ... } }` constructor without `mapOver` builds one object in the surrounding scope and can contain mapped lists. At every depth, `root` remains the original data. Every field of `data.` without a transformation is kept as sent. A transformed entity with an `id` updates that entity; otherwise one is created. Keys the company's field model does not declare are dropped before an entity write. Policy jobs instead construct the whole-policy or single-transaction command envelope; envelope keys are validated by that contract. additionalProperties: oneOf: - type: string description: A JEXL expression. - type: object required: - mapOver - values additionalProperties: false properties: mapOver: type: string description: | A dotted path into `data` that resolves to a list, such as `submission.locations`; a numeric segment indexes a list. values: $ref: '#/components/schemas/ImportTransformations' type: object description: One expression or nested mapping per child object key. - type: object required: - values additionalProperties: false properties: values: $ref: '#/components/schemas/ImportTransformations' description: >- Construct one object in the surrounding scope, including nested mappings. ImportGuards: type: array description: > Conditions that must hold for the write to proceed, evaluated against the transformed entity, reading its fields by bare name. Only a strict `true` passes, and a condition that cannot be evaluated fails. They run in addition to the company's own entity invariants. items: type: object required: - condition - errorMessage additionalProperties: false properties: condition: type: string description: A JEXL condition. errorMessage: type: string description: Reported on the attempt when the condition does not hold. ImportAttempt: type: object description: > One **import attempt**: a single transform → guard → write pass over an import row. An `import` request records the first attempt on its row, and each `retryImport` records another. Attempts are stored whether or not the write happened. The attempt is recorded before its first step runs, with every result `null`, and each step's result is stored on it as the step completes: `transformationResult` and `action`, then `guardResult`, then `writeResult`. The `import` and `retryImport` responses answer with the finished attempt. `writeResult` is stored in the same transaction as the entity write, so the two commit together or not at all. An attempt whose `guardResult` passed and whose `writeResult` is `null` wrote no entity: it is still in progress, or it crashed before its write committed. Its import row can be retried; the retry cannot create a second entity alongside one the crashed attempt wrote. required: - id - importRowId - entityType - action - attemptBatch - transformations - guards - transformationResult - guardResult - writeResult - createdAt - updatedAt properties: jobId: type: string format: uuid nullable: true description: Owning transformation job, or null for a synchronous attempt. sourceRowIds: type: array nullable: true items: type: string format: uuid description: >- Every source row for this result, in evaluation order. Null for synchronous attempts; importRowId always identifies the first source row. id: type: string format: uuid description: The import attempt id. importRowId: type: string format: uuid description: The import row this attempt ran against. entityType: type: string enum: - Event - Exposure - Quote - Submission - Person - Organization - Policy description: >- The job target type, or the original row type for a synchronous attempt. action: type: string nullable: true enum: - create - update - null description: > `update` when the transformed entity carried an `id`, else `create`. `null` until the transformations succeed, and for good when they failed before the transformed entity existed. attemptBatch: type: string nullable: true description: > The caller's optional key grouping attempts. An attempt recorded by an `import` request takes that request's `importBatch`; a retry carries the `attemptBatch` it was sent with. transformations: type: object additionalProperties: true description: > The transformations the attempt ran with, as sent: one entry per FMV1 field reference id, each a JEXL expression string or a `{ "mapOver": "", "values": { "": "" } }` mapping. Stored even when they are invalid; the failure is then reported in `transformationResult`. guards: type: array description: | The guards the attempt ran with, as sent. Each is `{ "condition": "", "errorMessage": "" }`. items: {} transformationResult: nullable: true description: > The outcome of applying the transformations; `null` until they have run. `status: ok` carries the transformed `entity`. `status: failed` carries a partial `entity`, with every failed field absent, and one entry in `errors` per failure. type: object required: - status - entity properties: status: type: string enum: - ok - failed entity: type: object additionalProperties: true description: The transformed entity, before it was written. errors: type: array description: Present only when `status` is `failed`. items: type: object required: - field - code - message properties: field: type: string description: > The transformation's field reference id; empty when the failure is the whole input's, such as a missing entity key in `data`. path: type: string description: >- Where inside a `mapOver` field, such as `locations[2].state`. code: type: string description: > Why it failed, such as `IMPORT_ENTITY_DATA_MISSING`, `IMPORT_INVALID_TRANSFORMATIONS`, `IMPORT_MAP_OVER_NOT_A_LIST` or `JEXL_EVALUATION_ERROR`. A `LOOKUP` failure is `IMPORT_LOOKUP_AMBIGUOUS` (several entities match), `IMPORT_LOOKUP_FORBIDDEN` (the caller may not read the entity type) or `IMPORT_LOOKUP_INVALID` (arguments it cannot run). message: type: string guardResult: nullable: true description: | The outcome of the guards; `null` until the guards have run, and for good when the transformations failed. `passed: false` lists every guard that did not hold, not only the first. type: object required: - passed properties: passed: type: boolean failures: type: array description: Present only when `passed` is `false`. items: type: object required: - index - errorMessage - reason properties: index: type: integer description: The guard's position in `guards`. errorMessage: type: string description: > For `refused`, the guard's `errorMessage`. For `error`, the guard could not be evaluated and the message is `The entity invariant "" could not be checked.` reason: type: string enum: - refused - error description: > `refused` — the condition gave anything but `true`. `error` — the condition could not be evaluated. writeResult: type: object nullable: true description: > The outcome of the create or update; `null` when no write was attempted, because the transformations or a guard failed, and until the write's outcome is stored. It is stored in the same transaction as the write, so `null` on an attempt whose guards passed means no entity was written: the attempt is in progress, or it crashed. `status: ok` names the entity written in `entityId`, and `created` says whether this attempt created it (`false`: it updated it). Policy writes also require a nonempty ordered list of committed transaction receipts. `status: validated` is a policy dry-run plan (refused for other entity types), with no entity or transaction IDs and no persisted policy writes. Whole-policy execution and dry runs produce these results. Both policy modes support execution and dry runs. `status: failed` is the refusal the entity create or update endpoint would have answered with: its `httpStatus`, and the error's `code`, `message`, `userMessages` and `details`. required: - status properties: status: type: string enum: - ok - failed - validated dryRun: type: boolean enum: - true description: Present only for a validated policy dry run. transactions: type: array minItems: 1 description: >- Ordered committed receipts when status is ok; planned action/date entries when status is validated. items: oneOf: - $ref: '#/components/schemas/PolicyImportTransactionReceipt' - type: object additionalProperties: false required: - action - effectiveDate properties: action: type: string enum: - NEW_BUSINESS - ENDORSE - CANCEL - REINSTATE - RENEW effectiveDate: type: string format: date entityId: type: string description: Present only when `status` is `ok`. created: type: boolean description: Present only when `status` is `ok`. httpStatus: type: integer description: Present only when `status` is `failed`. code: type: string description: Present only when `status` is `failed`. message: type: string description: Present only when `status` is `failed`. userMessages: type: array description: Present only when `status` is `failed`. items: type: string details: type: array description: > May be present when `status` is `failed`: the same entries the entity endpoints' error responses carry. items: type: object required: - message properties: field: type: string code: type: string reason: type: string expected: type: string message: type: string createdAt: type: string format: date-time description: When the attempt was recorded, before its first step ran. updatedAt: type: string format: date-time description: > When a step's result was last stored on the attempt. On an attempt with a `null` result still to come, an `updatedAt` long past means it crashed. PolicyImportTransactionReceipt: type: object additionalProperties: false required: - transactionId - policyId - policyVersion - action - effectiveDate properties: transactionId: type: string format: uuid policyId: type: string format: uuid policyVersion: type: integer minimum: 1 action: type: string enum: - NEW_BUSINESS - ENDORSE - CANCEL - REINSTATE - RENEW effectiveDate: type: string format: date 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. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- User-principal OAuth 2.0 Bearer authentication. Send a user-scoped Auth0 access token (audience = the app API audience) as `Authorization: Bearer `. The request resolves to the user's identity and is authorized by their Role on the `{companyId}` in the path — the same role-based permissions the web app enforces. This is the path the MCP connector uses to act on a user's behalf; endpoints that accept it list both `BearerAuth` and `ApiKeyAuth`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.