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": {}
  },
  "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": {}
  },
  "required_context_fields": {},
  "submit_context_fields": {},
  "submit_columns": {},
  "defaults": {}
}

Get Import Template

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_routes

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}})

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

​Get Import Template

​Request

​Headers

​Path Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​Related Endpoints

Create Session

Get Options Source

Get Import Template

Request

Headers

Path Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

Related Endpoints