> ## 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. # Get Import Attempt > Returns one import attempt, showing how an import row was mapped, which guards failed, and whether the record was created or updated. Use it to see why a row failed to import, then fix it with Retry Import (`retryFmv1Import`) or, for an attempt made by an import job, queue another job with Queue Import Job (`queueFmv1ImportJob`). Returns one **import attempt**: a single transform → guard → write pass over an import row, with the transformations and guards it ran with and what each stage produced. The attempt is recorded before its first step runs, and each stage's result is stored as that stage completes, so a `null` result is one the attempt has not reached, or never reached. - **`transformationResult`** — the transformed entity, or the fields that failed to transform. - **`guardResult`** — whether every guard held, and each one that did not. `null` when the guards never ran. - **`writeResult`** — the outcome of the create or update. `null` when no write was attempted, because the transformations or a guard failed. It is stored in the same transaction as the write, so on an attempt whose guards passed, `null` means no entity was written: the attempt is in progress, or it crashed before its write committed. Attempt ids are scoped to their company: an id belonging to another company returns `404`, exactly as an id that exists nowhere does. An attempt whose entity type you may not import reads as `404`, exactly as an id that exists nowhere does. **Required permission:** any one of `event.import`, `exposure.import`, `quote.import`, `submission.import`, `person.import` or `organization.import` or `policy.import`; the attempt's own type's `import` to read it. ## OpenAPI ````yaml /openapi/generated-external-api.yaml get /api/v1/companies/{companyId}/imports/attempts/{importAttemptId} 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/attempts/{importAttemptId}: get: tags: - Imports summary: Get Import Attempt description: > Returns one import attempt, showing how an import row was mapped, which guards failed, and whether the record was created or updated. Use it to see why a row failed to import, then fix it with Retry Import (`retryFmv1Import`) or, for an attempt made by an import job, queue another job with Queue Import Job (`queueFmv1ImportJob`). Returns one **import attempt**: a single transform → guard → write pass over an import row, with the transformations and guards it ran with and what each stage produced. The attempt is recorded before its first step runs, and each stage's result is stored as that stage completes, so a `null` result is one the attempt has not reached, or never reached. - **`transformationResult`** — the transformed entity, or the fields that failed to transform. - **`guardResult`** — whether every guard held, and each one that did not. `null` when the guards never ran. - **`writeResult`** — the outcome of the create or update. `null` when no write was attempted, because the transformations or a guard failed. It is stored in the same transaction as the write, so on an attempt whose guards passed, `null` means no entity was written: the attempt is in progress, or it crashed before its write committed. Attempt ids are scoped to their company: an id belonging to another company returns `404`, exactly as an id that exists nowhere does. An attempt whose entity type you may not import reads as `404`, exactly as an id that exists nowhere does. **Required permission:** any one of `event.import`, `exposure.import`, `quote.import`, `submission.import`, `person.import` or `organization.import` or `policy.import`; the attempt's own type's `import` to read it. operationId: getFmv1ImportAttempt parameters: - $ref: '#/components/parameters/companyId' - name: importAttemptId in: path required: true schema: type: string format: uuid description: The import attempt id. responses: '200': description: The import attempt content: application/json: schema: $ref: '#/components/schemas/ImportAttempt' examples: written: summary: An attempt that passed its guards and created the entity value: id: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42 importRowId: 9a1d4e7b-2c3f-4b8a-8d61-0e5f2a7b3c94 entityType: Submission action: create attemptBatch: october-load transformations: submissionName: submission.name locations: mapOver: submission.sites values: state: me.region guards: - condition: submissionName != null errorMessage: A submission needs a name. transformationResult: status: ok entity: submissionName: Acme Logistics locations: - state: CA - state: NV guardResult: passed: true writeResult: status: ok entityId: 6e2b8f14-3a7c-4d9e-b051-2c8a9f7d4e13 created: true createdAt: '2026-10-22T14:58:02.087Z' updatedAt: '2026-10-22T14:58:02.471Z' transformationFailed: summary: >- An attempt whose transformations failed, so nothing ran after them value: id: 1b7e9d3a-6c2f-4e8b-a5d0-7f3c1e9b2a68 importRowId: 9a1d4e7b-2c3f-4b8a-8d61-0e5f2a7b3c94 entityType: Submission action: null attemptBatch: october-load transformations: locations: mapOver: submission.site values: state: me.region guards: [] transformationResult: status: failed entity: name: Acme Logistics site: region: CA errors: - field: locations code: IMPORT_MAP_OVER_NOT_A_LIST message: >- mapOver path 'submission.site' must resolve to a list in data; found an object guardResult: null writeResult: null createdAt: '2026-10-22T14:51:40.311Z' updatedAt: '2026-10-22T14:51:40.695Z' '400': description: | Bad Request — the import attempt id is not a UUID, or the request carries a query parameter (this endpoint takes none). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidImportAttemptId: summary: Malformed import attempt id value: error: code: INVALID_IMPORT_ATTEMPT_ID message: >- An import attempt id path parameter is required, and must be a UUID. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: > Not Found — no import attempt with this id exists for this company. An id belonging to another company, and an attempt whose entity type you may not import, are reported the same way. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: Unknown import attempt id for this company value: error: code: IMPORT_ATTEMPT_NOT_FOUND message: >- Import attempt 7c9e6679-7425-40de-944b-e07fc1f90ae7 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: 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. 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 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.