Skip to main content
POST
/
v2
/
imports
/
{import_id}
/
mapping
/
suggest
Suggest Mapping
const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({source_columns: {}})
};

fetch('https://api.dcycle.io/v2/imports/{import_id}/mapping/suggest', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "suggestions": {
    "source_column": {},
    "column_confidence": 123,
    "value_confidence": {},
    "reason": {},
    "restored_from_history": true
  }
}

​
Suggest Mapping

Request automatic mapping suggestions from your uploaded file’s source columns to the template’s target columns. The backend uses lexical similarity, semantic matching, and import history to rank candidates.
Suggestions are best-effort. Review the confidence scores and adjust before confirming. History-restored mappings (restored_from_history: true) come from a prior successful import and skip value-level scoring.

​
Request

​
Headers

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

​
Path Parameters

​
import_id
string
required
UUID of the import sessionExample: "11111111-1111-1111-1111-111111111111"

​
Body Parameters

​
source_columns
array[string]
Override the detected source columns. When omitted, uses the columns detected during session creation.

​
Response

​
suggestions
object
Map of {target_column: suggestion | null}. Each key is a template column key; the value is a suggestion object or null if no match was found.

​
Example

curl -X POST "https://api.dcycle.io/v2/imports/11111111-1111-1111-1111-111111111111/mapping/suggest" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{}'

​
Successful Response

{
  "suggestions": {
    "origin": {
      "source_column": "origin",
      "column_confidence": 0.98,
      "value_confidence": null,
      "reason": "exact match on column name",
      "restored_from_history": false
    },
    "destination": {
      "source_column": "destination",
      "column_confidence": 0.98,
      "value_confidence": null,
      "reason": "exact match on column name",
      "restored_from_history": false
    },
    "weight": {
      "source_column": "weight_kg",
      "column_confidence": 0.82,
      "value_confidence": null,
      "reason": "semantic similarity",
      "restored_from_history": false
    },
    "vehicle_type": {
      "source_column": "vehicle_type",
      "column_confidence": 0.95,
      "value_confidence": 0.87,
      "reason": null,
      "restored_from_history": true
    },
    "date": {
      "source_column": "date",
      "column_confidence": 0.97,
      "value_confidence": null,
      "reason": "exact match on column name",
      "restored_from_history": false
    }
  }
}

​
Common Errors

​
401 Unauthorized

Cause: Missing or invalid API key 
{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

​
403 Forbidden

Cause: The authenticated user is not a member of the organization 
{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

​
404 Not Found

Cause: The import session does not exist or belongs to another organization 
{"detail": "Not Found"}

Confirm Mapping

Persist the chosen mapping

Create Session

Upload a file and start an import