Skip to main content

Getting Started

This guide walks you through your first API call to the valueverde Partner API. By the end, you will have successfully retrieved a list of energy cooperatives.

Prerequisites​

Before you begin, make sure you have:

  • An API key -- Contact partners@valueverde.de to request your partner API key.
  • A tool to make HTTP requests -- curl (used in examples below), Postman, or any HTTP client library.

Base URL​

All API requests use the following base URL:

https://api.valueverde.de/

Authentication​

Every request must include your API key in the X-API-Key header:

X-API-Key: YOUR_API_KEY

That's it — all endpoints use API key authentication only.

Your first request​

Let's retrieve the list of published energy cooperatives. Replace YOUR_API_KEY with the key you received from valueverde.

curl -X GET \
  "https://api.valueverde.de/api-cooperatives" \
  -H "X-API-Key: YOUR_API_KEY"

Understanding the response​

A successful request returns a JSON object with three top-level fields:

FieldTypeDescription
successbooleanAlways true for successful responses
dataarrayList of cooperative objects
metaobjectResponse metadata (total count, timestamp)

Here is an abbreviated example response:

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Buergerenergie Musterhausen eG",
      "city": "Musterhausen",
      "description": "A community-owned renewable energy cooperative in southern Germany.",
      "share_price": 100,
      "minimum_shares": 1,
      "maximum_shares": 100,
      "entry_fee": 30,
      "entry_fee_type": "fixed",
      "last_dividend": "3,5%",
      "has_bafa_funding": true,
      "application_url": "https://app.valueverde.de/cooperatives/buergerenergie-musterhausen-eg",
      "statistics": {
        "co2_savings_tons_per_year": 450,
        "average_dividend_percent": 3.2,
        "total_projects": 12,
        "active_projects": 10,
        "total_kwh_per_year": 1250000,
        "total_households_supplied": 520,
        "total_installed_capacity_kwp": 890.5,
        "sdg_numbers": [7, 11, 12, 13],
        "dominant_energy_type": "Solar",
        "dominant_energy_percentage": 75
      },
      "co2_per_share": {
        "value": 0.146,
        "method": "gezeichnet",
        "capital_year": 2023
      }
    }
  ],
  "meta": {
    "total": 15,
    "timestamp": "2026-03-15T12:00:00.000Z"
  }
}

Each cooperative object includes core data (name, location, share pricing), aggregated statistics (energy production, CO2 savings, projects), and a pre-calculated CO2 impact per share. See the API Reference for the full schema.

Troubleshooting​

401 Unauthorized -- Missing or invalid API key​

If you receive a 401 response, your API key is either missing or not recognized.

Missing API key:

{
  "error": "API key required",
  "code": "MISSING_API_KEY"
}

Check that you are including the X-API-Key header in your request. The header name is case-sensitive.

Invalid API key:

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Verify that your API key is correct and has no extra whitespace or characters. If the problem persists, contact partners@valueverde.de.

403 Forbidden -- Inactive client​

If your partner account has been deactivated, you will receive a 403 response:

{
  "error": "API client inactive",
  "code": "CLIENT_INACTIVE"
}

Contact partners@valueverde.de to resolve account issues.

Next steps​

  • API Reference -- Explore the full endpoint documentation, request/response schemas, and field descriptions.
  • Error Reference -- HTTP status codes, error formats, and troubleshooting guidance.