> ## 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. # List Import Attempts > Lists import attempts, newest first. Each attempt is one try at mapping an import row into a record and writing it, with what failed if it did. Use it to find failed import rows, filtered by `jobId` for an import job or by `importBatch` for a batch, and open one with Get Import Attempt (`getFmv1ImportAttempt`). Lists the company's **import attempts**, newest first. Each attempt is one transform → guard → write pass over an import row, recorded whether or not the write happened, with the transformations and guards it ran with and what each stage produced. Each item is the whole attempt, as **`GET /imports/attempts/{importAttemptId}`** returns it. ### Filtering Every filter is optional and exact-match; filters combine with AND. - **`importBatch`** — attempts on import rows sent with that `importBatch`. This finds every attempt on a batch's rows, including retries that carry an `attemptBatch` of their own. - **`attemptBatch`** — attempts recorded with that `attemptBatch`. An attempt made by an `import` request takes the request's `importBatch`; a retry carries the `attemptBatch` it was sent with. - **`jobId`** — attempts made by that import job. - **`importRowId`**, **`entityType`**, **`action`** — attempts on one row, of one entity type, or that created or updated. An unknown query parameter, or a filter value outside its allowed values, is a `400`, never an unfiltered or empty page. ### Paging `page` and `pageSize` are the standard 1-based pagination parameters. `totalCount` counts every attempt matching the filters, ignoring the paging. Continue while `page * pageSize < totalCount`. Only attempts whose entity type you may import are listed: a key holding `person.import` alone sees only Person attempts, and `totalCount` counts only those. **Required permission:** `.import` for the `entityType` filter (`person.import` for `Person`); without the filter, any one of `event.import`, `exposure.import`, `quote.import`, `submission.import`, `person.import`, `organization.import` or `policy.import`. ## OpenAPI ````yaml /openapi/generated-external-api.yaml get /api/v1/companies/{companyId}/imports/attempts 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: get: tags: - Imports summary: List Import Attempts description: > Lists import attempts, newest first. Each attempt is one try at mapping an import row into a record and writing it, with what failed if it did. Use it to find failed import rows, filtered by `jobId` for an import job or by `importBatch` for a batch, and open one with Get Import Attempt (`getFmv1ImportAttempt`). Lists the company's **import attempts**, newest first. Each attempt is one transform → guard → write pass over an import row, recorded whether or not the write happened, with the transformations and guards it ran with and what each stage produced. Each item is the whole attempt, as **`GET /imports/attempts/{importAttemptId}`** returns it. ### Filtering Every filter is optional and exact-match; filters combine with AND. - **`importBatch`** — attempts on import rows sent with that `importBatch`. This finds every attempt on a batch's rows, including retries that carry an `attemptBatch` of their own. - **`attemptBatch`** — attempts recorded with that `attemptBatch`. An attempt made by an `import` request takes the request's `importBatch`; a retry carries the `attemptBatch` it was sent with. - **`jobId`** — attempts made by that import job. - **`importRowId`**, **`entityType`**, **`action`** — attempts on one row, of one entity type, or that created or updated. An unknown query parameter, or a filter value outside its allowed values, is a `400`, never an unfiltered or empty page. ### Paging `page` and `pageSize` are the standard 1-based pagination parameters. `totalCount` counts every attempt matching the filters, ignoring the paging. Continue while `page * pageSize < totalCount`. Only attempts whose entity type you may import are listed: a key holding `person.import` alone sees only Person attempts, and `totalCount` counts only those. **Required permission:** `.import` for the `entityType` filter (`person.import` for `Person`); without the filter, any one of `event.import`, `exposure.import`, `quote.import`, `submission.import`, `person.import`, `organization.import` or `policy.import`. operationId: listFmv1ImportAttempts parameters: - name: jobId in: query schema: type: string format: uuid description: Select attempts produced by this transformation job. - $ref: '#/components/parameters/companyId' - name: page in: query required: false schema: type: integer minimum: 1 maximum: 9007199254740991 default: 1 description: > 1-based page number. Defaults to the first page. A `page` above 9007199254740991, or a `page` and `pageSize` whose product skips past that many rows, is a `400`. - name: pageSize in: query required: false schema: type: integer minimum: 1 default: 50 maximum: 100 description: > Number of attempts per page (default 50, maximum 100). A `pageSize` above 100 is **silently clamped to 100** rather than rejected; read the returned `pageSize`. Each attempt carries its transformations, guards and results, so pages stay small. - name: importBatch in: query required: false schema: type: string minLength: 1 description: Only attempts on import rows sent with this `importBatch`. - name: attemptBatch in: query required: false schema: type: string minLength: 1 description: Only attempts recorded with this `attemptBatch`. - name: importRowId in: query required: false schema: type: string format: uuid description: Only attempts on this import row. - name: entityType in: query required: false schema: type: string enum: - Event - Exposure - Quote - Submission - Person - Organization - Policy description: >- Only attempts importing this entity type. A type you may not import is a `403`. - name: action in: query required: false schema: type: string enum: - create - update description: | Only attempts that created, or updated, an entity. An attempt whose transformations failed before the entity existed has no `action` and matches neither. responses: '200': description: One page of the company's import attempts content: application/json: schema: $ref: '#/components/schemas/ImportAttemptsPageResponse' examples: attempts: summary: A row's first attempt failed a guard, and its retry passed value: items: - id: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42 importRowId: 9a1d4e7b-2c3f-4b8a-8d61-0e5f2a7b3c94 entityType: Submission action: create attemptBatch: fix-broker-names transformations: submissionName: submission.name brokerName: broker.fullName guards: - condition: brokerName != null errorMessage: A submission needs a broker name. transformationResult: status: ok entity: submissionName: Acme Logistics brokerName: Dana Reyes guardResult: passed: true writeResult: status: ok entityId: 6e2b8f14-3a7c-4d9e-b051-2c8a9f7d4e13 created: true createdAt: '2026-10-22T15:04:11.512Z' updatedAt: '2026-10-22T15:04:11.896Z' - id: 1b7e9d3a-6c2f-4e8b-a5d0-7f3c1e9b2a68 importRowId: 9a1d4e7b-2c3f-4b8a-8d61-0e5f2a7b3c94 entityType: Submission action: create attemptBatch: october-load transformations: submissionName: submission.name brokerName: broker.name guards: - condition: brokerName != null errorMessage: A submission needs a broker name. transformationResult: status: ok entity: submissionName: Acme Logistics guardResult: passed: false failures: - index: 0 errorMessage: A submission needs a broker name. reason: refused writeResult: null createdAt: '2026-10-22T14:58:02.087Z' updatedAt: '2026-10-22T14:58:02.471Z' totalCount: 2 page: 1 pageSize: 50 empty: summary: No attempt matches the filters value: items: [] totalCount: 0 page: 1 pageSize: 50 '400': description: > Bad Request — an unknown query parameter, a filter value outside its allowed values (`importRowId` not a UUID is `INVALID_IMPORT_ROW_ID`, an unknown `entityType` is `INVALID_ENTITY_TYPE`, an unknown `action` is `INVALID_ACTION`, an empty batch key is `BadRequest`), or `page` / `pageSize` not a positive integer or past the pagination ceiling. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unknownQueryKey: summary: A misspelt filter is refused, not ignored value: error: code: InvalidRequest message: >- Unknown key(s) in import attempts query: importbatch. Allowed keys: companyId, page, pageSize, importRowId, entityType, action, importBatch, attemptBatch invalidEntityType: summary: Unknown entityType value: error: code: INVALID_ENTITY_TYPE message: >- Invalid entityType: must be one of Event, Exposure, Quote, Submission, Person, Organization, Policy invalidPageSize: summary: Non-positive-integer pagination value value: error: code: BadRequest message: 'Invalid pageSize: must be a positive integer' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '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: ImportAttemptsPageResponse: type: object description: One page of a company's import attempts, newest first. required: - items - totalCount - page - pageSize properties: items: type: array description: The attempts on this page, newest first. items: $ref: '#/components/schemas/ImportAttempt' totalCount: type: integer description: How many attempts match the filters, ignoring the pagination. page: type: integer minimum: 1 description: The effective one-based page number. pageSize: type: integer minimum: 1 maximum: 100 description: The effective page size, default 50 and clamped to 100. 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 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.