Awards API

Create and manage badge awards (assertions) — badges issued to specific recipients.

All endpoints require authentication via the X-Api-Key header. See Authentication.

Create Award

Issue a badge to a recipient.

POST /awards

Parameters

Parameter	Type	Required	Description
badgeId	string	Yes	The badge ID to award
recipient	object	Yes	Recipient details (see below)
recipient.name	string	Yes	Recipient full name (minimum 5 characters)
recipient.email	string	Yes	Recipient email address
issuedOn	string	Yes	Issue date in ISO 8601 format (e.g. 2025-01-15)
expires	string	No	Expiration date in ISO 8601 format
blockchain	string	No	Blockchain for on-chain verification. Only matchain is supported. Available on the Pro plan.

Example

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

Response

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

Notes

• Counts as one award against your monthly quota (Free: 100/mo, Starter: 1,000/mo, Pro: 10,000/mo). The quota is measured against awards created since 00:00 UTC on the 1st of the current calendar month — it resets on the UTC calendar-month boundary, not on your billing anniversary.
• The blockchain parameter is only available on the Pro plan, and only accepts matchain.
• Blockchain anchoring is not yet live. Passing blockchain: "matchain" is accepted and recorded as a request, but no on-chain proof is written yet — awards carry no verifiable on-chain record at this time.

---

List Awards

Retrieve awards with optional filtering and pagination.

GET /awards

Query Parameters

Parameter	Type	Required	Description
filter	JSON string	No	Filter object (see below)
lastEvaluatedKey	string	No	Pagination token from a previous response

Filter Object

The filter parameter accepts a JSON string with these fields:

Field	Type	Description
badgeId	string	Filter by badge ID.
search	string	Substring to look up in either recipient names or emails (see searchField).
searchField	string	Either name (default) or email — which column to search.

Pagination via lastEvaluatedKey works with or without filters. Page size is 50.

Example — List All Awards

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

Example — Filter by 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"

Response

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

If lastEvaluatedKey is present in the response, there are more results. Pass it as a query parameter in the next request to get the next page.

---

Send Award Email

Send an email notification to a recipient about their award.

POST /awards/{awardId}/send

Parameters

Parameter	Type	Required	Description
awardId	string	Yes	The award ID (path parameter and body)
email	string	Yes	Recipient email address

Example

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

Response

Returns a plain confirmation string:

"email sent"

---

Share Award

Share an award with multiple recipients via email.

POST /awards/{awardId}/share

Parameters

Parameter	Type	Required	Description
awardId	string	Yes	The award ID (path parameter and body)
recipients	string	Yes	Comma-separated list of email addresses
subject	string	Yes	Email subject line
message	string	Yes	Email message body

Example

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

Response

Returns a plain confirmation string:

"email sent"

---

Revoke Award

Revoke an award you issued. The hosted Open Badges v2.0 assertion is marked revoked: true (with an optional reason) so any verifier sees the badge is no longer valid. The award record is kept for audit purposes, and no credit is refunded.

POST /awards/{awardId}/revoke

Parameters

Parameter	Type	Required	Description
awardId	string	Yes	The award ID (path parameter)
reason	string	No	Reason for revocation. Truncated to 500 characters.
notify	boolean	No	When true, emails the recipient that their award was revoked. Defaults to false.

Example

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

Response

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

Revoking an already-revoked award is idempotent — it returns the same response without re-sending a notification.

---

Delete Award

Hard-delete an award you issued. Unlike revoke, this removes the record entirely and the public award page will return 404. Use this for genuine mistakes (e.g. awarded to the wrong person); prefer revoke for real credentials so the assertion stays verifiable as revoked. No credit is refunded.

DELETE /awards/{awardId}

Parameters

Parameter	Type	Required	Description
awardId	string	Yes	The award ID (path parameter)

Example

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

Response

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

---

Download PDF Certificate

Generate a print-ready A4 PDF certificate for an award.

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

No authentication required — this endpoint is public so recipients can download their own certificate.

Example

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

The response is the binary PDF with a Content-Type: application/pdf header.

---

Track Award Event

Record an engagement event. Used by the public award page to populate engagement stats. No authentication required.

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

Parameters

This endpoint reads its body directly (no parameters wrapper).

Parameter	Type	Required	Description
event	string	Yes	One of view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	No	When event=share, the social network: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Per-IP duplicate suppression: the same event from the same IP is counted once per 24 hours.

Example

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

Response

{
  "ok": true
}

---

Get Award Stats

Retrieve cumulative engagement counters for an award.

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

No authentication required.

Response

Counters are returned keyed by the raw event type. totals holds the total count per event; networks breaks down the per-network split for events that carry a network (currently share). Events with no recorded activity are simply absent.

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