Vergaben-API

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

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

Vergabe erstellen

Stellt einer Empfängerin / einem Empfänger eine Auszeichnung aus.

POST /awards

Parameter

Parameter	Typ	Erforderlich	Beschreibung
badgeId	string	Ja	Die zu vergebende Auszeichnungs-ID
recipient	object	Ja	Empfängerdetails (siehe unten)
recipient.name	string	Ja	Vollständiger Name des Empfängers (mindestens 5 Zeichen)
recipient.email	string	Ja	E-Mail-Adresse des Empfängers
issuedOn	string	Ja	Ausstellungsdatum im ISO-8601-Format (z. B. 2025-01-15)
expires	string	Nein	Ablaufdatum im ISO-8601-Format
blockchain	string	Nein	Blockchain für On-Chain-Verifizierung. Nur matchain wird unterstützt. Im Pro-Plan verfügbar.

Beispiel

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

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

Hinweise

• Zählt einmal gegen dein Monatskontingent (Free: 100/Monat, Starter: 1.000/Monat, Pro: 10.000/Monat). Das Kontingent wird zu jeder Abrechnungsperiode zurückgesetzt.
• Der blockchain-Parameter ist nur im Pro-Plan verfügbar.

---

Vergaben auflisten

Ruft Vergaben 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 filter-Parameter akzeptiert einen JSON-String mit diesen Feldern:

Feld	Typ	Beschreibung
badgeId	string	Filtert nach Auszeichnungs-ID.
search	string	Teilstring zum Suchen in Empfängernamen oder -E-Mails (siehe searchField).
searchField	string	Entweder name (Standard) oder email — welche Spalte durchsucht wird.

Paginierung über lastEvaluatedKey funktioniert mit oder ohne Filter. Seitengröße ist 50.

Beispiel — alle Vergaben auflisten

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

Beispiel — nach Auszeichnung filtern

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

{
  "statusCode": 200,
  "info": {
    "awards": [
      {
        "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
        "badge": {
          "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
          "name": "JavaScript Fundamentals",
          "image": "https://ipfs.ninja/ipfs/Qm..."
        },
        "recipient": {
          "name": "Jane Smith",
          "email": "jane@example.com"
        },
        "issuedOn": "2025-01-15T00:00:00.000Z",
        "timestamp": "2025-01-15T10:30:00.000Z"
      }
    ],
    "lastEvaluatedKey": "eyJ..."
  }
}

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

---

Vergabe-E-Mail senden

Sendet einer empfangenden Person eine E-Mail-Benachrichtigung zu ihrer Vergabe.

POST /awards/{awardId}/send

Parameter

Parameter	Typ	Erforderlich	Beschreibung
awardId	string	Ja	Die Vergabe-ID (Pfadparameter und Body)
email	string	Ja	E-Mail-Adresse des Empfängers

Beispiel

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

{
  "statusCode": 200,
  "info": {
    "sent": true
  }
}

---

Vergabe teilen

Teilt eine Vergabe per E-Mail mit mehreren Empfänger:innen.

POST /awards/{awardId}/share

Parameter

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

Beispiel

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

{
  "statusCode": 200,
  "info": {
    "shared": true
  }
}

---

PDF-Zertifikat herunterladen

Erzeugt für eine Vergabe ein druckfertiges A4-PDF-Zertifikat.

GET /awards/{awardGuid}/pdf

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

Beispiel

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

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

---

Vergabe-Ereignis erfassen

Zeichnet ein Engagement-Ereignis auf (Aufruf, Teilen, Download, LinkedIn-Add). Wird von der öffentlichen Vergabeseite genutzt, um Engagement-Statistiken zu füllen. Keine Authentifizierung erforderlich.

POST /awards/{awardGuid}/event

Parameter

Parameter	Typ	Erforderlich	Beschreibung
kind	string	Ja	Einer von view, share, download, linkedin_add.
network	string	Nein	Wenn kind=share, das soziale Netzwerk: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Duplikat-Unterdrückung pro IP: derselbe kind von derselben IP wird einmal pro 24 Stunden gezählt.

Beispiel

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

---

Vergabe-Statistik abrufen

Ruft die kumulierten Engagement-Zähler einer Vergabe ab.

GET /awards/{awardGuid}/stats

Keine Authentifizierung erforderlich.

Antwort

{
  "statusCode": 200,
  "info": {
    "stats": {
      "views": 142,
      "shares": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 },
      "downloads": 3,
      "linkedin_adds": 4
    }
  }
}