Skip to main content

Badge Response Data Structures

This document describes the data structures returned by Pinpoint's badge-related API endpoints and how the backend parses badge information from Canvas Badges (Badgr).

Official Documentation​

For more information about Canvas Badges and the Badgr API:

Badge Assertions Response​

When fetching a user's badges from their Canvas Badges backpack, the API returns badge assertions. The backend can handle two different formats for the badgeclass field:

Response Structure​

The Badgr API returns badge assertions in the following structure:

{
  "status": {
    "success": true,
    "description": "Success"
  },
  "result": [
    {
      "badgeclass": "...",  // Can be string or object
      "issuedOn": "2024-01-15T10:30:00Z",
      "badgeclassName": "Example Badge Name"  // May be present if badgeclass is string
    }
  ]
}

Badgeclass Field Formats​

The badgeclass field can appear in two formats:

Format 1: String (Entity ID)​

When badgeclass is a string, it directly contains the badge class entity ID:

{
  "badgeclass": "mRvOju8gQhKhfEwUUfGTwg",
  "badgeclassName": "3D Printer Training",
  "issuedOn": "2024-01-15T10:30:00Z"
}

Format 2: Dictionary/Object​

When badgeclass is a dictionary, it contains additional badge information:

{
  "badgeclass": {
    "entityId": "mRvOju8gQhKhfEwUUfGTwg",
    "name": "3D Printer Training",
    "description": "Complete training for basic 3D printer operation"
  },
  "issuedOn": "2024-01-15T10:30:00Z"
}

The backend will extract the entity ID from the dictionary by checking these fields in order:

  1. entityId
  2. entity_id
  3. id

If the badgeclass is a dictionary, the badge name can be retrieved from the name field within the dictionary. Otherwise, the backend falls back to the badgeclassName field at the assertion level.

Backend Parsing Logic​

The backend handles both formats automatically. Here's how entity IDs are extracted:

badgeclass = assertion.get('badgeclass')
entity_id = None

# Extract entity ID from various formats
if isinstance(badgeclass, str):
    entity_id = badgeclass
elif isinstance(badgeclass, dict):
    entity_id = badgeclass.get('entityId') or badgeclass.get('entity_id') or badgeclass.get('id')

API Response DTOs​

Badge to Machine Type Relationship​

Endpoint: GET /badges/

Response Structure:

{
  "data": {
    "items": [
      {
        "badgeclass_entity_id": "mRvOju8gQhKhfEwUUfGTwg",
        "id": 1,
        "name": "Machine type 1",
        "isTrainer": false
      }
    ],
    "page": 1,
    "pages": 1,
    "per_page": 20,
    "total": 1
  }
}

Fields:

  • badgeclass_entity_id (string): The badge class entity ID from Canvas Badges
  • id (integer): The machine type ID
  • name (string): The machine type name
  • isTrainer (boolean): Whether this badge grants trainer status

Badge Class Information​

Endpoint: GET /badgr_requests/badge_class_info/<badgeclass_entity_id>

Response Structure:

{
  "data": {
    "name": "3D Printer Training",
    "description": "Complete training for basic 3D printer operation",
    "createdAt": "2024-01-01T00:00:00Z",
    "createdBy": "issuer@example.com"
  }
}

Fields:

  • name (string): The name of the badge
  • description (string): Description of what the badge represents
  • createdAt (string): ISO 8601 timestamp of when the badge was created
  • createdBy (string): Email or identifier of the badge creator

User Machine Types (from Badges)​

Endpoint: GET /users/<uid>/machine_types

Response Structure:

[
  {
    "machineType_ID": 1,
    "machineType": "Basic 3D Printer",
    "isDeleted": false
  }
]

This endpoint returns machine types the user has access to based on their earned badges. The backend:

  1. Fetches all badge assertions from the user's Canvas Badges backpack
  2. Extracts entity IDs from each assertion (handling both string and dictionary formats)
  3. Looks up machine types associated with those badge entity IDs
  4. Returns the unique machine types

Unknown Badges (Admin Endpoint)​

Endpoint: GET /admin/users/<target_uid>/unknown-badges

Response Structure:

{
  "data": {
    "items": [
      {
        "entity_id": "vVJlMJCcQs6oJF58K6BuDw",
        "name": "Advanced Training",
        "issued_on": "2024-01-15T10:30:00Z"
      }
    ]
  }
}

Fields:

  • entity_id (string): The badge class entity ID
  • name (string): The badge name (extracted from dictionary if available, otherwise from badgeclassName)
  • issued_on (string): ISO 8601 timestamp of when the badge was issued

This endpoint returns badges the user has earned that are not mapped to any machine types in Pinpoint.

Notes​

  • The backend automatically handles both string and dictionary formats for the badgeclass field
  • When badgeclass is a dictionary, additional metadata (like name) is available directly in the assertion
  • When badgeclass is a string, the badge name may be available in the badgeclassName field at the assertion level
  • Entity IDs are case-sensitive and should be stored exactly as returned by the Canvas Badges API