curl --request POST \
--url https://go.aiinsurance.io/api/v1/companies/{companyId}/imports \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"entityType": "Submission",
"data": {
"submission": {
"name": "Acme Logistics",
"sourceSystemCode": "SUB-1042"
}
},
"transformations": {
"submissionName": "submission.name"
},
"importBatch": "october-load"
}
'{
"importRowId": "9a1d4e7b-2c3f-4b8a-8d61-0e5f2a7b3c94",
"importAttempt": {
"id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
"importRowId": "9a1d4e7b-2c3f-4b8a-8d61-0e5f2a7b3c94",
"entityType": "Submission",
"action": "create",
"attemptBatch": "october-load",
"transformations": {
"submissionName": "submission.name"
},
"guards": [],
"transformationResult": {
"status": "ok",
"entity": {
"name": "Acme Logistics",
"sourceSystemCode": "SUB-1042",
"submissionName": "Acme Logistics"
}
},
"guardResult": {
"passed": true
},
"writeResult": {
"status": "ok",
"entityId": "6e2b8f14-3a7c-4d9e-b051-2c8a9f7d4e13",
"created": true
},
"createdAt": "2026-10-23T14:58:02.087Z",
"updatedAt": "2026-10-23T14:58:02.471Z"
}
}Import Entity
Imports one record from another system, or one spreadsheet row sent as JSON,
as a claim (Event), exposure, quote, submission, person, or organization,
mapping your source fields with transformations and checking them with
guards. Use it to load or migrate records one at a time with an immediate
result; for a bulk load, store the rows with Import Rows
(ingestFmv1ImportRows) and map them with Queue Import Job
(queueFmv1ImportJob). The row is stored even when the import fails, so fix
it with Retry Import (retryFmv1Import) rather than sending it again.
Imports one record from another system as an FMV1 entity, in the shape you hold it rather than the company’s field model.
datais stored as an import row, as sent, before anything else can fail.- The transformations turn
data.<entityKey>into an entity in this company’s field model. - The guards run against the transformed entity.
- If both succeeded, the entity is created, or updated when the
transformed entity carries an
id. Keys the field model does not declare are dropped first; the write is then held to every rule an ordinary entity create or update is, including the company’s own invariants.
Every request that gets past validation stores its row and answers 201
with the import attempt recording each step, whether or not the entity
was written: check importAttempt.writeResult. A refused write is reported
there as the error the entity endpoint would have answered with. The attempt
is the one Get Import Attempt returns; the request’s importBatch is its
attemptBatch.
The attempt is recorded before the transformations run, and each step’s
result is stored on it as the step completes. The entity write and its
writeResult commit together, so if the request fails part-way (a 5xx
or a dropped connection), read the row’s attempts: one whose guards passed
and whose writeResult is null wrote nothing, and retrying it cannot
leave two entities.
A malformed request is a 400, and stores nothing.
There is no Idempotency-Key: sending the same request twice stores two
rows, and may write twice. To try a stored row again, retry it rather than
sending the request again.
Required permission: <entityType>.import for the request’s
entityType, such as submission.import to import a Submission. The
permission is the target entity type’s own import verb; one type’s
permission does not import another type.
curl --request POST \
--url https://go.aiinsurance.io/api/v1/companies/{companyId}/imports \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"entityType": "Submission",
"data": {
"submission": {
"name": "Acme Logistics",
"sourceSystemCode": "SUB-1042"
}
},
"transformations": {
"submissionName": "submission.name"
},
"importBatch": "october-load"
}
'{
"importRowId": "9a1d4e7b-2c3f-4b8a-8d61-0e5f2a7b3c94",
"importAttempt": {
"id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a9c1f42",
"importRowId": "9a1d4e7b-2c3f-4b8a-8d61-0e5f2a7b3c94",
"entityType": "Submission",
"action": "create",
"attemptBatch": "october-load",
"transformations": {
"submissionName": "submission.name"
},
"guards": [],
"transformationResult": {
"status": "ok",
"entity": {
"name": "Acme Logistics",
"sourceSystemCode": "SUB-1042",
"submissionName": "Acme Logistics"
}
},
"guardResult": {
"passed": true
},
"writeResult": {
"status": "ok",
"entityId": "6e2b8f14-3a7c-4d9e-b051-2c8a9f7d4e13",
"created": true
},
"createdAt": "2026-10-23T14:58:02.087Z",
"updatedAt": "2026-10-23T14:58:02.471Z"
}
}Authorizations
User-principal OAuth 2.0 Bearer authentication. Send a user-scoped Auth0 access token (audience = the app API audience) as Authorization: Bearer <jwt>. 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.
Body
One record to import. data is stored as an import row exactly as sent, before
anything else can fail; the transformations and guards then run against it, and
the entity is created or updated.
How data.<entityKey> 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": "<data path>", "values": { "<childKey>": "<expression>" } }.
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.<entityKey> 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.
Show child attributes
Show child attributes
Response
The row was stored and an attempt recorded. Whether the entity was
written is the attempt's writeResult.
The stored import row's id and the attempt this request recorded.
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.
Show child attributes
Show child attributes