> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.
# List Clients
> Get the list of all unique clients with registered logistics requests
# 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
Your API key for authentication
**Example:** `sk_live_1234567890abcdef`
Your organization UUID
**Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
### Query Parameters
Filter clients to those with logistics requests linked to a specific project
**Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
## Response
Returns an array of unique client names, sorted alphabetically.
Array of unique client identifiers (strings)
## Example
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X GET "https://api.dcycle.io/v1/logistics/clients" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}"
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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}")
```
```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
"AMAZON",
"DHL",
"INDITEX",
"SEUR"
]
```
## Common Errors
### 401 Unauthorized
**Cause:** Missing or invalid API key
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"detail": "Invalid API key",
"code": "INVALID_API_KEY"
}
```
**Solution:** Verify your API key is valid and active. Get a new one from [Settings → API](https://app.dcycle.io/settings/api).
### 404 Not Found
**Cause:** Organization not found
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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).
## Related Endpoints
Filter packages by client
Create logistics requests with client identifier
List available vehicle types for calculations