Skip to main content
POST
/
v2
/
imports
/
{import_id}
/
mapping
Confirm 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({mapping: {}})
};

fetch('https://api.dcycle.io/v2/imports/{import_id}/mapping', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "import_id": "<string>",
  "mapping": {},
  "status": "<string>"
}

​
Confirm Mapping

Persist the column mapping the user accepted (or adjusted) after reviewing suggestions. This transitions the session status from parsed to mapped and makes the session resumable.
Confirming is optional — the Validate endpoint also accepts a mapping in the request body. However, confirming has two benefits: the mapping is persisted on the session (visible via List Sessions), and downstream calls behave consistently with what the user saw.

​
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

​
mapping
object
required
Map of {target_column: source_column | suggestion_object | null}. Each key is a template column key. The value can be:
  • A string (source column name)
  • A suggestion object from Suggest Mapping (the source_column is extracted automatically)
  • null to leave the target unmapped
Example: {"origin": "origin", "destination": "destination", "weight": "weight_kg", "date": "date"}

​
Response

​
import_id
string
UUID of the import session
​
mapping
object
The normalized flat mapping persisted on the session ({target: source_column | null})
​
status
string
Updated session status (typically mapped)

​
Example

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

​
Successful Response

{
  "import_id": "11111111-1111-1111-1111-111111111111",
  "mapping": {
    "origin": "origin",
    "destination": "destination",
    "weight": "weight_kg",
    "vehicle_type": "vehicle_type",
    "date": "date"
  },
  "status": "mapped"
}

​
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"}

​
422 Unprocessable Entity

Cause: Invalid or missing mapping object 
{
  "detail": [
    {
      "loc": ["body", "mapping"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Suggest Mapping

Get auto-suggested mappings first

Validate Import

Validate rows with the chosen mapping