Community

APIs

Update a staff member's role on the Issuer

put

User must have an owner role on the issuer.

Authorizations
Path parameters
idOrEntityIdstringRequired
Body
emailstringRequired

Email address associated with the staff member

Example: [email protected]
rolestring · enumRequired

Role of the user in the issuer.

Possible values:
Responses
200
OK
*/*
put
PUT /v2/issuers/{idOrEntityId}/staff HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "email": "[email protected]",
  "role": "owner"
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "role": "staff",
      "user": "Hey7J-GRSJeu6FNnHQwNyw",
      "userProfile": {
        "entityType": "BadgeUser",
        "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
        "firstName": "Jane",
        "lastName": "Doe",
        "emails": [
          {
            "email": "[email protected]",
            "verified": true,
            "primary": true
          }
        ],
        "url": [
          "https://example.com"
        ],
        "telephone": [
          "text"
        ],
        "badgrDomain": "badgrsupportgroup.badgr.com",
        "agreedTermsVersion": 4,
        "marketingOptIn": true,
        "hasPasswordSet": true
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Add a staff member to an Issuer

post

User must have an owner role on the issuer.

Authorizations
Path parameters
idOrEntityIdstringRequired
Body
emailstringRequired

Email address associated with the staff member

Example: [email protected]
rolestring · enumRequired

Role of the user in the issuer.

Possible values:
Responses
201
Staff member added
*/*
post
POST /v2/issuers/{idOrEntityId}/staff HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "email": "[email protected]",
  "role": "owner"
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "role": "staff",
      "user": "Hey7J-GRSJeu6FNnHQwNyw",
      "userProfile": {
        "entityType": "BadgeUser",
        "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
        "firstName": "Jane",
        "lastName": "Doe",
        "emails": [
          {
            "email": "[email protected]",
            "verified": true,
            "primary": true
          }
        ],
        "url": [
          "https://example.com"
        ],
        "telephone": [
          "text"
        ],
        "badgrDomain": "badgrsupportgroup.badgr.com",
        "agreedTermsVersion": 4,
        "marketingOptIn": true,
        "hasPasswordSet": true
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a staff member's role on the Issuer

patch

User must have an owner role on the issuer.

Authorizations
Path parameters
idOrEntityIdstringRequired
Body
emailstringRequired

Email address associated with the staff member

Example: [email protected]
rolestring · enumRequired

Role of the user in the issuer.

Possible values:
Responses
200
OK
*/*
patch
PATCH /v2/issuers/{idOrEntityId}/staff HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "email": "[email protected]",
  "role": "owner"
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "role": "staff",
      "user": "Hey7J-GRSJeu6FNnHQwNyw",
      "userProfile": {
        "entityType": "BadgeUser",
        "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
        "firstName": "Jane",
        "lastName": "Doe",
        "emails": [
          {
            "email": "[email protected]",
            "verified": true,
            "primary": true
          }
        ],
        "url": [
          "https://example.com"
        ],
        "telephone": [
          "text"
        ],
        "badgrDomain": "badgrsupportgroup.badgr.com",
        "agreedTermsVersion": 4,
        "marketingOptIn": true,
        "hasPasswordSet": true
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a single BadgeUser profile

get
Authorizations
Path parameters
idOrEntityIdstringRequired
Responses
200
OK
application/json
get
GET /v2/users/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "5f16c84d1ff787222b6c4d15",
      "entityType": "BadgeUser",
      "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
      "firstName": "Jane",
      "lastName": "Doe",
      "emails": [
        {
          "email": "[email protected]",
          "verified": true,
          "primary": true,
          "caseVariants": [
            "text"
          ]
        }
      ],
      "url": [
        "https://example.com"
      ],
      "telephone": [
        "text"
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "agreedTermsVersion": 4,
      "hasAgreedToLatestTermsVersion": true,
      "marketingOptIn": true,
      "hasPasswordSet": true,
      "recipient": {
        "identity": "[email protected]",
        "type": "email"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a BadgeUser

put
Authorizations
Path parameters
idOrEntityIdstringRequired
Body
firstNamestringOptionalExample: Jane
lastNamestringOptionalExample: Doe
marketingOptInbooleanOptionalExample: true
Responses
200
OK
application/json
put
PUT /v2/users/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "firstName": "Jane",
  "lastName": "Doe",
  "marketingOptIn": true
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "5f16c84d1ff787222b6c4d15",
      "entityType": "BadgeUser",
      "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
      "firstName": "Jane",
      "lastName": "Doe",
      "emails": [
        {
          "email": "[email protected]",
          "verified": true,
          "primary": true,
          "caseVariants": [
            "text"
          ]
        }
      ],
      "url": [
        "https://example.com"
      ],
      "telephone": [
        "text"
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "agreedTermsVersion": 4,
      "hasAgreedToLatestTermsVersion": true,
      "marketingOptIn": true,
      "hasPasswordSet": true,
      "recipient": {
        "identity": "[email protected]",
        "type": "email"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a BadgeUser

patch
Authorizations
Path parameters
idOrEntityIdstringRequired
Body
firstNamestringOptionalExample: Jane
lastNamestringOptionalExample: Doe
marketingOptInbooleanOptionalExample: true
Responses
200
OK
application/json
patch
PATCH /v2/users/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "firstName": "Jane",
  "lastName": "Doe",
  "marketingOptIn": true
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "5f16c84d1ff787222b6c4d15",
      "entityType": "BadgeUser",
      "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
      "firstName": "Jane",
      "lastName": "Doe",
      "emails": [
        {
          "email": "[email protected]",
          "verified": true,
          "primary": true,
          "caseVariants": [
            "text"
          ]
        }
      ],
      "url": [
        "https://example.com"
      ],
      "telephone": [
        "text"
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "agreedTermsVersion": 4,
      "hasAgreedToLatestTermsVersion": true,
      "marketingOptIn": true,
      "hasPasswordSet": true,
      "recipient": {
        "identity": "[email protected]",
        "type": "email"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get your own BadgeUser profile

get
Authorizations
Responses
200
OK
application/json
get
GET /v2/users/self HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "5f16c84d1ff787222b6c4d15",
      "entityType": "BadgeUser",
      "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
      "firstName": "Jane",
      "lastName": "Doe",
      "emails": [
        {
          "email": "[email protected]",
          "verified": true,
          "primary": true,
          "caseVariants": [
            "text"
          ]
        }
      ],
      "url": [
        "https://example.com"
      ],
      "telephone": [
        "text"
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "agreedTermsVersion": 4,
      "hasAgreedToLatestTermsVersion": true,
      "marketingOptIn": true,
      "hasPasswordSet": true,
      "recipient": {
        "identity": "[email protected]",
        "type": "email"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update your own BadgeUser

put
Authorizations
Body
firstNamestringOptionalExample: Jane
lastNamestringOptionalExample: Doe
marketingOptInbooleanOptionalExample: true
Responses
200
OK
application/json
put
PUT /v2/users/self HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "firstName": "Jane",
  "lastName": "Doe",
  "marketingOptIn": true
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "5f16c84d1ff787222b6c4d15",
      "entityType": "BadgeUser",
      "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
      "firstName": "Jane",
      "lastName": "Doe",
      "emails": [
        {
          "email": "[email protected]",
          "verified": true,
          "primary": true,
          "caseVariants": [
            "text"
          ]
        }
      ],
      "url": [
        "https://example.com"
      ],
      "telephone": [
        "text"
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "agreedTermsVersion": 4,
      "hasAgreedToLatestTermsVersion": true,
      "marketingOptIn": true,
      "hasPasswordSet": true,
      "recipient": {
        "identity": "[email protected]",
        "type": "email"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update your own BadgeUser

patch
Authorizations
Body
firstNamestringOptionalExample: Jane
lastNamestringOptionalExample: Doe
marketingOptInbooleanOptionalExample: true
Responses
200
OK
application/json
patch
PATCH /v2/users/self HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "firstName": "Jane",
  "lastName": "Doe",
  "marketingOptIn": true
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "5f16c84d1ff787222b6c4d15",
      "entityType": "BadgeUser",
      "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
      "firstName": "Jane",
      "lastName": "Doe",
      "emails": [
        {
          "email": "[email protected]",
          "verified": true,
          "primary": true,
          "caseVariants": [
            "text"
          ]
        }
      ],
      "url": [
        "https://example.com"
      ],
      "telephone": [
        "text"
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "agreedTermsVersion": 4,
      "hasAgreedToLatestTermsVersion": true,
      "marketingOptIn": true,
      "hasPasswordSet": true,
      "recipient": {
        "identity": "[email protected]",
        "type": "email"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a single Issuer

get
Authorizations
Path parameters
idOrEntityIdstringRequired
Query parameters
include_staffstringOptionalDefault: true
Responses
200
OK
get
GET /v2/issuers/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "6016c84d1ff787222b6c4d15",
      "entityType": "Issuer",
      "entityId": "Uu4wd2I1SKmD3vmtMJ19hw",
      "openBadgeId": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "name": "Credentials Faculty",
      "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
      "email": "[email protected]",
      "description": "This is the faculty of the Credentials University.",
      "url": "https://example.com",
      "staff": [
        {
          "role": "staff",
          "user": "Hey7J-GRSJeu6FNnHQwNyw",
          "userProfile": {
            "entityType": "BadgeUser",
            "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
            "firstName": "Jane",
            "lastName": "Doe",
            "emails": [
              {
                "email": "[email protected]",
                "verified": true,
                "primary": true
              }
            ],
            "url": [
              "https://example.com"
            ],
            "telephone": [
              "text"
            ],
            "badgrDomain": "badgrsupportgroup.badgr.com",
            "agreedTermsVersion": 4,
            "marketingOptIn": true,
            "hasPasswordSet": true
          }
        }
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "createdBy": "text",
      "organizationId": "6f4e4e4e2dc038241ad01d83",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "sourceUrl": "https://example.com/issuers/1",
      "imagePath": "uploads/issuers/issuer-JTdhRmlFQZScIjoUr6x4UQ.png",
      "originalJson": "{}",
      "badgeSkillLinkingPreferences": {
        "type": "TALENT_NEURON",
        "serverUri": "https://example.com/",
        "linkMode": "DEFAULT",
        "indeedRegion": "us"
      },
      "preferences": {
        "customPropertyDefinitions": [
          {
            "propertyType": "STRING_CHOICE",
            "targetEntityType": "BADGE_CLASS",
            "propertyId": "66bf8231d88b51901d49d637",
            "label": "Award Type",
            "subLabel": "Type of award",
            "public": true,
            "required": true,
            "choiceValues": [
              {
                "id": "65663ceb977692fcafcea0b9",
                "label": "text"
              }
            ]
          }
        ],
        "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
        "enabledPrintCertTemplateIds": [
          "5f4e4e4e2dc038241ad01d83",
          "6f4e4e4e2dc038241ad01d83"
        ]
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a single Issuer

put
Authorizations
Path parameters
idOrEntityIdstringRequired
Query parameters
include_staffstringOptionalDefault: true
Body
namestring · max: 1024Required

Name of the issuer

Example: Credentials Faculty
emailstring · email · max: 255Required

Contact email for the Issuer

Example: [email protected]
urlstring · uri · max: 1024Required

Homepage or website associated with the Issuer

Example: https://example.com
imagestringOptional

Image of the issuer. An URL or a bas64 encoded images.

Example: https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image
descriptionstring · max: 16384Required

Short description of the Issuer

Example: This is the faculty of the Credentials University.
badgrDomainstringOptional
Responses
200
OK
put
PUT /v2/issuers/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 354

{
  "name": "Credentials Faculty",
  "email": "[email protected]",
  "url": "https://example.com",
  "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
  "description": "This is the faculty of the Credentials University.",
  "badgrDomain": "text",
  "staff": [
    {
      "role": "owner",
      "user": "Hey7J-GRSJeu6FNnHQwNyw"
    }
  ],
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  }
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "6016c84d1ff787222b6c4d15",
      "entityType": "Issuer",
      "entityId": "Uu4wd2I1SKmD3vmtMJ19hw",
      "openBadgeId": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "name": "Credentials Faculty",
      "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
      "email": "[email protected]",
      "description": "This is the faculty of the Credentials University.",
      "url": "https://example.com",
      "staff": [
        {
          "role": "staff",
          "user": "Hey7J-GRSJeu6FNnHQwNyw",
          "userProfile": {
            "entityType": "BadgeUser",
            "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
            "firstName": "Jane",
            "lastName": "Doe",
            "emails": [
              {
                "email": "[email protected]",
                "verified": true,
                "primary": true
              }
            ],
            "url": [
              "https://example.com"
            ],
            "telephone": [
              "text"
            ],
            "badgrDomain": "badgrsupportgroup.badgr.com",
            "agreedTermsVersion": 4,
            "marketingOptIn": true,
            "hasPasswordSet": true
          }
        }
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "createdBy": "text",
      "organizationId": "6f4e4e4e2dc038241ad01d83",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "sourceUrl": "https://example.com/issuers/1",
      "imagePath": "uploads/issuers/issuer-JTdhRmlFQZScIjoUr6x4UQ.png",
      "originalJson": "{}",
      "badgeSkillLinkingPreferences": {
        "type": "TALENT_NEURON",
        "serverUri": "https://example.com/",
        "linkMode": "DEFAULT",
        "indeedRegion": "us"
      },
      "preferences": {
        "customPropertyDefinitions": [
          {
            "propertyType": "STRING_CHOICE",
            "targetEntityType": "BADGE_CLASS",
            "propertyId": "66bf8231d88b51901d49d637",
            "label": "Award Type",
            "subLabel": "Type of award",
            "public": true,
            "required": true,
            "choiceValues": [
              {
                "id": "65663ceb977692fcafcea0b9",
                "label": "text"
              }
            ]
          }
        ],
        "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
        "enabledPrintCertTemplateIds": [
          "5f4e4e4e2dc038241ad01d83",
          "6f4e4e4e2dc038241ad01d83"
        ]
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Delete a single Issuer

delete
Authorizations
Path parameters
idOrEntityIdstringRequired
Responses
204
Issuer deleted
delete
DELETE /v2/issuers/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Update a single Issuer

patch
Authorizations
Path parameters
idOrEntityIdstringRequired
Query parameters
include_staffstringOptionalDefault: true
Body
namestring · max: 1024Required

Name of the issuer

Example: Credentials Faculty
emailstring · email · max: 255Required

Contact email for the Issuer

Example: [email protected]
urlstring · uri · max: 1024Required

Homepage or website associated with the Issuer

Example: https://example.com
imagestringOptional

Image of the issuer. An URL or a bas64 encoded images.

Example: https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image
descriptionstring · max: 16384Required

Short description of the Issuer

Example: This is the faculty of the Credentials University.
badgrDomainstringOptional
Responses
200
OK
patch
PATCH /v2/issuers/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 354

{
  "name": "Credentials Faculty",
  "email": "[email protected]",
  "url": "https://example.com",
  "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
  "description": "This is the faculty of the Credentials University.",
  "badgrDomain": "text",
  "staff": [
    {
      "role": "owner",
      "user": "Hey7J-GRSJeu6FNnHQwNyw"
    }
  ],
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  }
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "6016c84d1ff787222b6c4d15",
      "entityType": "Issuer",
      "entityId": "Uu4wd2I1SKmD3vmtMJ19hw",
      "openBadgeId": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "name": "Credentials Faculty",
      "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
      "email": "[email protected]",
      "description": "This is the faculty of the Credentials University.",
      "url": "https://example.com",
      "staff": [
        {
          "role": "staff",
          "user": "Hey7J-GRSJeu6FNnHQwNyw",
          "userProfile": {
            "entityType": "BadgeUser",
            "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
            "firstName": "Jane",
            "lastName": "Doe",
            "emails": [
              {
                "email": "[email protected]",
                "verified": true,
                "primary": true
              }
            ],
            "url": [
              "https://example.com"
            ],
            "telephone": [
              "text"
            ],
            "badgrDomain": "badgrsupportgroup.badgr.com",
            "agreedTermsVersion": 4,
            "marketingOptIn": true,
            "hasPasswordSet": true
          }
        }
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "createdBy": "text",
      "organizationId": "6f4e4e4e2dc038241ad01d83",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "sourceUrl": "https://example.com/issuers/1",
      "imagePath": "uploads/issuers/issuer-JTdhRmlFQZScIjoUr6x4UQ.png",
      "originalJson": "{}",
      "badgeSkillLinkingPreferences": {
        "type": "TALENT_NEURON",
        "serverUri": "https://example.com/",
        "linkMode": "DEFAULT",
        "indeedRegion": "us"
      },
      "preferences": {
        "customPropertyDefinitions": [
          {
            "propertyType": "STRING_CHOICE",
            "targetEntityType": "BADGE_CLASS",
            "propertyId": "66bf8231d88b51901d49d637",
            "label": "Award Type",
            "subLabel": "Type of award",
            "public": true,
            "required": true,
            "choiceValues": [
              {
                "id": "65663ceb977692fcafcea0b9",
                "label": "text"
              }
            ]
          }
        ],
        "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
        "enabledPrintCertTemplateIds": [
          "5f4e4e4e2dc038241ad01d83",
          "6f4e4e4e2dc038241ad01d83"
        ]
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a single Issuer

get
Authorizations
Path parameters
issuerOpenBadgeIdBase64stringRequired
Query parameters
include_staffstringOptionalDefault: true
Responses
200
OK
get
GET /v2/issuers/openBadgeId/{issuerOpenBadgeIdBase64} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "6016c84d1ff787222b6c4d15",
      "entityType": "Issuer",
      "entityId": "Uu4wd2I1SKmD3vmtMJ19hw",
      "openBadgeId": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "name": "Credentials Faculty",
      "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
      "email": "[email protected]",
      "description": "This is the faculty of the Credentials University.",
      "url": "https://example.com",
      "staff": [
        {
          "role": "staff",
          "user": "Hey7J-GRSJeu6FNnHQwNyw",
          "userProfile": {
            "entityType": "BadgeUser",
            "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
            "firstName": "Jane",
            "lastName": "Doe",
            "emails": [
              {
                "email": "[email protected]",
                "verified": true,
                "primary": true
              }
            ],
            "url": [
              "https://example.com"
            ],
            "telephone": [
              "text"
            ],
            "badgrDomain": "badgrsupportgroup.badgr.com",
            "agreedTermsVersion": 4,
            "marketingOptIn": true,
            "hasPasswordSet": true
          }
        }
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "createdBy": "text",
      "organizationId": "6f4e4e4e2dc038241ad01d83",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "sourceUrl": "https://example.com/issuers/1",
      "imagePath": "uploads/issuers/issuer-JTdhRmlFQZScIjoUr6x4UQ.png",
      "originalJson": "{}",
      "badgeSkillLinkingPreferences": {
        "type": "TALENT_NEURON",
        "serverUri": "https://example.com/",
        "linkMode": "DEFAULT",
        "indeedRegion": "us"
      },
      "preferences": {
        "customPropertyDefinitions": [
          {
            "propertyType": "STRING_CHOICE",
            "targetEntityType": "BADGE_CLASS",
            "propertyId": "66bf8231d88b51901d49d637",
            "label": "Award Type",
            "subLabel": "Type of award",
            "public": true,
            "required": true,
            "choiceValues": [
              {
                "id": "65663ceb977692fcafcea0b9",
                "label": "text"
              }
            ]
          }
        ],
        "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
        "enabledPrintCertTemplateIds": [
          "5f4e4e4e2dc038241ad01d83",
          "6f4e4e4e2dc038241ad01d83"
        ]
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a single Issuer

put
Authorizations
Path parameters
issuerOpenBadgeIdBase64stringRequired
Query parameters
include_staffstringOptionalDefault: true
Body
namestring · max: 1024Required

Name of the issuer

Example: Credentials Faculty
emailstring · email · max: 255Required

Contact email for the Issuer

Example: [email protected]
urlstring · uri · max: 1024Required

Homepage or website associated with the Issuer

Example: https://example.com
imagestringOptional

Image of the issuer. An URL or a bas64 encoded images.

Example: https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image
descriptionstring · max: 16384Required

Short description of the Issuer

Example: This is the faculty of the Credentials University.
badgrDomainstringOptional
Responses
200
OK
put
PUT /v2/issuers/openBadgeId/{issuerOpenBadgeIdBase64} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 354

{
  "name": "Credentials Faculty",
  "email": "[email protected]",
  "url": "https://example.com",
  "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
  "description": "This is the faculty of the Credentials University.",
  "badgrDomain": "text",
  "staff": [
    {
      "role": "owner",
      "user": "Hey7J-GRSJeu6FNnHQwNyw"
    }
  ],
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  }
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "6016c84d1ff787222b6c4d15",
      "entityType": "Issuer",
      "entityId": "Uu4wd2I1SKmD3vmtMJ19hw",
      "openBadgeId": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "name": "Credentials Faculty",
      "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
      "email": "[email protected]",
      "description": "This is the faculty of the Credentials University.",
      "url": "https://example.com",
      "staff": [
        {
          "role": "staff",
          "user": "Hey7J-GRSJeu6FNnHQwNyw",
          "userProfile": {
            "entityType": "BadgeUser",
            "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
            "firstName": "Jane",
            "lastName": "Doe",
            "emails": [
              {
                "email": "[email protected]",
                "verified": true,
                "primary": true
              }
            ],
            "url": [
              "https://example.com"
            ],
            "telephone": [
              "text"
            ],
            "badgrDomain": "badgrsupportgroup.badgr.com",
            "agreedTermsVersion": 4,
            "marketingOptIn": true,
            "hasPasswordSet": true
          }
        }
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "createdBy": "text",
      "organizationId": "6f4e4e4e2dc038241ad01d83",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "sourceUrl": "https://example.com/issuers/1",
      "imagePath": "uploads/issuers/issuer-JTdhRmlFQZScIjoUr6x4UQ.png",
      "originalJson": "{}",
      "badgeSkillLinkingPreferences": {
        "type": "TALENT_NEURON",
        "serverUri": "https://example.com/",
        "linkMode": "DEFAULT",
        "indeedRegion": "us"
      },
      "preferences": {
        "customPropertyDefinitions": [
          {
            "propertyType": "STRING_CHOICE",
            "targetEntityType": "BADGE_CLASS",
            "propertyId": "66bf8231d88b51901d49d637",
            "label": "Award Type",
            "subLabel": "Type of award",
            "public": true,
            "required": true,
            "choiceValues": [
              {
                "id": "65663ceb977692fcafcea0b9",
                "label": "text"
              }
            ]
          }
        ],
        "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
        "enabledPrintCertTemplateIds": [
          "5f4e4e4e2dc038241ad01d83",
          "6f4e4e4e2dc038241ad01d83"
        ]
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Delete a single Issuer

delete
Authorizations
Path parameters
issuerOpenBadgeIdBase64stringRequired
Responses
204
Issuer deleted
delete
DELETE /v2/issuers/openBadgeId/{issuerOpenBadgeIdBase64} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a single Issuer

patch
Authorizations
Path parameters
issuerOpenBadgeIdBase64stringRequired
Query parameters
include_staffstringOptionalDefault: true
Body
namestring · max: 1024Required

Name of the issuer

Example: Credentials Faculty
emailstring · email · max: 255Required

Contact email for the Issuer

Example: [email protected]
urlstring · uri · max: 1024Required

Homepage or website associated with the Issuer

Example: https://example.com
imagestringOptional

Image of the issuer. An URL or a bas64 encoded images.

Example: https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image
descriptionstring · max: 16384Required

Short description of the Issuer

Example: This is the faculty of the Credentials University.
badgrDomainstringOptional
Responses
200
OK
patch
PATCH /v2/issuers/openBadgeId/{issuerOpenBadgeIdBase64} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 354

{
  "name": "Credentials Faculty",
  "email": "[email protected]",
  "url": "https://example.com",
  "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
  "description": "This is the faculty of the Credentials University.",
  "badgrDomain": "text",
  "staff": [
    {
      "role": "owner",
      "user": "Hey7J-GRSJeu6FNnHQwNyw"
    }
  ],
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  }
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "6016c84d1ff787222b6c4d15",
      "entityType": "Issuer",
      "entityId": "Uu4wd2I1SKmD3vmtMJ19hw",
      "openBadgeId": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "name": "Credentials Faculty",
      "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
      "email": "[email protected]",
      "description": "This is the faculty of the Credentials University.",
      "url": "https://example.com",
      "staff": [
        {
          "role": "staff",
          "user": "Hey7J-GRSJeu6FNnHQwNyw",
          "userProfile": {
            "entityType": "BadgeUser",
            "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
            "firstName": "Jane",
            "lastName": "Doe",
            "emails": [
              {
                "email": "[email protected]",
                "verified": true,
                "primary": true
              }
            ],
            "url": [
              "https://example.com"
            ],
            "telephone": [
              "text"
            ],
            "badgrDomain": "badgrsupportgroup.badgr.com",
            "agreedTermsVersion": 4,
            "marketingOptIn": true,
            "hasPasswordSet": true
          }
        }
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "createdBy": "text",
      "organizationId": "6f4e4e4e2dc038241ad01d83",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "sourceUrl": "https://example.com/issuers/1",
      "imagePath": "uploads/issuers/issuer-JTdhRmlFQZScIjoUr6x4UQ.png",
      "originalJson": "{}",
      "badgeSkillLinkingPreferences": {
        "type": "TALENT_NEURON",
        "serverUri": "https://example.com/",
        "linkMode": "DEFAULT",
        "indeedRegion": "us"
      },
      "preferences": {
        "customPropertyDefinitions": [
          {
            "propertyType": "STRING_CHOICE",
            "targetEntityType": "BADGE_CLASS",
            "propertyId": "66bf8231d88b51901d49d637",
            "label": "Award Type",
            "subLabel": "Type of award",
            "public": true,
            "required": true,
            "choiceValues": [
              {
                "id": "65663ceb977692fcafcea0b9",
                "label": "text"
              }
            ]
          }
        ],
        "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
        "enabledPrintCertTemplateIds": [
          "5f4e4e4e2dc038241ad01d83",
          "6f4e4e4e2dc038241ad01d83"
        ]
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a single Issuer

get
Authorizations
Path parameters
issuerOpenBadgeIdBase64stringRequired
Query parameters
include_staffstringOptionalDefault: true
Responses
200
OK
get
GET /v2/issuers/ref/{issuerOpenBadgeIdBase64} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "6016c84d1ff787222b6c4d15",
      "entityType": "Issuer",
      "entityId": "Uu4wd2I1SKmD3vmtMJ19hw",
      "openBadgeId": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "name": "Credentials Faculty",
      "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
      "email": "[email protected]",
      "description": "This is the faculty of the Credentials University.",
      "url": "https://example.com",
      "staff": [
        {
          "role": "staff",
          "user": "Hey7J-GRSJeu6FNnHQwNyw",
          "userProfile": {
            "entityType": "BadgeUser",
            "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
            "firstName": "Jane",
            "lastName": "Doe",
            "emails": [
              {
                "email": "[email protected]",
                "verified": true,
                "primary": true
              }
            ],
            "url": [
              "https://example.com"
            ],
            "telephone": [
              "text"
            ],
            "badgrDomain": "badgrsupportgroup.badgr.com",
            "agreedTermsVersion": 4,
            "marketingOptIn": true,
            "hasPasswordSet": true
          }
        }
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "createdBy": "text",
      "organizationId": "6f4e4e4e2dc038241ad01d83",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "sourceUrl": "https://example.com/issuers/1",
      "imagePath": "uploads/issuers/issuer-JTdhRmlFQZScIjoUr6x4UQ.png",
      "originalJson": "{}",
      "badgeSkillLinkingPreferences": {
        "type": "TALENT_NEURON",
        "serverUri": "https://example.com/",
        "linkMode": "DEFAULT",
        "indeedRegion": "us"
      },
      "preferences": {
        "customPropertyDefinitions": [
          {
            "propertyType": "STRING_CHOICE",
            "targetEntityType": "BADGE_CLASS",
            "propertyId": "66bf8231d88b51901d49d637",
            "label": "Award Type",
            "subLabel": "Type of award",
            "public": true,
            "required": true,
            "choiceValues": [
              {
                "id": "65663ceb977692fcafcea0b9",
                "label": "text"
              }
            ]
          }
        ],
        "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
        "enabledPrintCertTemplateIds": [
          "5f4e4e4e2dc038241ad01d83",
          "6f4e4e4e2dc038241ad01d83"
        ]
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a single Issuer

put
Authorizations
Path parameters
issuerOpenBadgeIdBase64stringRequired
Query parameters
include_staffstringOptionalDefault: true
Body
namestring · max: 1024Required

Name of the issuer

Example: Credentials Faculty
emailstring · email · max: 255Required

Contact email for the Issuer

Example: [email protected]
urlstring · uri · max: 1024Required

Homepage or website associated with the Issuer

Example: https://example.com
imagestringOptional

Image of the issuer. An URL or a bas64 encoded images.

Example: https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image
descriptionstring · max: 16384Required

Short description of the Issuer

Example: This is the faculty of the Credentials University.
badgrDomainstringOptional
Responses
200
OK
put
PUT /v2/issuers/ref/{issuerOpenBadgeIdBase64} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 354

{
  "name": "Credentials Faculty",
  "email": "[email protected]",
  "url": "https://example.com",
  "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
  "description": "This is the faculty of the Credentials University.",
  "badgrDomain": "text",
  "staff": [
    {
      "role": "owner",
      "user": "Hey7J-GRSJeu6FNnHQwNyw"
    }
  ],
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  }
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "6016c84d1ff787222b6c4d15",
      "entityType": "Issuer",
      "entityId": "Uu4wd2I1SKmD3vmtMJ19hw",
      "openBadgeId": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "name": "Credentials Faculty",
      "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
      "email": "[email protected]",
      "description": "This is the faculty of the Credentials University.",
      "url": "https://example.com",
      "staff": [
        {
          "role": "staff",
          "user": "Hey7J-GRSJeu6FNnHQwNyw",
          "userProfile": {
            "entityType": "BadgeUser",
            "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
            "firstName": "Jane",
            "lastName": "Doe",
            "emails": [
              {
                "email": "[email protected]",
                "verified": true,
                "primary": true
              }
            ],
            "url": [
              "https://example.com"
            ],
            "telephone": [
              "text"
            ],
            "badgrDomain": "badgrsupportgroup.badgr.com",
            "agreedTermsVersion": 4,
            "marketingOptIn": true,
            "hasPasswordSet": true
          }
        }
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "createdBy": "text",
      "organizationId": "6f4e4e4e2dc038241ad01d83",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "sourceUrl": "https://example.com/issuers/1",
      "imagePath": "uploads/issuers/issuer-JTdhRmlFQZScIjoUr6x4UQ.png",
      "originalJson": "{}",
      "badgeSkillLinkingPreferences": {
        "type": "TALENT_NEURON",
        "serverUri": "https://example.com/",
        "linkMode": "DEFAULT",
        "indeedRegion": "us"
      },
      "preferences": {
        "customPropertyDefinitions": [
          {
            "propertyType": "STRING_CHOICE",
            "targetEntityType": "BADGE_CLASS",
            "propertyId": "66bf8231d88b51901d49d637",
            "label": "Award Type",
            "subLabel": "Type of award",
            "public": true,
            "required": true,
            "choiceValues": [
              {
                "id": "65663ceb977692fcafcea0b9",
                "label": "text"
              }
            ]
          }
        ],
        "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
        "enabledPrintCertTemplateIds": [
          "5f4e4e4e2dc038241ad01d83",
          "6f4e4e4e2dc038241ad01d83"
        ]
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Delete a single Issuer

delete
Authorizations
Path parameters
issuerOpenBadgeIdBase64stringRequired
Responses
204
Issuer deleted
delete
DELETE /v2/issuers/ref/{issuerOpenBadgeIdBase64} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a single Issuer

patch
Authorizations
Path parameters
issuerOpenBadgeIdBase64stringRequired
Query parameters
include_staffstringOptionalDefault: true
Body
namestring · max: 1024Required

Name of the issuer

Example: Credentials Faculty
emailstring · email · max: 255Required

Contact email for the Issuer

Example: [email protected]
urlstring · uri · max: 1024Required

Homepage or website associated with the Issuer

Example: https://example.com
imagestringOptional

Image of the issuer. An URL or a bas64 encoded images.

Example: https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image
descriptionstring · max: 16384Required

Short description of the Issuer

Example: This is the faculty of the Credentials University.
badgrDomainstringOptional
Responses
200
OK
patch
PATCH /v2/issuers/ref/{issuerOpenBadgeIdBase64} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 354

{
  "name": "Credentials Faculty",
  "email": "[email protected]",
  "url": "https://example.com",
  "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
  "description": "This is the faculty of the Credentials University.",
  "badgrDomain": "text",
  "staff": [
    {
      "role": "owner",
      "user": "Hey7J-GRSJeu6FNnHQwNyw"
    }
  ],
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  }
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "6016c84d1ff787222b6c4d15",
      "entityType": "Issuer",
      "entityId": "Uu4wd2I1SKmD3vmtMJ19hw",
      "openBadgeId": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "name": "Credentials Faculty",
      "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
      "email": "[email protected]",
      "description": "This is the faculty of the Credentials University.",
      "url": "https://example.com",
      "staff": [
        {
          "role": "staff",
          "user": "Hey7J-GRSJeu6FNnHQwNyw",
          "userProfile": {
            "entityType": "BadgeUser",
            "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
            "firstName": "Jane",
            "lastName": "Doe",
            "emails": [
              {
                "email": "[email protected]",
                "verified": true,
                "primary": true
              }
            ],
            "url": [
              "https://example.com"
            ],
            "telephone": [
              "text"
            ],
            "badgrDomain": "badgrsupportgroup.badgr.com",
            "agreedTermsVersion": 4,
            "marketingOptIn": true,
            "hasPasswordSet": true
          }
        }
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "createdBy": "text",
      "organizationId": "6f4e4e4e2dc038241ad01d83",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "sourceUrl": "https://example.com/issuers/1",
      "imagePath": "uploads/issuers/issuer-JTdhRmlFQZScIjoUr6x4UQ.png",
      "originalJson": "{}",
      "badgeSkillLinkingPreferences": {
        "type": "TALENT_NEURON",
        "serverUri": "https://example.com/",
        "linkMode": "DEFAULT",
        "indeedRegion": "us"
      },
      "preferences": {
        "customPropertyDefinitions": [
          {
            "propertyType": "STRING_CHOICE",
            "targetEntityType": "BADGE_CLASS",
            "propertyId": "66bf8231d88b51901d49d637",
            "label": "Award Type",
            "subLabel": "Type of award",
            "public": true,
            "required": true,
            "choiceValues": [
              {
                "id": "65663ceb977692fcafcea0b9",
                "label": "text"
              }
            ]
          }
        ],
        "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
        "enabledPrintCertTemplateIds": [
          "5f4e4e4e2dc038241ad01d83",
          "6f4e4e4e2dc038241ad01d83"
        ]
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a single BadgeClass

get
Authorizations
Path parameters
idOrEntityIdstringRequired
Query parameters
include_archivedbooleanOptionalDefault: false
Responses
200
OK
get
GET /v2/badgeclasses/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-25T23:49:11.719Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update an existing BadgeClass.

put

Previously awarded Assertions will be updated with image rebaking

Authorizations
Path parameters
idOrEntityIdstringRequired
Body
namestring · max: 1024Required

Name of the BadgeClass

Example: Math Expert
descriptionstring · max: 16384Required

Short description of the BadgeClass

Example: This badge is awarded to students who have demonstrated mastery of Math.
imagestringRequired

Image of the issuer. An URL or a bas64 encoded images.

Example: https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image
achievementTypestringOptional

The type of achievement

Example: Course
criteriaUrlstring · uriOptional

External URL that describes in a human-readable format the criteria for the BadgeClass

Example: https://example.com/badge-classes/1/criteria
criteriaNarrativestringOptional

Markdown formatted description of the criteria

tagsstring[]Optional

List of tags that describe the BadgeClass

Responses
200
OK
put
PUT /v2/badgeclasses/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 974

{
  "name": "Math Expert",
  "description": "This badge is awarded to students who have demonstrated mastery of Math.",
  "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
  "achievementType": "Course",
  "criteriaUrl": "https://example.com/badge-classes/1/criteria",
  "criteriaNarrative": "text",
  "tags": [
    "text"
  ],
  "alignments": [
    {
      "targetName": "text",
      "targetUrl": "text",
      "targetDescription": "text",
      "targetFramework": "text",
      "targetCode": "text",
      "displayAsSkill": true
    }
  ],
  "expires": {
    "amount": 30,
    "duration": "days"
  },
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "ob3Properties": {
    "creditHours": 36,
    "fieldOfStudy": "Research",
    "humanCode": "R1",
    "specialization": "Computer Science Research"
  },
  "preferences": {
    "includeOnPublicPages": true,
    "customPropertyValues": [
      {
        "propertyId": "67b32887e2a7a7d5f7adabf1",
        "stringValue": "text",
        "doubleValue": 1,
        "arrayValue": [
          "text"
        ],
        "public": true
      }
    ],
    "enabledPrintCertTemplateIds": [
      "61e9d238c5afe622816febb3"
    ],
    "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
  }
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-25T23:49:11.719Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Delete a BadgeClass

delete

Restricted to owners or editors (not staff) of the corresponding Issuer.

Authorizations
Path parameters
idOrEntityIdstringRequired
Query parameters
hard_deletestringOptional
archivalNotestringOptional
Responses
204
BadgeClass deleted
delete
DELETE /v2/badgeclasses/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update an existing ClaimCode for a BadgeClass

put
Authorizations
Path parameters
idOrEntityIdstringRequired
claimCodestringRequired
Body
labelstringOptional

The label of the claim code

Example: Conference Event
limitinteger · int64Optional

The number of times the claim code can be used

Example: 10
expirationDatestring · date-timeOptional
Responses
200
OK
put
PUT /v2/badgeclasses/{idOrEntityId}/claim-codes/{claimCode} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 83

{
  "label": "Conference Event",
  "limit": 10,
  "expirationDate": "2025-07-25T23:49:11.719Z"
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "code": "5678945",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "label": "Conference Event",
      "limit": 10,
      "expirationDate": "2025-07-25T23:49:11.719Z",
      "enabled": true,
      "claimCount": 1,
      "claimUrl": "text"
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Archive a ClaimCode for a BadgeClass

delete
Authorizations
Path parameters
idOrEntityIdstringRequired
claimCodestringRequired
Responses
204
No Content
delete
DELETE /v2/badgeclasses/{idOrEntityId}/claim-codes/{claimCode} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a single BadgeClass

get
Authorizations
Path parameters
refstringRequired
Query parameters
include_archivedbooleanOptionalDefault: false
Responses
200
OK
get
GET /v2/badgeclasses/ref/{ref} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-25T23:49:11.719Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update an existing BadgeClass.

put

Previously awarded Assertions will be updated with image rebaking

Authorizations
Path parameters
refstringRequired
Body
namestring · max: 1024Required

Name of the BadgeClass

Example: Math Expert
descriptionstring · max: 16384Required

Short description of the BadgeClass

Example: This badge is awarded to students who have demonstrated mastery of Math.
imagestringRequired

Image of the issuer. An URL or a bas64 encoded images.

Example: https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image
achievementTypestringOptional

The type of achievement

Example: Course
criteriaUrlstring · uriOptional

External URL that describes in a human-readable format the criteria for the BadgeClass

Example: https://example.com/badge-classes/1/criteria
criteriaNarrativestringOptional

Markdown formatted description of the criteria

tagsstring[]Optional

List of tags that describe the BadgeClass

Responses
200
OK
put
PUT /v2/badgeclasses/ref/{ref} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 974

{
  "name": "Math Expert",
  "description": "This badge is awarded to students who have demonstrated mastery of Math.",
  "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
  "achievementType": "Course",
  "criteriaUrl": "https://example.com/badge-classes/1/criteria",
  "criteriaNarrative": "text",
  "tags": [
    "text"
  ],
  "alignments": [
    {
      "targetName": "text",
      "targetUrl": "text",
      "targetDescription": "text",
      "targetFramework": "text",
      "targetCode": "text",
      "displayAsSkill": true
    }
  ],
  "expires": {
    "amount": 30,
    "duration": "days"
  },
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "ob3Properties": {
    "creditHours": 36,
    "fieldOfStudy": "Research",
    "humanCode": "R1",
    "specialization": "Computer Science Research"
  },
  "preferences": {
    "includeOnPublicPages": true,
    "customPropertyValues": [
      {
        "propertyId": "67b32887e2a7a7d5f7adabf1",
        "stringValue": "text",
        "doubleValue": 1,
        "arrayValue": [
          "text"
        ],
        "public": true
      }
    ],
    "enabledPrintCertTemplateIds": [
      "61e9d238c5afe622816febb3"
    ],
    "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
  }
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-25T23:49:11.719Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Delete a BadgeClass

delete

Restricted to owners or editors (not staff) of the corresponding Issuer.

Authorizations
Path parameters
refstringRequired
Query parameters
hard_deletestringOptional
archivalNotestringOptional
Responses
204
BadgeClass deleted
delete
DELETE /v2/badgeclasses/ref/{ref} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get Assertion Collection(s) associated with the authenticated user's backpack

get
Authorizations
Path parameters
idOrEntityIdstringRequired
Responses
200
OK
*/*
get
GET /v2/backpack/collections/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "6116c84d1ff787222b6c4d15",
      "entityId": "dwUFfLWhQ3CutEowC1LB7g",
      "name": "My Collection",
      "description": "This is a collection of my favorite badges",
      "share_url": "https://example.com/collections/1",
      "shareHash": "text",
      "published": true,
      "owner": "UQbhRmNrQ4qn9_FJ5-eTtA",
      "assertions": [
        "UQbhRmNrQ4qn9_FJ5-eTtA"
      ],
      "credentials": [
        "UQbhRmNrQ4qn9_FJ5-eTtA"
      ],
      "entityType": "BackpackCollection"
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a Collection

put
Authorizations
Path parameters
idOrEntityIdstringRequired
Body
namestringOptional

Name of the collection

Example: My Collection
descriptionstringOptional

Short description of the Collection

Example: This is a collection of my favorite badges
publishedbooleanOptional

True if the Collection should have a share url

Example: true
assertionsstring[]Optional

The IDs or entity IDs of the assertions associated with this Collection

Example: UQbhRmNrQ4qn9_FJ5-eTtA
credentialsstring[]Optional

The IDs or entity IDs of the credentials associated with this Collection

Example: UQbhRmNrQ4qn9_FJ5-eTtA
Responses
200
OK
*/*
put
PUT /v2/backpack/collections/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 181

{
  "name": "My Collection",
  "description": "This is a collection of my favorite badges",
  "published": true,
  "assertions": [
    "UQbhRmNrQ4qn9_FJ5-eTtA"
  ],
  "credentials": [
    "UQbhRmNrQ4qn9_FJ5-eTtA"
  ]
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "6116c84d1ff787222b6c4d15",
      "entityId": "dwUFfLWhQ3CutEowC1LB7g",
      "name": "My Collection",
      "description": "This is a collection of my favorite badges",
      "share_url": "https://example.com/collections/1",
      "shareHash": "text",
      "published": true,
      "owner": "UQbhRmNrQ4qn9_FJ5-eTtA",
      "assertions": [
        "UQbhRmNrQ4qn9_FJ5-eTtA"
      ],
      "credentials": [
        "UQbhRmNrQ4qn9_FJ5-eTtA"
      ],
      "entityType": "BackpackCollection"
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Delete a collection

delete
Authorizations
Path parameters
idOrEntityIdstringRequired
Responses
204
No Content
delete
DELETE /v2/backpack/collections/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Get detail on an Assertion in the user's Backpack

get
Authorizations
Path parameters
idOrEntityIdstringRequired
Query parameters
Responses
200
OK
*/*
get
GET /v2/backpack/assertions/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "entityType": "Assertion",
      "id": "6116c84d1ff787222b6c4d15",
      "entityId": "i9CirfwJTuSfiqg0FFUBdQ",
      "openBadgeId": "https://api.badgr.io/public/assertions/i9CirfwJTuSfiqg0FFUBdQ",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "badgeclass": "K829IK8RS6ercwkpeFOn-Q",
      "badgeclassOpenBadgeId": "https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "image": "https://api.badgr.io/public/assertions/SsCfI7FlTr6hAJe4irXnfQ/image",
      "recipient": {
        "identity": "sha256$4c2657856f",
        "hashed": true,
        "type": "email",
        "salt": "jgsu868",
        "plaintextIdentity": "[email protected]"
      },
      "issuedOn": "2025-07-25T23:49:11.719Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2025-07-25T23:49:11.719Z",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "assertionRef": {
        "assertionUrl": "https://api.badgr.io/public/assertions/lY1LJ6K4RqG7ThGLYvWNng"
      },
      "badgeRef": {
        "badgeUrl": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg"
      },
      "issuerRef": {
        "issuerUrl": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw"
      },
      "pending": true,
      "source": "local",
      "sourceUrl": "https://example.com/assertions/1",
      "originalJson": "{}",
      "imagePath": "uploads/badges/assertion-lY1LJ6K4RqG7ThGLYvWNng.png",
      "ob3AwardProperties": {
        "activityStart": "2025-07-25T23:49:11.719Z",
        "activityEnd": "2025-07-25T23:49:11.719Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update acceptance of an Assertion in the user's Backpack

put
Authorizations
Path parameters
idOrEntityIdstringRequired
Responses
200
OK
*/*
put
PUT /v2/backpack/assertions/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "entityType": "Assertion",
      "id": "6116c84d1ff787222b6c4d15",
      "entityId": "i9CirfwJTuSfiqg0FFUBdQ",
      "openBadgeId": "https://api.badgr.io/public/assertions/i9CirfwJTuSfiqg0FFUBdQ",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "badgeclass": "K829IK8RS6ercwkpeFOn-Q",
      "badgeclassOpenBadgeId": "https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "image": "https://api.badgr.io/public/assertions/SsCfI7FlTr6hAJe4irXnfQ/image",
      "recipient": {
        "identity": "sha256$4c2657856f",
        "hashed": true,
        "type": "email",
        "salt": "jgsu868",
        "plaintextIdentity": "[email protected]"
      },
      "issuedOn": "2025-07-25T23:49:11.719Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2025-07-25T23:49:11.719Z",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "assertionRef": {
        "assertionUrl": "https://api.badgr.io/public/assertions/lY1LJ6K4RqG7ThGLYvWNng"
      },
      "badgeRef": {
        "badgeUrl": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg"
      },
      "issuerRef": {
        "issuerUrl": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw"
      },
      "pending": true,
      "source": "local",
      "sourceUrl": "https://example.com/assertions/1",
      "originalJson": "{}",
      "imagePath": "uploads/badges/assertion-lY1LJ6K4RqG7ThGLYvWNng.png",
      "ob3AwardProperties": {
        "activityStart": "2025-07-25T23:49:11.719Z",
        "activityEnd": "2025-07-25T23:49:11.719Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Remove an assertion from the backpack

delete
Authorizations
Path parameters
idOrEntityIdstringRequired
Responses
204
No Content
delete
DELETE /v2/backpack/assertions/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Get a single Assertion

get
Authorizations
Path parameters
idOrEntityIdstringRequired
Responses
200
OK
get
GET /v2/assertions/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "entityType": "Assertion",
      "id": "6116c84d1ff787222b6c4d15",
      "entityId": "i9CirfwJTuSfiqg0FFUBdQ",
      "openBadgeId": "https://api.badgr.io/public/assertions/i9CirfwJTuSfiqg0FFUBdQ",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "badgeclass": "K829IK8RS6ercwkpeFOn-Q",
      "badgeclassOpenBadgeId": "https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "image": "https://api.badgr.io/public/assertions/SsCfI7FlTr6hAJe4irXnfQ/image",
      "recipient": {
        "identity": "sha256$4c2657856f",
        "hashed": true,
        "type": "email",
        "salt": "jgsu868",
        "plaintextIdentity": "[email protected]"
      },
      "issuedOn": "2025-07-25T23:49:11.719Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2025-07-25T23:49:11.719Z",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "assertionRef": {
        "assertionUrl": "https://api.badgr.io/public/assertions/lY1LJ6K4RqG7ThGLYvWNng"
      },
      "badgeRef": {
        "badgeUrl": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg"
      },
      "issuerRef": {
        "issuerUrl": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw"
      },
      "pending": true,
      "source": "local",
      "sourceUrl": "https://example.com/assertions/1",
      "originalJson": "{}",
      "imagePath": "uploads/badges/assertion-lY1LJ6K4RqG7ThGLYvWNng.png",
      "ob3AwardProperties": {
        "activityStart": "2025-07-25T23:49:11.719Z",
        "activityEnd": "2025-07-25T23:49:11.719Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update an Assertion

put
Authorizations
Path parameters
idOrEntityIdstringRequired
Body
narrativestringOptional

Markdown narrative of the achievement

expiresstring · date-timeOptional
issuedOnstring · date-timeOptional

Timestamp when the assertion was issued

Responses
200
OK
put
PUT /v2/assertions/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 408

{
  "narrative": "text",
  "evidence": [
    {
      "url": "text",
      "narrative": "text",
      "name": "text",
      "description": "text",
      "genre": "text",
      "audience": "text"
    }
  ],
  "extensions": {
    "value": {
      "ANY_ADDITIONAL_PROPERTY": {}
    }
  },
  "expires": "2025-07-25T23:49:11.719Z",
  "issuedOn": "2025-07-25T23:49:11.719Z",
  "ob3AwardProperties": {
    "activityStart": "2025-07-25T23:49:11.719Z",
    "activityEnd": "2025-07-25T23:49:11.719Z",
    "licenseNumber": "text",
    "role": "text"
  }
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "entityType": "Assertion",
      "id": "6116c84d1ff787222b6c4d15",
      "entityId": "i9CirfwJTuSfiqg0FFUBdQ",
      "openBadgeId": "https://api.badgr.io/public/assertions/i9CirfwJTuSfiqg0FFUBdQ",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "badgeclass": "K829IK8RS6ercwkpeFOn-Q",
      "badgeclassOpenBadgeId": "https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "image": "https://api.badgr.io/public/assertions/SsCfI7FlTr6hAJe4irXnfQ/image",
      "recipient": {
        "identity": "sha256$4c2657856f",
        "hashed": true,
        "type": "email",
        "salt": "jgsu868",
        "plaintextIdentity": "[email protected]"
      },
      "issuedOn": "2025-07-25T23:49:11.719Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2025-07-25T23:49:11.719Z",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "assertionRef": {
        "assertionUrl": "https://api.badgr.io/public/assertions/lY1LJ6K4RqG7ThGLYvWNng"
      },
      "badgeRef": {
        "badgeUrl": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg"
      },
      "issuerRef": {
        "issuerUrl": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw"
      },
      "pending": true,
      "source": "local",
      "sourceUrl": "https://example.com/assertions/1",
      "originalJson": "{}",
      "imagePath": "uploads/badges/assertion-lY1LJ6K4RqG7ThGLYvWNng.png",
      "ob3AwardProperties": {
        "activityStart": "2025-07-25T23:49:11.719Z",
        "activityEnd": "2025-07-25T23:49:11.719Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Revoke an Assertion

delete
Authorizations
Path parameters
idOrEntityIdstringRequired
Body
revocation_reasonstringOptional
Responses
200
OK
delete
DELETE /v2/assertions/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 28

{
  "revocation_reason": "text"
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "entityType": "Assertion",
      "id": "6116c84d1ff787222b6c4d15",
      "entityId": "i9CirfwJTuSfiqg0FFUBdQ",
      "openBadgeId": "https://api.badgr.io/public/assertions/i9CirfwJTuSfiqg0FFUBdQ",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "badgeclass": "K829IK8RS6ercwkpeFOn-Q",
      "badgeclassOpenBadgeId": "https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "image": "https://api.badgr.io/public/assertions/SsCfI7FlTr6hAJe4irXnfQ/image",
      "recipient": {
        "identity": "sha256$4c2657856f",
        "hashed": true,
        "type": "email",
        "salt": "jgsu868",
        "plaintextIdentity": "[email protected]"
      },
      "issuedOn": "2025-07-25T23:49:11.719Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2025-07-25T23:49:11.719Z",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "assertionRef": {
        "assertionUrl": "https://api.badgr.io/public/assertions/lY1LJ6K4RqG7ThGLYvWNng"
      },
      "badgeRef": {
        "badgeUrl": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg"
      },
      "issuerRef": {
        "issuerUrl": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw"
      },
      "pending": true,
      "source": "local",
      "sourceUrl": "https://example.com/assertions/1",
      "originalJson": "{}",
      "imagePath": "uploads/badges/assertion-lY1LJ6K4RqG7ThGLYvWNng.png",
      "ob3AwardProperties": {
        "activityStart": "2025-07-25T23:49:11.719Z",
        "activityEnd": "2025-07-25T23:49:11.719Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get list of Assertions for the specified scope

get
Authorizations
Path parameters
scopestring · enumRequiredPossible values:
idOrEntityIdstringRequired
Query parameters
recipientstringOptional

A recipient identifier to filter by

numinteger · int32Optional

Request pagination of results, before/after cursors may be provided in response header

include_expiredbooleanOptionalDefault: false
include_revokedbooleanOptionalDefault: false
afterstringOptional

Pagination cursor provided in "Link" response header

beforestringOptional

Pagination cursor provided in "Link" response header

Responses
200
List of Assertions
get
GET /v2/{scope}/{idOrEntityId}/assertions HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "entityType": "Assertion",
      "id": "6116c84d1ff787222b6c4d15",
      "entityId": "i9CirfwJTuSfiqg0FFUBdQ",
      "openBadgeId": "https://api.badgr.io/public/assertions/i9CirfwJTuSfiqg0FFUBdQ",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "badgeclass": "K829IK8RS6ercwkpeFOn-Q",
      "badgeclassOpenBadgeId": "https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "image": "https://api.badgr.io/public/assertions/SsCfI7FlTr6hAJe4irXnfQ/image",
      "recipient": {
        "identity": "sha256$4c2657856f",
        "hashed": true,
        "type": "email",
        "salt": "jgsu868",
        "plaintextIdentity": "[email protected]"
      },
      "issuedOn": "2025-07-25T23:49:11.719Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2025-07-25T23:49:11.719Z",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "assertionRef": {
        "assertionUrl": "https://api.badgr.io/public/assertions/lY1LJ6K4RqG7ThGLYvWNng"
      },
      "badgeRef": {
        "badgeUrl": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg"
      },
      "issuerRef": {
        "issuerUrl": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw"
      },
      "pending": true,
      "source": "local",
      "sourceUrl": "https://example.com/assertions/1",
      "originalJson": "{}",
      "imagePath": "uploads/badges/assertion-lY1LJ6K4RqG7ThGLYvWNng.png",
      "ob3AwardProperties": {
        "activityStart": "2025-07-25T23:49:11.719Z",
        "activityEnd": "2025-07-25T23:49:11.719Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Issue a new Assertion to a recipient

post
Authorizations
Path parameters
scopestring · enumRequiredPossible values:
idOrEntityIdstringRequired

The entity ID of the selected scope entity

Example: K829IK8RS6ercwkpeFOn-Q
Body

Request to award an assertion. When request scope is issuers, one of badgeclass or badgeclassOpenBadgeId must be provided.

badgeclassstringOptional

ID or Entity ID of the badge class to be awarded

Example: K829IK8RS6ercwkpeFOn-Q
badgeclassOpenBadgeIdstring · uriOptional

OB URL of the badge class to be awarded

Example: https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q
issuedOnstring · date-timeOptional

Timestamp when the assertion was issued

allowDuplicateAwardsbooleanOptional

If set to false and the recipient already has this assertion, then the request will fail

narrativestringOptional

Markdown narrative of the achievement

expiresstring · date-timeOptional
Responses
201
Created
post
POST /v2/{scope}/{idOrEntityId}/assertions HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 650

{
  "badgeclass": "K829IK8RS6ercwkpeFOn-Q",
  "badgeclassOpenBadgeId": "https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q",
  "issuedOn": "2025-07-25T23:49:11.719Z",
  "recipient": {
    "identity": "[email protected]",
    "type": "email",
    "hashed": true
  },
  "allowDuplicateAwards": true,
  "narrative": "text",
  "evidence": [
    {
      "url": "https://example.com",
      "narrative": "text",
      "name": "text",
      "description": "text",
      "genre": "text",
      "audience": "text"
    }
  ],
  "extensions": {
    "value": {
      "ANY_ADDITIONAL_PROPERTY": {}
    }
  },
  "expires": "2025-07-25T23:49:11.719Z",
  "ob3AwardProperties": {
    "activityStart": "2025-07-25T23:49:11.719Z",
    "activityEnd": "2025-07-25T23:49:11.719Z",
    "licenseNumber": "text",
    "role": "text"
  }
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "entityType": "Assertion",
      "id": "6116c84d1ff787222b6c4d15",
      "entityId": "i9CirfwJTuSfiqg0FFUBdQ",
      "openBadgeId": "https://api.badgr.io/public/assertions/i9CirfwJTuSfiqg0FFUBdQ",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "badgeclass": "K829IK8RS6ercwkpeFOn-Q",
      "badgeclassOpenBadgeId": "https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "image": "https://api.badgr.io/public/assertions/SsCfI7FlTr6hAJe4irXnfQ/image",
      "recipient": {
        "identity": "sha256$4c2657856f",
        "hashed": true,
        "type": "email",
        "salt": "jgsu868",
        "plaintextIdentity": "[email protected]"
      },
      "issuedOn": "2025-07-25T23:49:11.719Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2025-07-25T23:49:11.719Z",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "assertionRef": {
        "assertionUrl": "https://api.badgr.io/public/assertions/lY1LJ6K4RqG7ThGLYvWNng"
      },
      "badgeRef": {
        "badgeUrl": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg"
      },
      "issuerRef": {
        "issuerUrl": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw"
      },
      "pending": true,
      "source": "local",
      "sourceUrl": "https://example.com/assertions/1",
      "originalJson": "{}",
      "imagePath": "uploads/badges/assertion-lY1LJ6K4RqG7ThGLYvWNng.png",
      "ob3AwardProperties": {
        "activityStart": "2025-07-25T23:49:11.719Z",
        "activityEnd": "2025-07-25T23:49:11.719Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a list of Issuers for authenticated user

get
Authorizations
Query parameters
include_staffstringOptionalDefault: true
Responses
200
OK
get
GET /v2/issuers HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "6016c84d1ff787222b6c4d15",
      "entityType": "Issuer",
      "entityId": "Uu4wd2I1SKmD3vmtMJ19hw",
      "openBadgeId": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "name": "Credentials Faculty",
      "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
      "email": "[email protected]",
      "description": "This is the faculty of the Credentials University.",
      "url": "https://example.com",
      "staff": [
        {
          "role": "staff",
          "user": "Hey7J-GRSJeu6FNnHQwNyw",
          "userProfile": {
            "entityType": "BadgeUser",
            "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
            "firstName": "Jane",
            "lastName": "Doe",
            "emails": [
              {
                "email": "[email protected]",
                "verified": true,
                "primary": true
              }
            ],
            "url": [
              "https://example.com"
            ],
            "telephone": [
              "text"
            ],
            "badgrDomain": "badgrsupportgroup.badgr.com",
            "agreedTermsVersion": 4,
            "marketingOptIn": true,
            "hasPasswordSet": true
          }
        }
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "createdBy": "text",
      "organizationId": "6f4e4e4e2dc038241ad01d83",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "sourceUrl": "https://example.com/issuers/1",
      "imagePath": "uploads/issuers/issuer-JTdhRmlFQZScIjoUr6x4UQ.png",
      "originalJson": "{}",
      "badgeSkillLinkingPreferences": {
        "type": "TALENT_NEURON",
        "serverUri": "https://example.com/",
        "linkMode": "DEFAULT",
        "indeedRegion": "us"
      },
      "preferences": {
        "customPropertyDefinitions": [
          {
            "propertyType": "STRING_CHOICE",
            "targetEntityType": "BADGE_CLASS",
            "propertyId": "66bf8231d88b51901d49d637",
            "label": "Award Type",
            "subLabel": "Type of award",
            "public": true,
            "required": true,
            "choiceValues": [
              {
                "id": "65663ceb977692fcafcea0b9",
                "label": "text"
              }
            ]
          }
        ],
        "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
        "enabledPrintCertTemplateIds": [
          "5f4e4e4e2dc038241ad01d83",
          "6f4e4e4e2dc038241ad01d83"
        ]
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Create a new Issuer

post
Authorizations
Query parameters
include_staffstringOptionalDefault: true
Body
namestring · max: 1024Required

Name of the issuer

Example: Credentials Faculty
emailstring · email · max: 255Required

Contact email for the Issuer

Example: [email protected]
urlstring · uri · max: 1024Required

Homepage or website associated with the Issuer

Example: https://example.com
sourceUrlstring · uriOptional

The original URL of the issuer if it was imported

Example: https://example.com/issuers/1
originalJsonstring · max: 2000000Optional

The original OB JSON of the issuer if it was imported

Example: {}
imagestringOptional

Image of the issuer. An URL or a bas64 encoded images.

Example: https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image
descriptionstring · max: 16384Optional

Short description of the Issuer

Example: This is the faculty of the Credentials University.
badgrDomainstringOptional

Organization domain host

Example: badgrsupportgroup.badgr.com
createdBystringOptional

User who created this issuer

organizationIdstringOptional

The ID of the organization which this issuer should be associated with. Requires organization write access.

Example: 6f4e4e4e2dc038241ad01d83
Responses
201
Issuer created
post
POST /v2/issuers HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 460

{
  "name": "Credentials Faculty",
  "email": "[email protected]",
  "url": "https://example.com",
  "sourceUrl": "https://example.com/issuers/1",
  "originalJson": "{}",
  "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
  "description": "This is the faculty of the Credentials University.",
  "staff": [
    {
      "role": "owner",
      "user": "Hey7J-GRSJeu6FNnHQwNyw"
    }
  ],
  "badgrDomain": "badgrsupportgroup.badgr.com",
  "createdBy": "text",
  "organizationId": "6f4e4e4e2dc038241ad01d83"
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "6016c84d1ff787222b6c4d15",
      "entityType": "Issuer",
      "entityId": "Uu4wd2I1SKmD3vmtMJ19hw",
      "openBadgeId": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "name": "Credentials Faculty",
      "image": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw/image",
      "email": "[email protected]",
      "description": "This is the faculty of the Credentials University.",
      "url": "https://example.com",
      "staff": [
        {
          "role": "staff",
          "user": "Hey7J-GRSJeu6FNnHQwNyw",
          "userProfile": {
            "entityType": "BadgeUser",
            "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
            "firstName": "Jane",
            "lastName": "Doe",
            "emails": [
              {
                "email": "[email protected]",
                "verified": true,
                "primary": true
              }
            ],
            "url": [
              "https://example.com"
            ],
            "telephone": [
              "text"
            ],
            "badgrDomain": "badgrsupportgroup.badgr.com",
            "agreedTermsVersion": 4,
            "marketingOptIn": true,
            "hasPasswordSet": true
          }
        }
      ],
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "createdBy": "text",
      "organizationId": "6f4e4e4e2dc038241ad01d83",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "sourceUrl": "https://example.com/issuers/1",
      "imagePath": "uploads/issuers/issuer-JTdhRmlFQZScIjoUr6x4UQ.png",
      "originalJson": "{}",
      "badgeSkillLinkingPreferences": {
        "type": "TALENT_NEURON",
        "serverUri": "https://example.com/",
        "linkMode": "DEFAULT",
        "indeedRegion": "us"
      },
      "preferences": {
        "customPropertyDefinitions": [
          {
            "propertyType": "STRING_CHOICE",
            "targetEntityType": "BADGE_CLASS",
            "propertyId": "66bf8231d88b51901d49d637",
            "label": "Award Type",
            "subLabel": "Type of award",
            "public": true,
            "required": true,
            "choiceValues": [
              {
                "id": "65663ceb977692fcafcea0b9",
                "label": "text"
              }
            ]
          }
        ],
        "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
        "enabledPrintCertTemplateIds": [
          "5f4e4e4e2dc038241ad01d83",
          "6f4e4e4e2dc038241ad01d83"
        ]
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Invite a staff member to an Issuer

post

User must have an owner role on the issuer.

Authorizations
Path parameters
idOrEntityIdstringRequired
Body
emailstringRequired

Email address associated with the staff member

Example: [email protected]
rolestring · enumRequired

Role of the user in the issuer.

Possible values:
Responses
200
OK
*/*
post
POST /v2/issuers/{idOrEntityId}/staff/invitations HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "email": "[email protected]",
  "role": "owner"
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "email": "[email protected]",
      "role": "owner",
      "status": "PENDING"
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a list of BadgeClasses for a single Issuer

get
Authorizations
Path parameters
idOrEntityIdstringRequired
Query parameters
include_archivedbooleanOptionalDefault: false
Responses
200
OK
get
GET /v2/issuers/{idOrEntityId}/badgeclasses HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-25T23:49:11.719Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Create a new BadgeClass associated with an Issuer

post
Authorizations
Path parameters
idOrEntityIdstringRequired
Body
issuerstringOptional

Entity ID of the issuer

Example: ZvYydoQhRtOKalNzFPZR2A-Q
namestring · max: 1024Required

Name of the BadgeClass

Example: Math Expert
imagestringRequired

Image of the issuer. An URL or a bas64 encoded images.

Example: https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image
achievementTypestringOptional

The type of achievement

Example: Course
descriptionstring · max: 16384Required

Short description of the BadgeClass

Example: This badge is awarded to students who have demonstrated mastery of Math.
criteriaUrlstring · uriOptional

External URL that describes in a human-readable format the criteria for the BadgeClass

Example: https://example.com/badge-classes/1/criteria
criteriaNarrativestringOptional

Markdown formatted description of the criteria

tagsstring[]Optional

List of tags that describe the BadgeClass

Responses
201
Created
post
POST /v2/issuers/{idOrEntityId}/badgeclasses HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1010

{
  "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
  "name": "Math Expert",
  "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
  "achievementType": "Course",
  "description": "This badge is awarded to students who have demonstrated mastery of Math.",
  "criteriaUrl": "https://example.com/badge-classes/1/criteria",
  "criteriaNarrative": "text",
  "tags": [
    "text"
  ],
  "alignments": [
    {
      "targetName": "text",
      "targetUrl": "text",
      "targetDescription": "text",
      "targetFramework": "text",
      "targetCode": "text",
      "displayAsSkill": true
    }
  ],
  "expires": {
    "amount": 30,
    "duration": "days"
  },
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "ob3Properties": {
    "creditHours": 36,
    "fieldOfStudy": "Research",
    "humanCode": "R1",
    "specialization": "Computer Science Research"
  },
  "preferences": {
    "includeOnPublicPages": true,
    "customPropertyValues": [
      {
        "propertyId": "67b32887e2a7a7d5f7adabf1",
        "stringValue": "text",
        "doubleValue": 1,
        "arrayValue": [
          "text"
        ],
        "public": true
      }
    ],
    "enabledPrintCertTemplateIds": [
      "61e9d238c5afe622816febb3"
    ],
    "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
  }
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-25T23:49:11.719Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a list of BadgeClasses for authenticated user

get
Authorizations
Query parameters
include_archivedbooleanOptionalDefault: false
Responses
200
OK
get
GET /v2/badgeclasses HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-25T23:49:11.719Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Create a new BadgeClass

post
Authorizations
Body
issuerstringRequired

Entity ID of the issuer

Example: ZvYydoQhRtOKalNzFPZR2A-Q
namestring · max: 1024Required

Name of the BadgeClass

Example: Math Expert
descriptionstring · max: 16384Required

Short description of the BadgeClass

Example: This badge is awarded to students who have demonstrated mastery of Math.
imagestringRequired

Image of the issuer. An URL or a bas64 encoded images.

Example: https://example.com/images/1
achievementTypestringOptional

The type of achievement

Example: Course
criteriaUrlstring · uriOptional

External URL that describes in a human-readable format the criteria for the BadgeClass

Example: https://example.com/badge-classes/1/criteria
criteriaNarrativestringOptional

Markdown formatted description of the criteria

tagsstring[]Optional

List of tags that describe the BadgeClass

Responses
201
BadgeClass created
post
POST /v2/badgeclasses HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 975

{
  "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
  "name": "Math Expert",
  "description": "This badge is awarded to students who have demonstrated mastery of Math.",
  "image": "https://example.com/images/1",
  "achievementType": "Course",
  "criteriaUrl": "https://example.com/badge-classes/1/criteria",
  "criteriaNarrative": "text",
  "tags": [
    "text"
  ],
  "alignments": [
    {
      "targetName": "text",
      "targetUrl": "text",
      "targetDescription": "text",
      "targetFramework": "text",
      "targetCode": "text",
      "displayAsSkill": true
    }
  ],
  "expires": {
    "amount": 30,
    "duration": "days"
  },
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "ob3Properties": {
    "creditHours": 36,
    "fieldOfStudy": "Research",
    "humanCode": "R1",
    "specialization": "Computer Science Research"
  },
  "preferences": {
    "includeOnPublicPages": true,
    "customPropertyValues": [
      {
        "propertyId": "67b32887e2a7a7d5f7adabf1",
        "stringValue": "text",
        "doubleValue": 1,
        "arrayValue": [
          "text"
        ],
        "public": true
      }
    ],
    "enabledPrintCertTemplateIds": [
      "61e9d238c5afe622816febb3"
    ],
    "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
  }
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-25T23:49:11.719Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Duplicate a BadgeClass

post

Create a duplicate of the original BadgeClass with a new name

Authorizations
Path parameters
idOrEntityIdstringRequired
Body
newNamestringRequired

The new name for the duplicate badgeclass

Example: Badgeclass Copy
Responses
201
BadgeClass created
post
POST /v2/badgeclasses/{idOrEntityId}/duplicate HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "newName": "Badgeclass Copy"
}
{
  "id": "68e9d238c5afe622816febb3",
  "entityType": "BadgeClass",
  "entityId": "iOMWsaF1QbmMCofM54JlUg",
  "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
  "sourceUrl": "https://example.com/badge-classes/1",
  "originalJson": "{}",
  "createdAt": "2025-07-25T23:49:11.719Z",
  "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
  "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
  "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
  "name": "Math Expert",
  "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
  "description": "This badge is awarded to students who have demonstrated mastery of Math.",
  "achievementType": "Course",
  "criteriaUrl": "https://example.com/badge-classes/1/criteria",
  "criteriaNarrative": "text",
  "alignments": [
    {
      "targetName": "text",
      "targetUrl": "text",
      "targetDescription": "text",
      "targetFramework": "text",
      "targetCode": "text",
      "displayAsSkill": true
    }
  ],
  "tags": [
    "text"
  ],
  "expires": {
    "amount": 30,
    "duration": "days"
  },
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "source": "local",
  "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
  "archived": true,
  "archivedDate": "2025-07-25T23:49:11.719Z",
  "archivalNote": "text",
  "ob3Properties": {
    "creditHours": 36,
    "fieldOfStudy": "Research",
    "humanCode": "R1",
    "specialization": "Computer Science Research"
  },
  "preferences": {
    "includeOnPublicPages": true,
    "customPropertyValues": [
      {
        "propertyId": "67b32887e2a7a7d5f7adabf1",
        "stringValue": "text",
        "doubleValue": 1,
        "arrayValue": [
          "text"
        ],
        "public": true
      }
    ],
    "enabledPrintCertTemplateIds": [
      "61e9d238c5afe622816febb3"
    ],
    "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
  }
}

Get a list of ClaimCodes for a single BadgeClass

get
Authorizations
Path parameters
idOrEntityIdstringRequired
Query parameters
includeClaimCodeCountbooleanOptional
Responses
200
OK
get
GET /v2/badgeclasses/{idOrEntityId}/claim-codes HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "code": "5678945",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "label": "Conference Event",
      "limit": 10,
      "expirationDate": "2025-07-25T23:49:11.719Z",
      "enabled": true,
      "claimCount": 1,
      "claimUrl": "text"
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Create a new ClaimCode for a BadgeClass

post
Authorizations
Path parameters
idOrEntityIdstringRequired
Body
labelstringOptional

The label of the claim code

Example: Conference Event
limitinteger · int64Optional

The number of times the claim code can be used

Example: 10
expirationDatestring · date-timeOptional
Responses
201
Created
post
POST /v2/badgeclasses/{idOrEntityId}/claim-codes HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 83

{
  "label": "Conference Event",
  "limit": 10,
  "expirationDate": "2025-07-25T23:49:11.719Z"
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "code": "5678945",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "label": "Conference Event",
      "limit": 10,
      "expirationDate": "2025-07-25T23:49:11.719Z",
      "enabled": true,
      "claimCount": 1,
      "claimUrl": "text"
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Reactivate a BadgeClass by id

post

Reactivate a BadgeClass that was archived

Authorizations
Path parameters
idOrEntityIdstringRequired
Responses
200
OK
post
POST /v2/badgeclasses/reactivate/{idOrEntityId} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-25T23:49:11.719Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Reactivate a BadgeClass by ref

post

Reactivate an archived BadgeClass by its base64 encoded OpenBadge ID

Authorizations
Path parameters
refstringRequired
Responses
200
OK
post
POST /v2/badgeclasses/reactivate/ref/{ref} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "68e9d238c5afe622816febb3",
      "entityType": "BadgeClass",
      "entityId": "iOMWsaF1QbmMCofM54JlUg",
      "openBadgeId": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg",
      "sourceUrl": "https://example.com/badge-classes/1",
      "originalJson": "{}",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "name": "Math Expert",
      "image": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg/image",
      "description": "This badge is awarded to students who have demonstrated mastery of Math.",
      "achievementType": "Course",
      "criteriaUrl": "https://example.com/badge-classes/1/criteria",
      "criteriaNarrative": "text",
      "alignments": [
        {
          "targetName": "text",
          "targetUrl": "text",
          "targetDescription": "text",
          "targetFramework": "text",
          "targetCode": "text",
          "displayAsSkill": true
        }
      ],
      "tags": [
        "text"
      ],
      "expires": {
        "amount": 30,
        "duration": "days"
      },
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "source": "local",
      "imagePath": "uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png",
      "archived": true,
      "archivedDate": "2025-07-25T23:49:11.719Z",
      "archivalNote": "text",
      "ob3Properties": {
        "creditHours": 36,
        "fieldOfStudy": "Research",
        "humanCode": "R1",
        "specialization": "Computer Science Research"
      },
      "preferences": {
        "includeOnPublicPages": true,
        "customPropertyValues": [
          {
            "propertyId": "67b32887e2a7a7d5f7adabf1",
            "stringValue": "text",
            "doubleValue": 1,
            "arrayValue": [
              "text"
            ],
            "public": true
          }
        ],
        "enabledPrintCertTemplateIds": [
          "61e9d238c5afe622816febb3"
        ],
        "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Upload a new Assertion to the backpack

post

Upload a new Assertion to the backpack using url, image or OpenBadge JSON

Authorizations
Body
urlstring · uriOptional

URL of the badge to import

Example: https://example.com/assertions/1
assertionobjectOptional

OpenBadge JSON of the award to import

imagestringOptional

Image URL or base64 encoded image data of the assertion.

Example: https://example.com/assertions/1/image
Responses
201
Created
*/*
post
POST /v2/backpack/import HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 106

{
  "url": "https://example.com/assertions/1",
  "assertion": {},
  "image": "https://example.com/assertions/1/image"
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "entityType": "Assertion",
      "id": "6116c84d1ff787222b6c4d15",
      "entityId": "i9CirfwJTuSfiqg0FFUBdQ",
      "openBadgeId": "https://api.badgr.io/public/assertions/i9CirfwJTuSfiqg0FFUBdQ",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "badgeclass": "K829IK8RS6ercwkpeFOn-Q",
      "badgeclassOpenBadgeId": "https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "image": "https://api.badgr.io/public/assertions/SsCfI7FlTr6hAJe4irXnfQ/image",
      "recipient": {
        "identity": "sha256$4c2657856f",
        "hashed": true,
        "type": "email",
        "salt": "jgsu868",
        "plaintextIdentity": "[email protected]"
      },
      "issuedOn": "2025-07-25T23:49:11.719Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2025-07-25T23:49:11.719Z",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "assertionRef": {
        "assertionUrl": "https://api.badgr.io/public/assertions/lY1LJ6K4RqG7ThGLYvWNng"
      },
      "badgeRef": {
        "badgeUrl": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg"
      },
      "issuerRef": {
        "issuerUrl": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw"
      },
      "pending": true,
      "source": "local",
      "sourceUrl": "https://example.com/assertions/1",
      "originalJson": "{}",
      "imagePath": "uploads/badges/assertion-lY1LJ6K4RqG7ThGLYvWNng.png",
      "ob3AwardProperties": {
        "activityStart": "2025-07-25T23:49:11.719Z",
        "activityEnd": "2025-07-25T23:49:11.719Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get Assertion Collection(s) associated with the authenticated user's backpack

get
Authorizations
Responses
200
OK
*/*
get
GET /v2/backpack/collections HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "6116c84d1ff787222b6c4d15",
      "entityId": "dwUFfLWhQ3CutEowC1LB7g",
      "name": "My Collection",
      "description": "This is a collection of my favorite badges",
      "share_url": "https://example.com/collections/1",
      "shareHash": "text",
      "published": true,
      "owner": "UQbhRmNrQ4qn9_FJ5-eTtA",
      "assertions": [
        "UQbhRmNrQ4qn9_FJ5-eTtA"
      ],
      "credentials": [
        "UQbhRmNrQ4qn9_FJ5-eTtA"
      ],
      "entityType": "BackpackCollection"
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Create a new Collection

post
Authorizations
Body
namestringRequired

Name of the collection

Example: My Collection
descriptionstringOptional

Short description of the Collection

Example: This is a collection of my favorite badges
publishedbooleanRequired

True if the Collection should have a share url

Example: true
Responses
201
Created
*/*
post
POST /v2/backpack/collections HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 100

{
  "name": "My Collection",
  "description": "This is a collection of my favorite badges",
  "published": true
}
{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "id": "6116c84d1ff787222b6c4d15",
      "entityId": "dwUFfLWhQ3CutEowC1LB7g",
      "name": "My Collection",
      "description": "This is a collection of my favorite badges",
      "share_url": "https://example.com/collections/1",
      "shareHash": "text",
      "published": true,
      "owner": "UQbhRmNrQ4qn9_FJ5-eTtA",
      "assertions": [
        "UQbhRmNrQ4qn9_FJ5-eTtA"
      ],
      "credentials": [
        "UQbhRmNrQ4qn9_FJ5-eTtA"
      ],
      "entityType": "BackpackCollection"
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Revoke multiple Assertions

post
Authorizations
Bodyobject[]
idstringOptional

ID of the Assertion to revoke

Example: 62aa04adf5afe00d0a6dac72
entityIdstringOptional

Entity ID of the Assertion to revoke

Example: i9CirfwJTuSfiqg0FFUBdQ
revocationReasonstringRequired

Short description of why the Assertion is being revoked

Example: Course was cancelled
revokedbooleanRead-onlyOptional
reasonstringRead-onlyOptional

Error reason if assertion could not be revoked

codestringRead-onlyOptional

Error code if assertion could not be revoked

Responses
200
OK
post
POST /v2/assertions/revoke HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 113

[
  {
    "id": "62aa04adf5afe00d0a6dac72",
    "entityId": "i9CirfwJTuSfiqg0FFUBdQ",
    "revocationReason": "Course was cancelled"
  }
]
[
  {
    "id": "62aa04adf5afe00d0a6dac72",
    "entityId": "i9CirfwJTuSfiqg0FFUBdQ",
    "revocationReason": "Course was cancelled",
    "revoked": true,
    "reason": "text",
    "code": "text"
  }
]

Enable a disabled ClaimCode for a BadgeClass

patch
Authorizations
Path parameters
idOrEntityIdstringRequired
claimCodestringRequired
Responses
200
OK
patch
PATCH /v2/badgeclasses/{idOrEntityId}/claim-codes/{claimCode}/enable HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "code": "5678945",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "label": "Conference Event",
      "limit": 10,
      "expirationDate": "2025-07-25T23:49:11.719Z",
      "enabled": true,
      "claimCount": 1,
      "claimUrl": "text"
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Disable an enabled ClaimCode for a BadgeClass

patch
Authorizations
Path parameters
idOrEntityIdstringRequired
claimCodestringRequired
Responses
200
OK
patch
PATCH /v2/badgeclasses/{idOrEntityId}/claim-codes/{claimCode}/disable HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "code": "5678945",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "label": "Conference Event",
      "limit": 10,
      "expirationDate": "2025-07-25T23:49:11.719Z",
      "enabled": true,
      "claimCount": 1,
      "claimUrl": "text"
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a list of Organizations where the authenticated user is admin

get
Authorizations
Responses
200
OK
get
GET /v2/organizations HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "organizations": [
    {
      "id": "67ae3efe2ee1d96b56fc1957",
      "name": "University of Credentials",
      "profile": {
        "url": "https://www.example.com",
        "email": "[email protected]",
        "description": "A university that issues credentials.",
        "imageUrl": "https://www.example.com/logo.png"
      }
    }
  ]
}

Get a list of Assertions in authenticated user's backpack

get
Authorizations
Query parameters
Responses
200
OK
*/*
get
GET /v2/backpack/assertions HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "entityType": "Assertion",
      "id": "6116c84d1ff787222b6c4d15",
      "entityId": "i9CirfwJTuSfiqg0FFUBdQ",
      "openBadgeId": "https://api.badgr.io/public/assertions/i9CirfwJTuSfiqg0FFUBdQ",
      "createdAt": "2025-07-25T23:49:11.719Z",
      "createdBy": "Hey7J-GRSJeu6FNnHQwNyw",
      "badgeclass": "K829IK8RS6ercwkpeFOn-Q",
      "badgeclassOpenBadgeId": "https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q",
      "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
      "issuerOpenBadgeId": "https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A",
      "image": "https://api.badgr.io/public/assertions/SsCfI7FlTr6hAJe4irXnfQ/image",
      "recipient": {
        "identity": "sha256$4c2657856f",
        "hashed": true,
        "type": "email",
        "salt": "jgsu868",
        "plaintextIdentity": "[email protected]"
      },
      "issuedOn": "2025-07-25T23:49:11.719Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2025-07-25T23:49:11.719Z",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "assertionRef": {
        "assertionUrl": "https://api.badgr.io/public/assertions/lY1LJ6K4RqG7ThGLYvWNng"
      },
      "badgeRef": {
        "badgeUrl": "https://api.badgr.io/public/badges/iOMWsaF1QbmMCofM54JlUg"
      },
      "issuerRef": {
        "issuerUrl": "https://api.badgr.ws/public/issuers/Uu4wd2I1SKmD3vmtMJ19hw"
      },
      "pending": true,
      "source": "local",
      "sourceUrl": "https://example.com/assertions/1",
      "originalJson": "{}",
      "imagePath": "uploads/badges/assertion-lY1LJ6K4RqG7ThGLYvWNng.png",
      "ob3AwardProperties": {
        "activityStart": "2025-07-25T23:49:11.719Z",
        "activityEnd": "2025-07-25T23:49:11.719Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Remove a staff member from the Issuer

delete

User must have an owner role on the issuer.

Authorizations
Path parameters
idOrEntityIdstringRequired
emailBase64stringRequired

Base64 encoded email address of the staff member

Responses
204
Staff member removed
*/*
delete
DELETE /v2/issuers/{idOrEntityId}/staff/{emailBase64} HTTP/1.1
Host: api.badgr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "timestamp": "2025-07-25T23:49:11.719Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}
PreviousPaginationNextAssertions

Last updated

Was this helpful?