Skip to main content

Customer API

Overview​

Endpoint:

  • Production: https://customer.api.energyzero.nl
  • Prerelease: https://customer.api.staging.energyzero.nl

The Customer API endpoint provides a comprehensive GraphQL API tailored for energy insights applications from the customer perspective. It exposes all the data and self-service capabilities needed for a modern, interactive energy platform. This includes both granular energy usage insights and self-service options such as updating invoice addresses and recalculating monthly advance payment amounts.

Key Features​

  • Customer-Centric Data Access
    Retrieve all relevant information for end-customers, including consumption data, billing details, and more.
  • Self-Service Operations
    Empower customers to manage their account with features like:
    • Changing invoice addresses
    • Recalculating monthly advance payments
  • Modern GraphQL Architecture
    Built with GraphQL, allowing flexible queries and efficient data retrieval.

How to Use the API​

GraphQL Basics​

The API is structured around a GraphQL schema, which defines all available data types, queries, and mutations. The two main entry points are:

  • Queries: Retrieve data from the API.
  • Mutations: Perform actions that modify data, such as updating customer information or recalculating payments.

From these entry points, you can traverse the schema to access nested data and related entities, mirroring the relationships in your application's data model.

Introspection & Interactive Exploration​

GraphQL introspection makes the API self-documenting. You can use tools like Apollo Studio Sandbox to:

  • Explore the schema interactively
  • View all available queries, mutations, and types
  • Test requests in both test and production environments

To access the API via Apollo Studio, set the endpoint to either the prerelease or production details provided at the start of this document and provide a valid JWT access token in the Authorization header. This enables you to browse the schema, see documentation for each field, and build queries with autocomplete support.

GraphQL introspection and interactive tools like Apollo Studio or GraphiQL provide a developer-friendly experience, enabling you to discover and understand the API without needing separate, static documentation.

Schema Structure​

The API schema defines:

  • Objects: Core resources such as Customer, Invoice, and UsageData
  • Queries: Entry points for fetching data
  • Mutations: Entry points for modifying data
  • Interfaces, Enums, Unions, Input Objects, and Scalars: For advanced schema design and type safety

Refer to the static schema definitions elsewhere in this documentation for a detailed breakdown of all types, fields, and relationships.

Best Practices & Additional Resources​

  • Use the Interactive Explorer: Always start with introspection tools to understand the latest schema and available operations.
  • Keep Your Documentation Up-to-Date: If you maintain static documentation, update it with every schema change to ensure accuracy.
  • Error Handling: Mutations and queries may return errors; consult the schema and error codes for guidance.
  • Security: Always use a valid JWT access token for authentication.

Further Reading​

For detailed static schema definitions and type references, continue to the next sections of this documentation. For hands-on exploration, use the Apollo Studio Sandbox with your credentials.