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
Get auto-suggested column mapping from source to template columns
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));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
}
}← 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.Request
Headers
string
required
Your API key for authenticationExample:
sk_live_1234567890abcdefstring
required
Your organization UUIDExample:
a8315ef3-dd50-43f8-b7ce-d839e68d51faPath 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
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.
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 sourceboolean
true when this suggestion was lifted from a prior successful import rather than re-scoredExample
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. 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
Was this page helpful?