Nachweise-API

Erstelle und verwalte Nachweise (Assertions) — Badges, die an konkrete Empfänger:innen ausgestellt sind.

Alle Endpunkte erfordern eine Authentifizierung über den Header X-Api-Key. Siehe Authentifizierung.

Nachweis erstellen

Stelle einer Empfängerin bzw. einem Empfänger ein Badge aus.

Du musst an Hunderte oder Tausende Empfänger:innen auf einmal ausstellen, statt einen API-Aufruf pro Person zu machen? Nutze die UI-Funktion Massen-Nachweise, die einen CSV-Upload akzeptiert.

POST /awards

Parameter

Parameter	Typ	Erforderlich	Beschreibung
`badgeId`	string	Ja	Die ID des auszustellenden Badges
`recipient`	object	Ja	Angaben zur Empfängerin bzw. zum Empfänger (siehe unten)
`recipient.name`	string	Ja	Vollständiger Name der Empfängerin bzw. des Empfängers (mindestens 5 Zeichen)
`recipient.email`	string	Ja	E-Mail-Adresse der Empfängerin bzw. des Empfängers
`issuedOn`	string	Ja	Ausstellungsdatum im ISO-8601-Format (z. B. `2025-01-15`)
`expires`	string	Nein	Ablaufdatum im ISO-8601-Format

Beispiel

bash

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15"
    }
  }'

Antwort

json

{
  "awardId": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Hinweise

Zählt als ein Nachweis gegen deinen jährlichen Nachweis-Pool (Free: 1.200/Jahr, Starter: 12.000/Jahr, Pro: 120.000/Jahr). Der Pool ist ein flexibles Jahreskontingent — du kannst es über das Jahr verteilt jederzeit ausschöpfen, auch in Schüben — und wird am Jahrestag der Registrierung deines Kontos zurückgesetzt. Die Abrechnung bleibt monatlich; nur das Nachweis-Kontingent ist jährlich. Details siehe Tarife & Abrechnung.

Nachweise auflisten

Rufe Nachweise mit optionaler Filterung und Paginierung ab.

GET /awards

Query-Parameter

Parameter	Typ	Erforderlich	Beschreibung
`filter`	JSON-String	Nein	Filterobjekt (siehe unten)
`lastEvaluatedKey`	string	Nein	Paginierungs-Token aus einer vorherigen Antwort

Filterobjekt

Der Parameter filter akzeptiert einen JSON-String mit diesen Feldern:

Feld	Typ	Beschreibung
`badgeId`	string	Nach Badge-ID filtern.
`search`	string	Teilzeichenfolge, die in den Namen oder E-Mail-Adressen der Empfänger:innen gesucht wird (siehe `searchField`).
`searchField`	string	Entweder `name` (Standard) oder `email` — in welcher Spalte gesucht wird.

Die Paginierung über lastEvaluatedKey funktioniert mit und ohne Filter. Die Seitengröße beträgt 50.

Beispiel — alle Nachweise auflisten

bash

curl -X GET https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here"

Beispiel — nach Badge filtern

bash

curl -X GET "https://api.badges.ninja/awards?filter=%7B%22badgeId%22%3A%22b1c2d3e4%22%7D" \
  -H "X-Api-Key: bws_your_api_key_here"

Antwort

json

{
  "count": 1,
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
      "badge": {
        "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
        "name": "JavaScript Fundamentals",
        "image": "https://badges.ninja/images/{sha256}.png"
      },
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15T00:00:00.000Z",
      "timestamp": "2025-01-15T10:30:00.000Z"
    }
  ],
  "lastEvaluatedKey": "eyJ..."
}

Ist lastEvaluatedKey in der Antwort enthalten, gibt es weitere Ergebnisse. Übergib es in der nächsten Anfrage als Query-Parameter, um die nächste Seite zu erhalten.

Nachweis-E-Mail senden

Sende einer Empfängerin bzw. einem Empfänger eine E-Mail-Benachrichtigung zu ihrem bzw. seinem Nachweis.

POST /awards/{awardId}/send

Parameter

Parameter	Typ	Erforderlich	Beschreibung
`awardId`	string	Ja	Die Nachweis-ID (Pfadparameter und Body)
`email`	string	Ja	E-Mail-Adresse der Empfängerin bzw. des Empfängers

Beispiel

bash

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "email": "jane@example.com"
    }
  }'

Antwort

Gibt einen einfachen Bestätigungs-String zurück:

json

"email sent"

Nachweis teilen

Teile einen Nachweis per E-Mail mit mehreren Empfänger:innen.

POST /awards/{awardId}/share

Parameter

Parameter	Typ	Erforderlich	Beschreibung
`awardId`	string	Ja	Die Nachweis-ID (Pfadparameter und Body)
`recipients`	string	Ja	Kommagetrennte Liste von E-Mail-Adressen
`subject`	string	Ja	Betreffzeile der E-Mail
`message`	string	Ja	Nachrichtentext der E-Mail

Beispiel

bash

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/share \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "recipients": "manager@example.com,hr@example.com",
      "subject": "Check out my new badge!",
      "message": "I just earned the JavaScript Fundamentals badge."
    }
  }'

Antwort

Gibt einen einfachen Bestätigungs-String zurück:

json

"email sent"

Nachweis widerrufen

Widerrufe einen von dir ausgestellten Nachweis. Die gehostete Open-Badges-v2.0-Assertion wird mit revoked: true (und optional einem Grund) markiert, sodass jeder Verifizierer erkennt, dass das Badge nicht mehr gültig ist. Der Nachweis-Datensatz bleibt zu Prüfzwecken erhalten, und es wird kein Guthaben erstattet.

Der Widerruf wird auch auf die Open-Badges-3.0-Verifiable-Credential des Nachweises übertragen: Das Bit des Nachweises wird in der W3C Bitstring Status List umgeschaltet, auf die der credentialStatus der VC verweist, sodass auch VC-Wallets den Widerruf erkennen. Siehe Widerruf (Bitstring Status List).

POST /awards/{awardId}/revoke

Parameter

Parameter	Typ	Erforderlich	Beschreibung
`awardId`	string	Ja	Die Nachweis-ID (Pfadparameter)
`reason`	string	Nein	Grund für den Widerruf. Wird auf 500 Zeichen gekürzt.
`notify`	boolean	Nein	Bei `true` wird die Empfängerin bzw. der Empfänger per E-Mail über den Widerruf des Nachweises informiert. Standardmäßig `false`.

Beispiel

bash

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/revoke \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "reason": "Issued to the wrong recipient",
      "notify": true
    }
  }'

Antwort

json

{
  "revoked": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Das Widerrufen eines bereits widerrufenen Nachweises ist idempotent — es wird dieselbe Antwort zurückgegeben, ohne erneut eine Benachrichtigung zu senden.

Massenwiderruf

Um viele Nachweise auf einmal zu widerrufen, nutze den dauerhaften Bulk-Endpunkt mit action: "revoke", statt diesen Endpunkt pro Nachweis aufzurufen:

bash

curl -X POST https://api.badges.ninja/awards/bulk-send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "action": "revoke", "awardIds": ["<id1>", "<id2>"], "reason": "Program cancelled", "notify": false } }'

Er gibt { "jobId", "total" } zurück; der Job widerruft jede ID serverseitig (bereits widerrufene werden übersprungen) und ist fortsetzbar. Bereits widerrufene und nicht existierende IDs werden als übersprungen gemeldet.

Nachweis löschen

Lösche einen von dir ausgestellten Nachweis endgültig. Anders als beim Widerruf wird der Datensatz dabei vollständig entfernt, und die öffentliche Nachweisseite liefert 404. Nutze das für echte Fehler (z. B. an die falsche Person ausgestellt); bevorzuge für echte Nachweise den Widerruf, damit die Assertion als widerrufen verifizierbar bleibt. Es wird kein Guthaben erstattet.

DELETE /awards/{awardId}

Parameter

Parameter	Typ	Erforderlich	Beschreibung
`awardId`	string	Ja	Die Nachweis-ID (Pfadparameter)

Beispiel

bash

curl -X DELETE https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012 \
  -H "X-Api-Key: bws_your_api_key_here"

Antwort

json

{
  "deleted": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

PDF-Zertifikat herunterladen

Erzeuge ein druckfertiges A4-PDF-Zertifikat für einen Nachweis.

GET /certify-badge/award/{awardGuid}/pdf

Keine Authentifizierung erforderlich — dieser Endpunkt ist öffentlich, damit Empfänger:innen ihr eigenes Zertifikat herunterladen können.

Beispiel

bash

curl -OJ https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/pdf

Die Antwort ist das binäre PDF mit dem Header Content-Type: application/pdf.

Nachweis-Ereignis erfassen

Erfasse ein Interaktionsereignis. Wird von der öffentlichen Nachweisseite genutzt, um Interaktionsstatistiken zu füllen. Keine Authentifizierung erforderlich.

POST /certify-badge/award/{awardGuid}/event

Parameter

Dieser Endpunkt liest seinen Body direkt (ohne parameters-Wrapper).

Parameter	Typ	Erforderlich	Beschreibung
`event`	string	Ja	Eines von `view`, `share`, `download`, `click_linkedin_addtoprofile`, `click_pdf`, `click_verify`.
`network`	string	Nein	Bei `event=share` das soziale Netzwerk: `linkedin`, `twitter`, `facebook`, `whatsapp`, `telegram`, `email`, `copy`.

Duplikatunterdrückung pro IP: Dasselbe Ereignis von derselben IP wird nur einmal pro 24 Stunden gezählt.

Beispiel

bash

curl -X POST https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/event \
  -H "Content-Type: application/json" \
  -d '{"event": "share", "network": "linkedin"}'

Antwort

json

{
  "ok": true
}

Nachweis-Statistiken abrufen

Rufe die kumulierten Interaktionszähler eines Nachweises ab.

GET /certify-badge/award/{awardGuid}/stats

Keine Authentifizierung erforderlich.

Antwort

Die Zähler werden nach dem rohen Ereignistyp geordnet zurückgegeben. totals enthält die Gesamtzahl pro Ereignis; networks schlüsselt die Aufteilung nach Netzwerk für Ereignisse auf, die ein network tragen (derzeit share). Ereignisse ohne erfasste Aktivität fehlen einfach.

json

{
  "totals": {
    "view": 142,
    "share": 16,
    "download": 3,
    "click_linkedin_addtoprofile": 4
  },
  "networks": {
    "share": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 }
  }
}

Nachweise-API ​

Nachweis erstellen ​

Parameter ​

Beispiel ​

Antwort ​

Hinweise ​

Nachweise auflisten ​

Query-Parameter ​

Filterobjekt ​

Beispiel — alle Nachweise auflisten ​

Beispiel — nach Badge filtern ​

Antwort ​

Nachweis-E-Mail senden ​

Parameter ​

Beispiel ​

Antwort ​

Nachweis teilen ​

Parameter ​

Beispiel ​

Antwort ​

Nachweis widerrufen ​

Parameter ​

Beispiel ​

Antwort ​

Massenwiderruf ​

Nachweis löschen ​

Parameter ​

Beispiel ​

Antwort ​

PDF-Zertifikat herunterladen ​

Beispiel ​

Nachweis-Ereignis erfassen ​

Parameter ​

Beispiel ​

Antwort ​

Nachweis-Statistiken abrufen ​

Antwort ​

Nachweise-API

Nachweis erstellen

Parameter

Beispiel

Antwort

Hinweise

Nachweise auflisten

Query-Parameter

Filterobjekt

Beispiel — alle Nachweise auflisten

Beispiel — nach Badge filtern

Antwort

Nachweis-E-Mail senden

Parameter

Beispiel

Antwort

Nachweis teilen

Parameter

Beispiel

Antwort

Nachweis widerrufen

Parameter

Beispiel

Antwort

Massenwiderruf

Nachweis löschen

Parameter

Beispiel

Antwort

PDF-Zertifikat herunterladen

Beispiel

Nachweis-Ereignis erfassen

Parameter

Beispiel

Antwort

Nachweis-Statistiken abrufen

Antwort