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

{
  "statusCode": 200,
  "info": {
    "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 resets each billing period.
• The blockchain parameter is only available on the Pro plan.

---

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

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

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

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

---

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

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

---

Download PDF Certificate

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

GET /awards/{awardGuid}/pdf

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

Example

curl -OJ https://api.badges.ninja/awards/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 (view, share, download, LinkedIn add). Used by the public award page to populate engagement stats. No authentication required.

POST /awards/{awardGuid}/event

Parameters

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

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

Example

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

---

Get Award Stats

Retrieve cumulative engagement counters for an award.

GET /awards/{awardGuid}/stats

No authentication required.

Response

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