List Clients

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

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

import requests

url = "https://api.dcycle.io/v1/logistics/clients"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/logistics/clients \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "response": [
    {}
  ]
}

GET

logistics

clients

List Clients

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

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

import requests

url = "https://api.dcycle.io/v1/logistics/clients"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/v1/logistics/clients \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>'

{
  "response": [
    {}
  ]
}

List Logistics Clients

Get all unique client identifiers that have been used in logistics requests for your organization. Useful for populating dropdowns, filtering reports, or verifying data imports.

New API: This endpoint is part of the new API architecture with improved design and maintainability.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters

uuid

Filter clients to those with logistics requests linked to a specific projectExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Response

Returns an array of unique client names, sorted alphabetically.

array

Array of unique client identifiers (strings)

Example

curl -X GET "https://api.dcycle.io/v1/logistics/clients" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")

headers = {
    "x-api-key": api_key,
    "x-organization-id": org_id
}

response = requests.get(
    "https://api.dcycle.io/v1/logistics/clients",
    headers=headers
)

clients = response.json()
print(f"Found {len(clients)} clients:")
for client in clients:
    print(f"  - {client}")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;

const headers = {
  'x-api-key': apiKey,
  'x-organization-id': orgId
};

axios.get(
  'https://api.dcycle.io/v1/logistics/clients',
  { headers }
)
.then(response => {
  console.log(`Found ${response.data.length} clients:`);
  response.data.forEach(client => {
    console.log(`  - ${client}`);
  });
})
.catch(error => console.error(error));

Successful Response

[
  "AMAZON",
  "DHL",
  "INDITEX",
  "SEUR"
]

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Solution: Verify your API key is valid and active. Get a new one from Settings → API.

404 Not Found

Cause: Organization not found

{
  "code": "ORGANIZATION_NOT_FOUND",
  "detail": "Organization with id=UUID('...') not found"
}

Solution: Verify that the x-organization-id header contains a valid organization UUID.

Use Cases

Populate a Client Selector

Build a dropdown for filtering packages by client:

def get_client_options():
    """Get client options for a dropdown selector"""
    response = requests.get(
        "https://api.dcycle.io/v1/logistics/clients",
        headers=headers
    )

    clients = response.json()

    # Add "All clients" option
    options = [{"value": "", "label": "All clients"}]
    for client in clients:
        options.append({"value": client, "label": client})

    return options

# Use in your UI
client_options = get_client_options()

Validate Client Before Filtering

Before filtering packages, verify the client exists:

def get_packages_for_client(client_name):
    """Get packages for a specific client with validation"""
    # Get available clients
    clients_response = requests.get(
        "https://api.dcycle.io/v1/logistics/clients",
        headers=headers
    )
    available_clients = clients_response.json()

    if client_name not in available_clients:
        raise ValueError(
            f"Client '{client_name}' not found. "
            f"Available: {', '.join(available_clients)}"
        )

    # Get packages for the client
    packages_response = requests.get(
        f"https://api.dcycle.io/v1/logistics/packages?client={client_name}",
        headers=headers
    )

    return packages_response.json()

Generate Summary by Client

Get emissions summary for each client:

def get_emissions_by_client():
    """Get total emissions grouped by client"""
    # Get all clients
    clients_response = requests.get(
        "https://api.dcycle.io/v1/logistics/clients",
        headers=headers
    )
    clients = clients_response.json()

    summary = {}
    for client in clients:
        # Get packages for this client
        packages_response = requests.get(
            f"https://api.dcycle.io/v1/logistics/packages?client={client}",
            headers=headers
        )
        packages = packages_response.json()

        # Sum emissions
        total_co2e = sum(
            pkg.get('total_co2e', 0) or 0
            for pkg in packages.get('items', [])
        )
        total_distance = sum(
            pkg.get('total_distance_km', 0) or 0
            for pkg in packages.get('items', [])
        )

        summary[client] = {
            'packages': packages.get('total', 0),
            'total_co2e_kg': total_co2e,
            'total_distance_km': total_distance
        }

    return summary

# Example output
emissions = get_emissions_by_client()
for client, data in emissions.items():
    print(f"{client}: {data['packages']} packages, {data['total_co2e_kg']:.2f} kgCO2e")

Notes

The client list is dynamically generated based on the logistics requests in your organization. New clients appear automatically when you create requests with new client identifiers.

Client names are case-sensitive. "AMAZON" and "amazon" are considered different clients. We recommend using consistent naming conventions (e.g., always uppercase).

Get Packages

Filter packages by client

Create Request

Create logistics requests with client identifier

Get Vehicle Types

List available vehicle types for calculations

Get HOCs Generate Report

​List Logistics Clients

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​404 Not Found

​Use Cases

​Populate a Client Selector

​Validate Client Before Filtering

​Generate Summary by Client

​Notes

​Related Endpoints

Get Packages

Create Request

Get Vehicle Types

List Logistics Clients

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

Use Cases

Populate a Client Selector

Validate Client Before Filtering

Generate Summary by Client

Notes

Related Endpoints