API voor referenties

Maak en beheer referenties (assertions) — badges die aan specifieke ontvangers worden uitgegeven.

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

Referentie aanmaken

Geef een badge uit aan een ontvanger.

Wil je aan honderden of duizenden ontvangers tegelijk uitgeven in plaats van één API-aanroep per persoon? Gebruik de UI-functie Bulkreferenties, die een CSV-upload accepteert.

POST /awards

Parameters

Parameter	Type	Vereist	Beschrijving
badgeId	string	Ja	De ID van de badge die wordt uitgegeven
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	Vervaldatum in ISO 8601-formaat

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

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

Opmerkingen

• Telt als één referentie van je jaarlijkse referentiepool (Free: 1.200/jaar, Starter: 12.000/jaar, Pro: 120.000/jaar). De pool is een flexibel jaartegoed — besteed het wanneer je wilt in de loop van het jaar, ook in pieken — en wordt gereset op de verjaardag van de registratie van je account. De facturering blijft maandelijks; alleen het referentiequotum is jaarlijks. Zie Abonnementen & facturering voor details.

---

Referenties weergeven

Haal referenties op met optionele filtering en paginering.

GET /awards

Queryparameters

Parameter	Type	Vereist	Beschrijving
filter	JSON string	Nee	Filterobject (zie hieronder)
lastEvaluatedKey	string	Nee	Pagineringstoken uit een eerdere respons

Filterobject

De parameter filter accepteert een JSON-string met de volgende velden:

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

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

Voorbeeld — alle referenties weergeven

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

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

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

---

Referentie-e-mail versturen

Stuur een e-mailmelding naar een ontvanger over zijn of haar referentie.

POST /awards/{awardId}/send

Parameters

Parameter	Type	Vereist	Beschrijving
awardId	string	Ja	De award-ID (padparameter en body)
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

Geeft een gewone bevestigingsstring terug:

"email sent"

---

Referentie delen

Deel een referentie per e-mail met meerdere ontvangers.

POST /awards/{awardId}/share

Parameters

Parameter	Type	Vereist	Beschrijving
awardId	string	Ja	De award-ID (padparameter en body)
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

Geeft een gewone bevestigingsstring terug:

"email sent"

---

Referentie intrekken

Trek een referentie in die je hebt uitgegeven. De gehoste Open Badges v2.0-assertion wordt gemarkeerd met revoked: true (met een optionele reden), zodat elke verificateur ziet dat de badge niet langer geldig is. Het referentierecord blijft bewaard voor auditdoeleinden en er worden geen credits terugbetaald.

Intrekking werkt ook door in de Open Badges 3.0 Verifiable Credential van de referentie: de bit van de award wordt omgezet in de W3C Bitstring Status List waarnaar de credentialStatus van de VC verwijst, zodat ook VC-wallets het detecteren. Zie Intrekking (Bitstring Status List).

POST /awards/{awardId}/revoke

Parameters

Parameter	Type	Vereist	Beschrijving
awardId	string	Ja	De award-ID (padparameter)
reason	string	Nee	Reden voor de intrekking. Wordt afgekapt op 500 tekens.
notify	boolean	Nee	Bij true ontvangt de ontvanger een e-mail dat zijn of haar referentie is ingetrokken. Standaard false.

Voorbeeld

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

Respons

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

Het intrekken van een al ingetrokken referentie is idempotent — je krijgt dezelfde respons terug zonder dat de melding opnieuw wordt verstuurd.

In bulk intrekken

Om veel referenties tegelijk in te trekken, gebruik je het duurzame bulk-endpoint met action: "revoke" in plaats van dit endpoint per award aan te roepen:

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

Het geeft { "jobId", "total" } terug; de taak trekt elke id server-side in (al ingetrokken id's worden overgeslagen) en kan worden hervat. Al ingetrokken en niet-bestaande id's worden gerapporteerd als overgeslagen.

---

Referentie verwijderen

Verwijder een referentie die je hebt uitgegeven definitief. In tegenstelling tot intrekken verwijdert dit het record volledig en geeft de publieke referentiepagina 404 terug. Gebruik dit voor echte vergissingen (bijv. uitgegeven aan de verkeerde persoon); geef bij echte referenties de voorkeur aan intrekken, zodat de assertion verifieerbaar blijft als ingetrokken. Er worden geen credits terugbetaald.

DELETE /awards/{awardId}

Parameters

Parameter	Type	Vereist	Beschrijving
awardId	string	Ja	De award-ID (padparameter)

Voorbeeld

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

Respons

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

---

PDF-certificaat downloaden

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

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

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

Voorbeeld

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

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

---

Referentie-event bijhouden

Registreer een betrokkenheidsevent. Wordt gebruikt door de publieke referentiepagina om betrokkenheidsstatistieken te vullen. Geen authenticatie vereist.

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

Parameters

Dit endpoint leest zijn body rechtstreeks (geen parameters-wrapper).

Parameter	Type	Vereist	Beschrijving
event	string	Ja	Een van view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Nee	Bij event=share het sociale netwerk: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Onderdrukking van duplicaten per IP: hetzelfde event van hetzelfde IP wordt eenmaal per 24 uur geteld.

Voorbeeld

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

Respons

{
  "ok": true
}

---

Referentiestatistieken ophalen

Haal de cumulatieve betrokkenheidstellers van een referentie op.

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

Geen authenticatie vereist.

Respons

Tellers worden teruggegeven met het ruwe eventtype als sleutel. totals bevat het totaalaantal per event; networks toont de verdeling per netwerk voor events met een network (momenteel share). Events zonder geregistreerde activiteit ontbreken eenvoudigweg.

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