Quickstart

In vier stappen van een sleutel naar een werkende koppeling. Reken op tien minuten.

1. Een sleutel maken

Een beheerder van de vereniging maakt sleutels aan in Ledenboek onder Instellingen → API-sleutels → Nieuwe sleutel. Geef de sleutel een naam waaraan je later herkent waarvoor hij is, en kies de rechten. Standaard staat alles op lezen en niets op schrijven; voor stap 4 heb je ook leden:schrijven nodig.

De sleutel wordt één keer getoond. Zet hem in een omgevingsvariabele en niet in je code:

shell

export LEDENBOEK_API_KEY="lb_test_..."

Werk je in een voorbeeldvereniging, dan begint de sleutel met lb_test_. Daar gaan geen mails en geen betaalverzoeken de deur uit, dus je kunt alles proberen zonder echte leden te raken.

2. Je eerste aanroep

GET /v2/organization werkt met elke sleutel en geeft de vereniging terug, de onderdelen die aan staan en de rechten van je sleutel. Een goede eerste controle dat alles klopt.

curl https://api.ledenboek.nl/v2/organization \
  -H "Authorization: Bearer $LEDENBOEK_API_KEY"

const response = await fetch("https://api.ledenboek.nl/v2/organization", {
  headers: { Authorization: `Bearer ${process.env.LEDENBOEK_API_KEY}` },
});
const organization = await response.json();
console.log(organization.name, organization.api_key.scopes);

<?php
$ch = curl_init("https://api.ledenboek.nl/v2/organization");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("LEDENBOEK_API_KEY")],
    CURLOPT_RETURNTRANSFER => true,
]);
$organization = json_decode(curl_exec($ch), true);
echo $organization["name"];

import os
import requests

response = requests.get(
    "https://api.ledenboek.nl/v2/organization",
    headers={"Authorization": f"Bearer {os.environ['LEDENBOEK_API_KEY']}"},
)
organization = response.json()
print(organization["name"], organization["api_key"]["scopes"])

Het antwoord:

200 OK

{
  "object": "organization",
  "id": 42,
  "name": "WSV De Kaag",
  "slug": "wsv-de-kaag",
  "country": "Nederland",
  "language": "nl",
  "website_url": "https://www.wsvdekaag.nl",
  "modules": {
    "groups": true,
    "committees": true,
    "participants": false,
    "relationships": false,
    "events": true,
    "invoicing": true
  },
  "api_key": {
    "name": "Koppeling met de website",
    "prefix": "lb_test_8kQz",
    "environment": "test",
    "scopes": [
      "leden:lezen",
      "leden:schrijven"
    ]
  }
}

Krijg je een 401, kijk dan of de header precies Authorization: Bearer lb_... is. Bij een 402 heeft de vereniging geen geldig abonnement.

3. Door leden bladeren

Met het recht leden:lezen haal je leden op met GET /v2/members. Een lijst komt in pagina's van maximaal 100 records (standaard 25). Zolang has_more waar is, vraag je de volgende pagina op door next_cursor mee te geven als starting_after.

curl "https://api.ledenboek.nl/v2/members?limit=100" \
  -H "Authorization: Bearer $LEDENBOEK_API_KEY"

# Next page: pass next_cursor from the previous response
curl "https://api.ledenboek.nl/v2/members?limit=100&starting_after=1234" \
  -H "Authorization: Bearer $LEDENBOEK_API_KEY"

const headers = { Authorization: `Bearer ${process.env.LEDENBOEK_API_KEY}` };
const members = [];
let cursor = null;

do {
  const url = new URL("https://api.ledenboek.nl/v2/members");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("starting_after", cursor);

  const page = await (await fetch(url, { headers })).json();
  members.push(...page.data);
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);

<?php
$members = [];
$cursor = null;

do {
    $query = http_build_query(array_filter(["limit" => 100, "starting_after" => $cursor]));
    $ch = curl_init("https://api.ledenboek.nl/v2/members?" . $query);
    curl_setopt_array($ch, [
        CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("LEDENBOEK_API_KEY")],
        CURLOPT_RETURNTRANSFER => true,
    ]);
    $page = json_decode(curl_exec($ch), true);
    $members = array_merge($members, $page["data"]);
    $cursor = $page["has_more"] ? $page["next_cursor"] : null;
} while ($cursor !== null);

import os
import requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['LEDENBOEK_API_KEY']}"

members, cursor = [], None
while True:
    params = {"limit": 100}
    if cursor:
        params["starting_after"] = cursor
    page = session.get("https://api.ledenboek.nl/v2/members", params=params).json()
    members.extend(page["data"])
    if not page["has_more"]:
        break
    cursor = page["next_cursor"]

Een pagina ziet er zo uit (ingekort; alle velden staan in de referentie):

200 OK

{
  "object": "list",
  "data": [
    {
      "object": "member",
      "id": 1234,
      "membership_number": "L042",
      "first_name": "Anna",
      "last_name": "de Vries",
      "email": "anna@example.com",
      "status": "active",
      "member_since": "2024-03-01",
      "created_at": "2024-03-01T10:12:00+01:00",
      "updated_at": "2026-10-02T08:30:00+02:00"
    }
  ],
  "has_more": true,
  "next_cursor": "1234"
}

4. Een lid aanmaken

Met leden:schrijven maak je een lid aan met POST /v2/members. Stuur een Idempotency-Key mee: een unieke waarde per nieuw lid, bijvoorbeeld een UUID. Valt de verbinding weg en stuur je hetzelfde verzoek opnieuw met dezelfde sleutel, dan krijg je het eerste antwoord terug en staat het lid er niet twee keer in.

curl https://api.ledenboek.nl/v2/members \
  -X POST \
  -H "Authorization: Bearer $LEDENBOEK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a3e-8d4b-4c1e-9a7f-2b5d0e9c4a11" \
  -d '{"first_name": "Anna", "last_name": "de Vries", "email": "anna@example.com"}'

// Store this key with your own record, so a retry sends the same one.
const idempotencyKey = crypto.randomUUID();

const response = await fetch("https://api.ledenboek.nl/v2/members", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LEDENBOEK_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  },
  body: JSON.stringify({ first_name: "Anna", last_name: "de Vries", email: "anna@example.com" }),
});
const member = await response.json();

<?php
// Store this key with your own record, so a retry sends the same one.
$idempotencyKey = bin2hex(random_bytes(16));

$ch = curl_init("https://api.ledenboek.nl/v2/members");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("LEDENBOEK_API_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: " . $idempotencyKey,
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "first_name" => "Anna",
        "last_name" => "de Vries",
        "email" => "anna@example.com",
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$member = json_decode(curl_exec($ch), true);

import os
import uuid
import requests

# Store this key with your own record, so a retry sends the same one.
idempotency_key = str(uuid.uuid4())

response = requests.post(
    "https://api.ledenboek.nl/v2/members",
    headers={
        "Authorization": f"Bearer {os.environ['LEDENBOEK_API_KEY']}",
        "Idempotency-Key": idempotency_key,
    },
    json={"first_name": "Anna", "last_name": "de Vries", "email": "anna@example.com"},
)
member = response.json()

Klopt er een veld niet, dan krijg je 422 met per veld wat er mis is:

422 Unprocessable Entity

{
  "type": "https://developers.ledenboek.nl/errors/validation_failed",
  "title": "Gegevens kloppen niet",
  "status": 422,
  "detail": "Een of meer velden zijn niet goed ingevuld; zie errors.",
  "instance": "/v2/members",
  "errors": [
    {
      "field": "email",
      "code": "invalid",
      "message": "E-mail is ongeldig"
    }
  ]
}

Verder

Authenticatie: welke rechten er zijn en wat een testsleutel anders doet.
Concepten: met updated_since alleen ophalen wat er veranderd is.
API-referentie: alle endpoints. Met de spec op /openapi.json genereer je zelf een client in je eigen taal, bijvoorbeeld met OpenAPI Generator.