APIs

Update a staff member's role on the Issuer

put

User must have an owner role on the issuer.

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

application/json

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

*/*

400

Bad Request

*/*

put

/v2/issuers/{idOrEntityId}/staff

HTTPcURLJavaScriptPython

PUT /v2/issuers/{idOrEntityId}/staff HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "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.

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

application/json

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

*/*

400

Bad Request

*/*

post

/v2/issuers/{idOrEntityId}/staff

HTTPcURLJavaScriptPython

POST /v2/issuers/{idOrEntityId}/staff HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "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.

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

application/json

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

*/*

400

Bad Request

*/*

patch

/v2/issuers/{idOrEntityId}/staff

HTTPcURLJavaScriptPython

PATCH /v2/issuers/{idOrEntityId}/staff HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a single BadgeUser profile

get

Required scopes

This endpoint requires the following scopes:

• : See who you are
• : Update your profile

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Responses

200

OK

application/json

400

Bad Request

*/*

get

/v2/users/{idOrEntityId}

HTTPcURLJavaScriptPython

GET /v2/users/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a BadgeUser

put

Required scopes

This endpoint requires the following scopes:

• : See who you are
• : Update your profile

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

application/json

firstNamestringOptionalExample: Jane

lastNamestringOptionalExample: Doe

marketingOptInbooleanOptionalExample: true

Responses

200

OK

application/json

400

Bad Request

*/*

put

/v2/users/{idOrEntityId}

HTTPcURLJavaScriptPython

PUT /v2/users/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a BadgeUser

patch

Required scopes

This endpoint requires the following scopes:

• : See who you are
• : Update your profile

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

application/json

firstNamestringOptionalExample: Jane

lastNamestringOptionalExample: Doe

marketingOptInbooleanOptionalExample: true

Responses

200

OK

application/json

400

Bad Request

*/*

patch

/v2/users/{idOrEntityId}

HTTPcURLJavaScriptPython

PATCH /v2/users/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get your own BadgeUser profile

get

Required scopes

This endpoint requires the following scopes:

• : See who you are
• : Update your profile

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Responses

200

OK

application/json

400

Bad Request

*/*

get

/v2/users/self

HTTPcURLJavaScriptPython

GET /v2/users/self HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update your own BadgeUser

put

Required scopes

This endpoint requires the following scopes:

• : See who you are
• : Update your profile

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Body

application/json

firstNamestringOptionalExample: Jane

lastNamestringOptionalExample: Doe

marketingOptInbooleanOptionalExample: true

Responses

200

OK

application/json

400

Bad Request

*/*

put

/v2/users/self

HTTPcURLJavaScriptPython

PUT /v2/users/self HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update your own BadgeUser

patch

Required scopes

This endpoint requires the following scopes:

• : See who you are
• : Update your profile

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Body

application/json

firstNamestringOptionalExample: Jane

lastNamestringOptionalExample: Doe

marketingOptInbooleanOptionalExample: true

Responses

200

OK

application/json

400

Bad Request

*/*

patch

/v2/users/self

HTTPcURLJavaScriptPython

PATCH /v2/users/self HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a single Issuer

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Query parameters

include_staffstringOptionalDefault: true

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/issuers/{idOrEntityId}

HTTPcURLJavaScriptPython

GET /v2/issuers/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a single Issuer

put

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Query parameters

include_staffstringOptionalDefault: true

Body

application/json

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

application/jsonapplication/ld+json

400

Bad Request

*/*

put

/v2/issuers/{idOrEntityId}

HTTPcURLJavaScriptPython

PUT /v2/issuers/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Delete a single Issuer

delete

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Responses

204

Issuer deleted

400

Bad Request

*/*

delete

/v2/issuers/{idOrEntityId}

HTTPcURLJavaScriptPython

DELETE /v2/issuers/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Update a single Issuer

patch

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Query parameters

include_staffstringOptionalDefault: true

Body

application/json

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

application/jsonapplication/ld+json

400

Bad Request

*/*

patch

/v2/issuers/{idOrEntityId}

HTTPcURLJavaScriptPython

PATCH /v2/issuers/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a single Issuer

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

issuerOpenBadgeIdBase64stringRequired

Query parameters

include_staffstringOptionalDefault: true

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/issuers/openBadgeId/{issuerOpenBadgeIdBase64}

HTTPcURLJavaScriptPython

GET /v2/issuers/openBadgeId/{issuerOpenBadgeIdBase64} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a single Issuer

put

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

issuerOpenBadgeIdBase64stringRequired

Query parameters

include_staffstringOptionalDefault: true

Body

application/json

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

application/jsonapplication/ld+json

400

Bad Request

*/*

put

/v2/issuers/openBadgeId/{issuerOpenBadgeIdBase64}

HTTPcURLJavaScriptPython

PUT /v2/issuers/openBadgeId/{issuerOpenBadgeIdBase64} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Delete a single Issuer

delete

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

issuerOpenBadgeIdBase64stringRequired

Responses

204

Issuer deleted

application/jsonapplication/ld+json

400

Bad Request

*/*

delete

/v2/issuers/openBadgeId/{issuerOpenBadgeIdBase64}

HTTPcURLJavaScriptPython

DELETE /v2/issuers/openBadgeId/{issuerOpenBadgeIdBase64} HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "timestamp": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a single Issuer

patch

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

issuerOpenBadgeIdBase64stringRequired

Query parameters

include_staffstringOptionalDefault: true

Body

application/json

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

application/jsonapplication/ld+json

400

Bad Request

*/*

patch

/v2/issuers/openBadgeId/{issuerOpenBadgeIdBase64}

HTTPcURLJavaScriptPython

PATCH /v2/issuers/openBadgeId/{issuerOpenBadgeIdBase64} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a single Issuer

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

issuerOpenBadgeIdBase64stringRequired

Query parameters

include_staffstringOptionalDefault: true

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/issuers/ref/{issuerOpenBadgeIdBase64}

HTTPcURLJavaScriptPython

GET /v2/issuers/ref/{issuerOpenBadgeIdBase64} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a single Issuer

put

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

issuerOpenBadgeIdBase64stringRequired

Query parameters

include_staffstringOptionalDefault: true

Body

application/json

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

application/jsonapplication/ld+json

400

Bad Request

*/*

put

/v2/issuers/ref/{issuerOpenBadgeIdBase64}

HTTPcURLJavaScriptPython

PUT /v2/issuers/ref/{issuerOpenBadgeIdBase64} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Delete a single Issuer

delete

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

issuerOpenBadgeIdBase64stringRequired

Responses

204

Issuer deleted

application/jsonapplication/ld+json

400

Bad Request

*/*

delete

/v2/issuers/ref/{issuerOpenBadgeIdBase64}

HTTPcURLJavaScriptPython

DELETE /v2/issuers/ref/{issuerOpenBadgeIdBase64} HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "timestamp": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a single Issuer

patch

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

issuerOpenBadgeIdBase64stringRequired

Query parameters

include_staffstringOptionalDefault: true

Body

application/json

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

application/jsonapplication/ld+json

400

Bad Request

*/*

patch

/v2/issuers/ref/{issuerOpenBadgeIdBase64}

HTTPcURLJavaScriptPython

PATCH /v2/issuers/ref/{issuerOpenBadgeIdBase64} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get draft version

get

Authorizations

accessToken

HTTPRequired

Path parameters

idstringRequired

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/pathways/{id}/versions/draft

HTTPcURLJavaScriptPython

GET /v2/pathways/{id}/versions/draft HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "pathwayId": "66aa04adf5afe00d0a6dac72",
  "issuerId": "62aa04adf5afe00d0a6dac72",
  "draftStructureVersion": 1,
  "lastPublishedAt": "2026-01-02T21:30:37.535Z",
  "draftLastUpdatedAt": "2026-01-02T21:30:37.535Z",
  "creationDate": "2026-01-02T21:30:37.535Z",
  "hasThirdPartyBadges": true,
  "hasDraftChanges": true,
  "preferences": {
    "includeOnPublicPages": true
  },
  "root": {
    "elementId": "65aa04adf5afe00d0a6dac72",
    "name": "Math 101",
    "shortCode": "M101",
    "description": "Complete Math 101 course",
    "alignmentUrl": "www.example.com/skills/E1",
    "frameworkName": "OSMT",
    "targetCode": "E1",
    "completionBadge": "https://api.staging.badgr.dev/public/badges/ngurEbvbQiCAs5EkwEgIBw",
    "requirements": {
      "childElementRequirements": {
        "countRule": {
          "notRequiredCount": 1,
          "@type": "allButN"
        }
      },
      "nonChildElementRequirements": {
        "countRule": {
          "notRequiredCount": 1,
          "@type": "allButN"
        },
        "elementIds": [
          "text"
        ]
      },
      "badgeRequirements": {
        "requiredBadges": [
          {
            "badgeUrl": "https://api.badgr.io/public/badges/ngurE1vbQiCAs5EkwEgIBw",
            "displayOrder": 0
          }
        ]
      },
      "requiredCriteriaCount": 1,
      "courseRequirements": {
        "requiredCourses": [
          {
            "lms": "CANVAS",
            "domain": "canvas.instructure.com",
            "courseId": "123678",
            "name": "Math 101",
            "completionRequirement": {
              "doNotAwardBefore": "2026-01-02T21:30:37.535Z",
              "@type": "completed"
            },
            "displayOrder": 0,
            "url": "https://canvas.instructure.com/courses/123678"
          }
        ]
      },
      "experienceRequirements": {
        "requiredExperiences": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "name": "Conference",
            "description": "Attend Instructure Conference 2025",
            "displayOrder": 0
          }
        ]
      },
      "shortcutBadges": [
        "text"
      ],
      "allowCompletionBadgeShortcut": true
    },
    "requiredForParentCompletion": true,
    "children": []
  }
}

Update pathway draft

put

Authorizations

accessToken

HTTPRequired

Path parameters

idstringRequired

Body

application/json

issuerIdstringRequired

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

put

/v2/pathways/{id}/versions/draft

HTTPcURLJavaScriptPython

PUT /v2/pathways/{id}/versions/draft HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1216

{
  "issuerId": "text",
  "root": {
    "elementId": "65aa04adf5afe00d0a6dac72",
    "name": "Math 101",
    "shortCode": "M101",
    "description": "Complete Math 101 course",
    "alignmentUrl": "www.example.com/skills/E1",
    "frameworkName": "OSMT",
    "targetCode": "E1",
    "completionBadge": "https://api.staging.badgr.dev/public/badges/ngurEbvbQiCAs5EkwEgIBw",
    "requirements": {
      "childElementRequirements": {
        "countRule": {
          "notRequiredCount": 1,
          "@type": "allButN"
        }
      },
      "nonChildElementRequirements": {
        "countRule": {
          "notRequiredCount": 1,
          "@type": "allButN"
        },
        "elementIds": [
          "text"
        ]
      },
      "badgeRequirements": {
        "requiredBadges": [
          {
            "badgeUrl": "https://api.badgr.io/public/badges/ngurE1vbQiCAs5EkwEgIBw",
            "displayOrder": 0
          }
        ]
      },
      "requiredCriteriaCount": 1,
      "courseRequirements": {
        "requiredCourses": [
          {
            "lms": "CANVAS",
            "domain": "canvas.instructure.com",
            "courseId": "123678",
            "name": "Math 101",
            "completionRequirement": {
              "doNotAwardBefore": "2026-01-02T21:30:37.535Z",
              "@type": "completed"
            },
            "displayOrder": 0
          }
        ]
      },
      "experienceRequirements": {
        "requiredExperiences": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "name": "Conference",
            "description": "Attend Instructure Conference 2025",
            "displayOrder": 0
          }
        ]
      },
      "shortcutBadges": [
        "text"
      ],
      "allowCompletionBadgeShortcut": true
    },
    "requiredForParentCompletion": true,
    "children": []
  }
}

{
  "pathwayId": "66aa04adf5afe00d0a6dac72",
  "issuerId": "62aa04adf5afe00d0a6dac72",
  "draftStructureVersion": 1,
  "lastPublishedAt": "2026-01-02T21:30:37.535Z",
  "draftLastUpdatedAt": "2026-01-02T21:30:37.535Z",
  "creationDate": "2026-01-02T21:30:37.535Z",
  "hasThirdPartyBadges": true,
  "hasDraftChanges": true,
  "preferences": {
    "includeOnPublicPages": true
  },
  "root": {
    "elementId": "65aa04adf5afe00d0a6dac72",
    "name": "Math 101",
    "shortCode": "M101",
    "description": "Complete Math 101 course",
    "alignmentUrl": "www.example.com/skills/E1",
    "frameworkName": "OSMT",
    "targetCode": "E1",
    "completionBadge": "https://api.staging.badgr.dev/public/badges/ngurEbvbQiCAs5EkwEgIBw",
    "requirements": {
      "childElementRequirements": {
        "countRule": {
          "notRequiredCount": 1,
          "@type": "allButN"
        }
      },
      "nonChildElementRequirements": {
        "countRule": {
          "notRequiredCount": 1,
          "@type": "allButN"
        },
        "elementIds": [
          "text"
        ]
      },
      "badgeRequirements": {
        "requiredBadges": [
          {
            "badgeUrl": "https://api.badgr.io/public/badges/ngurE1vbQiCAs5EkwEgIBw",
            "displayOrder": 0
          }
        ]
      },
      "requiredCriteriaCount": 1,
      "courseRequirements": {
        "requiredCourses": [
          {
            "lms": "CANVAS",
            "domain": "canvas.instructure.com",
            "courseId": "123678",
            "name": "Math 101",
            "completionRequirement": {
              "doNotAwardBefore": "2026-01-02T21:30:37.535Z",
              "@type": "completed"
            },
            "displayOrder": 0,
            "url": "https://canvas.instructure.com/courses/123678"
          }
        ]
      },
      "experienceRequirements": {
        "requiredExperiences": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "name": "Conference",
            "description": "Attend Instructure Conference 2025",
            "displayOrder": 0
          }
        ]
      },
      "shortcutBadges": [
        "text"
      ],
      "allowCompletionBadgeShortcut": true
    },
    "requiredForParentCompletion": true,
    "children": []
  }
}

Get a single BadgeClass

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Query parameters

include_archivedbooleanOptionalDefault: false

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/badgeclasses/{idOrEntityId}

HTTPcURLJavaScriptPython

GET /v2/badgeclasses/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "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"
      },
      "imageAltText": "text"
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

application/json

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

imageAltTextstringOptional

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

put

/v2/badgeclasses/{idOrEntityId}

HTTPcURLJavaScriptPython

PUT /v2/badgeclasses/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 996

{
  "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"
  },
  "imageAltText": "text"
}

{
  "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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "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"
      },
      "imageAltText": "text"
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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.

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Query parameters

hard_deletestringOptional

archivalNotestringOptional

Responses

204

BadgeClass deleted

application/jsonapplication/ld+json

400

Bad Request

*/*

delete

/v2/badgeclasses/{idOrEntityId}

HTTPcURLJavaScriptPython

DELETE /v2/badgeclasses/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

claimCodestringRequired

Body

application/json

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

application/jsonapplication/ld+json

400

Bad Request

*/*

put

/v2/badgeclasses/{idOrEntityId}/claim-codes/{claimCode}

HTTPcURLJavaScriptPython

PUT /v2/badgeclasses/{idOrEntityId}/claim-codes/{claimCode} HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 83

{
  "label": "Conference Event",
  "limit": 10,
  "expirationDate": "2026-01-02T21:30:37.535Z"
}

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "code": "5678945",
      "createdAt": "2026-01-02T21:30:37.535Z",
      "label": "Conference Event",
      "limit": 10,
      "expirationDate": "2026-01-02T21:30:37.535Z",
      "enabled": true,
      "claimCount": 1,
      "claimUrl": "text"
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

claimCodestringRequired

Responses

204

No Content

application/jsonapplication/ld+json

400

Bad Request

*/*

delete

/v2/badgeclasses/{idOrEntityId}/claim-codes/{claimCode}

HTTPcURLJavaScriptPython

DELETE /v2/badgeclasses/{idOrEntityId}/claim-codes/{claimCode} HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "timestamp": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get a single BadgeClass

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

refstringRequired

Query parameters

include_archivedbooleanOptionalDefault: false

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/badgeclasses/ref/{ref}

HTTPcURLJavaScriptPython

GET /v2/badgeclasses/ref/{ref} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "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"
      },
      "imageAltText": "text"
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

refstringRequired

Body

application/json

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

imageAltTextstringOptional

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

put

/v2/badgeclasses/ref/{ref}

HTTPcURLJavaScriptPython

PUT /v2/badgeclasses/ref/{ref} HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 996

{
  "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"
  },
  "imageAltText": "text"
}

{
  "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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "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"
      },
      "imageAltText": "text"
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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.

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

refstringRequired

Query parameters

hard_deletestringOptional

archivalNotestringOptional

Responses

204

BadgeClass deleted

application/jsonapplication/ld+json

400

Bad Request

*/*

delete

/v2/badgeclasses/ref/{ref}

HTTPcURLJavaScriptPython

DELETE /v2/badgeclasses/ref/{ref} HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : List assertions in your backpack
• : Upload badges to your backpack

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Responses

200

OK

*/*

400

Bad Request

*/*

get

/v2/backpack/collections/{idOrEntityId}

HTTPcURLJavaScriptPython

GET /v2/backpack/collections/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update a Collection

put

Required scopes

This endpoint requires the following scopes:

• : Upload badges to your backpack

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

application/json

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

*/*

400

Bad Request

*/*

put

/v2/backpack/collections/{idOrEntityId}

HTTPcURLJavaScriptPython

PUT /v2/backpack/collections/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Delete a collection

delete

Required scopes

This endpoint requires the following scopes:

• : Upload badges to your backpack

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Responses

204

No Content

400

Bad Request

*/*

delete

/v2/backpack/collections/{idOrEntityId}

HTTPcURLJavaScriptPython

DELETE /v2/backpack/collections/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Get detail on an Assertion in the user's Backpack

get

Required scopes

This endpoint requires the following scopes:

• : List assertions in your backpack
• : Upload badges to your backpack

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Query parameters

Responses

200

OK

*/*

400

Bad Request

*/*

get

/v2/backpack/assertions/{idOrEntityId}

HTTPcURLJavaScriptPython

GET /v2/backpack/assertions/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
        "activityEnd": "2026-01-02T21:30:37.535Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Upload badges to your backpack

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Responses

200

OK

*/*

400

Bad Request

*/*

put

/v2/backpack/assertions/{idOrEntityId}

HTTPcURLJavaScriptPython

PUT /v2/backpack/assertions/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
        "activityEnd": "2026-01-02T21:30:37.535Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Upload badges to your backpack

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Responses

204

No Content

400

Bad Request

*/*

delete

/v2/backpack/assertions/{idOrEntityId}

HTTPcURLJavaScriptPython

DELETE /v2/backpack/assertions/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Get a single Assertion

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/assertions/{idOrEntityId}

HTTPcURLJavaScriptPython

GET /v2/assertions/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
        "activityEnd": "2026-01-02T21:30:37.535Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Update an Assertion

put

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

application/json

narrativestringOptional

Markdown narrative of the achievement

expiresstring · date-timeOptional

issuedOnstring · date-timeOptional

Timestamp when the assertion was issued

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

put

/v2/assertions/{idOrEntityId}

HTTPcURLJavaScriptPython

PUT /v2/assertions/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "issuedOn": "2026-01-02T21:30:37.535Z",
  "ob3AwardProperties": {
    "activityStart": "2026-01-02T21:30:37.535Z",
    "activityEnd": "2026-01-02T21:30:37.535Z",
    "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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
        "activityEnd": "2026-01-02T21:30:37.535Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Revoke an Assertion

delete

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

application/json

revocation_reasonstringOptional

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

delete

/v2/assertions/{idOrEntityId}

HTTPcURLJavaScriptPython

DELETE /v2/assertions/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
        "activityEnd": "2026-01-02T21:30:37.535Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

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

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/{scope}/{idOrEntityId}/assertions

HTTPcURLJavaScriptPython

GET /v2/{scope}/{idOrEntityId}/assertions HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
        "activityEnd": "2026-01-02T21:30:37.535Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

scopestring · enumRequiredPossible values:

idOrEntityIdstringRequired

The entity ID of the selected scope entity

Example: K829IK8RS6ercwkpeFOn-Q

Body

application/json

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

application/jsonapplication/ld+json

400

Bad Request

*/*

post

/v2/{scope}/{idOrEntityId}/assertions

HTTPcURLJavaScriptPython

POST /v2/{scope}/{idOrEntityId}/assertions HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "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": "2026-01-02T21:30:37.535Z",
  "ob3AwardProperties": {
    "activityStart": "2026-01-02T21:30:37.535Z",
    "activityEnd": "2026-01-02T21:30:37.535Z",
    "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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
        "activityEnd": "2026-01-02T21:30:37.535Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Create pathway in draft state

post

Authorizations

accessToken

HTTPRequired

Body

application/json

issuerIdstringRequired

ID of the issuer where the pathway will be created

Example: 62aa04adf5afe00d0a6dac72

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

post

/v2/pathways

HTTPcURLJavaScriptPython

POST /v2/pathways HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1285

{
  "issuerId": "62aa04adf5afe00d0a6dac72",
  "preferences": {
    "includeOnPublicPages": true
  },
  "draftRoot": {
    "elementId": "65aa04adf5afe00d0a6dac72",
    "name": "Math 101",
    "shortCode": "M101",
    "description": "Complete Math 101 course",
    "alignmentUrl": "www.example.com/skills/E1",
    "frameworkName": "OSMT",
    "targetCode": "E1",
    "completionBadge": "https://api.staging.badgr.dev/public/badges/ngurEbvbQiCAs5EkwEgIBw",
    "requirements": {
      "childElementRequirements": {
        "countRule": {
          "notRequiredCount": 1,
          "@type": "allButN"
        }
      },
      "nonChildElementRequirements": {
        "countRule": {
          "notRequiredCount": 1,
          "@type": "allButN"
        },
        "elementIds": [
          "text"
        ]
      },
      "badgeRequirements": {
        "requiredBadges": [
          {
            "badgeUrl": "https://api.badgr.io/public/badges/ngurE1vbQiCAs5EkwEgIBw",
            "displayOrder": 0
          }
        ]
      },
      "requiredCriteriaCount": 1,
      "courseRequirements": {
        "requiredCourses": [
          {
            "lms": "CANVAS",
            "domain": "canvas.instructure.com",
            "courseId": "123678",
            "name": "Math 101",
            "completionRequirement": {
              "doNotAwardBefore": "2026-01-02T21:30:37.535Z",
              "@type": "completed"
            },
            "displayOrder": 0
          }
        ]
      },
      "experienceRequirements": {
        "requiredExperiences": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "name": "Conference",
            "description": "Attend Instructure Conference 2025",
            "displayOrder": 0
          }
        ]
      },
      "shortcutBadges": [
        "text"
      ],
      "allowCompletionBadgeShortcut": true
    },
    "requiredForParentCompletion": true,
    "children": []
  }
}

{
  "pathwayId": "66aa04adf5afe00d0a6dac72",
  "issuerId": "62aa04adf5afe00d0a6dac72",
  "draftStructureVersion": 1,
  "lastPublishedAt": "2026-01-02T21:30:37.535Z",
  "draftLastUpdatedAt": "2026-01-02T21:30:37.535Z",
  "creationDate": "2026-01-02T21:30:37.535Z",
  "hasThirdPartyBadges": true,
  "hasDraftChanges": true,
  "preferences": {
    "includeOnPublicPages": true
  },
  "root": {
    "elementId": "65aa04adf5afe00d0a6dac72",
    "name": "Math 101",
    "shortCode": "M101",
    "description": "Complete Math 101 course",
    "alignmentUrl": "www.example.com/skills/E1",
    "frameworkName": "OSMT",
    "targetCode": "E1",
    "completionBadge": "https://api.staging.badgr.dev/public/badges/ngurEbvbQiCAs5EkwEgIBw",
    "requirements": {
      "childElementRequirements": {
        "countRule": {
          "notRequiredCount": 1,
          "@type": "allButN"
        }
      },
      "nonChildElementRequirements": {
        "countRule": {
          "notRequiredCount": 1,
          "@type": "allButN"
        },
        "elementIds": [
          "text"
        ]
      },
      "badgeRequirements": {
        "requiredBadges": [
          {
            "badgeUrl": "https://api.badgr.io/public/badges/ngurE1vbQiCAs5EkwEgIBw",
            "displayOrder": 0
          }
        ]
      },
      "requiredCriteriaCount": 1,
      "courseRequirements": {
        "requiredCourses": [
          {
            "lms": "CANVAS",
            "domain": "canvas.instructure.com",
            "courseId": "123678",
            "name": "Math 101",
            "completionRequirement": {
              "doNotAwardBefore": "2026-01-02T21:30:37.535Z",
              "@type": "completed"
            },
            "displayOrder": 0,
            "url": "https://canvas.instructure.com/courses/123678"
          }
        ]
      },
      "experienceRequirements": {
        "requiredExperiences": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "name": "Conference",
            "description": "Attend Instructure Conference 2025",
            "displayOrder": 0
          }
        ]
      },
      "shortcutBadges": [
        "text"
      ],
      "allowCompletionBadgeShortcut": true
    },
    "requiredForParentCompletion": true,
    "children": []
  }
}

Evaluate experience on the pathway for a user

post

Authorizations

accessToken

HTTPRequired

Path parameters

pathwayIdstringRequired

experienceIdstring · uuidRequired

Body

application/json

recipientone ofRequired

or

or

passedbooleanRequired

Responses

204

No Content

400

Bad Request

*/*

post

/v2/pathways/{pathwayId}/experience/{experienceId}/submit

HTTPcURLJavaScriptPython

POST /v2/pathways/{pathwayId}/experience/{experienceId}/submit HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 72

{
  "recipient": {
    "email": "[email protected]",
    "@type": "email"
  },
  "passed": true
}

No content

Evaluate experience on the pathway for multiple users

post

CSV file should contain recipientId,passed header row. Each row should contain a single entry of recipientId (email:[email protected]) and a passed value (true/false) separated by a comma.

Authorizations

accessToken

HTTPRequired

Path parameters

pathwayIdstringRequired

experienceIdstring · uuidRequired

Body

text/csv

stringOptionalExample: recipientId,passed email:[email protected],true

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

post

/v2/pathways/{pathwayId}/experience/{experienceId}/submit-csv

HTTPcURLJavaScriptPython

POST /v2/pathways/{pathwayId}/experience/{experienceId}/submit-csv HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: text/csv
Accept: */*
Content-Length: 51

"recipientId,passed\nemail:[email protected],true\n"

{
  "errors": [
    {
      "recipientId": {
        "email": "[email protected]",
        "@type": "email"
      },
      "error": "NOT_SUBSCRIBED"
    }
  ],
  "successes": [
    {
      "email": "[email protected]",
      "@type": "email"
    }
  ]
}

Get published version

get

Authorizations

accessToken

HTTPRequired

Path parameters

idstringRequired

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/pathways/{id}/versions/published

HTTPcURLJavaScriptPython

GET /v2/pathways/{id}/versions/published HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "pathwayId": "66aa04adf5afe00d0a6dac72",
  "issuerId": "62aa04adf5afe00d0a6dac72",
  "draftStructureVersion": 1,
  "lastPublishedAt": "2026-01-02T21:30:37.535Z",
  "draftLastUpdatedAt": "2026-01-02T21:30:37.535Z",
  "creationDate": "2026-01-02T21:30:37.535Z",
  "hasThirdPartyBadges": true,
  "hasDraftChanges": true,
  "preferences": {
    "includeOnPublicPages": true
  },
  "root": {
    "elementId": "65aa04adf5afe00d0a6dac72",
    "name": "Math 101",
    "shortCode": "M101",
    "description": "Complete Math 101 course",
    "alignmentUrl": "www.example.com/skills/E1",
    "frameworkName": "OSMT",
    "targetCode": "E1",
    "completionBadge": "https://api.staging.badgr.dev/public/badges/ngurEbvbQiCAs5EkwEgIBw",
    "requirements": {
      "childElementRequirements": {
        "countRule": {
          "notRequiredCount": 1,
          "@type": "allButN"
        }
      },
      "nonChildElementRequirements": {
        "countRule": {
          "notRequiredCount": 1,
          "@type": "allButN"
        },
        "elementIds": [
          "text"
        ]
      },
      "badgeRequirements": {
        "requiredBadges": [
          {
            "badgeUrl": "https://api.badgr.io/public/badges/ngurE1vbQiCAs5EkwEgIBw",
            "displayOrder": 0
          }
        ]
      },
      "requiredCriteriaCount": 1,
      "courseRequirements": {
        "requiredCourses": [
          {
            "lms": "CANVAS",
            "domain": "canvas.instructure.com",
            "courseId": "123678",
            "name": "Math 101",
            "completionRequirement": {
              "doNotAwardBefore": "2026-01-02T21:30:37.535Z",
              "@type": "completed"
            },
            "displayOrder": 0,
            "url": "https://canvas.instructure.com/courses/123678"
          }
        ]
      },
      "experienceRequirements": {
        "requiredExperiences": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "name": "Conference",
            "description": "Attend Instructure Conference 2025",
            "displayOrder": 0
          }
        ]
      },
      "shortcutBadges": [
        "text"
      ],
      "allowCompletionBadgeShortcut": true
    },
    "requiredForParentCompletion": true,
    "children": []
  }
}

Promote current draft version to published

post

Authorizations

accessToken

HTTPRequired

Path parameters

idstringRequired

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

post

/v2/pathways/{id}/versions/published

HTTPcURLJavaScriptPython

POST /v2/pathways/{id}/versions/published HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "pathwayId": "66aa04adf5afe00d0a6dac72",
  "issuerId": "62aa04adf5afe00d0a6dac72",
  "draftStructureVersion": 1,
  "lastPublishedAt": "2026-01-02T21:30:37.535Z",
  "draftLastUpdatedAt": "2026-01-02T21:30:37.535Z",
  "creationDate": "2026-01-02T21:30:37.535Z",
  "hasThirdPartyBadges": true,
  "hasDraftChanges": true,
  "preferences": {
    "includeOnPublicPages": true
  },
  "root": {
    "elementId": "65aa04adf5afe00d0a6dac72",
    "name": "Math 101",
    "shortCode": "M101",
    "description": "Complete Math 101 course",
    "alignmentUrl": "www.example.com/skills/E1",
    "frameworkName": "OSMT",
    "targetCode": "E1",
    "completionBadge": "https://api.staging.badgr.dev/public/badges/ngurEbvbQiCAs5EkwEgIBw",
    "requirements": {
      "childElementRequirements": {
        "countRule": {
          "notRequiredCount": 1,
          "@type": "allButN"
        }
      },
      "nonChildElementRequirements": {
        "countRule": {
          "notRequiredCount": 1,
          "@type": "allButN"
        },
        "elementIds": [
          "text"
        ]
      },
      "badgeRequirements": {
        "requiredBadges": [
          {
            "badgeUrl": "https://api.badgr.io/public/badges/ngurE1vbQiCAs5EkwEgIBw",
            "displayOrder": 0
          }
        ]
      },
      "requiredCriteriaCount": 1,
      "courseRequirements": {
        "requiredCourses": [
          {
            "lms": "CANVAS",
            "domain": "canvas.instructure.com",
            "courseId": "123678",
            "name": "Math 101",
            "completionRequirement": {
              "doNotAwardBefore": "2026-01-02T21:30:37.535Z",
              "@type": "completed"
            },
            "displayOrder": 0,
            "url": "https://canvas.instructure.com/courses/123678"
          }
        ]
      },
      "experienceRequirements": {
        "requiredExperiences": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "name": "Conference",
            "description": "Attend Instructure Conference 2025",
            "displayOrder": 0
          }
        ]
      },
      "shortcutBadges": [
        "text"
      ],
      "allowCompletionBadgeShortcut": true
    },
    "requiredForParentCompletion": true,
    "children": []
  }
}

Reverts pathway draft to the current published version

post

Authorizations

accessToken

HTTPRequired

Path parameters

idstringRequired

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

post

/v2/pathways/{id}/versions/draft/revert

HTTPcURLJavaScriptPython

POST /v2/pathways/{id}/versions/draft/revert HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "pathwayId": "66aa04adf5afe00d0a6dac72",
  "issuerId": "62aa04adf5afe00d0a6dac72",
  "draftStructureVersion": 1,
  "lastPublishedAt": "2026-01-02T21:30:37.535Z",
  "draftLastUpdatedAt": "2026-01-02T21:30:37.535Z",
  "creationDate": "2026-01-02T21:30:37.535Z",
  "hasThirdPartyBadges": true,
  "hasDraftChanges": true,
  "preferences": {
    "includeOnPublicPages": true
  },
  "root": {
    "elementId": "65aa04adf5afe00d0a6dac72",
    "name": "Math 101",
    "shortCode": "M101",
    "description": "Complete Math 101 course",
    "alignmentUrl": "www.example.com/skills/E1",
    "frameworkName": "OSMT",
    "targetCode": "E1",
    "completionBadge": "https://api.staging.badgr.dev/public/badges/ngurEbvbQiCAs5EkwEgIBw",
    "requirements": {
      "childElementRequirements": {
        "countRule": {
          "notRequiredCount": 1,
          "@type": "allButN"
        }
      },
      "nonChildElementRequirements": {
        "countRule": {
          "notRequiredCount": 1,
          "@type": "allButN"
        },
        "elementIds": [
          "text"
        ]
      },
      "badgeRequirements": {
        "requiredBadges": [
          {
            "badgeUrl": "https://api.badgr.io/public/badges/ngurE1vbQiCAs5EkwEgIBw",
            "displayOrder": 0
          }
        ]
      },
      "requiredCriteriaCount": 1,
      "courseRequirements": {
        "requiredCourses": [
          {
            "lms": "CANVAS",
            "domain": "canvas.instructure.com",
            "courseId": "123678",
            "name": "Math 101",
            "completionRequirement": {
              "doNotAwardBefore": "2026-01-02T21:30:37.535Z",
              "@type": "completed"
            },
            "displayOrder": 0,
            "url": "https://canvas.instructure.com/courses/123678"
          }
        ]
      },
      "experienceRequirements": {
        "requiredExperiences": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "name": "Conference",
            "description": "Attend Instructure Conference 2025",
            "displayOrder": 0
          }
        ]
      },
      "shortcutBadges": [
        "text"
      ],
      "allowCompletionBadgeShortcut": true
    },
    "requiredForParentCompletion": true,
    "children": []
  }
}

Update pathway group subscriptions

post

Authorizations

accessToken

HTTPRequired

Path parameters

idstringRequired

Body

application/json

groupIdsToAddstring[]RequiredExample: 61aa04adf5afe00d0a6dac72

groupIdsToRemovestring[]RequiredExample: 67aa04adf5afe00d0a6dac72

Responses

200

OK

No content

400

Bad Request

*/*

post

/v2/pathways/{id}/subscriptions

HTTPcURLJavaScriptPython

POST /v2/pathways/{id}/subscriptions HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 94

{
  "groupIdsToAdd": [
    "61aa04adf5afe00d0a6dac72"
  ],
  "groupIdsToRemove": [
    "67aa04adf5afe00d0a6dac72"
  ]
}

No content

Get a list of Issuers for authenticated user

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Query parameters

include_staffstringOptionalDefault: true

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/issuers

HTTPcURLJavaScriptPython

GET /v2/issuers HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Create a new Issuer

post

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Query parameters

include_staffstringOptionalDefault: true

Body

application/json

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

application/jsonapplication/ld+json

400

Bad Request

*/*

post

/v2/issuers

HTTPcURLJavaScriptPython

POST /v2/issuers HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
  "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.

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

application/json

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

*/*

400

Bad Request

*/*

post

/v2/issuers/{idOrEntityId}/staff/invitations

HTTPcURLJavaScriptPython

POST /v2/issuers/{idOrEntityId}/staff/invitations HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Query parameters

include_archivedbooleanOptionalDefault: false

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/issuers/{idOrEntityId}/badgeclasses

HTTPcURLJavaScriptPython

GET /v2/issuers/{idOrEntityId}/badgeclasses HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "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"
      },
      "imageAltText": "text"
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

application/json

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

imageAltTextstringOptional

Responses

201

Created

application/jsonapplication/ld+json

400

Bad Request

*/*

post

/v2/issuers/{idOrEntityId}/badgeclasses

HTTPcURLJavaScriptPython

POST /v2/issuers/{idOrEntityId}/badgeclasses HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1032

{
  "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"
  },
  "imageAltText": "text"
}

{
  "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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "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"
      },
      "imageAltText": "text"
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Query parameters

include_archivedbooleanOptionalDefault: false

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/badgeclasses

HTTPcURLJavaScriptPython

GET /v2/badgeclasses HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "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"
      },
      "imageAltText": "text"
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Create a new BadgeClass

post

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Body

application/json

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

imageAltTextstringOptional

Responses

201

BadgeClass created

application/jsonapplication/ld+json

400

Bad Request

*/*

post

/v2/badgeclasses

HTTPcURLJavaScriptPython

POST /v2/badgeclasses HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 997

{
  "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"
  },
  "imageAltText": "text"
}

{
  "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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "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"
      },
      "imageAltText": "text"
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

application/json

newNamestringRequired

The new name for the duplicate badgeclass

Example: Badgeclass Copy

Responses

201

BadgeClass created

application/jsonapplication/ld+json

400

Bad Request

*/*

post

/v2/badgeclasses/{idOrEntityId}/duplicate

HTTPcURLJavaScriptPython

POST /v2/badgeclasses/{idOrEntityId}/duplicate HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "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": "2026-01-02T21:30:37.535Z",
  "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"
  },
  "imageAltText": "text"
}

Get a list of ClaimCodes for a single BadgeClass

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Query parameters

includeClaimCodeCountbooleanOptional

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/badgeclasses/{idOrEntityId}/claim-codes

HTTPcURLJavaScriptPython

GET /v2/badgeclasses/{idOrEntityId}/claim-codes HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "code": "5678945",
      "createdAt": "2026-01-02T21:30:37.535Z",
      "label": "Conference Event",
      "limit": 10,
      "expirationDate": "2026-01-02T21:30:37.535Z",
      "enabled": true,
      "claimCount": 1,
      "claimUrl": "text"
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

application/json

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

application/jsonapplication/ld+json

400

Bad Request

*/*

post

/v2/badgeclasses/{idOrEntityId}/claim-codes

HTTPcURLJavaScriptPython

POST /v2/badgeclasses/{idOrEntityId}/claim-codes HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 83

{
  "label": "Conference Event",
  "limit": 10,
  "expirationDate": "2026-01-02T21:30:37.535Z"
}

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "code": "5678945",
      "createdAt": "2026-01-02T21:30:37.535Z",
      "label": "Conference Event",
      "limit": 10,
      "expirationDate": "2026-01-02T21:30:37.535Z",
      "enabled": true,
      "claimCount": 1,
      "claimUrl": "text"
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

post

/v2/badgeclasses/reactivate/{idOrEntityId}

HTTPcURLJavaScriptPython

POST /v2/badgeclasses/reactivate/{idOrEntityId} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "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"
      },
      "imageAltText": "text"
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

refstringRequired

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

post

/v2/badgeclasses/reactivate/ref/{ref}

HTTPcURLJavaScriptPython

POST /v2/badgeclasses/reactivate/ref/{ref} HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "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"
      },
      "imageAltText": "text"
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Upload badges to your backpack

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Body

application/json

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

*/*

400

Bad Request

*/*

post

/v2/backpack/import

HTTPcURLJavaScriptPython

POST /v2/backpack/import HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
        "activityEnd": "2026-01-02T21:30:37.535Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : List assertions in your backpack
• : Upload badges to your backpack

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Responses

200

OK

*/*

400

Bad Request

*/*

get

/v2/backpack/collections

HTTPcURLJavaScriptPython

GET /v2/backpack/collections HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Create a new Collection

post

Required scopes

This endpoint requires the following scopes:

• : Upload badges to your backpack

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Body

application/json

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

*/*

400

Bad Request

*/*

post

/v2/backpack/collections

HTTPcURLJavaScriptPython

POST /v2/backpack/collections HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Revoke multiple Assertions

post

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Bodyobject[]

application/json

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

application/jsonapplication/ld+json

400

Bad Request

*/*

post

/v2/assertions/revoke

HTTPcURLJavaScriptPython

POST /v2/assertions/revoke HTTP/1.1
Host: api.badges.parchment.com
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

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

claimCodestringRequired

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

patch

/v2/badgeclasses/{idOrEntityId}/claim-codes/{claimCode}/enable

HTTPcURLJavaScriptPython

PATCH /v2/badgeclasses/{idOrEntityId}/claim-codes/{claimCode}/enable HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "code": "5678945",
      "createdAt": "2026-01-02T21:30:37.535Z",
      "label": "Conference Event",
      "limit": 10,
      "expirationDate": "2026-01-02T21:30:37.535Z",
      "enabled": true,
      "claimCount": 1,
      "claimUrl": "text"
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "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

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

claimCodestringRequired

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

patch

/v2/badgeclasses/{idOrEntityId}/claim-codes/{claimCode}/disable

HTTPcURLJavaScriptPython

PATCH /v2/badgeclasses/{idOrEntityId}/claim-codes/{claimCode}/disable HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "result": [
    {
      "code": "5678945",
      "createdAt": "2026-01-02T21:30:37.535Z",
      "label": "Conference Event",
      "limit": 10,
      "expirationDate": "2026-01-02T21:30:37.535Z",
      "enabled": true,
      "claimCount": 1,
      "claimUrl": "text"
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Get progress status for the recipient

get

Authorizations

accessToken

HTTPRequired

Path parameters

idstringRequired

Query parameters

recipientIdentifierstringRequired

Identifier of the recipient, format: recipientType:recipientId

Example: email:[email protected]

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/pathways/{id}/recipient-progress

HTTPcURLJavaScriptPython

GET /v2/pathways/{id}/recipient-progress?recipientIdentifier=text HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "61aa04adf5afe00d0a6dac72",
  "scope": {
    "identifier": {
      "email": "[email protected]",
      "@type": "email"
    },
    "@type": "recipient"
  },
  "pathwayId": "66aa04adf5afe00d0a6dac72",
  "calculationInfo": {
    "staleBeforeVersion": 1,
    "stale": true,
    "computedVersion": 1,
    "computedDate": "2026-01-02T21:30:37.535Z",
    "computedPublishedStructureVersion": 1
  },
  "progress": {
    "endProgress": {
      "status": "COMPLETED",
      "required": 10,
      "completed": 4,
      "failed": 1,
      "inProgress": 3,
      "notStarted": 2
    },
    "elementProgress": {
      "ANY_ADDITIONAL_PROPERTY": {
        "status": "COMPLETED",
        "cappedProgress": {
          "required": 5,
          "completed": 1,
          "inProgress": 1,
          "failed": 2,
          "preRequisiteStepFailed": 1,
          "directRequirementFailed": 1,
          "notStarted": 1
        },
        "completionBadgeNewlyAwarded": true,
        "completedByShortcut": true,
        "badgeProgress": {
          "earnedBadges": [
            "https://api.staging.badgr.dev/public/badges/2Lkni4uvRjGqlz8zCg_5uA"
          ],
          "maxBadgeCount": 1
        },
        "courseProgress": {
          "earnedCriteria": [
            {
              "lms": "CANVAS",
              "domain": "text",
              "courseId": "text",
              "completionRequirement": {
                "doNotAwardBefore": "2026-01-02T21:30:37.535Z",
                "@type": "completed"
              },
              "evaluatedAt": "2026-01-02T21:30:37.535Z"
            }
          ]
        },
        "experienceProgress": {
          "evaluations": [
            {
              "experienceId": "123e4567-e89b-12d3-a456-426614174000",
              "passed": true,
              "lastEvaluatedAt": "2026-01-02T21:30:37.535Z"
            }
          ]
        }
      }
    }
  }
}

Get progress status for the recipient group

get

Authorizations

accessToken

HTTPRequired

Path parameters

idstringRequired

recipientGroupIdstringRequired

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/pathways/{id}/recipient-groups/{recipientGroupId}/progress

HTTPcURLJavaScriptPython

GET /v2/pathways/{id}/recipient-groups/{recipientGroupId}/progress HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "61aa04adf5afe00d0a6dac72",
  "scope": {
    "recipientGroupId": "text",
    "@type": "groupAggregate"
  },
  "pathwayId": "66aa04adf5afe00d0a6dac72",
  "calculationInfo": {
    "staleBeforeVersion": 1,
    "stale": true,
    "computedVersion": 1,
    "computedDate": "2026-01-02T21:30:37.535Z",
    "computedPublishedStructureVersion": 1
  },
  "progressAggregate": {
    "elementProgress": {
      "ANY_ADDITIONAL_PROPERTY": {
        "overallProgress": {
          "progress": {
            "completedValue": 1,
            "requiredValue": 2,
            "failedValue": 1,
            "maxValue": 1
          },
          "notStartedCount": 1,
          "inProgressCount": 1,
          "failedCount": 1,
          "completedCount": 1
        },
        "experienceProgress": {
          "experienceIdsWithFailedRecipients": [
            "123e4567-e89b-12d3-a456-426614174000"
          ],
          "experienceIdsWithNotEvaluatedRecipients": [
            "123e4567-e89b-12d3-a456-426614174000"
          ]
        },
        "courseProgress": {
          "byRequirements": [
            {
              "requirementId": {
                "lms": "CANVAS",
                "domain": "text",
                "courseId": "text",
                "completionRequirement": {
                  "doNotAwardBefore": "2026-01-02T21:30:37.535Z",
                  "@type": "completed"
                }
              },
              "completed": 5
            }
          ]
        }
      }
    }
  }
}

Get aggregate progress status for the entire pathway

get

Authorizations

accessToken

HTTPRequired

Path parameters

idstringRequired

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/pathways/{id}/aggregate-progress

HTTPcURLJavaScriptPython

GET /v2/pathways/{id}/aggregate-progress HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "61aa04adf5afe00d0a6dac72",
  "pathwayId": "66aa04adf5afe00d0a6dac72",
  "calculationInfo": {
    "staleBeforeVersion": 1,
    "stale": true,
    "computedVersion": 1,
    "computedDate": "2026-01-02T21:30:37.535Z",
    "computedPublishedStructureVersion": 1
  },
  "progressAggregate": {
    "elementProgress": {
      "ANY_ADDITIONAL_PROPERTY": {
        "overallProgress": {
          "progress": {
            "completedValue": 1,
            "requiredValue": 2,
            "failedValue": 1,
            "maxValue": 1
          },
          "notStartedCount": 1,
          "inProgressCount": 1,
          "failedCount": 1,
          "completedCount": 1
        },
        "experienceProgress": {
          "experienceIdsWithFailedRecipients": [
            "123e4567-e89b-12d3-a456-426614174000"
          ],
          "experienceIdsWithNotEvaluatedRecipients": [
            "123e4567-e89b-12d3-a456-426614174000"
          ]
        },
        "courseProgress": {
          "byRequirements": [
            {
              "requirementId": {
                "lms": "CANVAS",
                "domain": "text",
                "courseId": "text",
                "completionRequirement": {
                  "doNotAwardBefore": "2026-01-02T21:30:37.535Z",
                  "@type": "completed"
                }
              },
              "completed": 5
            }
          ]
        }
      }
    }
  }
}

Get a list of Organizations where the authenticated user is admin

get

Required scopes

This endpoint requires the following scopes:

• : Read organization data

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Responses

200

OK

application/jsonapplication/ld+json

400

Bad Request

*/*

get

/v2/organizations

HTTPcURLJavaScriptPython

GET /v2/organizations HTTP/1.1
Host: api.badges.parchment.com
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

Required scopes

This endpoint requires the following scopes:

• : List assertions in your backpack
• : Upload badges to your backpack

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Query parameters

Responses

200

OK

*/*

400

Bad Request

*/*

get

/v2/backpack/assertions

HTTPcURLJavaScriptPython

GET /v2/backpack/assertions HTTP/1.1
Host: api.badges.parchment.com
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": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
      "narrative": "text",
      "evidence": [
        {
          "url": "https://example.com",
          "narrative": "text",
          "name": "text",
          "description": "text",
          "genre": "text",
          "audience": "text"
        }
      ],
      "revoked": true,
      "revocationReason": "text",
      "acceptance": "Unaccepted",
      "expires": "2026-01-02T21:30:37.535Z",
      "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": "2026-01-02T21:30:37.535Z",
        "activityEnd": "2026-01-02T21:30:37.535Z",
        "licenseNumber": "text",
        "role": "text"
      }
    }
  ],
  "timestamp": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}

Delete pathway

delete

Authorizations

accessToken

HTTPRequired

Path parameters

idstringRequired

Responses

204

Pathway deleted

400

Bad Request

*/*

delete

/v2/pathways/{id}

HTTPcURLJavaScriptPython

DELETE /v2/pathways/{id} HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Remove a staff member from the Issuer

delete

User must have an owner role on the issuer.

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

oauthaccessToken

OAuth2authorizationCodeRequired

OAuth2 authorizationCode flow is currently not functional on the Swagger UI.

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

emailBase64stringRequired

Base64 encoded email address of the staff member

Responses

204

Staff member removed

*/*

400

Bad Request

*/*

delete

/v2/issuers/{idOrEntityId}/staff/{emailBase64}

HTTPcURLJavaScriptPython

DELETE /v2/issuers/{idOrEntityId}/staff/{emailBase64} HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "status": {
    "success": true,
    "description": "ok"
  },
  "timestamp": "2026-01-02T21:30:37.535Z",
  "validationErrors": [
    "text"
  ],
  "nonFieldErrors": [
    "text"
  ],
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "errorCode": "text",
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1
}