Upload customers

POST /partner/customers turns each entry into a customer_draft through the same validation, dedupe, cap and attribution path as the portal's CSV import. Name and email are enough; the customer completes the rest (address, charger, authorization) in the claim flow.

Request

curl -X POST https://api.joulo.nl/functions/v1/api/partner/customers \
  -H "Authorization: Bearer jpk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "consent": true,
    "send_invite": true,
    "customers": [
      { "name": "Jan de Vries", "email": "[email protected]", "external_ref": "KLANT-8842", "referral_code": "AB12CD34" },
      {
        "type": "zakelijk",
        "company_name": "Bedrijf B.V.",
        "name": "Piet Pietersen",
        "email": "[email protected]",
        "kvk": "12345678",
        "btw": "NL001234567B01"
      }
    ]
  }'

Your own customer reference (external_ref)

Pass your own customer id as external_ref (max 120 characters, free-form) and it comes back unchanged on every read route: GET /partner/drafts, GET /partner/customers and GET /partner/ere-positions. That is the stable key to reconcile against your own system.

Prefer it over the alternatives: an e-mail address can change, and an EAN belongs to the connection, so after a change of occupant the same EAN carries a different customer. external_ref survives both.

• We never interpret the value and do not enforce uniqueness. Deduplication stays on e-mail, so a duplicate reference never breaks a batch.
• customer_ref is accepted as an input alias. On the way out the field is always called external_ref • in GET /partner/customers the name customer_ref is already taken by Joulo's own pseudonymous reference.
• It follows the same disclosure rules as name and e-mail: if a customer objects under the GDPR, the row falls back to pseudonymous and external_ref is omitted.
• CSV imports accept it as a column named external_ref, customer_ref, klantnummer or referentie.

Friend referral codes

If your customer holds a Joulo referral code from a friend (an existing Joulo customer), pass it as referral_code on that row. When the customer completes the claim flow, the friend referral is attributed exactly as if the code had been entered on joulo.nl — the referring friend earns their referral discount, on top of your partner attribution.

• An unknown code never blocks the row: the draft is still created, and the response reports the code as unmatched in referral_codes so you can ask the customer to double-check.
• Validate a code live (for instance on your own signup form) with GET /partner/referral-codes/check?code=AB12CD34:

{ "ok": true, "code": "AB12CD34", "valid": true, "referrer_first_name": "Sanne" }

The response discloses only the referrer's first name — the same as the public signup banner on joulo.nl.

Sending the address

If you already asked the customer where they live, send it along:

{
  "name": "Jan de Vries",
  "email": "[email protected]",
  "external_ref": "BBP-8842",
  "postal_code": "6971 LB",
  "house_number": "12",
  "house_number_addition": "B",
  "city": "Brummen"
}

This is worth more than a filled-in form. During registration Joulo resolves the EAN from postcode and house number against the Dutch EAN register, and corrects the street and city against the BAG. With the address on the draft, that lookup has already run when the customer opens the screen. They confirm an EAN instead of hunting for one on an energy bill. That is the step where sign-ups stall.

• Send the address of the connection where they charge, not a billing address. The authorization binds that connection.
• One address can carry more than one EAN. The customer picks and confirms, and always signs the authorization themselves.
• postal_code is normalised to 1234AB; spaces and case do not matter. house_number takes the digits, and an addition packed onto it (12B) is split off automatically.
• All four fields are optional and independent. Postcode plus house number is what drives the EAN lookup.
• The address is a head start, never a source of truth. It seeds the registration only while the customer has entered no address of their own. Whatever they type wins.
• A field we cannot read never costs you the row. The draft is created without the address and the row is named in address_ignored.
• CSV imports accept the columns postcode, huisnummer, toevoeging and plaats.

Pre-coupling the charger

If you already know which charger the customer owns, send it with the row and they never have to type it themselves:

{
  "name": "Jan de Vries",
  "email": "[email protected]",
  "external_ref": "BBP-8842",
  "charger_brand": "bluebird",
  "charger_id": "ec:64:c9:6d:29:40"
}

charger_brand is required whenever you send charger_id, and bluebird is the only accepted value. BlueBird Power is the one brand where Joulo holds a fleet operator key, so a charger can be attached without the customer authenticating with the manufacturer. Every other brand needs the customer to complete an OAuth step in person, which a partner cannot do on their behalf • those rows are rejected with charger_brand_unsupported rather than guessed at.

The id is normalised, so EC-64-C9-6D-29-40, EC64C96D2940 and ec:64:c9:6d:29:40 all resolve to the same charger.

Checked at upload, not at claim

We validate the id against the brand backend while your request is running, so a charger the manufacturer has not linked to Joulo comes back as charger_not_linked in the same response. That is the point of pre-coupling: you find out immediately, per row, instead of the customer hitting a dead end days later.

We also refuse an id that already sits on another Joulo account or another open draft, as charger_claimed. Validation proves a charger is on the Joulo fleet, never that it belongs to this particular customer, so the first claim wins and a contested id goes to support.

If our check cannot run at all — the brand backend is down, or our operator key is refused — the row is accepted with the id stored unvalidated. That failure is ours, not yours, and it never costs you a row. The claim re-checks before attaching anything.

What the customer sees

The charger is attached when the customer activates their claim, not at upload: it needs an account to hang off. They still confirm their details and sign the authorization, they just never see the charger step. The activate response carries charger_linked: true and sends them straight to their dashboard instead of the coupling screen.

If the charger turns out to be taken between your upload and their claim, the claim still completes • the authorization is far too valuable to throw away over a charger. They land on the coupling screen instead and charger_linked is false.

Business customers (zakelijk / vve)

A business row differs from a consumer row in three ways:

• kvk is required for zakelijk (exactly 8 digits) • a business row without it is rejected with missing_kvk. For vve the KvK registration is voluntary, so kvk is optional there • but validated when present.
• company_name carries the legal entity; name stays the contact person. On activation company_name becomes the customer's registered business name and btw is stored as the entity's VAT number. Rows without company_name fall back to name as the business name (the pre-2026-08 behaviour).
• The fee regime follows automatically. Once the customer activates their claim, the account is stamped zakelijk/vve and the flat business fee applies • you never set fees through this API.

The claim itself does not complete a business registration: after claiming, the customer signs in and finishes the full registration (address, charger, authorization signed by an authorized representative, plus a KvK extract and energy contract they upload themselves • those documents cannot be supplied through this API). Track progress via registration_status on GET /partner/customers.

Limits: at most 1.000 rows per request and a rolling cap of 50.000 rows per 30 days per partner. Rows over either limit are reported in skipped, never silently dropped.

Response

{
  "ok": true,
  "added": 2,
  "batch_id": "…",
  "created": [
    { "draft_id": "8f2c…", "email": "[email protected]", "external_ref": "KLANT-8842" },
    { "draft_id": "b41a…", "email": "[email protected]", "external_ref": null }
  ],
  "address_ignored": [
    { "email": "[email protected]", "reason": "invalid_postal_code" }
  ],
  "claim_urls": [
    { "email": "[email protected]", "claim_url": "https://joulo.nl/claim/…" }
  ],
  "referral_codes": [
    { "email": "[email protected]", "code": "AB12CD34", "matched": true }
  ],
  "rejected": [
    { "email": "[email protected]", "reason": "existing_user" }
  ],
  "skipped": {
    "invalid": 0,
    "reserved_domain": 0,
    "missing_kvk": 0,
    "already_drafted": 0,
    "existing_user": 1,
    "suppressed": 0,
    "conflict": 0,
    "over_request_limit": 0,
    "over_cap": 0,
    "charger_brand_unsupported": 0,
    "charger_not_linked": 0,
    "charger_claimed": 0
  },
  "cap": { "rolling_days": 30, "rolling_cap": 50000, "remaining_before": 49998 }
}

• created names every row that became a draft, in the order you sent them. draft_id is what POST /partner/drafts/auth-link wants, so you no longer need a GET /partner/drafts round-trip after an upload. When send_invite is false, each entry also carries its claim_url.
• address_ignored is only present when a row carried an address we could not read (invalid_postal_code or invalid_house_number). The draft is created regardless • an address is a head start, not a condition.
• claim_urls is only present when send_invite is false. It repeats what created already carries and stays for existing integrations.
• referral_codes is only present when at least one row carried a referral_code; matched: false means the code is unknown (the draft is still created).
• rejected names every address that did not become a draft, with a stable reason code: invalid, invalid_type, invalid_ean, reserved_domain, missing_kvk, already_drafted, existing_user, suppressed, conflict, over_request_limit, over_cap, charger_brand_unsupported, charger_not_linked, charger_claimed.
• invalid_type means the row's type was not one of particulier, zakelijk, vve. invalid_ean means the supplied EAN was not exactly 18 digits.
• reserved_domain means the address is on a Joulo-owned domain. Those are staff addresses, never customers, so they can't be pre-registered.
• existing_user means the address already belongs to a Joulo account, so the upload is refused for that row — an existing customer keeps whatever attribution they already have and never gets a claim invitation for an account they already own. Matching ignores dots and +tags on Gmail/Googlemail addresses, so [email protected] and [email protected] count as the same customer.
• skipped keeps the per-reason totals for the same rows.
• cap shows the rolling upload window so your integration can pace batches.

The claim flow

Each draft resolves to a personal link on joulo.nl/claim/…. The customer confirms who they are, connects their charger and signs the ERE authorization themselves.

Embedding in a webview (auth links)

The claim link identifies the draft, not the user: opening it still requires a sign-in. Inside an embedded webview that is a problem — Google blocks OAuth in webviews, and an emailed magic link forces the user out to their mail client.

For that case, mint a short-lived auth link just-in-time, the moment the user opens the screen:

POST /partner/drafts/auth-link
{ "draft_id": "…" }        // or { "email": "[email protected]" }

{ "ok": true, "auth_url": "https://joulo.nl/claim-auth/…", "expires_in": 300 }

Load auth_url straight into the webview. Joulo signs the customer in server-side and lands them on the claim page — no OAuth, no email round-trip.

• Take draft_id from the created array of your upload response. email works just as well and saves you from storing the id at all.
• The link is valid for 5 minutes and is a login credential: never store it, never email it, request a fresh one per screen-open. Re-minting invalidates the previous link.
• If the customer is new to Joulo, an account is created on the uploaded email address (confirmed, passwordless).
• If the email — or the uploaded EAN — already belongs to an existing Joulo account, the auth link deliberately does not sign in. The customer lands on the normal claim page and signs in with their own account. A partner-delivered link can never grant access to an existing account.
• Works only for drafts in invited or claimed status; activated, expired or conflicted drafts return an error.

Reading back status

Two lifecycles run one after the other. The draft status covers the claim (from upload to an activated account); once a draft is active, the customer appears in GET /partner/customers and registration_status takes over.

registration_status then runs concept → ingediend → in_review → goedgekeurd (or afgekeurd). A position only shows up in GET /partner/ere-positions once the registration is running and eligible sessions exist. As a reading model: draft active means onboarding started, registration_status: goedgekeurd means onboarding finished, and a row in ere-positions means ERE is building up.

GET /partner/drafts is paginated with limit (1–500, default 500) and offset. The response repeats limit and offset, and adds count. Page through everything you ever uploaded: the rolling cap of 50.000 rows per 30 days runs well past one page.

To look up one customer, filter with ?external_ref= or ?email=. Both match exactly, within your own partner:

curl "https://api.joulo.nl/functions/v1/api/partner/drafts?external_ref=KLANT-8842" \
  -H "Authorization: Bearer jpk_live_..."

count then reports what the filter leaves, so paging stays correct. stats keeps counting all your drafts by status • it feeds a dashboard, not a page.

Each row repeats what you uploaded • external_ref, ean and the address fields • so you can reconcile without keeping a local copy.

• GET /partner/drafts • uploaded rows and their claim status. A row moves to conflict on its own when the address hard-bounces: the claim mail can never arrive, so it leaves your open work instead of sitting on invited forever. Re-uploading that address is refused with suppressed.
• GET /partner/customers • attributed customers, including the effective fee and your partner share per customer. Every row carries a source that decides how much identity is disclosed:

An invited customer is identified because the e-mail address came out of your own customer base; contact and technical details stay masked unless you pre-registered them. A customer who objects under the AVG is demoted back to self_signup on both routes.