List Groups by Category

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

fetch('https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/{organization_id}/{category}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/{organization_id}/{category}"

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

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

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/{organization_id}/{category} \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --header 'x-user-id: <x-user-id>'

{
  "organization_id": "<string>",
  "emission_groups": [
    {}
  ]
}

GET

api

custom_emission_groups

list_of_emission_groups

{organization_id}

{category}

List Groups by Category

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

fetch('https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/{organization_id}/{category}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/{organization_id}/{category}"

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

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

print(response.text)

curl --request GET \
  --url https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/{organization_id}/{category} \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --header 'x-user-id: <x-user-id>'

{
  "organization_id": "<string>",
  "emission_groups": [
    {}
  ]
}

List Groups by Category

Retrieve all custom emission groups for a specific organization filtered by category (purchases, wastes, or energy).

This endpoint requires the organization_id in the path rather than using the header. Ensure you use the correct organization ID.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

string

required

Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Path Parameters

string

required

UUID of the organizationExample: "org-uuid-here"

string

required

Category to filter byValues: "purchases", "wastes", or "energy"

Response

{
  "organization_id": "org-uuid",
  "emission_groups": [
    {
      "id": "group-uuid-1",
      "name": "Supplier ABC Materials 2024",
      "category": "purchases",
      "group_start_date": "2024-01-01",
      "group_end_date": "2024-12-31",
      "group_uploaded_by": "procurement@company.com"
    },
    {
      "id": "group-uuid-2",
      "name": "Supplier XYZ Products",
      "category": "purchases",
      "group_start_date": null,
      "group_end_date": null,
      "group_uploaded_by": null
    }
  ]
}

Example

curl "https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/${DCYCLE_ORG_ID}/purchases" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-user-id: ${DCYCLE_USER_ID}"

import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('DCYCLE_API_KEY')}",
    "x-user-id": os.getenv("DCYCLE_USER_ID")
}

org_id = os.getenv("DCYCLE_ORG_ID")
category = "purchases"

response = requests.get(
    f"https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/{org_id}/{category}",
    headers=headers
)

data = response.json()
print(f"Found {len(data['emission_groups'])} {category} groups:\n")

for group in data['emission_groups']:
    print(f"- {group['name']} (ID: {group['id']})")

const axios = require('axios');

const headers = {
  'Authorization': `Bearer ${process.env.DCYCLE_API_KEY}`,
  'x-user-id': process.env.DCYCLE_USER_ID
};

const orgId = process.env.DCYCLE_ORG_ID;
const category = 'purchases';

axios.get(
  `https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/${orgId}/${category}`,
  { headers }
)
.then(response => {
  const data = response.data;
  console.log(`Found ${data.emission_groups.length} ${category} groups:\n`);

  data.emission_groups.forEach(group => {
    console.log(`- ${group.name} (ID: ${group.id})`);
  });
})
.catch(error => console.error(error));

Use Cases

Load Category-Specific Groups

Get groups for a specific category when creating records:

# When creating a purchase, load purchase groups
category = "purchases"
groups = requests.get(
    f"https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/{org_id}/{category}",
    headers=headers
).json()

print(f"Available purchase groups:")
for group in groups['emission_groups']:
    print(f"  [{group['id']}] {group['name']}")

Build Category Selector

Create a dropdown for each category:

async function loadGroupsByCategory(category) {
  const orgId = process.env.DCYCLE_ORG_ID;

  const response = await axios.get(
    `https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/${orgId}/${category}`,
    { headers }
  );

  return response.data.emission_groups.map(group => ({
    value: group.id,
    label: group.name
  }));
}

// Usage in UI
const purchaseGroups = await loadGroupsByCategory('purchases');
const wasteGroups = await loadGroupsByCategory('wastes');
const energyGroups = await loadGroupsByCategory('energy');

Filter All Categories

Get groups for all categories:

categories = ["purchases", "wastes", "energy"]
all_groups = {}

for category in categories:
    response = requests.get(
        f"https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/{org_id}/{category}",
        headers=headers
    ).json()

    all_groups[category] = response['emission_groups']

# Display summary
for category, groups in all_groups.items():
    print(f"{category.capitalize()}: {len(groups)} groups")

Check Group Availability

Verify groups exist before allowing custom factor selection:

category = "energy"
groups = requests.get(
    f"https://api.dcycle.io/api/v1/custom_emission_groups/list_of_emission_groups/{org_id}/{category}",
    headers=headers
).json()

if len(groups['emission_groups']) == 0:
    print(f"⚠️ No {category} groups available. Create one first.")
else:
    print(f"✅ {len(groups['emission_groups'])} {category} groups available")

Response Fields

string

UUID of the organization

array

Array of custom emission group objectsEach group contains:

id: Group UUID
name: Group name
category: Category type
group_start_date: Optional validity start date
group_end_date: Optional validity end date
group_uploaded_by: Optional uploader reference

Common Errors

422 Validation Error - Invalid Category

Cause: Invalid category. Must be ‘purchases’, ‘wastes’, or ‘energy’

{
  "detail": "Invalid category. Must be 'purchases', 'wastes', or 'energy'",
  "code": "VALIDATION_ERROR"
}

Solution: Use purchases, wastes, or energy for the category parameter.

404 Not Found

Cause: Organization not found

{
  "detail": "Organization not found",
  "code": "NOT_FOUND"
}

Solution: Verify the organization ID is correct.

List All Groups

View groups across all categories

Organization Data

Get groups with factors

Create Group

Add new group

Introduction

Logistics

Facilities

Vehicles

Purchases

Wastes

Reference Data

Custom Emission Factors

Custom Emission Groups

List Groups by Category

List Groups by Category

Request

Headers

Path Parameters

Response

Example

Use Cases

Load Category-Specific Groups

Build Category Selector

Filter All Categories

Check Group Availability

Response Fields

Common Errors

422 Validation Error - Invalid Category

404 Not Found

List All Groups

Organization Data

Create Group

​List Groups by Category

​Request

​Headers

​Path Parameters

​Response

​Example

​Use Cases

​Load Category-Specific Groups

​Build Category Selector

​Filter All Categories

​Check Group Availability

​Response Fields

​Common Errors

​422 Validation Error - Invalid Category

​404 Not Found

​Related Endpoints

List All Groups

Organization Data

Create Group

List Groups by Category

Request

Headers

Path Parameters

Response

Example

Use Cases

Load Category-Specific Groups

Build Category Selector

Filter All Categories

Check Group Availability

Response Fields

Common Errors

422 Validation Error - Invalid Category

404 Not Found

Related Endpoints