API voor uitreikingen

Maak en beheer badge-uitreikingen (assertions) — badges die aan specifieke ontvangers worden uitgegeven.

Alle endpoints vereisen authenticatie via de X-Api-Key-header. Zie Authenticatie.

Uitreiking aanmaken

Reik een badge uit aan een ontvanger.

POST /awards

Parameters

Parameter	Type	Verplicht	Omschrijving
badgeId	string	Ja	Het ID van de uit te reiken badge
recipient	object	Ja	Gegevens van de ontvanger (zie hieronder)
recipient.name	string	Ja	Volledige naam van de ontvanger (minimaal 5 tekens)
recipient.email	string	Ja	E-mailadres van de ontvanger
issuedOn	string	Ja	Uitgiftedatum in ISO 8601-formaat (bijv. 2025-01-15)
expires	string	Nee	Verloopdatum in ISO 8601-formaat
blockchain	string	Nee	Blockchain voor verificatie op de keten. Alleen matchain wordt ondersteund. Beschikbaar in het Pro-abonnement.

Voorbeeld

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"
    }
  }'

Respons

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

Opmerkingen

• Telt als één uitreiking tegen je maandelijkse quotum (Free: 100/maand, Starter: 1.000/maand, Pro: 10.000/maand). Het quotum wordt elke factuurperiode gereset.
• De parameter blockchain is alleen beschikbaar in het Pro-abonnement.

---

Uitreikingen opvragen

Haal uitreikingen op met optionele filtering en paginering.

GET /awards

Query-parameters

Parameter	Type	Verplicht	Omschrijving
filter	JSON-string	Nee	Filterobject (zie hieronder)
lastEvaluatedKey	string	Nee	Pagineringstoken uit een eerder antwoord

Filterobject

De parameter filter accepteert een JSON-string met deze velden:

Veld	Type	Omschrijving
badgeId	string	Filter op badge-ID.
search	string	Substring om in de namen of e-mailadressen van ontvangers te zoeken (zie searchField).
searchField	string	Ofwel name (standaard) of email — in welke kolom gezocht wordt.

Paginering via lastEvaluatedKey werkt met of zonder filters. De paginagrootte is 50.

Voorbeeld — alle uitreikingen opvragen

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

Voorbeeld — filteren op badge

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"

Respons

{
  "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..."
  }
}

Als lastEvaluatedKey aanwezig is in de respons, zijn er meer resultaten. Geef hem mee als queryparameter bij het volgende verzoek om de volgende pagina op te halen.

---

Uitreikings-e-mail versturen

Stuur een e-mailmelding naar een ontvanger over diens uitreiking.

POST /awards/{awardId}/send

Parameters

Parameter	Type	Verplicht	Omschrijving
awardId	string	Ja	ID van de uitreiking (path- en body-parameter)
email	string	Ja	E-mailadres van de ontvanger

Voorbeeld

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"
    }
  }'

Respons

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

---

Uitreiking delen

Deel een uitreiking met meerdere ontvangers per e-mail.

POST /awards/{awardId}/share

Parameters

Parameter	Type	Verplicht	Omschrijving
awardId	string	Ja	ID van de uitreiking (path- en body-parameter)
recipients	string	Ja	Door komma's gescheiden lijst met e-mailadressen
subject	string	Ja	Onderwerpregel van de e-mail
message	string	Ja	Berichttekst van de e-mail

Voorbeeld

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."
    }
  }'

Respons

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

---

PDF-certificaat downloaden

Genereer een afdrukklaar A4-PDF-certificaat voor een uitreiking.

GET /awards/{awardGuid}/pdf

Geen authenticatie vereist — dit endpoint is publiek zodat ontvangers hun eigen certificaat kunnen downloaden.

Voorbeeld

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

De respons is de binaire PDF met header Content-Type: application/pdf.

---

Gebeurtenis van een uitreiking registreren

Registreer een betrokkenheidsgebeurtenis (bekijken, delen, downloaden, LinkedIn-toevoeging). Wordt door de publieke uitreikingspagina gebruikt om betrokkenheidsstatistieken te vullen. Geen authenticatie vereist.

POST /awards/{awardGuid}/event

Parameters

Parameter	Type	Verplicht	Omschrijving
kind	string	Ja	Eén van view, share, download, linkedin_add.
network	string	Nee	Wanneer kind=share, het sociale netwerk: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Onderdrukking van dubbele registraties per IP: hetzelfde kind vanaf hetzelfde IP wordt één keer per 24 uur geteld.

Voorbeeld

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"}}'

---

Statistieken van een uitreiking opvragen

Haal de cumulatieve betrokkenheidstellers op voor een uitreiking.

GET /awards/{awardGuid}/stats

Geen authenticatie vereist.

Respons

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