iotoms Docs

Suggest a column mapping for an import file

POST
/api/v1/ai/import/analyze

Send only the column headers and a few sample rows. AI identifies whether the file holds items, customers or vendors and proposes a column-to-field mapping with confidence scores, for review before importing.

How to use it

  1. Read the column headers and up to 30 sample rows from the file on your side.
  2. Send fileName, columns, sampleRows and rowCount; add entityTypeHint to force the record type.
  3. Review and edit the proposed mappings, then convert all rows and send them to Import a batch of records. Nothing is saved by this call.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Header Parameters

Request Body

application/json
  1. body
fileName*string

Name of the file being imported (max 255 characters); helps the AI guess the record type.

Length0 <= length <= 255
columns*array<string>

Column headers from the file, in order (1 to 80). Headers must be unique and not blank.

Items0 <= items <= 80
sampleRows*array<array<string>>

Sample rows (1 to 30), each a list of cell values in the same order as columns. Only the first 20 are sent to the AI and long cells are cut to 120 characters. Never send the whole file.

Items0 <= items <= 30
rowCount*integer

Total number of data rows in the file; informational only.

Formatint64
entityTypeHint?|

Optional: force the record type (ITEM, CUSTOMER or VENDOR) instead of letting the AI decide.

Value in"ITEM""CUSTOMER""VENDOR"null

Response Body

OK

*/*
  1. response
status*string

Outcome of the request: SUCCESS when it worked; errors return an error status with the reason in message.

message*string

Short human-readable message describing the outcome.

data?

The proposed record type and column-to-field mapping, for review before importing.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/ai/import/analyze' \  -H 'Content-Type: application/json' \  -d '{  "fileName": "string",  "columns": [],  "sampleRows": [],  "rowCount": 0}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "entityType": "ITEM",    "entityConfidence": 0.1,    "reasoning": "string",    "mappings": [      {        "sourceColumn": "string",        "targetField": "string",        "confidence": 0.1,        "transform": {          "type": "string",          "valueMap": {            "property1": "string",            "property2": "string"          },          "defaultValue": "string"        },        "note": "string"      }    ],    "unmappedColumns": [      "string"    ],    "targetFields": [      {        "name": "string",        "type": "string",        "required": true,        "description": "string",        "enumValues": [          "string"        ]      }    ]  }}