Get Unique Values
const options = {
method: 'POST',
headers: {'x-organization-id': '<x-organization-id>', 'Content-Type': 'application/json'},
body: JSON.stringify({mapping: {}, constant_values: {}})
};
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));import requests
url = "https://api.dcycle.io/v2/imports/{import_id}/unique-values"
payload = {
"mapping": {},
"constant_values": {}
}
headers = {
"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}/unique-values \
--header 'Content-Type: application/json' \
--header 'x-organization-id: <x-organization-id>' \
--data '
{
"mapping": {},
"constant_values": {}
}
'{
"columns": {
"column_key": "<string>",
"source_column": "<string>",
"total_unique": 123,
"truncated": true,
"is_constant": true,
"values": {
"raw": "<string>",
"status": "<string>",
"resolved": "<string>"
}
}
}Get Unique Values
The distinct raw values of each mapped category column, with what the system could resolve them to
POST
/
v2
/
imports
/
{import_id}
/
unique-values
Get Unique Values
const options = {
method: 'POST',
headers: {'x-organization-id': '<x-organization-id>', 'Content-Type': 'application/json'},
body: JSON.stringify({mapping: {}, constant_values: {}})
};
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));import requests
url = "https://api.dcycle.io/v2/imports/{import_id}/unique-values"
payload = {
"mapping": {},
"constant_values": {}
}
headers = {
"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}/unique-values \
--header 'Content-Type: application/json' \
--header 'x-organization-id: <x-organization-id>' \
--data '
{
"mapping": {},
"constant_values": {}
}
'{
"columns": {
"column_key": "<string>",
"source_column": "<string>",
"total_unique": 123,
"truncated": true,
"is_constant": true,
"values": {
"raw": "<string>",
"status": "<string>",
"resolved": "<string>"
}
}
}← Imports
After you choose which source column feeds which field, this returns the distinct raw values found in every mapped category column, each with what the system managed to resolve it to. It is the step between mapping columns and mapping values: the user confirms that
Note the third entry: no
Cause:
"ES-Madrid" in their file means the Madrid facility before anything is imported.
It is a
POST because you send the mapping in the body. Nothing is imported here — no rows of your data are created. It is not a pure read either: a call that actually resolves values records what it did, so the same call twice leaves two entries in that log. A call that resolves nothing — an empty mapping, or a column whose values are all blank — still returns 200 and writes nothing. Treat it as a step of the flow, not as a query you can poll freely.Null fields are omitted, not sent as
null. The response is serialised with response_model_exclude_none, so a value the system could not resolve comes back without a resolved key at all — not as "resolved": null.This applies to null only: a field that is false or 0 is still sent.Read it as entry.get("resolved") in Python or entry.resolved ?? null in JavaScript. Code that assumes the key is always present will throw on exactly the rows that need human attention.Request
Headers
string
required
UUID of the organization the import belongs to.Format: UUID
string
Your API key.
Path Parameters
string
required
UUID of the import session, as returned by Create Session.Format: UUID
Body Parameters
object
required
The column mapping the user has chosen:
{ target_field: source_column }. A target field with no source column is sent as null.Example: { "facility": "Site", "waste_code": "LER", "notes": null }object
Fixed values for fields that have no source column, as
{ target_field: value }.A constant on a category column still shows up in the response — as a column with is_constant: true and a single raw value to resolve — so the user confirms it once instead of per row.Response
array[object]
One entry per mapped category column. Columns that need no value mapping are not listed.
Show Column
Show Column
string
The target field this column feeds.
string
The column in the uploaded file it was mapped from. Always present: for a column whose value came from
constant_values it arrives as an empty string, not as null or absent.integer
How many distinct raw values the column holds in total.
boolean
default:"false"
true when values is a subset of total_unique. Compare the two before telling the user the list is complete.boolean
default:"false"
true when the column has no source column and its single value came from constant_values rather than from the file.array[object]
The distinct raw values and how far the system got with each.
An entry also carries diagnostic fields when the system has them — among others
Show Value Entry
Show Value Entry
string
The value exactly as it appears in the file.
string
matched — resolved with confidence, nothing to ask.suggested — a candidate was found but should be confirmed.unmatched — nothing was found; the user must choose.string
What the raw value resolved to. Absent entirely when nothing was resolved — see the warning above.
resolution_origin, embedding_score, embedding_margin, llm_confidence and top_candidates. They follow the same rule as resolved: present when set, absent when null. A suggested entry in practice always carries resolution_origin, so do not treat the three fields above as the whole object.Example
curl -X POST "https://api.dcycle.io/v2/imports/YOUR_IMPORT_ID/unique-values" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-organization-id: YOUR_ORGANIZATION_ID" \
-H "Content-Type: application/json" \
-d '{
"mapping": {
"facility": "Site",
"waste_code": "LER"
},
"constant_values": {
"treatment": "recycling"
}
}'
import requests
HEADERS = {
"x-api-key": "YOUR_API_KEY",
"x-organization-id": "YOUR_ORGANIZATION_ID",
}
data = requests.post(
f"https://api.dcycle.io/v2/imports/{import_id}/unique-values",
headers=HEADERS,
json={
"mapping": {"facility": "Site", "waste_code": "LER"},
"constant_values": {"treatment": "recycling"},
},
timeout=60,
).json()
for column in data["columns"]:
if column["truncated"]:
print(f"{column['column_key']}: showing part of {column['total_unique']} values")
# `resolved` is ABSENT when nothing matched — never assume the key exists
needs_user = [v for v in column["values"] if v.get("resolved") is None]
print(f"{column['column_key']}: {len(needs_user)} values need a decision")
const response = await fetch(
`https://api.dcycle.io/v2/imports/${importId}/unique-values`,
{
method: "POST",
headers: {
"x-api-key": "YOUR_API_KEY",
"x-organization-id": "YOUR_ORGANIZATION_ID",
"Content-Type": "application/json",
},
body: JSON.stringify({
mapping: { facility: "Site", waste_code: "LER" },
constant_values: { treatment: "recycling" },
}),
},
);
const data = await response.json();
for (const column of data.columns) {
// `resolved` may be missing entirely, not null
const needsUser = column.values.filter((v) => v.resolved === undefined);
console.log(`${column.column_key}: ${needsUser.length} need a decision`);
}
Successful Response
Returns200 OK.
{
"columns": [
{
"column_key": "facility",
"source_column": "Site",
"total_unique": 3,
"truncated": false,
"is_constant": false,
"values": [
{
"raw": "ES-Madrid",
"status": "matched",
"resolved": "Madrid Office"
},
{
"raw": "ES-Bcn",
"status": "suggested",
"resolved": "Barcelona Office",
"resolution_origin": "lexical_fuzzy",
"embedding_score": 0.82,
"embedding_margin": 0.11
},
{
"raw": "Planta 4",
"status": "unmatched"
}
]
}
]
}
resolved key at all, rather than "resolved": null.
Only null fields disappear. truncated and is_constant are false here and are present — exclude_none drops None, not falsy values — so those two you can read directly.
Common Errors
422 Unprocessable Entity
Cause:mapping is missing from the body. It is the only required field.
{
"detail": [
{
"loc": ["body", "mapping"],
"msg": "field required",
"type": "value_error.missing"
}
]
}
import_id is not a valid UUID.
{
"detail": [
{
"loc": ["path", "import_id"],
"msg": "value is not a valid uuid",
"type": "type_error.uuid"
}
]
}
Use Cases
Build the value-mapping screen
Render one section per column. Values withstatus: matched can be collapsed; suggested shows the candidate with a confirm control; unmatched needs a picker. Sorting by status puts the work that needs a human first.
Do not promise a complete list
Whentruncated is true, values holds only part of total_unique. Saying “3 values to map” when there are 300 turns into a failed import later — show the real total and page the rest.
Related Endpoints
Confirm Mapping
Send back the decisions the user made here
Suggest Mapping
The column mapping this endpoint takes as input
Validate Import
The step after the values are mapped
Imports API
The whole import flow, in order
Was this page helpful?