Skip to main content
POST
/
v2
/
imports
/
{import_id}
/
unique-values
Get Unique Category Values
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}/unique-values', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "columns": {
    "column_key": "<string>",
    "source_column": "<string>",
    "values": {
      "raw": "<string>",
      "resolved": {},
      "status": "<string>"
    },
    "total_unique": 123,
    "truncated": true
  }
}

​
Get Unique Category Values

Use this endpoint after column mapping and before validation when your client needs to build a value-mapping step for category fields. Given the current column mapping, the backend returns:
  • category columns only
  • the mapped source column name from the uploaded file
  • distinct non-empty raw values found in that source column
  • whether the distinct value list was truncated at the backend cap
This is especially useful for templates like logistics_recharges, where fields such as country, fuel, and toc may need user review before row-level validation starts.
Each value in the response includes a resolved canonical value and a status field (matched or unmatched). Use these to pre-fill your value-mapping UI — matched values can be accepted automatically, while unmatched ones need user attention.

​
Request

​
Path Parameters

​
import_id
string
required
UUID of the import session created with POST /v2/imports/sessions.

​
Headers

​
x-api-key
string
required
Your API key for authentication.
​
x-organization-id
string
required
Your organization UUID. The import session must belong to this organization.

​
Body

​
mapping
object
required
The current source-to-template column mapping. This uses the same shape as POST /v2/imports/{import_id}/validate.Keys are template column keys and values are source column names from the uploaded file.
Example body: 
{
  "mapping": {
    "country": "País",
    "vehicle_license_plate": "Matrícula",
    "fuel": "Combustible",
    "toc": "Tipo transporte"
  }
}

​
Response

​
columns
array[object]
Distinct values grouped by mapped category column, returned in template order.

​
Examples

​
Fetch unique values for mapped category columns

curl -X POST "https://api.dcycle.io/v2/imports/11111111-1111-1111-1111-111111111111/unique-values" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "mapping": {
      "country": "País",
      "vehicle_license_plate": "Matrícula",
      "fuel": "Combustible",
      "toc": "Tipo transporte"
    }
  }'

​
Successful response

{
  "columns": [
    {
      "column_key": "country",
      "source_column": "País",
      "values": [
        { "raw": "France", "resolved": "fr", "status": "matched" },
        { "raw": "Spain", "resolved": "es", "status": "matched" },
        { "raw": "españa", "resolved": "es", "status": "matched" },
        { "raw": "Gondor", "resolved": null, "status": "unmatched" }
      ],
      "total_unique": 4,
      "truncated": false
    },
    {
      "column_key": "fuel",
      "source_column": "Combustible",
      "values": [
        { "raw": "diesel", "resolved": "diesel", "status": "matched" },
        { "raw": "hvo", "resolved": "hvo", "status": "matched" },
        { "raw": "b_7", "resolved": "b_7", "status": "matched" },
        { "raw": "compressed_natural_gas", "resolved": "compressed_natural_gas", "status": "matched" }
      ],
      "total_unique": 4,
      "truncated": false
    }
  ]
}

​
Typical Usage In The Imports Flow

  1. Call POST /v2/imports/{import_id}/mapping/suggest.
  2. Let the user confirm or adjust the column mapping.
  3. Call POST /v2/imports/{import_id}/unique-values.
  4. For each returned category column, render a value-mapping UI. Pre-fill matched entries using the resolved field — only unmatched values need user attention.
  5. Use GET /v2/imports/options/{source_key} or template inline options to present canonical choices for unmatched values.
  6. Once value mapping is confirmed, pass it as value_mappings to POST /v2/imports/{import_id}/validate.

​
Notes And Limits

  • Only template columns with type="category" are included.
  • Columns without a mapped source column are skipped.
  • Empty values and whitespace-only values are excluded.
  • Distinct values are capped to avoid oversized payloads.
  • If truncated=true, prompt the user to clean the source data or narrow the upload before relying on the full distinct set.

​
Common Errors

​
400 Bad Request

Cause: The mapping references unknown target columns, unknown source columns, or invalid duplicate mappings. Solution: Reuse the same validated mapping structure you would send to the validate endpoint.

​
403 Forbidden

Cause: The import session belongs to a different organization. Solution: Use the correct x-organization-id for the session you created.

​
404 Not Found

Cause: The import session or its template could not be found. Solution: Confirm the import_id is valid and the session still exists.