API

Hier beschreiben wir die REST-API (Version 1.0) Ihres Alumnii-Systems. Die API liefert JSON in UTF-8. Wir werden sie voraussichtlich erweitern und anpassen und informieren Sie rechtzeitig über anstehende Änderungen. Wenn Ihnen an der API oder an dieser Dokumentation etwas fehlt, sagen Sie uns bitte Bescheid.

Authentifizierung

Für den Zugriff brauchen Sie einen API-Schlüssel. Falls Sie noch keinen haben, wenden Sie sich bitte an Ihre Ansprechperson bei Alumnii. Jeder API-Schlüssel gehört zu einem Benutzer, und dieser Benutzer muss Administratorrechte haben, damit der Schlüssel funktioniert.

Den Schlüssel übergeben Sie im HTTP-Header Authorization, mit dem Präfix Token und einem Leerzeichen davor. Lautet Ihr Schlüssel thisisyourapikey, übergeben Sie also Token thisisyourapikey. Ein Beispielaufruf mit curl:

curl -X GET https://ihr-alumnii-system.de/api/ -H 'Authorization: Token thisisyourapikey'

Ohne gültigen Schlüssel antwortet die API mit 401, gehört der Schlüssel zu einem Benutzer ohne Administratorrechte, mit 403.

Endpunkte

Endpunkt	Methoden	Inhalt
`/api/`	GET	Übersicht der Einstiegspunkte
`/api/schema/`	GET	OpenAPI-Schema der API
`/api/addressbook/users/`	GET	Liste der Mitglieder
`/api/addressbook/users/<id>/`	GET	Ein einzelnes Mitglied
`/api/addressbook/users/<id>/groups/`	GET	Die Mitgliedergruppen eines Mitglieds
`/api/events/event/`	GET, POST	Liste der Veranstaltungen, neue Veranstaltung anlegen
`/api/events/event/<id>/`	GET, PUT, PATCH, DELETE	Eine Veranstaltung lesen, ändern oder löschen

Schema

Unter /api/schema/ veröffentlicht die API ein OpenAPI-Schema (OpenAPI 3.0), mit dem Sie Clients für die API generieren können. Sie rufen es wie jeden anderen Endpunkt mit Ihrem API-Schlüssel ab. Das Schema wird im YAML-Format ausgeliefert; als JSON erhalten Sie es mit dem Parameter format=openapi-json:

curl -X GET 'https://ihr-alumnii-system.de/api/schema/?format=openapi-json' -H 'Authorization: Token thisisyourapikey'

Seitenweise Ausgabe

Alle Listen gibt die API seitenweise mit 100 Einträgen pro Seite aus. Mit den Feldern count, next und previous einer Antwort gehen Sie eine Liste durch: count ist die Gesamtzahl der Einträge, next und previous enthalten die URLs der nächsten und der vorigen Seite und sind null, wenn es keine solche Seite gibt. Unter results stehen die eigentlichen Einträge. Eine bestimmte Seite rufen Sie mit dem Parameter page ab, zum Beispiel /api/addressbook/users/?page=2.

Mitglieder

Der Endpunkt /api/addressbook/users/ liefert die Liste der Mitglieder, ein einzelnes Mitglied erhalten Sie unter /api/addressbook/users/<id>/. Beide liefern dieselben Felder. Tags und Admin-Tags werden als Liste von Zeichenketten ausgegeben. Ein Beispiel für ein exportiertes Mitglied:

{
  "id": 2,
  "created": "2018-03-05T09:12:44.102311+01:00",
  "email": "melina.musterfrau@example.com",
  "address": "Frau",
  "honorific_prefix": "",
  "first_name": "Melina",
  "family_name": "Musterfrau",
  "former_family_name": "",
  "date_of_birth": null,
  "about_me": "",
  "secondary_email": "",
  "phone_nr": "",
  "mobile_nr": "",
  "webpage": "",
  "company_address": "",
  "street": "Daimlerstr. 25",
  "additional_address_info": "",
  "zip_code": "76185",
  "city": "Karlsruhe",
  "state_region": "",
  "country": "DE",
  "secondary_company_address": "",
  "secondary_street": "",
  "secondary_additional_address_info": "",
  "secondary_zip_code": "",
  "secondary_city": "",
  "secondary_state_region": "",
  "secondary_country": "",
  "modified": "2018-07-11T11:19:15.437214+02:00",
  "receive_newsletter": false,
  "tags": ["Mitglied"],
  "admin_tags": [],
  "admin_url": "https://ihr-alumnii-system.de/admin/addressbook/profileuser/2/change/",
  "frontend_url": "https://ihr-alumnii-system.de/addressbook/2/",
  "current_company": "Google",
  "current_position": "Projektmanagerin",
  "social_media": {
    "linkedin": "https://www.linkedin.com/in/melina-musterfrau",
    "xing": "",
    "facebook": "",
    "twitter": "",
    "youtube": "",
    "instagram": "",
    "skype": "",
    "pinterest": "",
    "tumblr": "",
    "researchgate": "",
    "bluesky": ""
  },
  "extra_fields": {
    "studiengang": {"value": "wi", "display": "Wirtschaftsinformatik", "visible": true},
    "mentoring": null
  },
  "grad_year": "2012"
}

Hinweise zu den Feldern:

Textfelder sind nie null, Datumsfelder können null sein.
address ist die Anrede („Frau“, „Herr“ oder leer).
admin_url verlinkt auf das Mitglied im Adminbereich Ihres Alumnii-Systems, frontend_url auf sein Profil im Mitgliederbereich.
current_company und current_position stammen aus der jüngsten Station im Lebenslauf des Mitglieds.
social_media enthält die Profile in sozialen Netzwerken; hat ein Mitglied keine hinterlegt, ist das Objekt leer ({}).
extra_fields enthält die Zusatzfelder, für die ein API-Name vergeben ist. Jedes Feld hat entweder den Wert null (keine Antwort) oder ein Objekt mit dem gespeicherten Wert (value), dem angezeigten Text (display) und der Sichtbarkeit für andere Mitglieder (visible).
Die Felder am Ende des Beispiels (hier grad_year) stehen für die Felder, die es nur in Ihrem Datenmodell gibt. Welche das sind und in welchem Format sie ausgegeben werden, hängt von der Konfiguration Ihres Systems ab.

Filtern

Die Liste der Mitglieder lässt sich mit diesen GET-Parametern filtern:

id und email prüfen auf exakte Übereinstimmung.
modified_gte filtert nach dem Datum der letzten Änderung. Die Abfrage /api/addressbook/users/?modified_gte=2018-07-01 liefert zum Beispiel alle Mitglieder, die seit dem 1. Juli 2018 geändert wurden.
Außerdem können Sie nach den Feldern Ihres eigenen Datenmodells filtern (exakte Übereinstimmung, bei Auswahlfeldern mit dem gespeicherten Wert).

Mitgliedergruppen

Unter /api/addressbook/users/<id>/groups/ erhalten Sie die Mitgliedergruppen eines Mitglieds als Liste, sortiert nach Kategorie und Name:

[
  {
    "id": 3,
    "name": "Regionalgruppe Karlsruhe",
    "category": "Regionalgruppen",
    "description": "",
    "registration_type": "open",
    "details_only_for_members": false
  }
]

registration_type gibt an, wie Mitglieder der Gruppe beitreten: open (frei), application (auf Antrag) oder closed (nur durch die Gruppenverwaltung).

Veranstaltungen

Unter /api/events/event/ können Sie Veranstaltungen nicht nur lesen, sondern auch anlegen (POST), ändern (PUT, PATCH) und löschen (DELETE). Ein gekürztes Beispiel:

{
  "id": 12,
  "attendants": [
    {"id": 2, "email": "melina.musterfrau@example.com", "attending_type": "YES", "guests": 1}
  ],
  "membergroups": [3],
  "created": "2026-09-01T10:15:00.000000+02:00",
  "modified": "2026-09-14T16:40:12.000000+02:00",
  "title_de": "Sommerfest",
  "title_en": null,
  "category": "veranstaltung",
  "street": "Schlossplatz 1",
  "zip_code": "76131",
  "city": "Karlsruhe",
  "country": "DE",
  "location": "49.0134,8.4044",
  "virtual_event": false,
  "begin": "2026-11-12T18:30:00+01:00",
  "end": "2026-11-12T22:00:00+01:00",
  "registration_date": null,
  "text_de": "<p>Wir laden Sie herzlich ein …</p>",
  "attendants_max": 80,
  "guests_allowed": true,
  "visible_internal": true,
  "visible_external": false,
  "external_registration_url": "",
  "pic": null,
  "pic_thumb": null,
  "pic_email_thumb": null,
  "created_by": null,
  "last_modified_by": null
}

Hinweise zu den Feldern:

Texte, die es in mehreren Sprachen gibt, haben pro Sprache ein eigenes Feld mit Sprachkürzel, zum Beispiel title_de und title_en. Ist ein Text in einer Sprache nicht gepflegt, ist das Feld null.
attendants listet die Rückmeldungen der Mitglieder: attending_type ist YES (Teilnahme), MAY (vielleicht) oder NOT (keine Teilnahme), guests die Zahl der Gäste.
membergroups ist eine Liste der IDs der Mitgliedergruppen, auf die die Veranstaltung beschränkt ist.
location enthält die Koordinaten als „Breitengrad,Längengrad“.
id, created, modified, attendants, pic_thumb und pic_email_thumb können Sie nur lesen. Die Vorschaubilder erzeugt das System aus pic; ein Bild darf höchstens 10 MB groß sein.
created_by und last_modified_by verweisen auf die Benutzer, die die Veranstaltung angelegt und zuletzt geändert haben, oder sind null.