Suggest Mapping

Get auto-suggested column mapping from source to template columns

POST /v2/imports/{import_id}/mapping/suggest

Suggest Mapping

JavaScript

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));

200

{
  "suggestions": {
    "source_column": {},
    "column_confidence": 123,
    "value_confidence": {},
    "reason": {},
    "restored_from_history": true
  }
}

← Imports

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.

Repeating the call is cheap and returns the same answer: the suggestion is stored on the session, and a repeat with the same inputs (source columns, template columns, mapping history, sheet and header row) is answered from it for up to 10 minutes. Concurrent identical calls wait for the first one and return its answer. Declaring custom columns or sending different source_columns computes a new suggestion.

Request

Headers

x-api-key · string · required

Your API key for authentication

Example: sk_live_1234567890abcdef

x-organization-id · string · required

Your organization UUID

Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Path Parameters

import_id · string · required

UUID of the import session

Example: "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.

Show Suggestion Object

source_column · string | null

Name of the source column suggested for this target

column_confidence · number

Confidence (0.0–1.0) that the source column identity matches the target, based on name similarity

value_confidence · number | null

For category columns only: confidence (0.0–1.0) that sample values map to the target enum. null for non-category columns or history-restored items.

reason · string | null

Human-readable explanation of why this mapping was suggested. shared_source_value_evidence means the source column is already suggested for another column and is suggested here too because its sample values resolve to this column’s options (for example a CUPS column that identifies each row’s facility); both columns allow a shared source

restored_from_history · boolean

true when this suggestion was lifted from a prior successful import rather than re-scored

Example

cURL

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. Both cases return the same response, so a session id from another organization is indistinguishable from one that does not exist.

{"code": "NOT_FOUND", "detail": "ImportSessionModel with id='1b2c3d4e-5f60-7182-93a4-b5c6d7e8f901' not found"}

Related Endpoints

Confirm Mapping

Persist the chosen mapping

Create Session

Upload a file and start an import