Partner API
Upload and track pre-registered customers programmatically with a per-partner API key
The Partner API is the programmatic version of the partner portal's voor-aanmelden flow. Push customers from your own CRM or installation pipeline (name + email is enough), and each row becomes a claimable draft: the customer receives a personal claim link, confirms their details and signs the ERE authorization themselves. Attribution to your partner account happens at claim time.
It is available to approved Joulo partners with a portal account on partners.joulo.nl.
Getting an API key
- Log in at partners.joulo.nl.
- Open API-koppeling.
- Create a key. The secret starts with
jpk_live_and is shown once • only a SHA-256 hash is stored.
A partner has exactly one active key at a time: minting a new key revokes the previous one (rotation model). Keys can also be revoked from the same page.
Store the key in an environment variable or secrets manager. If a key leaks, mint a new one • the old key stops working immediately.
Base URL and authentication
https://api.joulo.nl/functions/v1/apiSend the key as a bearer token on every request:
curl https://api.joulo.nl/functions/v1/api/partner/me \
-H "Authorization: Bearer jpk_live_..."What a key can reach
An API key is bound to one partner and can upload and read back its own customers • nothing more. Everything else (company settings, payout IBAN, branding, minting or revoking keys) stays portal-session-only.
| Method | Path | Purpose |
|---|---|---|
GET | /me | Identify the key's partner context |
GET | /partner/me | Partner profile |
GET | /partner/drafts | Pre-registered customers awaiting claim |
GET | /partner/customers | Claimed, attributed customers (pseudonymised for self-signups) |
GET | /partner/ere-positions | Per-EAN ERE position in bulk • see ERE positions |
POST | /partner/drafts/import | Bulk import in the CSV row shape |
POST | /partner/customers | Upload customers • see Upload customers |
Requests outside this allowlist return 403, even though the key's scopes
(partners:read, partners:write) would nominally cover them.
Rate limits
Two token buckets apply; throttled requests return 429 with a Retry-After
header:
- Pre-auth, per IP + token prefix: burst of 30, refill 1 request/second.
- Per identity, after authentication: burst of 60, refill 1 request/second.
Both are comfortably above a normal integration's load (for example a poll-per-minute sync or a batched nightly upload).
OAuth2 and the portal
The partner portal itself talks to the same endpoints with an OAuth2 session
(partners:read / partners:write scopes). For server-to-server
integrations, the API key is the supported path • it never acts as a Joulo
user and cannot be used to impersonate one.