Issue a hosted signing link; the customer signs Joulo's clause text and the authorization is recorded at Joulo.

Machtiging

The machtiging (authorization) is the hinge of the whole flow, and it is not delegable. Your app can present the step, but the customer always signs Joulo's own clause text on a Joulo-hosted screen, and Joulo records the signatory, the moment, and the clause version. The authorized party is always Joulo B.V.

Issue a signing link

You call POST /v1/mandate-links for a concept account. Joulo mints a single-use, signed URL.

The customer signs

You deliver the URL to the customer (in your app, or by email). They open it, review Joulo's clause text and their connection details, and sign.

Joulo records it

On signing, Joulo records the mandate against the signatory person with a server-authoritative valid_from, and the connection moves into review. From then on, mandate_status reads active.

Issue a signing link

POST /v1/mandate-links — scope cpo:mandates:write

curl -X POST https://api.joulo.nl/functions/v1/api/v1/mandate-links \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "60092124-c768-4191-9c9d-55ef3fc49999" }'

{
  "ok": true,
  "mandate_status": "pending",
  "url": "https://joulo.nl/machtiging/cpo/5d305aefc3db3b59...",
  "token": "5d305aefc3db3b59...",
  "expires_at": "2026-08-19T12:44:21Z"
}

Body

Field	Required	Description
`account_id`	yes	The concept account to sign for.
`connection_id`	no	Disambiguates when an account has more than one active connection.

The link is valid for 30 days. If the account is already signed, you get mandate_status: "active" and already_signed: true instead of a new link.

The URL host follows the environment you called. On the sandbox it is staging.joulo.nl.

Deliver the URL, don't re-host the screen. The signing page must be the Joulo-hosted one — that's what makes the authorization provably ours. Show it in an in-app browser, link to it, or email it.

The signing screen

The customer sees the connection (EAN + address), the signatory name, and Joulo's authorization clauses (grant to Joulo, consent to the NEa, the customer's own confirmations, and the conditions). If they are switching from another ERE provider, they can declare it — the mandate then starts on 1 January of the following year. You see that as mandate_valid_from, and a month you deliver before it comes back as outside_mandate.

When a machtiging lapses

The clause text ends the authorization when the name, address or EAN changes. So correcting an EAN on a signed connection is not a field edit: it revokes the machtiging. POST /v1/connections:update does that revocation for you when you acknowledge it, and you then issue a new link here. The customer signs the corrected EAN and the counting window opens again.

Errors

HTTP	`error`
400	`invalid_account_id`
404	`account_not_found`
409	`no_connection`, `no_signatory`

Tracking status

Poll GET /v1/accounts — each connection reports mandate_status (pending → active) and, once signed, mandate_valid_from.

Machtiging

On this page