LEARNTEC 2027Treffen Sie Virtualbadge.io im Februar 2027 in Karlsruhe.Termin an unserem Stand vereinbaren
Anleitung

REST-API und Webhooks: Ausstellung aus dem eigenen System auslösen

Ihr Prüfungssystem oder Ihre Kursverwaltung fügt Teilnehmer selbst hinzu und löst den Versand aus. Sie testen in der Sandbox und lassen sich Ereignisse per Webhook melden. Die Anleitung zeigt jeden Schritt in Virtualbadge.io.

45 Min.Für AusstellerStand: November 2026
Auf einen BlickAnleitung
in 6 Schritten
Dauer
rund 45 Minuten
Für
Aussteller
Wo
Vorlage öffnen Teilnehmer Teilnehmer hinzufügen Per API hinzufügen
Tarif
Professional, sonst als Zusatzoption
Das brauchen Sie
  • Eine Entwicklerin oder ein Entwickler in Ihrem Team
  • Zugriff auf „Einstellungen“ und „Integrationen“
  • Eine aktive Vorlage

Noch kein Konto? Kostenlos testen. Die Testphase läuft sieben Tage.

Die REST-API ist der direkte Weg aus dem eigenen System. Ein Request fügt bis zu 100 Personen zu einer Vorlage hinzu und versendet auf Wunsch gleich die E-Mails. Die vollständige Dokumentation steht unter docs.virtualbadge.io.

Schritt 1: API-Token erzeugen

Öffnen Sie „Einstellungen“ und „Integrationen“. Unter „API Zugriff“ erzeugen Sie mit „Token generieren“ einen Token. Darunter stehen die URL für Anfragen und der geheime Zugriffs-Token.

Behandeln Sie den Token wie ein Passwort und legen Sie ihn nicht im Frontend-Code ab.

API Zugriff in den Integrationen.

Schritt 2: Beispiel zur Vorlage öffnen

Öffnen Sie in der Vorlage „Teilnehmer“, klicken Sie auf „Teilnehmer hinzufügen“ und wählen Sie „Per API hinzufügen“. Der Dialog „API Integration“ zeigt in drei Schritten ein fertiges Beispiel für genau diese Vorlage, wahlweise als cURL, JavaScript oder Python.

„Per API hinzufügen“ im Menü der Teilnehmerliste.

Schritt 3: Teilnehmer per Request hinzufügen

Senden Sie einen POST-Request an /v2/public/recipient/. Der Token steht im Header „Authorization“ als Bearer-Token. Im Body nennen Sie die Vorlage im Feld certificate und die Personen im Feld recipients. Pflicht sind je Person email und full_name.

Mit send_emails legen Sie fest, ob die E-Mails sofort verschickt werden, mit add_duplicates, ob doppelte E-Mail-Adressen erlaubt sind. Ein Request nimmt bis zu 100 Personen auf.

Dialog „API Integration“ mit Beispiel-Request und Antwort.
Beispiel
curl -X POST "https://api.virtualbadge.io/v2/public/recipient/" \  -H "Authorization: Bearer YOUR_API_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "certificate": "cert_8Kq2mXv4TzR1pLw9",    "send_emails": true,    "add_duplicates": true,    "recipients": [      { "email": "lena.hoffmann@example.org", "full_name": "Lena Hoffmann" }    ]  }'
Felder im Request
FeldBedeutung
certificateID der Vorlage
recipientsListe der Personen, bis zu 100 je Request
emailE-Mail-Adresse der Person, Pflichtfeld
full_nameName der Person, Pflichtfeld
send_emailstrue versendet die E-Mails sofort
add_duplicatestrue erlaubt doppelte E-Mail-Adressen

Schritt 4: Antwort verarbeiten

Bei Erfolg antwortet die API mit dem Status 201 und den erstellten Teilnehmer-Objekten. Jede Person erhält eine eindeutige id und eine access_page_url, die Adresse ihrer Teilnehmeransicht. Speichern Sie beide Werte in Ihrem System.

Schritt 5: Ereignisse per Webhook empfangen

Webhooks melden Ihrem System, wenn etwas passiert ist, zum Beispiel wenn ein Nachweis erzeugt oder der Zugriff eines Teilnehmers widerrufen wurde. Die Tabelle nennt die Ereignisse. Einrichtung und Felder beschreibt die API-Dokumentation.

Webhook-Ereignisse
EreignisWann es ausgelöst wird
Certificate/Badge GeneratedEin Nachweis wurde erzeugt
Credential Email SentDie E-Mail mit dem Nachweis wurde gesendet
Recipient Access RevokedDer Zugriff eines Teilnehmers wurde widerrufen
Training CompletedEin Training wurde abgeschlossen, von Hand oder automatisch

Schritt 6: In der Sandbox testen und umstellen

Testen Sie zuerst in einer Sandbox-Organisation. Nachweise von dort sind als Test gekennzeichnet. Ist alles richtig, übernehmen Sie die Vorlage in der Übersicht über „Zur Produktiv-Organisation migrieren“. Dabei entsteht dort eine Kopie mit Grundlegenden Details, Design und Teilnehmererlebnis. Prüfen Sie danach Token und Vorlagen-ID in Ihrem System, denn die Kopie ist eine eigene Vorlage.

„Vorlage verwalten“ in der Übersicht: „Migrieren“ erstellt eine Kopie der Vorlage in der Produktiv-Organisation.

Gehen Sie diese Anleitung mit Ihren eigenen Daten durch.

Ergebnis prüfen

  • Ein Test-Request liefert den Status 201.
  • Die Person erscheint in der Teilnehmerliste der Vorlage.
  • Ihr System hat id und access_page_url gespeichert.

Mehr dazu: API-DokumentationIntegrationen

Häufige Fragen

Wie viele Personen passen in einen Request?

Bis zu 100 Personen.

Wo finde ich die ID der Vorlage?

Im Dialog „API Integration“ ist sie im Beispiel schon eingetragen. Sie steht auch unten in der Übersicht der Vorlage.

Wo steht die vollständige Dokumentation?

Unter docs.virtualbadge.io. Der Dialog führt über „Zur Doku“ direkt dorthin.

Geht das auch ohne eigene Entwicklung?

Ja, über Zapier. Dort brauchen Sie keinen API-Token. Für Moodle gibt es ein eigenes Plugin.

So geht es weiter

Probieren Sie es mit Ihrem eigenen Zertifikat aus

Laden Sie Ihr aktuelles Zertifikatsdesign hoch, stellen Sie einen Testnachweis aus und gehen Sie die Anleitungen mit echten Daten durch. Die Testphase läuft sieben Tage.

Mehr als 1.000 Organisationen stellen mit Virtualbadge.io aus, darunter telc, SRH, APOLLON Hochschule, EBS Universität, Mannheim Business School und VDI Wissensforum. Für den Deutsch-Test für den Beruf nennt das BAMF Virtualbadge.io als Plattform für digitale Zertifikate (Trägerrundschreiben 04/26, Anlage 1).