Create Logistics Requests (v2)

• All or nothing. If any record is invalid the answer is 422 BULK_RECORDS_REJECTED, listing every invalid record, and nothing is written: no leg, package or hub.
• Idempotent. Idempotency-Key is required: retrying with the same key and body returns the original job.
• Per-leg results. A leg whose distance or emissions could not be calculated is a failed item of the job, with its reason (error_code), and stays stored without emissions.

curl -i -X POST "https://api.dcycle.io/v2/logistics/requests" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b1f9c2e-4d3a-4f8e-9a61-2c5d8e0f1a37" \
  -d '{
    "records": [
      {
        "client_row_id": "SHIP-001",
        "movement_id": "SHIP-001",
        "origin": "Madrid, Spain",
        "destination": "Barcelona, Spain",
        "origin_country": "ES",
        "load": 1000,
        "load_unit": "kg",
        "toc": "van_3_5_t_diesel",
        "shipment_date": "2026-10-01"
      }
    ]
  }'

{
  "id": "4f0b8b3e-6a41-4b7e-9d0c-2c1f3a5e8d10",
  "status": "processing",
  "entity_type": "logistics",
  "operation": "create",
  "source": "api_bulk",
  "counts": { "submitted": 1, "succeeded": 0, "failed": 0 },
  "chunks_total": 1,
  "chunks_done": 0,
  "created_at": "2026-10-15T08:00:00.000Z",
  "finished_at": null,
  "links": {
    "self": "/v2/ingest-jobs/4f0b8b3e-6a41-4b7e-9d0c-2c1f3a5e8d10",
    "items": "/v2/ingest-jobs/4f0b8b3e-6a41-4b7e-9d0c-2c1f3a5e8d10/items"
  }
}

{
  "type": "https://code.dcycle.io/api-reference/errors#BULK_RECORDS_REJECTED",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "BULK_RECORDS_REJECTED",
  "detail": "1 of the submitted records are invalid; nothing was written.",
  "errors": [
    {
      "source_row_index": 0,
      "client_row_id": "SHIP-001",
      "error_code": "INVALID_LOAD",
      "error_params": { "detail": "Load cannot be negative or 0" }
    }
  ],
  "rejected": 1,
  "request_id": "b2248a31-0f5e-4a54-9f0a-3d1f2b6c7e90"
}

{
  "dry_run": true,
  "submitted": 1,
  "valid": 1
}

​

Request

​

Headers

​

Query Parameters

​

Body Parameters

​

How the fields are read

• toc: copy the toc of List TOCs exactly, e.g. van_3_5_t_diesel. It is matched loosely (case, spaces and dots are ignored, and a TOC whose vehicle and type both appear in the text matches), so a near miss can resolve to another TOC. It is looked up in the region of origin_country (GLO when omitted), then in GLO, then in EU. If it matches no TOC and you sent category, the leg is calculated with that category’s generic average, without an error. Send category alone only when you want that average.
• load_unit: kg (default), t or ton, pallet or pallets (1,500 kg each), teu (10,000 kg) and feu (20,000 kg), in any case. Any other value is read as kilograms, without an error.
• load: optional; without it, the TOC’s default load is used. load_factor multiplies the load, the default load included. The load is stored in kg with two decimals.
• distance_km: used as sent. When you omit it, the distance is computed from origin and destination and multiplied by a distance adjustment factor: 0.95 for road, 0.85 for maritime, 1 for rail and air. A distance you send is not adjusted.
• origin and destination: a leg without distance_km needs both (an existing hub_id supplies the origin); a record missing either is rejected with ADDRESS_REQUIRED. A destination equal to the name of an active hub of your organization is replaced by the hub’s address. origin is not read as a hub name here; use hub_id.
• hub_id: a hub name, not its id. If it names an active hub of your organization, the leg’s origin is that hub’s address and the origin you send is ignored. Otherwise an active hub is created with this record’s origin as its address, and later records of the batch with the same hub_id use that hub and its address. An inactive hub with that name is not reused: a new active one is created.
• shipment_date: optional; without it the leg is dated at the upload time (UTC).
• year and tkm: not used to calculate the leg, which takes the year of shipment_date instead of year and recalculates tkm as load in tonnes × distance. A tkm you send stays on the leg only if its calculation fails.

​

Legs are upserted on their business key

• Sending a leg again in a later batch replaces it: every field takes the value you send or its default (an omitted shipment_date becomes the upload time, an omitted hub_id unlinks the hub), its emissions are cleared, and it is calculated again. Its id is kept. Changing a key field, such as package_key, creates a new leg and leaves the old one.
• Two records of the same batch with the same key are rejected (DUPLICATE_RECORD).
• Legs created by any other route (the app, file uploads, the v1 endpoints) share the key: a leg sent here replaces the leg with the same key, wherever it came from.

​

Response

​

202 Accepted

{
  "id": "4f0b8b3e-6a41-4b7e-9d0c-2c1f3a5e8d10",
  "status": "processing",
  "entity_type": "logistics",
  "operation": "create",
  "source": "api_bulk",
  "counts": { "submitted": 1, "succeeded": 0, "failed": 0 },
  "chunks_total": 1,
  "chunks_done": 0,
  "created_at": "2026-10-15T08:00:00.000Z",
  "finished_at": null,
  "links": {
    "self": "/v2/ingest-jobs/4f0b8b3e-6a41-4b7e-9d0c-2c1f3a5e8d10",
    "items": "/v2/ingest-jobs/4f0b8b3e-6a41-4b7e-9d0c-2c1f3a5e8d10/items"
  }
}

​

Job status

​

Why a leg failed to calculate

​

The leg changed while the job was running (rare)

​

Errors

​

422 BULK_RECORDS_REJECTED — invalid records

{
  "type": "https://code.dcycle.io/api-reference/errors#BULK_RECORDS_REJECTED",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "BULK_RECORDS_REJECTED",
  "detail": "3 of the submitted records are invalid; nothing was written.",
  "errors": [
    {"source_row_index": 1, "client_row_id": "row-2", "error_code": "INVALID_LOAD",
     "error_params": {"detail": "Load cannot be negative or 0"}},
    {"source_row_index": 2, "client_row_id": "row-3", "error_code": "SCHEMA_INVALID",
     "error_params": {"errors": [{"loc": ["category"], "type": "value_error", "msg": "Value error, Invalid category"}]}},
    {"source_row_index": 3, "client_row_id": "row-4", "error_code": "DUPLICATE_RECORD",
     "error_params": {"duplicate_of": 0}}
  ],
  "rejected": 3,
  "request_id": "b2248a31-0f5e-4a54-9f0a-3d1f2b6c7e90"
}

​

422 IDEMPOTENCY_KEY_REUSED

{
  "type": "https://code.dcycle.io/api-reference/errors#IDEMPOTENCY_KEY_REUSED",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "IDEMPOTENCY_KEY_REUSED",
  "detail": "This Idempotency-Key was already used with a different request body. Use a new key per batch.",
  "request_id": "b2248a31-0f5e-4a54-9f0a-3d1f2b6c7e90"
}

​

409 IDEMPOTENCY_KEY_IN_PROGRESS

​

422 REQUEST_VALIDATION_FAILED — malformed request

​

401, 400, 404 and 403: key and organization

• 401: no API key (AUTH_REQUIRED, CREDENTIALS_REQUIRED), a wrong or revoked one (INVALID_API_KEY), a key of an organization that is neither this one nor one of its parents (API_KEY_ORG_MISMATCH) or one too old to have an owner (API_KEY_NO_OWNER).
• 400 ORGANIZATION_ID_REQUIRED: no x-organization-id; 404 ORGANIZATION_NOT_FOUND: no organization has that id.
• 403 LOGGED_USER_NOT_MEMBER: the key’s user is not a member of the organization in x-organization-id.

​

429 TOO_MANY_REQUESTS

​

Examples

​

Create a batch and wait for the calculation

import os
import time
import uuid

import requests

BASE = "https://api.dcycle.io"
HEADERS = {
    "x-api-key": os.environ["DCYCLE_API_KEY"],
    "x-organization-id": os.environ["DCYCLE_ORG_ID"],
}
records = [
    {
        "client_row_id": "SHIP-001",
        "movement_id": "SHIP-001",  # unique per leg: it is part of the leg's business key
        "origin": "Madrid, Spain",
        "destination": "Barcelona, Spain",
        "origin_country": "ES",
        "load": 1000,
        "load_unit": "kg",
        "toc": "van_3_5_t_diesel",  # copied from GET /v1/logistics/tocs
        "shipment_date": "2026-10-01",
    }
]

# One key per batch: reuse it only to retry this same batch.
response = requests.post(
    f"{BASE}/v2/logistics/requests",
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={"records": records},
    timeout=120,
)
if response.status_code == 422 and response.json().get("code") == "BULK_RECORDS_REJECTED":
    for rejection in response.json()["errors"]:
        print(rejection["source_row_index"], rejection["client_row_id"], rejection["error_code"],
              rejection["error_params"])
    raise SystemExit("Fix the listed records and send the whole batch again")
response.raise_for_status()

job_url = BASE + response.headers["Location"]
deadline = time.monotonic() + 30 * 60
while True:
    job_response = requests.get(job_url, headers=HEADERS, timeout=30)
    job_response.raise_for_status()
    job = job_response.json()
    if job["status"] != "processing":
        break
    if time.monotonic() > deadline:
        raise SystemExit(f"Job {job['id']} is still processing after 30 minutes: contact support with its id")
    time.sleep(10)

page = 1
while job["status"] == "completed_with_errors":  # read every page of failures
    failed = requests.get(
        f"{job_url}/items",
        headers=HEADERS,
        params={"status": "failed", "size": 500, "page": page},
        timeout=30,
    ).json()
    for item in failed["items"]:
        print("not calculated:", item["client_row_id"], item["error_code"], item["error_params"])
    if page * failed["size"] >= failed["total"]:
        break
    page += 1

​

Retries and idempotency

• Network error or timeout: retry with the same Idempotency-Key and the same body. If the first attempt was accepted you get its job back, and nothing is written twice.
• 409 IDEMPOTENCY_KEY_IN_PROGRESS: the first request with that key is still being processed. Wait Retry-After seconds and retry with the same key and body.
• 422 BULK_RECORDS_REJECTED: nothing was written. Fix the records and send the batch again; the same key works, since the first request created no job.
• 422 IDEMPOTENCY_KEY_REUSED: the key already belongs to another batch. Use a new key, or resend the original body unchanged.
• 429: too many requests in flight for your API key on this endpoint (unlike the Idempotency-Key, the limit is per key, not per organization). Wait Retry-After seconds; the request was not processed.

​

Limits

​

Related Endpoints