Skip to main content
GET
https://api.dcycle.io
/
api
/
v1
/
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));
{
  "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

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9
​
x-user-id
string
required
Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

​
Path Parameters

​
organization_id
string
required
UUID of the organizationExample: "org-uuid-here"
​
category
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": "[email protected]"
    },
    {
      "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}"

​
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

​
organization_id
string
UUID of the organization
​
emission_groups
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

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

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