Skip to main content
GET
/
v1
/
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));
{
  "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

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
This endpoint requires no query parameters. It returns all unique clients for your organization.

​
Response

Returns an array of unique client names, sorted alphabetically.
​
response
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}"

​
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