Open API Ledenbeheer
Laatst bijgewerkt 12 dagen geleden
Toegang tot de open-api is beschikbaar vanaf de pro-licentie.
Introductie
De Ledenbeheer API's zijn toegankelijk voor geregistreerde API-partners en vereisen authenticatie via een partner-token. Integratiepartners kunnen met behulp van deze API's de leden beheren en inschrijvingen verwerken voor de clubs waarmee ze zijn verbonden.Voor geïnteresseerde partijen is het mogelijk om een partner-token aan te vragen bij info@ledenbeheer.be.
Onze API is momenteel in ontwikkeling voor uitbreiding met meer functionaliteiten. Als je interesse hebt in extra functies, neem dan gerust contact met ons op.
API’s aanroepen
Alle API’s kunnen aangeroepen worden, en vereisen een partner authenticatie token en andere endpoint-specifieke parameters.Een endpoint die voor alle geregistreerde partners beschikbaar gesteld wordt is test_connection, waar enkel de partner authenticatie token vereist is.Deze endpoint geeft de permissies voor de partner token terug in 2 delen: beschikbare endpoints en beschikbare clubs.
Deze endpoint kan aangeroepen worden via https://integrations.ledenbeheer.be/test_connection?auth=PARTNER_AUTHENTICATION_TOKEN , waar de PARTNER_AUTHENTICATION_TOKEN placeholder vervangen wordt door het uitgereikte token.
Het resultaat van alle Ledenbeheer API’s wordt teruggeven in JSON formaat, zoals het voorbeeld hieronder voor de test_connection endpoint.
{"availableEndpoints":["test_connection","create_user_account","edit_user_account","get_user_accounts","get_dsv_annual_periods","register_user_account_for_dsv_annual_period"],"availableClubs":[{"id":102,"label":"Voorbeeldclub 1"},{"id":103,"label":"Voorbeeldclub 2"},{"id":104,"label":"Voorbeeldclub 3"}],"result":true,"process_time":0.26,"request_size":"373"}
Parameters zoals “address_country”, “address_postal_code”, “address_city” en “nationality” vereisen een waarde die in de lijst van mogelijke waardes voorkomt. Je kan deze lijsten verkrijgen door de get_valid_field_options API op te roepen met een geldige partner authenticatie token. Deze waarden worden gecontroleerd als “address_country” gelijk is aan “BE” of “NL”. De NL steden of postcodes kan je alsook vinden in de response van get_valid_field_options onder “cities_nl” en “postals_nl”.
API beperkingen
Een integratie partner kan maximum 100 requests uitvoeren per minuut, en de Ledenbeheer server zal een foutmelding weergeven als deze limiet overschreden wordt.
{"errors”:[“ You have exceeded your maximum amount of requests per minute”]}
De Ledenbeheer server zal alle requests van integratiepartners blokkeren als de server een hoge belasting heeft.Dit wordt gedaan om de diensten voor Ledenbeheer klanten te waarborgen, en hun de hoogste prioriteit te geven betreffende server resources.
{"errors”:[“ Server too busy, try again later”]}
Gebruikersaccounts aanmaken
Gebruikersaccounts voor clubs op Ledenbeheer kunnen aangemaakt worden met het create_user_account endpoint.Deze endpoint laat een partner toe om hoofd-accounts end kind-accounts aan te maken, en zal ook basisvalidatie uitvoeren om het aanmaken van gedupliceerde accounts te verhinderen. Alle gebruikeraccounts die aangemaakt worden met deze API worden automatisch aanzien als actieve leden, zelfs als er geen bestellingen of registraties gemaakt worden voor deze gebruiker.
Om aan de privacywetgeving te voldoen moet voor alle leden onder 18 jaar een kind-account aangemaakt worden onder de voogd-account voor deze gebruiker (meestal een account van een ouder van het lid).Functionaliteiten zoals beurtenkaarten worden per hoofd-account beheerd, het is dus belangrijk dat deze accounts correct aangemaakt worden.
Parameters
Onderstaande parameters worden geaccepteerd voor deze API.
Al deze parameters zijn ook geldig bij de API om een lid te bewerken
Resultaat
De Ledenbeheer API zal een JSON resultaat afleveren, waar de “result” key ofwel false ofwel het nieuwe ID van de gebruiker zal bevatten.Indien de “result” key false is zal een foutmelding worden teruggegeven in de “errors” key.
{"result”:5468458}
{“result”: false,"errors”:[“ Invalid email address.”]}
Voorbeeld URL
Gebruikersaccounts wijzigen
Bestaande gebruikersaccounts voor clubs op Ledenbeheer kunnen gewijzigd worden met het edit_user_account endpoint.Om aan de privacywetgeving te voldoen moet voor alle leden onder 18 jaar een kind-account aangemaakt worden onder de voogd-account voor deze gebruiker (meestal een account van een ouder van het lid).Functionaliteiten zoals beurtenkaarten worden per hoofd-account beheerd, het is dus belangrijk dat deze accounts correct aangemaakt worden.
Parameters
Onderstaande parameters worden geaccepteerd voor deze API.
Resultaat
De Ledenbeheer API zal een JSON resultaat afleveren, waar de “result” key ofwel false ofwel het ID van de gebruiker zal bevatten.
Indien de “result” key false is zal een foutmelding worden teruggegeven in de “errors” key.
{"result”:5468458}
{“result”: false,"errors”:[“ Invalid phone number.”]}
Voorbeeld URL
Lijst van gebruikersaccounts voor een club oproepen
De lijst van bestaande gebruikersaccounts voor clubs op Ledenbeheer kan opgeroepen worden met het get_user_accounts endpoint.
Parameters
Onderstaande parameters worden geaccepteerd voor deze API.
Resultaat
De Ledenbeheer API zal een JSON resultaat afleveren, waar de “result” key ofwel false ofwel de lijst van gebruikers zal bevatten.federation_dsv_membership_no wordt enkel meegegeven indien je daarvoor rechten hebt, heb je dit recht nodig dan contacteer je ons om dit in te stellen.
Indien de “result” key false is zal een foutmelding worden teruggegeven in de “errors” key.
{"result": {"111855": {"uid": "111855","fname": "John","lname": "Smith","email": "john.smith@gmail.com","parent_uid": 0,"birthdate": "1997-08-21","birthdate_unix": "557107200","phone": "0123456789","sex": "Man","address": {"street": "Duet","streetNumber": "33","postal": "7430","city": "Gent","country": "BE","federation_dsv_membership_no": "123456"}},"458436": {"uid": "458436","fname": "Anna","lname": "Woods","email": "anna.woods@gmail.com","parent_uid": 111855,"birthdate": "1960-12-11","birthdate_unix": "-285728400","phone": "0476337442","sex": "Vrouw","address": {"street": "Duet","streetNumber": "33","postal": "7430","city": "Gent","country": "BE","federation_dsv_membership_no": "234567"}}},"process_time": 0.255,"request_size": "1526"}
{“result”: false,"errors”:[“You don't have permission to access this club.”]}
Voorbeeld URL
https://integrations.ledenbeheer.be/get_user_accounts?auth=PARTNER_AUTHENTICATION_TOKEN&club=102
Enkele gebruiker oproepen voor een specifieke club
Zelfde response data als van een lijst van gebruikers, maar nu voor een enkele gebruiker, deze kan opgeroepen worden via get_user_account endpoint.
Parameters
Onderstaande parameters worden geaccepteerd voor deze API.
Resultaat
De Ledenbeheer API zal een JSON resultaat afleveren, waar de “result” key ofwel false ofwel de details van de gebruiker zal bevatten.federation_dsv_membership_no wordt enkel meegegeven indien je daarvoor rechten hebt, heb je dit recht nodig dan contacteer je ons om dit in te stellen.
Indien de “result” key false is zal een foutmelding worden teruggegeven in de “errors” key.
{"result": {"uid": "111855","fname": "John","lname": "Smith","email": "john.smith@gmail.com","parent_uid": 0,"birthdate": "1997-08-21","birthdate_unix": "557107200","phone": "0123456789","sex": "Man","address": {"street": "Duet","streetNumber": "33","postal": "7430","city": "Gent","country": "BE"},"dsv_membership_no": "123456"},"process_time": 0.255,"request_size": "1526"}
{“result”: false,"errors”:[“You don't have permission to access this club.”]}
Voorbeeld URL
Lijst van actieve leden voor een club oproepen
De lijst van actieve leden voor clubs op Ledenbeheer kan opgeroepen worden met het get_active_club_members endpoint.
Parameters
Onderstaande parameters worden geaccepteerd voor deze API.
Inschrijvingen ophalen via de API
Gebruik het volgende endpoint:
Parameters
De datumfilter selecteert cursussen en activiteiten waarvan de periode overlapt met de opgegeven periode.
cURL
curl --get "https://integrations.ledenbeheer.be/get_course_registrations" \
-H "Authorization: Bearer UW_TOKEN" \
--data-urlencode "club=12345" \
--data-urlencode "startDate=2026-01-01" \
--data-urlencode "endDate=2026-12-31" \
--data-urlencode "includeCancelled=0"
JavaScript / Node.js
Gebruik deze code alleen op een server, niet rechtstreeks in een browser.
const token = process.env.LEDENBEHEER_TOKEN;
const clubId = 12345;
const url = new URL(
"https://integrations.ledenbeheer.be/get_course_registrations"
);
url.searchParams.set("club", clubId);
url.searchParams.set("startDate", "2026-01-01");
url.searchParams.set("endDate", "2026-12-31");
url.searchParams.set("includeCancelled", "0");
const response = await fetch(url, {
headers: {
Authorization: Bearer ${token},
Accept: "application/json"
}
});
const data = await response.json();
if (!response.ok || data.result === false || data.errors?.length) {
throw new Error(data.errors?.join(", ") || HTTP ${response.status});
}
for (const course of Object.values(data.result)) {
console.log(`${course.title}: ${course.registrations.length} inschrijvingen`);
}PHP
<?php
$token = getenv('LEDENBEHEER_TOKEN');
$query = http_build_query([
'club' => 12345,
'startDate' => '2026-01-01',
'endDate' => '2026-12-31',
'includeCancelled' => 0,
]);
$curl = curl_init(
'https://integrations.ledenbeheer.be/get_course_registrations?' . $query
);
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $token,
'Accept: application/json',
],
CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($body === false) {
throw new RuntimeException(curl_error($curl));
}
curl_close($curl);
$data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if ($status >= 400 || $data['result'] === false || !empty($data['errors'])) {
throw new RuntimeException(
implode(', ', $data['errors'] ?? ["HTTP-fout {$status}"])
);
}
foreach ($data['result'] as $course) {
printf(
"%s: %d inschrijvingen\n",
$course['title'],
count($course['registrations'])
);
}5. Structuur van het antwoord
Een verkort antwoord ziet er als volgt uit:
{
"result": {
"70001": {
"nid": 70001,
"title": "Zwemlessen beginners",
"type": "course",
"status": 1,
"startDate": "2026-09-01",
"endDate": "2026-12-15",
"location": "Sportcentrum",
"tariffs": [
{
"nid": 70002,
"title": "Standaardtarief",
"registrationPeriod": ["2026-06-01 09:00", "2026-08-31"],
"sessionPeriod": ["2026-09-01", "2026-12-15"]
}
],
"sessions": [
{
"nid": 70003,
"title": "Les 1",
"date": "2026-09-01",
"from": "18:00",
"to": "19:00",
"status": 1
}
],
"registrations": [
{
"uid": 456,
"fname": "Jan",
"lname": "Janssens",
"tariff_label": "Standaardtarief",
"oid": 90001
}
]
}
},
"ordersPerUser": {
"456": {
"uid": 456,
"firstName": "Jan",
"lastName": "Janssens",
"email": "jan@example.be",
"orders": {
"90001": {
"oid": 90001,
"orderID": "BESTELLING-001",
"date": "2026-06-15",
"status": 1,
"amountPaid": 100,
"amountOutstanding": 0,
"amountTotal": 100
}
}
}
}
}Belangrijke velden
· result is een object, geïndexeerd op het ID van de cursus of activiteit.
· type is course of activity.
· registrations bevat de basisgegevens van de inschrijving.
· oid koppelt een inschrijving aan een bestelling in ordersPerUser.
· ordersPerUser bevat contact-, factuur- en betaalgegevens.
· status geeft de status van een cursus, sessie of bestelling weer.
· Bij includeCancelled=0 worden geannuleerde bestellingen niet opgenomen.
Gebruik bij het verwerken van de gegevens bij voorkeur nid, uid en oid als stabiele sleutels, niet de titels of namen.
De huidige handleiding beschrijft responsibleUsers nog niet expliciet. Onderstaande tekst kan rechtstreeks worden toegevoegd bij Inschrijvingen ophalen via de API. Het endpoint geeft per cursus ook sessies en inschrijvingen terug. Persoonsdetails kunnen daarna via get_user_accounts worden opgehaald. Open API Ledenbeheer
Cursusverantwoordelijken ophalen
Elk cursusobject in het resultaat van get_course_registrations kan de eigenschap responsibleUsers bevatten. Dit veld bevat de Ledenbeheer-gebruikers die als verantwoordelijke aan de cursus zijn gekoppeld.
Voorbeeld:
{ "nid": "123", "title": "Ballet beginners", "responsibleUsers": { "555": "Kevin Docent", "778": "Anne Lesgever" }, "sessions": [ { "nid": "456", "date": "2026-09-07", "from": "18:00:00", "to": "19:00:00" } ] }De sleutel van ieder item is het unieke Ledenbeheer-gebruikers-ID, ook uid genoemd. De waarde is de zichtbare naam van de verantwoordelijke.
Gebruik altijd het uid als stabiele koppelsleutel. Namen kunnen wijzigen en zijn niet noodzakelijk uniek.
Om de volledige persoonsgegevens van een verantwoordelijke op te halen, zoals voornaam, familienaam, e-mailadres en telefoonnummer, kan de integratie het endpoint get_user_accounts voor dezelfde club gebruiken. Het uid uit responsibleUsers komt overeen met het uid in het resultaat van get_user_accounts.
Voorbeeld van de koppeling:
{ "responsibleUsers": { "555": "Kevin Docent" } }{ "result": { "555": { "uid": "555", "fname": "Kevin", "lname": "Docent", "email": "kevin@example.be", "phone": "0470000000" } } }Aandachtspunten:
Een cursus kan nul, één of meerdere verantwoordelijken hebben.
Een leeg of ontbrekend
responsibleUsersbetekent dat voor die cursus geen verantwoordelijke werd doorgegeven.responsibleUsershoort bij de volledige cursus en hoeft niet bij iedere sessie herhaald te worden.Een integratie die verantwoordelijken per lesmoment plant, kan de cursusverantwoordelijken koppelen aan alle sessies binnen die cursus.
Verwijder een eerder opgeslagen verantwoordelijke niet onmiddellijk wanneer het veld tijdelijk ontbreekt. Controleer eerst opnieuw of de koppeling werkelijk in Ledenbeheer verwijderd werd.
Bewaar naast het
uidook het cursus-IDnid, zodat dezelfde gebruiker voor meerdere cursussen correct kan worden verwerkt.Synchronisaties horen idempotent te zijn: dezelfde cursus, gebruiker en sessie mogen bij een volgende synchronisatie niet dubbel worden aangemaakt.
6. Synchronisatie
Het endpoint biedt momenteel geen updatedSince-parameter en geen paginering. De datumfilter kijkt naar de periode van de cursus of activiteit, niet naar het moment waarop een inschrijving gewijzigd werd.
Een aanbevolen synchronisatiestrategie is daarom:
1. Haal periodiek het volledige huidige seizoen op.
2. Bewaar cursussen op basis van nid.
3. Bewaar inschrijvingen op basis van de combinatie nid, uid, oid en tariff_label.
4. Werk bestaande records bij.
5. Verwijder records niet onmiddellijk wanneer ze ontbreken; controleer eerst opnieuw met includeCancelled=1.
Voorbeeld van een periodieke synchronisatie:
startDate=2026-01-01
endDate=2026-12-31
includeCancelled=17. Foutafhandeling
Controleer zowel de HTTP-status als de velden result en errors.
{
"result": false,
"errors": ["Invalid token"]
}Mogelijke fouten zijn:
· Ongeldig of uitgeschakeld token
· Token heeft geen toegang tot de gevraagde club
· Ontbrekend of ongeldig club-ID
· Tijdelijke overbelasting van de server
· Overschrijding van de limiet van 100 aanvragen per minuut
Bij HTTP 503 kan de aanvraag later opnieuw worden geprobeerd. Gebruik bijvoorbeeld oplopende wachttijden van 2, 5, 10 en 30 seconden.
Parameters
club, verplicht, het club ID
startDate en endDate, optioneel, als je enkel cursussen in een bepaalde periode wil ophalen.
includeCancelled, optioneel, standaard 0. Geef waarde van 1 terug als je geannuleerde inschrijvingen ook wil ophalen.
Output
result: dit object lijst alle cursussen en activiteiten op in de opgevraagde tijdsperiode.
Elk cursus-object bevat de eigenschappen van een cursus, en alle sessies, tarieven, extra diensten, kortingen en inschrijvingenordersPerUser: dit object bevat een lijst van alle gebruikers die inschrijvingen hebben op de cursussen in de opgegeven periode, en geeft je details over de kostennota’s die aangemaakt werden voor deze inschrijvingen. Kortingen en extra diensten worden hier ook weergegeven als die deel waren van de kostennota.