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.

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.

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