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

import requests

url = "https://api.dcycle.io/v2/imports/{import_id}/mapping/suggest"

payload = { "source_columns": {} }
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v2/imports/{import_id}/mapping/suggest \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "source_columns": {}
}
'

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

POST

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

import requests

url = "https://api.dcycle.io/v2/imports/{import_id}/mapping/suggest"

payload = { "source_columns": {} }
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v2/imports/{import_id}/mapping/suggest \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "source_columns": {}
}
'

{
  "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

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Path Parameters

string

required

UUID of the import sessionExample: "11111111-1111-1111-1111-111111111111"

Body Parameters

array[string]

Override the detected source columns. When omitted, uses the columns detected during session creation.

Response

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

string | null

Name of the source column suggested for this target

number

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

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.

string | null

Human-readable explanation of why this mapping was suggested

boolean

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

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 '{}'

import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    "Content-Type": "application/json",
}

import_id = "11111111-1111-1111-1111-111111111111"

response = requests.post(
    f"https://api.dcycle.io/v2/imports/{import_id}/mapping/suggest",
    headers=headers,
    json={},
)

suggestions = response.json()["suggestions"]
for target, suggestion in suggestions.items():
    if suggestion:
        src = suggestion["source_column"]
        conf = suggestion["column_confidence"]
        print(f"  {target} ← {src} (confidence: {conf:.2f})")
    else:
        print(f"  {target} ← (no match)")

const axios = require('axios');

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID,
  'Content-Type': 'application/json',
};

const importId = '11111111-1111-1111-1111-111111111111';

axios.post(`https://api.dcycle.io/v2/imports/${importId}/mapping/suggest`, {}, { headers })
  .then(response => {
    const { suggestions } = response.data;
    Object.entries(suggestions).forEach(([target, s]) => {
      if (s) console.log(`${target} ← ${s.source_column} (${s.column_confidence})`);
      else console.log(`${target} ← no match`);
    });
  });

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

​Suggest Mapping

​Request

​Headers

​Path Parameters

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Related Endpoints

Confirm Mapping

Create Session

Suggest Mapping

Request

Headers

Path Parameters

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

Related Endpoints