Integrated API
Onboard your customers, capture their machtiging, and deliver charging data programmatically • ERE registration and payout run on Joulo's rails.
Integrated API
The Integrated API is for CPOs that run their own app or portal and want to build ERE onboarding into their own product — no Joulo-hosted portal, no CSV uploads. You create the account, the customer signs their machtiging on a Joulo-hosted signing screen, and you push charging data over REST. Joulo runs the EAN validation, MID checks, NEa registration, and payout behind the scenes.
This is one of three CPO integration models. If you'd rather Joulo host a branded portal for your customers, see the white-label CPO portal instead. The Integrated API is offered per agreement to approved CPO partners.
The one rule that never bends
The machtiging (authorization) is a legal act that must land, provably, at Joulo: the signing person, the moment of signing, and the clause version are recorded through our endpoints. Your app can show the signing step, but the customer always signs Joulo's own clause text on a Joulo-hosted screen, and the authorized party is always Joulo B.V. This is why account creation and mandate capture are two separate steps.
Base URL
https://api.joulo.nl/functions/v1/apiAuthentication is OAuth 2.0 client credentials (machine-to-machine). See Authentication.
The lifecycle
Create the account
POST /v1/accounts — the customer's identity + connection (EAN + address), as
a concept. No machtiging yet, so it doesn't count toward anything.
See Accounts.
Capture the machtiging
POST /v1/mandate-links returns a signed link. The customer opens it and signs
Joulo's clause text; Joulo records the authorization and the counting window
opens. See Machtiging.
Register the charger
POST /v1/chargers links the account to a MID-certified model from the Joulo
catalog — the meter requirement for ERE. See Chargers.
Deliver charging data
POST /v1/sessions:batch pushes monthly kWh totals, idempotent per month.
See Charging data.
Joulo registers and pays out
After review, Joulo registers the MID-metered kWh as Emissiereductie-eenheden
(ERE) with the NEa and pays out per your agreement — directly to the customer,
or settled through you (payout_handler).
Idempotency & attribution
Every write is idempotent on a natural key, so retries are safe:
| Endpoint | Idempotency key |
|---|---|
POST /v1/accounts | cpo_external_ref (your customer number) |
POST /v1/mandate-links | one active mandate per connection |
POST /v1/chargers | one charger per account |
POST /v1/sessions:batch | (connection, month) |
Every account you create is attributed to your CPO partner automatically — the token you authenticate with is bound to exactly one partner.