Create Logistics Requests (Bulk, v2)

const options = {method: 'POST'};

fetch('https://api.dcycle.io/v2/logistics/requests/bulk', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": 123,
  "failed": 123,
  "results": [
    {}
  ],
  "errors": [
    {}
  ]
}

POST

logistics

requests

bulk

Create Logistics Requests (Bulk, v2)

const options = {method: 'POST'};

fetch('https://api.dcycle.io/v2/logistics/requests/bulk', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": 123,
  "failed": 123,
  "results": [
    {}
  ],
  "errors": [
    {}
  ]
}

Create Logistics Requests (Bulk, v2)

v2 of Create Logistics Requests (Bulk). It accepts the exact same request body and returns the same response shape, but the distance and emissions calculation for every record is performed asynchronously by a background worker instead of inline. The endpoint returns as soon as the records are persisted, which makes it well suited for large daily batches.

Same contract as v1. Headers, body parameters, validation, deduplication and the 5,000-record limit are identical to POST /v1/logistics/requests/bulk. See the v1 reference for the full request documentation.

v1 vs v2

Behaviour	v1 (`/v1/logistics/requests/bulk`)	v2 (`/v2/logistics/requests/bulk`)
Distance & emissions	Calculated inline for every record before responding	Deferred to a background worker
`results[].co2e`	Final emissions value	`null` while the async calculation is pending
Response latency	Scales with batch size (geocoding + distance APIs)	Low and roughly constant
Progress tracking	—	A processing job is created and updated as records are calculated
Sync-phase errors (validation, in-batch duplicates)	Returned in `errors[]`	Returned in `errors[]` and recorded on the processing job

In v2, each results[].co2e is null in the immediate response. Distances and emissions are filled in asynchronously. Read the final values back via GET /v1/logistics/requests, and track overall progress through the processing job surfaced in the activity panel.

Request

The request body is identical to v1.

curl -X POST "https://api.dcycle.io/v2/logistics/requests/bulk" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "origin": "Madrid, Spain",
        "destination": "Barcelona, Spain",
        "origin_country": "ES",
        "load": 1000,
        "load_unit": "kg",
        "toc": "truck_diesel",
        "movement_id": "SHIP-001"
      }
    ],
    "options": { "continue_on_error": true }
  }'

import os
import requests

response = requests.post(
    "https://api.dcycle.io/v2/logistics/requests/bulk",
    headers={
        "x-api-key": os.environ["DCYCLE_API_KEY"],
        "x-organization-id": os.environ["DCYCLE_ORG_ID"],
    },
    json={
        "records": [
            {
                "origin": "Madrid, Spain",
                "destination": "Barcelona, Spain",
                "origin_country": "ES",
                "load": 1000,
                "load_unit": "kg",
                "toc": "truck_diesel",
                "movement_id": "SHIP-001",
            }
        ],
        "options": {"continue_on_error": True},
    },
)
result = response.json()
print(f"Accepted {result['success']}/{result['total_received']} records for async calculation")

const axios = require('axios');

axios.post('https://api.dcycle.io/v2/logistics/requests/bulk', {
  records: [
    {
      origin: 'Madrid, Spain',
      destination: 'Barcelona, Spain',
      origin_country: 'ES',
      load: 1000,
      load_unit: 'kg',
      toc: 'truck_diesel',
      movement_id: 'SHIP-001',
    },
  ],
  options: { continue_on_error: true },
}, {
  headers: {
    'x-api-key': process.env.DCYCLE_API_KEY,
    'x-organization-id': process.env.DCYCLE_ORG_ID,
  },
}).then(response => {
  const { success, total_received } = response.data;
  console.log(`Accepted ${success}/${total_received} records for async calculation`);
});

Successful Response

The response shape matches v1. The key difference is that each results[].co2e is null because emissions are not yet calculated when the response is returned.

{
  "total_received": 3,
  "total_processed": 3,
  "success": 3,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "id": "0d9b8817-fc47-47c3-b134-b3565ae1a57f",
      "movement_id": "SHIP-001",
      "package_id": null,
      "co2e": null
    },
    {
      "index": 1,
      "id": "683a0184-6dac-44ab-80a2-ce31b14ce927",
      "movement_id": "SHIP-002",
      "package_id": null,
      "co2e": null
    }
  ],
  "errors": []
}

integer

Number of records accepted and enqueued for asynchronous calculation (records that passed synchronous validation and deduplication).

integer

Number of records that failed synchronous validation or were rejected as in-batch duplicates. Failures detected during the asynchronous calculation phase (e.g. missing distance or load) are reported on the processing job, not in this response.

array

One entry per accepted record. Each co2e is null until the asynchronous calculation completes.

array

Synchronous-phase errors only (validation, in-batch duplicates), each with index, movement_id and error.

Tracking progress

A processing job is created for the batch and updated as records are calculated. Its status moves PENDING → RUNNING → COMPLETED (or FAILED), with per-record success/failure counts and a capped list of error entries (stage: "sync" for validation/dedup, stage: "calculation" for async failures such as NO_TOC, NO_LOAD or NO_DISTANCE). The job is visible in the activity panel. Read the calculated emissions back once the job completes:

curl -X GET "https://api.dcycle.io/v1/logistics/requests?file_id[]=..." \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

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

422 Unprocessable Entity

Cause: Invalid or missing required fields in the request body

{
  "detail": [
    {
      "loc": ["body", "requests"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Migrating from v1? The request body is unchanged. Update the URL prefix to /v2, treat results[].co2e as pending (null), and read final emissions back from the list endpoint or wait for the processing job to complete.

Create Request (v2)

Create a single request

Get Requests

Retrieve requests with filtering and pagination

Upload CSV

Bulk import via CSV file

Get Packages

View aggregated package emissions

​Create Logistics Requests (Bulk, v2)

​v1 vs v2

​Request

​Successful Response

​Tracking progress

​Common Errors

​401 Unauthorized

​403 Forbidden

​422 Unprocessable Entity

​Related Endpoints

Create Request (v2)

Get Requests

Upload CSV

Get Packages

Create Logistics Requests (Bulk, v2)

v1 vs v2

Request

Successful Response

Tracking progress

Common Errors

401 Unauthorized

403 Forbidden

422 Unprocessable Entity

Related Endpoints