Utmärkelse-API

Skapa och hantera märkesutmärkelser (assertions) — märken som utfärdats till specifika mottagare.

Alla ändpunkter kräver autentisering via X-Api-Key-headern. Se Autentisering.

Skapa utmärkelse

Utfärda ett märke till en mottagare.

POST /awards

Parametrar

Parameter	Typ	Obligatorisk	Beskrivning
badgeId	string	Ja	Märkes-ID som ska utfärdas
recipient	object	Ja	Mottagardetaljer (se nedan)
recipient.name	string	Ja	Mottagarens fullständiga namn (minst 5 tecken)
recipient.email	string	Ja	Mottagarens e-postadress
issuedOn	string	Ja	Utfärdandedatum i ISO 8601-format (t.ex. 2025-01-15)
expires	string	Nej	Utgångsdatum i ISO 8601-format
blockchain	string	Nej	Blockchain för on-chain-verifiering. Endast matchain stöds. Tillgänglig i Pro-planen.

Exempel

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

Svar

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

Anmärkningar

• Räknas som en utmärkelse mot din månadskvot (Free: 100/mån, Starter: 1 000/mån, Pro: 10 000/mån). Kvoten återställs varje faktureringsperiod.
• Parametern blockchain är endast tillgänglig i Pro-planen.

---

Lista utmärkelser

Hämta utmärkelser med valfri filtrering och paginering.

GET /awards

Query-parametrar

Parameter	Typ	Obligatorisk	Beskrivning
filter	JSON-sträng	Nej	Filterobjekt (se nedan)
lastEvaluatedKey	string	Nej	Pagineringstoken från ett tidigare svar

Filterobjekt

Parametern filter accepterar en JSON-sträng med dessa fält:

Fält	Typ	Beskrivning
badgeId	string	Filtrera efter märkes-ID.
search	string	Delsträng att söka efter i antingen mottagarnamn eller e-postadresser (se searchField).
searchField	string	Antingen name (standard) eller email — vilken kolumn som ska sökas.

Paginering via lastEvaluatedKey fungerar med eller utan filter. Sidstorleken är 50.

Exempel — Lista alla utmärkelser

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

Exempel — Filtrera efter märke

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"

Svar

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

Om lastEvaluatedKey finns i svaret finns det fler resultat. Skicka den som en query-parameter i nästa begäran för att få nästa sida.

---

Skicka utmärkelse-e-post

Skicka ett e-postmeddelande till en mottagare om deras utmärkelse.

POST /awards/{awardId}/send

Parametrar

Parameter	Typ	Obligatorisk	Beskrivning
awardId	string	Ja	Utmärkelse-ID (sökvägsparameter och body)
email	string	Ja	Mottagarens e-postadress

Exempel

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

Svar

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

---

Dela utmärkelse

Dela en utmärkelse med flera mottagare via e-post.

POST /awards/{awardId}/share

Parametrar

Parameter	Typ	Obligatorisk	Beskrivning
awardId	string	Ja	Utmärkelse-ID (sökvägsparameter och body)
recipients	string	Ja	Kommaseparerad lista med e-postadresser
subject	string	Ja	E-postens ämnesrad
message	string	Ja	E-postens meddelandetext

Exempel

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

Svar

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

---

Ladda ner PDF-certifikat

Generera ett utskriftsklart A4-PDF-certifikat för en utmärkelse.

GET /awards/{awardGuid}/pdf

Ingen autentisering krävs — denna ändpunkt är offentlig så att mottagare kan ladda ner sitt eget certifikat.

Exempel

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

Svaret är den binära PDF-filen med en Content-Type: application/pdf-header.

---

Spåra utmärkelsehändelse

Registrera en engagemangshändelse (visning, delning, nedladdning, LinkedIn-tillägg). Används av den offentliga utmärkelsesidan för att fylla engagemangsstatistik. Ingen autentisering krävs.

POST /awards/{awardGuid}/event

Parametrar

Parameter	Typ	Obligatorisk	Beskrivning
kind	string	Ja	En av view, share, download, linkedin_add.
network	string	Nej	När kind=share, det sociala nätverket: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Dubblettundertryckning per IP: samma kind från samma IP räknas en gång per 24 timmar.

Exempel

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

---

Hämta utmärkelsestatistik

Hämta kumulativa engagemangsräknare för en utmärkelse.

GET /awards/{awardGuid}/stats

Ingen autentisering krävs.

Svar

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