Get Import Template

const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};

fetch('https://api.dcycle.io/v2/imports/templates/{template_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "template_id": "<string>",
  "description": {},
  "columns": {
    "key": "<string>",
    "label": "<string>",
    "type": "<string>",
    "required": true,
    "aliases": {},
    "options": {},
    "options_source": {},
    "default": "<any>",
    "validations": {},
    "allow_shared_source": true
  },
  "required_context_fields": {},
  "submit_context_fields": {},
  "submit_columns": {},
  "defaults": {}
}

GET

imports

templates

{template_id}

Get Import Template

const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};

fetch('https://api.dcycle.io/v2/imports/templates/{template_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "template_id": "<string>",
  "description": {},
  "columns": {
    "key": "<string>",
    "label": "<string>",
    "type": "<string>",
    "required": true,
    "aliases": {},
    "options": {},
    "options_source": {},
    "default": "<any>",
    "validations": {},
    "allow_shared_source": true
  },
  "required_context_fields": {},
  "submit_context_fields": {},
  "submit_columns": {},
  "defaults": {}
}

← Imports Retrieve the metadata for a backend import template, including its column definitions, validation rules, and required context fields. Templates define the expected structure of an import file.

Templates are static configuration — not organization-specific. Any authenticated caller can fetch any template.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

Path Parameters

string

required

Template identifierExamples: logistics_requests, purchases, wastes, invoices_electricity, transport_routesThere is no endpoint that lists the available identifiers. For the social ones — own_workforce, own_workforce_trainings and own_workforce_accidents_absenteeisms — see Own Workforce Import Templates.

Response

string

Template identifier

string | null

Human-readable description of the template

array[object]

Column definitions for this template

Show Column Object

string

Internal column key (used in mapping)

string

Human-readable label

string

Data type: string, number, date, category, boolean

boolean

Whether this column must be mapped

array[string]

Alternative names recognized during auto-mapping (e.g. ["peso", "weight_kg"])

array[string] | null

Fixed list of allowed values for category columns

string | null

Dynamic option provider key (e.g. fuel_types, countries). Use Get Options Source to resolve values.

any

Default value applied when the cell is empty

array[object]

Validation rules applied to this column (e.g. {rule: "range", params: {min: 0}})

boolean

true when this column may take its values from the same source column as another column that also allows it. For example, in facility consumption imports one CUPS column can both identify the facility (facility_id) and fill cups_code.

array[string]

Context fields that must be provided at session creation (e.g. ["facility_id"] for wastes)

array[string]

Context fields that can be provided at submit time

array[string]

Columns included in the submitted output

object

Global default values applied across all columns

Example

curl -X GET "https://api.dcycle.io/v2/imports/templates/logistics_requests" \
  -H "x-api-key: ${DCYCLE_API_KEY}"

import requests
import os

headers = {"x-api-key": os.getenv("DCYCLE_API_KEY")}

response = requests.get(
    "https://api.dcycle.io/v2/imports/templates/logistics_requests",
    headers=headers,
)

template = response.json()
print(f"Template: {template['template_id']}")
print(f"Columns ({len(template['columns'])}):")
for col in template["columns"]:
    req = " (required)" if col["required"] else ""
    print(f"  {col['key']} [{col['type']}]{req} — {col['label']}")

const axios = require('axios');

const headers = { 'x-api-key': process.env.DCYCLE_API_KEY };

axios.get('https://api.dcycle.io/v2/imports/templates/logistics_requests', { headers })
  .then(response => {
    const { template_id, columns } = response.data;
    console.log(`Template: ${template_id}, ${columns.length} columns`);
    columns.forEach(c => {
      console.log(`  ${c.key} [${c.type}]${c.required ? ' (required)' : ''}`);
    });
  });

Successful Response

{
  "template_id": "logistics_requests",
  "description": "Logistics transport requests",
  "columns": [
    {
      "key": "origin",
      "label": "Origin",
      "type": "string",
      "required": true,
      "aliases": ["from", "origen", "departure"],
      "options": null,
      "options_source": null,
      "default": null,
      "validations": []
    },
    {
      "key": "destination",
      "label": "Destination",
      "type": "string",
      "required": true,
      "aliases": ["to", "destino", "arrival"],
      "options": null,
      "options_source": null,
      "default": null,
      "validations": []
    },
    {
      "key": "weight",
      "label": "Weight (kg)",
      "type": "number",
      "required": true,
      "aliases": ["peso", "weight_kg"],
      "options": null,
      "options_source": null,
      "default": null,
      "validations": [{"rule": "range", "params": {"min": 0}}]
    },
    {
      "key": "vehicle_type",
      "label": "Vehicle Type",
      "type": "category",
      "required": false,
      "aliases": ["tipo_vehiculo"],
      "options": null,
      "options_source": "toc_types",
      "default": null,
      "validations": []
    }
  ],
  "required_context_fields": [],
  "submit_context_fields": [],
  "submit_columns": ["origin", "destination", "weight", "vehicle_type", "date"],
  "defaults": {}
}

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: Template does not exist

{
  "detail": "Template 'invalid_template' not found."
}

Create Session

Use the template_id when creating an import session

Get Options Source

Resolve dynamic option values for category columns

​Request

​Headers

​Path Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Related Endpoints

Create Session

Get Options Source

Request

Headers

Path Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

Related Endpoints