List Groups by Category

Get custom emission groups filtered by category for an organization

GET /api/v1/custom_emission_groups/list_of_emission_groups/{organization_id}/{category}

List Groups by Category

JavaScript

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));

200

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

Legacy API. This page documents the previous version of the API. This particular operation has no documented equivalent in the current API yet, so this remains the documented way to do it. Prefer the current API for everything it already covers.

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 authentication

Example: sk_live_1234567890abcdef

x-organization-id · string · required

Your organization UUID

Example: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

x-user-id · string · required

Your user UUID

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Path Parameters

organization_id · string · required

UUID of the organization

Example: "org-uuid-here"

category · string · required

Category to filter by

Values: "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": "[e-mail]"
    },
    {
      "id": "group-uuid-2",
      "name": "Supplier XYZ Products",
      "category": "purchases",
      "group_start_date": null,
      "group_end_date": null,
      "group_uploaded_by": null
    }
  ]
}

Example

cURL

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 objects

Each 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.

Related Endpoints

List All Groups

View groups across all categories

Organization Data

Get groups with factors

Create Group

Add new group