> ## 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. # Queue Import Job > Maps stored import rows into records in bulk, in the background, for a migration or spreadsheet load. Store the rows first with Import Rows (`ingestFmv1ImportRows`), then follow the job with Get Import Job (`getFmv1ImportJob`) and List Import Attempts (`listFmv1ImportAttempts`) filtered by `jobId`. To fix failed rows or change the mapping, queue another job; for one record with an immediate result, use Import Entity (`createFmv1Import`). Queues transformations over stored import rows. The response contains the job ID and returns before mapping or writing. A new job is also how to retry or change a mapping; no re-import is needed. Jobs run in queue order within a company, with one attempt per result. Different jobs can map the same row into different entity types. Expressions read `row` (the first source JSON value) and `rows` (all source JSON values for this result). Mapping starts with an empty target entity. Use `groupBy` to combine related rows. Within a result rows are ordered by storage time, then row ID; do not assume a source record kind is first. Selectors are snapshotted when the job is accepted. Mapping and guard failures are recorded on attempts and processing continues. Queue dispatch failures leave the job queued for automatic recovery. GET the job and list attempts with `jobId` to follow progress. Policy jobs require `policyMode: whole-policy` or `single-transaction` and refuse `groupBy`. Their transformations produce the corresponding policy command envelope. Both modes support execution and `dryRun: true`. Single commands return one receipt; whole-policy rows return ordered transaction receipts. See [Policy import contracts](/api-reference/imports/overview#policy-import-contracts). **Required permission:** the target entity type's import permission (`policy.import` for `Policy`, `exposure.import` for `Exposure`, for example). Selecting rows stored by the synchronous endpoint additionally requires their original entity type's import permission. Permissions and API-key revocation are checked again by the worker. ## OpenAPI ````yaml /openapi/generated-external-api.yaml post /api/v1/companies/{companyId}/imports/jobs 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/jobs: post: tags: - Imports summary: Queue Import Job description: > Maps stored import rows into records in bulk, in the background, for a migration or spreadsheet load. Store the rows first with Import Rows (`ingestFmv1ImportRows`), then follow the job with Get Import Job (`getFmv1ImportJob`) and List Import Attempts (`listFmv1ImportAttempts`) filtered by `jobId`. To fix failed rows or change the mapping, queue another job; for one record with an immediate result, use Import Entity (`createFmv1Import`). Queues transformations over stored import rows. The response contains the job ID and returns before mapping or writing. A new job is also how to retry or change a mapping; no re-import is needed. Jobs run in queue order within a company, with one attempt per result. Different jobs can map the same row into different entity types. Expressions read `row` (the first source JSON value) and `rows` (all source JSON values for this result). Mapping starts with an empty target entity. Use `groupBy` to combine related rows. Within a result rows are ordered by storage time, then row ID; do not assume a source record kind is first. Selectors are snapshotted when the job is accepted. Mapping and guard failures are recorded on attempts and processing continues. Queue dispatch failures leave the job queued for automatic recovery. GET the job and list attempts with `jobId` to follow progress. Policy jobs require `policyMode: whole-policy` or `single-transaction` and refuse `groupBy`. Their transformations produce the corresponding policy command envelope. Both modes support execution and `dryRun: true`. Single commands return one receipt; whole-policy rows return ordered transaction receipts. See [Policy import contracts](/api-reference/imports/overview#policy-import-contracts). **Required permission:** the target entity type's import permission (`policy.import` for `Policy`, `exposure.import` for `Exposure`, for example). Selecting rows stored by the synchronous endpoint additionally requires their original entity type's import permission. Permissions and API-key revocation are checked again by the worker. operationId: queueFmv1ImportJob parameters: - $ref: '#/components/parameters/companyId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/QueueImportJobRequest' examples: batchMapping: summary: Map a stored batch into exposures value: entityType: Exposure source: importBatch: october-load transformations: exposureName: row.name exposureType: '''company''' guards: - condition: exposureName != null errorMessage: A name is required attemptBatch: mapping-v2 groupedRows: summary: Combine related source rows into one result value: entityType: Exposure source: importBatch: october-load groupBy: - accountId transformations: exposureName: rows[0].accountName exposureType: '''company''' wholePolicyContract: summary: Queue a whole-policy mapping value: entityType: Policy policyMode: whole-policy source: importBatch: policy-terms transformations: term: row.term segments: row.segments attemptBatch: policy-contract-v1 singleTransactionContract: summary: Queue single cancellation commands value: entityType: Policy policyMode: single-transaction dryRun: true source: importBatch: policy-cancellations transformations: action: '''CANCEL''' policyId: row.policyId cancellationDate: row.cancellationDate responses: '202': description: Job accepted for background execution. content: application/json: schema: type: object required: - id properties: id: type: string format: uuid examples: accepted: summary: Job queued value: id: 550e8400-e29b-41d4-a716-446655440003 '400': description: >- Invalid job, missing or inaccessible explicit source IDs, or a group larger than 1000 rows. No job is queued. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '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: QueueImportJobRequest: oneOf: - $ref: '#/components/schemas/QueueEntityImportJobRequest' - $ref: '#/components/schemas/QueuePolicyImportJobRequest' 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 QueueEntityImportJobRequest: type: object additionalProperties: false required: - entityType - source properties: entityType: type: string enum: - Event - Exposure - Quote - Submission - Person - Organization description: The entity type this job writes, independent of its source rows. source: type: object additionalProperties: false description: >- At least one selector is required. Selectors combine with AND. Membership is snapshotted when queued; later rows are excluded. Explicit IDs must all exist, be accessible and match the other selectors. properties: importRowIds: type: array minItems: 1 maxItems: 1000 items: type: string format: uuid importBatch: type: string minLength: 1 filter: type: object additionalProperties: true description: >- PostgreSQL JSON containment filter on the original data. When used alone it must be non-empty. For example, {"kind":"policy"} selects objects containing that pair. groupBy: type: array minItems: 1 maxItems: 20 items: type: string minLength: 1 description: >- Optional JSON path segments. Rows with equal non-null values at this path produce one result together; missing/null values stay separate. Maximum 1000 rows per result. Omitted means one result per row. quoteMode: type: string enum: - restore-bound description: >- Quote jobs only, without groupBy. Restore an already bound legacy quote from its retained source identity, original bound/applied_to_policy status and existing policy. Existing quotes retain their identity and parent links; conflicting statuses or source evidence are refused. This does not bind a policy or generate invoices, recommended forms or lifecycle packets. See the historical bound quote contract in the import overview. transformations: $ref: '#/components/schemas/ImportTransformations' guards: $ref: '#/components/schemas/ImportGuards' attemptBatch: type: string nullable: true minLength: 1 description: Optional label applied to every attempt created by this job. QueuePolicyImportJobRequest: type: object additionalProperties: false required: - entityType - source - policyMode properties: entityType: type: string enum: - Policy description: The entity type this job writes, independent of its source rows. source: type: object additionalProperties: false description: >- At least one selector is required. Selectors combine with AND. Membership is snapshotted when queued; later rows are excluded. Explicit IDs must all exist, be accessible and match the other selectors. properties: importRowIds: type: array minItems: 1 maxItems: 1000 items: type: string format: uuid importBatch: type: string minLength: 1 filter: type: object additionalProperties: true description: >- PostgreSQL JSON containment filter on the original data. When used alone it must be non-empty. For example, {"kind":"policy"} selects objects containing that pair. transformations: $ref: '#/components/schemas/ImportTransformations' guards: $ref: '#/components/schemas/ImportGuards' attemptBatch: type: string nullable: true minLength: 1 description: Optional label applied to every attempt created by this job. policyMode: type: string enum: - whole-policy - single-transaction description: >- Selects the schema of the transformed policy command: WholePolicyImport or SinglePolicyTransactionImport. dryRun: type: boolean default: false description: >- Validate every planned policy transaction against the preceding simulated state without persisting policy state; retain the import job and attempt. Both modes validate without domain persistence; save-only calculations and unsupported vendor-tax lifecycle changes are refused. description: >- One row is one policy term or one transaction; groupBy is refused. Both modes support execution and dry runs. Single-transaction mode executes one command and returns one transaction receipt. 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. 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.