APIs

Get assertions for the authenticated user

get

Returns a paginated list of OB 2.1 assertions for the authenticated badge recipient

Required scopes

This endpoint requires the following scopes:

• : List assertions in your backpack

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Query parameters

limitinteger · int32Optional

offsetinteger · int32Optional

sincestring · date-timeOptional

Responses

200

Assertions retrieved successfully

application/ld+json

400

Bad Request

*/*

401

Unauthorized

application/ld+json

404

User not found

application/ld+json

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/bcv1/assertions

GET /bcv1/assertions HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "assertions": [
    {
      "@context": "text",
      "badge": "https://example.com/badges/1",
      "evidence": [
        "text"
      ],
      "expires": "2026-01-01T00:00:00.000Z",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "id": "text",
      "image": {
        "caption": "text",
        "id": "text"
      },
      "issuedOn": "2026-01-01T00:00:00.000Z",
      "narrative": "text",
      "recipient": {
        "hashed": true,
        "identity": "text",
        "salt": "text",
        "type": "text"
      },
      "revocationReason": "text",
      "revoked": true,
      "type": "text",
      "verification": {
        "allowedOrigins": [
          "text"
        ],
        "creator": "text",
        "startsWith": "text",
        "type": "HostedBadge",
        "url": "text",
        "verificationProperty": "text"
      }
    }
  ],
  "status": {
    "error": "text",
    "statusCode": 1,
    "statusText": "text"
  }
}

Import an assertion

post

Import an OB 2.1 assertion by URL into the authenticated user's backpack

Required scopes

This endpoint requires the following scopes:

• : Upload badges to your backpack

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Body

stringOptional

Responses

200

Assertion imported successfully

application/ld+json

400

Invalid request or failed to import

application/ld+json

401

Unauthorized

application/ld+json

404

User not found

application/ld+json

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post/bcv1/assertions

POST /bcv1/assertions HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 6

"text"

{
  "status": {
    "error": "text",
    "statusCode": 1,
    "statusText": "text"
  }
}

Get assertions for the authenticated user

get

Returns a paginated list of OB 2.1 assertions for the authenticated badge recipient

Required scopes

This endpoint requires the following scopes:

• : List assertions in your backpack

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Query parameters

limitinteger · int32Optional

offsetinteger · int32Optional

sincestring · date-timeOptional

Responses

200

Assertions retrieved successfully

application/ld+json

400

Bad Request

*/*

401

Unauthorized

application/ld+json

404

User not found

application/ld+json

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/bcv1/ims/ob/v2p1/assertions

GET /bcv1/ims/ob/v2p1/assertions HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "assertions": [
    {
      "@context": "text",
      "badge": "https://example.com/badges/1",
      "evidence": [
        "text"
      ],
      "expires": "2026-01-01T00:00:00.000Z",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "id": "text",
      "image": {
        "caption": "text",
        "id": "text"
      },
      "issuedOn": "2026-01-01T00:00:00.000Z",
      "narrative": "text",
      "recipient": {
        "hashed": true,
        "identity": "text",
        "salt": "text",
        "type": "text"
      },
      "revocationReason": "text",
      "revoked": true,
      "type": "text",
      "verification": {
        "allowedOrigins": [
          "text"
        ],
        "creator": "text",
        "startsWith": "text",
        "type": "HostedBadge",
        "url": "text",
        "verificationProperty": "text"
      }
    }
  ],
  "status": {
    "error": "text",
    "statusCode": 1,
    "statusText": "text"
  }
}

Import an assertion

post

Import an OB 2.1 assertion by URL into the authenticated user's backpack

Required scopes

This endpoint requires the following scopes:

• : Upload badges to your backpack

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Body

stringOptional

Responses

200

Assertion imported successfully

application/ld+json

400

Invalid request or failed to import

application/ld+json

401

Unauthorized

application/ld+json

404

User not found

application/ld+json

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post/bcv1/ims/ob/v2p1/assertions

POST /bcv1/ims/ob/v2p1/assertions HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 6

"text"

{
  "status": {
    "error": "text",
    "statusCode": 1,
    "statusText": "text"
  }
}

Get the authenticated user's profile

get

Returns the OB 2.1 profile of the authenticated badge recipient

Required scopes

This endpoint requires the following scopes:

• : See who you are

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Responses

200

Profile retrieved successfully

application/ld+json

400

Bad Request

*/*

401

Unauthorized

application/ld+json

404

User not found

application/ld+json

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/bcv1/ims/ob/v2p1/profile

GET /bcv1/ims/ob/v2p1/profile HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "profile": {
    "@context": "text",
    "email": "text",
    "id": "text",
    "name": "text",
    "telephone": "text",
    "type": "text",
    "url": "text"
  },
  "status": {
    "error": "text",
    "statusCode": 1,
    "statusText": "text"
  }
}

Get the Badge Connect manifest for a domain

get

Returns the Badge Connect service discovery manifest for the specified domain

Authorizations

HTTPRequired

Path parameters

domainstringRequired

Responses

200

Manifest retrieved successfully

application/ld+json

@contextstringRequired

idstringRequired

400

Bad Request

*/*

404

Domain not found

application/ld+json

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/bcv1/manifest/{domain}

GET /bcv1/manifest/{domain} HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "@context": "text",
  "badgeConnectAPI": [
    {
      "apiBase": "text",
      "authorizationUrl": "text",
      "image": "text",
      "name": "text",
      "privacyPolicyUrl": "text",
      "registrationUrl": "text",
      "scopesOffered": [
        "text"
      ],
      "termsOfServiceUrl": "text",
      "tokenUrl": "text",
      "version": "text"
    }
  ],
  "id": "text"
}

Get the authenticated user's profile

get

Returns the OB 2.1 profile of the authenticated badge recipient

Required scopes

This endpoint requires the following scopes:

• : See who you are

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Responses

200

Profile retrieved successfully

application/ld+json

400

Bad Request

*/*

401

Unauthorized

application/ld+json

404

User not found

application/ld+json

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/bcv1/profile

GET /bcv1/profile HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "profile": {
    "@context": "text",
    "email": "text",
    "id": "text",
    "name": "text",
    "telephone": "text",
    "type": "text",
    "url": "text"
  },
  "status": {
    "error": "text",
    "statusCode": 1,
    "statusText": "text"
  }
}

Get OB 2.1 assertions via OB 3.0 path

get

Forwards to the Badge Connect v1 assertions endpoint for backward compatibility

Required scopes

This endpoint requires the following scopes:

• : List assertions in your backpack

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Responses

200

Assertions retrieved successfully. Response format is the same as the OB 2.1 GET /assertions endpoint.

application/ld+json

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/ims/ob/v3p0/assertions

GET /ims/ob/v3p0/assertions HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "assertions": [
    {
      "@context": "text",
      "badge": "https://example.com/badges/1",
      "evidence": [
        "text"
      ],
      "expires": "2026-01-01T00:00:00.000Z",
      "extensions": {
        "ANY_ADDITIONAL_PROPERTY": {}
      },
      "id": "text",
      "image": {
        "caption": "text",
        "id": "text"
      },
      "issuedOn": "2026-01-01T00:00:00.000Z",
      "narrative": "text",
      "recipient": {
        "hashed": true,
        "identity": "text",
        "salt": "text",
        "type": "text"
      },
      "revocationReason": "text",
      "revoked": true,
      "type": "text",
      "verification": {
        "allowedOrigins": [
          "text"
        ],
        "creator": "text",
        "startsWith": "text",
        "type": "HostedBadge",
        "url": "text",
        "verificationProperty": "text"
      }
    }
  ],
  "status": {
    "error": "text",
    "statusCode": 1,
    "statusText": "text"
  }
}

Get verifiable credentials for the authenticated user

get

Returns a paginated list of signed OB 3.0 verifiable credentials for the authenticated badge recipient

Required scopes

This endpoint requires the following scopes:

• : List assertions in your backpack

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Query parameters

limitinteger · int32OptionalDefault: 20

offsetinteger · int32OptionalDefault: 0

sincestring · date-timeOptional

Responses

200

Credentials retrieved successfully

*/*

400

Invalid request parameters

*/*

401

Unauthorized

*/*

403

Access denied

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/ims/ob/v3p0/credentials

GET /ims/ob/v3p0/credentials HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "credential": [
    {
      "@context": [
        "text"
      ],
      "credentialSchema": [
        {
          "id": "text",
          "type": "text"
        }
      ],
      "credentialStatus": {
        "id": "text",
        "statusListCredential": "text",
        "statusListIndex": "text",
        "statusPurpose": "text",
        "type": "text"
      },
      "credentialSubject": {
        "achievement": {
          "achievementType": "Achievement",
          "alignment": [
            {
              "targetCode": "text",
              "targetDescription": "text",
              "targetFramework": "text",
              "targetName": "text",
              "targetType": "ceasn:Competency",
              "targetUrl": "text",
              "type": [
                "text"
              ]
            }
          ],
          "creditsAvailable": 1,
          "criteria": {
            "id": "text",
            "narrative": "text"
          },
          "description": "text",
          "fieldOfStudy": "text",
          "humanCode": "text",
          "id": "text",
          "image": {
            "caption": "text",
            "id": "text"
          },
          "name": "text",
          "specialization": "text",
          "type": [
            "text"
          ]
        },
        "activityEndDate": "2026-01-01T00:00:00.000Z",
        "activityStartDate": "2026-01-01T00:00:00.000Z",
        "id": "text",
        "identifier": [
          {
            "hashed": true,
            "identityHash": "text",
            "identityType": "emailAddress",
            "salt": "text",
            "type": "text"
          }
        ],
        "licenseNumber": "text",
        "narrative": "text",
        "role": "text",
        "type": [
          "text"
        ]
      },
      "description": "text",
      "evidence": [
        {
          "audience": "text",
          "description": "text",
          "genre": "text",
          "id": "text",
          "name": "text",
          "narrative": "text"
        }
      ],
      "id": "text",
      "image": {
        "caption": "text",
        "id": "text"
      },
      "issuer": {
        "description": "text",
        "email": "text",
        "id": "text",
        "name": "text",
        "type": [
          "text"
        ],
        "url": "text"
      },
      "name": "text",
      "proof": [
        {
          "@context": [
            "text"
          ],
          "created": "text",
          "cryptosuite": "text",
          "proofPurpose": "text",
          "proofValue": "text",
          "type": "text",
          "verificationMethod": "text"
        }
      ],
      "type": [
        "text"
      ],
      "validFrom": "text",
      "validUntil": "text"
    }
  ]
}

Get the OB 3.0 service discovery document

get

Returns the Badge Connect service descriptor for OB 3.0 API discovery

Authorizations

HTTPRequired

Responses

200

Service descriptor retrieved successfully

application/json

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/ims/ob/v3p0/discovery

GET /ims/ob/v3p0/discovery HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "info": {
    "title": "OpenAPI schema for Open Badges",
    "version": "3.0"
  },
  "openapi": "3.0.1",
  "paths": {
    "/credentials": {
      "get": {
        "operationId": "getCredentials",
        "summary": "Get verifiable credentials"
      }
    },
    "/profile": {
      "get": {
        "operationId": "getProfile",
        "summary": "Get user profile"
      }
    }
  },
  "servers": [
    {
      "url": "https://api.badgr.com/ims/ob/v3p0"
    }
  ]
}

Get the authenticated user's profile

get

Returns the OB 3.0 profile of the authenticated badge recipient

Required scopes

This endpoint requires the following scopes:

• : See who you are

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Responses

200

Profile retrieved successfully

*/*

@contextstring[]Required

emailstring · nullableOptional

namestring · nullableOptional

phonestring · nullableOptional

typestring[]Required

urlstring · nullableOptional

400

Bad Request

*/*

401

Not authenticated

*/*

403

Access denied

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/ims/ob/v3p0/profile

GET /ims/ob/v3p0/profile HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "@context": [
    "text"
  ],
  "email": "text",
  "name": "text",
  "phone": "text",
  "type": [
    "text"
  ],
  "url": "text"
}

Retrieve creation methods for a batch of assertions

get

Required scopes

This endpoint requires the following scopes:

• : Read badge classes and assertions in your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Query parameters

idsstring[] · min: 1 · max: 100Required

IDs or entity IDs of the assertions or credentials.

Responses

200

OK

application/json

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/assertions/creation-methods

GET /v2/assertions/creation-methods?ids=text HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "assertions": [
    {
      "creationMethod": {
        "type": "text",
        "courseUrl": "text",
        "lmsPlatform": "CANVAS"
      },
      "entityId": "text",
      "id": "text"
    }
  ]
}

Revoke multiple Assertions

post

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Bodyobject · V2ApiRevokeMultipleAssertion[]

codestring · nullableRead-onlyOptional

Error code if assertion could not be revoked

entityIdstring · nullableOptional

Entity ID of the Assertion to revoke

Example: i9CirfwJTuSfiqg0FFUBdQ

idstring · nullableOptional

ID of the Assertion to revoke

Example: 62aa04adf5afe00d0a6dac72

reasonstring · nullableRead-onlyOptional

Error reason if assertion could not be revoked

revocationReasonstringRequired

Short description of why the Assertion is being revoked

Example: Course was cancelled

revokedboolean · nullableRead-onlyOptional

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post/v2/assertions/revoke

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

[
  {
    "entityId": "i9CirfwJTuSfiqg0FFUBdQ",
    "id": "62aa04adf5afe00d0a6dac72",
    "revocationReason": "Course was cancelled"
  }
]

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "result": [
    {
      "code": "text",
      "entityId": "i9CirfwJTuSfiqg0FFUBdQ",
      "id": "62aa04adf5afe00d0a6dac72",
      "reason": "text",
      "revocationReason": "Course was cancelled",
      "revoked": true
    }
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

Revoke an Assertion

delete

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

revocation_reasonstringOptional

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

delete/v2/assertions/{idOrEntityId}

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

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

Get a single Assertion

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/assertions/{idOrEntityId}

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

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

Update an Assertion

put

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

expiresstring · date-time · nullableOptional

issuedOnstring · date-time · nullableOptional

Timestamp when the assertion was issued

narrativestring · nullableOptional

Markdown narrative of the achievement

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

put/v2/assertions/{idOrEntityId}

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

{
  "evidence": [
    {
      "audience": "text",
      "description": "text",
      "genre": "text",
      "name": "text",
      "narrative": "text",
      "url": "text"
    }
  ],
  "expires": "2026-01-01T00:00:00.000Z",
  "extensions": {
    "value": {
      "ANY_ADDITIONAL_PROPERTY": {}
    }
  },
  "issuedOn": "2026-01-01T00:00:00.000Z",
  "narrative": "text",
  "ob3AwardProperties": {
    "activityEnd": "2026-01-01T00:00:00.000Z",
    "activityStart": "2026-01-01T00:00:00.000Z",
    "licenseNumber": "text",
    "role": "text"
  }
}

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

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

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Query parameters

Responses

200

OK

*/*

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/backpack/assertions

GET /v2/backpack/assertions HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

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

Remove an assertion from the backpack

delete

Required scopes

This endpoint requires the following scopes:

• : Upload badges to your backpack

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Responses

204

No Content

No content

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

delete/v2/backpack/assertions/{idOrEntityId}

DELETE /v2/backpack/assertions/{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

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Query parameters

Responses

200

OK

*/*

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/backpack/assertions/{idOrEntityId}

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

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

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

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Responses

200

OK

*/*

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

put/v2/backpack/assertions/{idOrEntityId}

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

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

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

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Responses

200

OK

*/*

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/backpack/collections

GET /v2/backpack/collections HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

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

Create a new Collection

post

Required scopes

This endpoint requires the following scopes:

• : Upload badges to your backpack

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Body

descriptionstring · nullableOptional

Short description of the Collection

Example: This is a collection of my favorite badges

namestringRequired

Name of the collection

Example: My Collection

publishedbooleanRequired

True if the Collection should have a share url

Example: true

Responses

201

Created

*/*

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post/v2/backpack/collections

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

{
  "description": "This is a collection of my favorite badges",
  "name": "My Collection",
  "published": true
}

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

Delete a collection

delete

Required scopes

This endpoint requires the following scopes:

• : Upload badges to your backpack

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Responses

204

No Content

No content

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

delete/v2/backpack/collections/{idOrEntityId}

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

No content

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

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Responses

200

OK

*/*

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/backpack/collections/{idOrEntityId}

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

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

Update a Collection

put

Required scopes

This endpoint requires the following scopes:

• : Upload badges to your backpack

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

assertionsstring[] · nullableOptional

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

Example: UQbhRmNrQ4qn9_FJ5-eTtA

credentialsstring[] · nullableOptional

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

Example: UQbhRmNrQ4qn9_FJ5-eTtA

descriptionstring · nullableOptional

Short description of the Collection

Example: This is a collection of my favorite badges

namestring · nullableOptional

Name of the collection

Example: My Collection

publishedboolean · nullableOptional

True if the Collection should have a share url

Example: true

Responses

200

OK

*/*

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

put/v2/backpack/collections/{idOrEntityId}

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

{
  "assertions": [
    "UQbhRmNrQ4qn9_FJ5-eTtA"
  ],
  "credentials": [
    "UQbhRmNrQ4qn9_FJ5-eTtA"
  ],
  "description": "This is a collection of my favorite badges",
  "name": "My Collection",
  "published": true
}

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

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

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Body

imagestring · nullableOptional

Image URL or base64 encoded image data of the assertion.

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

urlstring · uri · nullableOptional

URL of the badge to import

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

Responses

201

Created

*/*

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post/v2/backpack/import

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

{
  "assertion": {
    "array": true,
    "bigDecimal": true,
    "bigInteger": true,
    "binary": true,
    "boolean": true,
    "container": true,
    "double": true,
    "embeddedValue": true,
    "empty": true,
    "float": true,
    "floatingPointNumber": true,
    "int": true,
    "integralNumber": true,
    "long": true,
    "missingNode": true,
    "nodeType": "ARRAY",
    "null": true,
    "number": true,
    "object": true,
    "pojo": true,
    "short": true,
    "string": true,
    "valueNode": true
  },
  "image": "https://example.com/assertions/1/image",
  "url": "https://example.com/assertions/1"
}

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

Get a list of BadgeClasses for authenticated user

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Query parameters

include_archivedbooleanOptionalDefault: false

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/badgeclasses

GET /v2/badgeclasses HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

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

Create a new BadgeClass

post

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Body

achievementTypestring · nullableOptional

The type of achievement

Example: Course

criteriaNarrativestring · nullableOptional

Markdown formatted description of the criteria

criteriaUrlstring · uri · nullableOptional

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

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

descriptionstring · max: 16384 · nullableRequired

Short description of the BadgeClass

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

imagestring · nullableRequired

Image of the badge class as a base64-encoded data URI. External URLs are not allowed.

Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==

imageAltTextstring · nullableOptional

issuerstring · nullableRequired

Entity ID of the issuer

Example: ZvYydoQhRtOKalNzFPZR2A-Q

namestring · max: 1024 · nullableRequired

Name of the BadgeClass

Example: Math Expert

tagsstring[] · nullableOptional

List of tags that describe the BadgeClass

Responses

201

BadgeClass created

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post/v2/badgeclasses

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

{
  "achievementType": "Course",
  "alignments": [
    {
      "displayAsSkill": true,
      "targetCode": "text",
      "targetDescription": "text",
      "targetFramework": "text",
      "targetName": "text",
      "targetUrl": "text"
    }
  ],
  "criteriaNarrative": "text",
  "criteriaUrl": "https://example.com/badge-classes/1/criteria",
  "description": "This badge is awarded to students who have demonstrated mastery of Math.",
  "expires": {
    "amount": 30,
    "duration": "days"
  },
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==",
  "imageAltText": "text",
  "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
  "name": "Math Expert",
  "ob3Properties": {
    "creditHours": 36,
    "fieldOfStudy": "Research",
    "humanCode": "R1",
    "specialization": "Computer Science Research"
  },
  "preferences": {
    "customPropertyValues": [
      {
        "arrayValue": [
          "text"
        ],
        "doubleValue": 1,
        "propertyId": "67b32887e2a7a7d5f7adabf1",
        "public": true,
        "stringValue": "text"
      }
    ],
    "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3",
    "enabledPrintCertTemplateIds": [
      "61e9d238c5afe622816febb3"
    ],
    "includeOnPublicPages": true
  },
  "tags": [
    "text"
  ]
}

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

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

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

refstringRequired

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

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

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

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post/v2/badgeclasses/reactivate/{idOrEntityId}

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

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

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

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

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

delete/v2/badgeclasses/ref/{ref}

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

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

Get a single BadgeClass

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

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

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/badgeclasses/ref/{ref}

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

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

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

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

refstringRequired

Body

achievementTypestringOptional

The type of achievement

Example: Course

criteriaNarrativestringOptional

Markdown formatted description of the criteria

criteriaUrlstring · uriOptional

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

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

descriptionstring · max: 16384 · nullableRequired

Short description of the BadgeClass

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

imagestringRequired

Image of the badge class as a base64-encoded data URI. External URLs are not allowed.

Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==

imageAltTextstringOptional

namestring · max: 1024 · nullableRequired

Name of the BadgeClass

Example: Math Expert

tagsstring[]Optional

List of tags that describe the BadgeClass

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

put/v2/badgeclasses/ref/{ref}

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: 1051

{
  "achievementType": "Course",
  "alignments": [
    {
      "displayAsSkill": true,
      "targetCode": "text",
      "targetDescription": "text",
      "targetFramework": "text",
      "targetName": "text",
      "targetUrl": "text"
    }
  ],
  "criteriaNarrative": "text",
  "criteriaUrl": "https://example.com/badge-classes/1/criteria",
  "description": "This badge is awarded to students who have demonstrated mastery of Math.",
  "expires": {
    "amount": 30,
    "duration": "days"
  },
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==",
  "imageAltText": "text",
  "name": "Math Expert",
  "ob3Properties": {
    "creditHours": 36,
    "fieldOfStudy": "Research",
    "humanCode": "R1",
    "specialization": "Computer Science Research"
  },
  "preferences": {
    "customPropertyValues": [
      {
        "arrayValue": [
          "text"
        ],
        "doubleValue": 1,
        "propertyId": "67b32887e2a7a7d5f7adabf1",
        "public": true,
        "stringValue": "text"
      }
    ],
    "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3",
    "enabledPrintCertTemplateIds": [
      "61e9d238c5afe622816febb3"
    ],
    "includeOnPublicPages": true
  },
  "tags": [
    "text"
  ]
}

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

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

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

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

delete/v2/badgeclasses/{idOrEntityId}

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

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

Get a single BadgeClass

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

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

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/badgeclasses/{idOrEntityId}

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

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

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

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

achievementTypestringOptional

The type of achievement

Example: Course

criteriaNarrativestringOptional

Markdown formatted description of the criteria

criteriaUrlstring · uriOptional

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

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

descriptionstring · max: 16384 · nullableRequired

Short description of the BadgeClass

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

imagestringRequired

Image of the badge class as a base64-encoded data URI. External URLs are not allowed.

Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==

imageAltTextstringOptional

namestring · max: 1024 · nullableRequired

Name of the BadgeClass

Example: Math Expert

tagsstring[]Optional

List of tags that describe the BadgeClass

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

put/v2/badgeclasses/{idOrEntityId}

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

{
  "achievementType": "Course",
  "alignments": [
    {
      "displayAsSkill": true,
      "targetCode": "text",
      "targetDescription": "text",
      "targetFramework": "text",
      "targetName": "text",
      "targetUrl": "text"
    }
  ],
  "criteriaNarrative": "text",
  "criteriaUrl": "https://example.com/badge-classes/1/criteria",
  "description": "This badge is awarded to students who have demonstrated mastery of Math.",
  "expires": {
    "amount": 30,
    "duration": "days"
  },
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==",
  "imageAltText": "text",
  "name": "Math Expert",
  "ob3Properties": {
    "creditHours": 36,
    "fieldOfStudy": "Research",
    "humanCode": "R1",
    "specialization": "Computer Science Research"
  },
  "preferences": {
    "customPropertyValues": [
      {
        "arrayValue": [
          "text"
        ],
        "doubleValue": 1,
        "propertyId": "67b32887e2a7a7d5f7adabf1",
        "public": true,
        "stringValue": "text"
      }
    ],
    "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3",
    "enabledPrintCertTemplateIds": [
      "61e9d238c5afe622816febb3"
    ],
    "includeOnPublicPages": true
  },
  "tags": [
    "text"
  ]
}

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

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

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

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

Create a new ClaimCode for a BadgeClass

post

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

expirationDatestring · date-time · nullableOptional

labelstring · nullableOptional

The label of the claim code

Example: Conference Event

limitinteger · int64 · nullableOptional

The number of times the claim code can be used

Example: 10

Responses

201

Created

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

{
  "expirationDate": "2026-01-01T00:00:00.000Z",
  "label": "Conference Event",
  "limit": 10
}

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

Archive a ClaimCode for a BadgeClass

delete

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

claimCodestringRequired

Responses

204

No Content

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

Update an existing ClaimCode for a BadgeClass

put

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

claimCodestringRequired

Body

expirationDatestring · date-time · nullableOptional

labelstring · nullableOptional

The label of the claim code

Example: Conference Event

limitinteger · int64 · nullableOptional

The number of times the claim code can be used

Example: 10

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

{
  "expirationDate": "2026-01-01T00:00:00.000Z",
  "label": "Conference Event",
  "limit": 10
}

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

Disable an enabled ClaimCode for a BadgeClass

patch

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

claimCodestringRequired

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

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

Enable a disabled ClaimCode for a BadgeClass

patch

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

claimCodestringRequired

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

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

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

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

newNamestringRequired

The new name for the duplicate badgeclass

Example: Badgeclass Copy

Responses

201

BadgeClass created

achievementTypestring · nullableOptional

The type of achievement

Example: Course

archivalNotestring · nullableOptional

archivedboolean · nullableOptional

archivedDatestring · date-time · nullableOptional

createdAtstring · date-time · nullableOptional

Timestamp when the BadgeClass was created

createdBystring · nullableOptional

Entity ID of the user who created this BadgeClass

Example: Hey7J-GRSJeu6FNnHQwNyw

criteriaNarrativestring · nullableOptional

Markdown formatted description of the criteria

criteriaUrlstring · uri · nullableOptional

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

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

descriptionstringRequired

Short description of the badge class

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

entityIdstringRequired

Unique identifier for this BadgeClass

Example: iOMWsaF1QbmMCofM54JlUg

entityTypestringRequiredExample: BadgeClass

idstringRequired

Internal ID for this BadgeClass

Example: 68e9d238c5afe622816febb3

imagestringRequired

Image of the badge class. Most commonly an URL.

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

imageAltTextstring · nullableOptional

imagePathstring · nullableOptional

Internal image path

Example: uploads/badges/badgeclass-lY1LJ6K4RqG7ThGLYvWNng.png

issuerstringRequired

Entity ID of the issuer

Example: ZvYydoQhRtOKalNzFPZR2A-Q

issuerOpenBadgeIdstring · uriRequired

OB URL of the issuer

Example: https://api.badgr.io/public/issuers/ZvYydoQhRtOKalNzFPZR2A

namestringRequired

Name of the badge class

Example: Math Expert

openBadgeIdstring · uriRequired

URL of the OpenBadge compliant json

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

originalJsonstring · nullableOptional

The original OB JSON if the badge class was exported

Example: {}

sourcestring · nullableOptional

The original source of the BadgeClass

Example: local

sourceUrlstring · nullableOptional

The original URL of the BadgeClass if it was imported

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

tagsstring[]Required

List of tags that describe the BadgeClass

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post/v2/badgeclasses/{idOrEntityId}/duplicate

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

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

Get a list of Issuers for authenticated user

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Query parameters

include_staffstringOptionalDefault: true

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/issuers

GET /v2/issuers HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

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

Create a new Issuer

post

Creating an Issuer within an Organization (via organizationId) additionally requires the rw:org scope.

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers
• : Associate issuers with your organization and update organization data

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Query parameters

include_staffstringOptionalDefault: true

Body

badgrDomainstring · nullableOptional

Organization domain host

Example: badgrsupportgroup.badgr.com

createdBystring · nullableOptional

User who created this issuer

descriptionstring · max: 16384 · nullableOptional

Short description of the Issuer

Example: This is the faculty of the Credentials University.

emailstring · email · max: 255 · nullableRequired

Contact email for the Issuer

Example: [e-mail]

imagestring · nullableOptional

Image of the issuer as a base64-encoded data URI. External URLs are not allowed.

Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==

namestring · max: 1024 · nullableRequired

Name of the issuer

Example: Credentials Faculty

organizationIdstring · nullableOptional

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

Example: 6f4e4e4e2dc038241ad01d83

originalJsonstring · max: 2000000 · nullableOptional

The original OB JSON of the issuer if it was imported

Example: {}

sourceUrlstring · uri · nullableOptional

The original URL of the issuer if it was imported

Example: https://example.com/issuers/1

urlstring · uri · max: 1024 · nullableRequired

Homepage or website associated with the Issuer

Example: https://example.com

Responses

201

Issuer created

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post/v2/issuers

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

{
  "badgrDomain": "badgrsupportgroup.badgr.com",
  "createdBy": "text",
  "description": "This is the faculty of the Credentials University.",
  "email": "[e-mail]",
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==",
  "name": "Credentials Faculty",
  "organizationId": "6f4e4e4e2dc038241ad01d83",
  "originalJson": "{}",
  "sourceUrl": "https://example.com/issuers/1",
  "staff": [
    {
      "role": "owner",
      "user": "Hey7J-GRSJeu6FNnHQwNyw"
    }
  ],
  "url": "https://example.com"
}

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

Delete a single Issuer

delete

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

issuerOpenBadgeIdBase64stringRequired

Responses

204

Issuer deleted

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

delete/v2/issuers/openBadgeId/{issuerOpenBadgeIdBase64}

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

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

Get a single Issuer

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

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

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/issuers/openBadgeId/{issuerOpenBadgeIdBase64}

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

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

Update a single Issuer

patch

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

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

badgrDomainstringOptional

descriptionstring · max: 16384Required

Short description of the Issuer

Example: This is the faculty of the Credentials University.

emailstring · email · max: 255 · nullableRequired

Contact email for the Issuer

Example: [e-mail]

imagestringOptional

Image of the issuer as a base64-encoded data URI. External URLs are not allowed.

Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==

namestring · max: 1024 · nullableRequired

Name of the issuer

Example: Credentials Faculty

urlstring · uri · max: 1024 · nullableRequired

Homepage or website associated with the Issuer

Example: https://example.com

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

patch/v2/issuers/openBadgeId/{issuerOpenBadgeIdBase64}

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: 959

{
  "badgrDomain": "text",
  "description": "This is the faculty of the Credentials University.",
  "email": "[e-mail]",
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==",
  "name": "Credentials Faculty",
  "preferences": {
    "customPropertyDefinitions": [
      {
        "choiceValues": [
          {
            "id": "65663ceb977692fcafcea0b9",
            "label": "text"
          }
        ],
        "label": "Award Type",
        "propertyId": "66bf8231d88b51901d49d637",
        "propertyType": "STRING_CHOICE",
        "public": true,
        "required": true,
        "subLabel": "Type of award",
        "targetEntityType": "BADGE_CLASS"
      }
    ],
    "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
    "enabledPrintCertTemplateIds": [
      "5f4e4e4e2dc038241ad01d83",
      "6f4e4e4e2dc038241ad01d83"
    ],
    "newBadgeEnabledPrintCertTemplateIds": [
      "5f4e4e4e2dc038241ad01d83"
    ],
    "ob3Enabled": false,
    "showOnOrgPublicPage": true
  },
  "staff": [
    {
      "role": "owner",
      "user": "Hey7J-GRSJeu6FNnHQwNyw"
    }
  ],
  "url": "https://example.com"
}

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

Update a single Issuer

put

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

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

badgrDomainstringOptional

descriptionstring · max: 16384Required

Short description of the Issuer

Example: This is the faculty of the Credentials University.

emailstring · email · max: 255 · nullableRequired

Contact email for the Issuer

Example: [e-mail]

imagestringOptional

Image of the issuer as a base64-encoded data URI. External URLs are not allowed.

Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==

namestring · max: 1024 · nullableRequired

Name of the issuer

Example: Credentials Faculty

urlstring · uri · max: 1024 · nullableRequired

Homepage or website associated with the Issuer

Example: https://example.com

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

put/v2/issuers/openBadgeId/{issuerOpenBadgeIdBase64}

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: 959

{
  "badgrDomain": "text",
  "description": "This is the faculty of the Credentials University.",
  "email": "[e-mail]",
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==",
  "name": "Credentials Faculty",
  "preferences": {
    "customPropertyDefinitions": [
      {
        "choiceValues": [
          {
            "id": "65663ceb977692fcafcea0b9",
            "label": "text"
          }
        ],
        "label": "Award Type",
        "propertyId": "66bf8231d88b51901d49d637",
        "propertyType": "STRING_CHOICE",
        "public": true,
        "required": true,
        "subLabel": "Type of award",
        "targetEntityType": "BADGE_CLASS"
      }
    ],
    "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
    "enabledPrintCertTemplateIds": [
      "5f4e4e4e2dc038241ad01d83",
      "6f4e4e4e2dc038241ad01d83"
    ],
    "newBadgeEnabledPrintCertTemplateIds": [
      "5f4e4e4e2dc038241ad01d83"
    ],
    "ob3Enabled": false,
    "showOnOrgPublicPage": true
  },
  "staff": [
    {
      "role": "owner",
      "user": "Hey7J-GRSJeu6FNnHQwNyw"
    }
  ],
  "url": "https://example.com"
}

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

Delete a single Issuer

delete

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

issuerOpenBadgeIdBase64stringRequired

Responses

204

Issuer deleted

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

delete/v2/issuers/ref/{issuerOpenBadgeIdBase64}

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

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

Get a single Issuer

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

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

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/issuers/ref/{issuerOpenBadgeIdBase64}

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

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

Update a single Issuer

patch

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

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

badgrDomainstringOptional

descriptionstring · max: 16384Required

Short description of the Issuer

Example: This is the faculty of the Credentials University.

emailstring · email · max: 255 · nullableRequired

Contact email for the Issuer

Example: [e-mail]

imagestringOptional

Image of the issuer as a base64-encoded data URI. External URLs are not allowed.

Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==

namestring · max: 1024 · nullableRequired

Name of the issuer

Example: Credentials Faculty

urlstring · uri · max: 1024 · nullableRequired

Homepage or website associated with the Issuer

Example: https://example.com

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

patch/v2/issuers/ref/{issuerOpenBadgeIdBase64}

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: 959

{
  "badgrDomain": "text",
  "description": "This is the faculty of the Credentials University.",
  "email": "[e-mail]",
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==",
  "name": "Credentials Faculty",
  "preferences": {
    "customPropertyDefinitions": [
      {
        "choiceValues": [
          {
            "id": "65663ceb977692fcafcea0b9",
            "label": "text"
          }
        ],
        "label": "Award Type",
        "propertyId": "66bf8231d88b51901d49d637",
        "propertyType": "STRING_CHOICE",
        "public": true,
        "required": true,
        "subLabel": "Type of award",
        "targetEntityType": "BADGE_CLASS"
      }
    ],
    "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
    "enabledPrintCertTemplateIds": [
      "5f4e4e4e2dc038241ad01d83",
      "6f4e4e4e2dc038241ad01d83"
    ],
    "newBadgeEnabledPrintCertTemplateIds": [
      "5f4e4e4e2dc038241ad01d83"
    ],
    "ob3Enabled": false,
    "showOnOrgPublicPage": true
  },
  "staff": [
    {
      "role": "owner",
      "user": "Hey7J-GRSJeu6FNnHQwNyw"
    }
  ],
  "url": "https://example.com"
}

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

Update a single Issuer

put

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

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

badgrDomainstringOptional

descriptionstring · max: 16384Required

Short description of the Issuer

Example: This is the faculty of the Credentials University.

emailstring · email · max: 255 · nullableRequired

Contact email for the Issuer

Example: [e-mail]

imagestringOptional

Image of the issuer as a base64-encoded data URI. External URLs are not allowed.

Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==

namestring · max: 1024 · nullableRequired

Name of the issuer

Example: Credentials Faculty

urlstring · uri · max: 1024 · nullableRequired

Homepage or website associated with the Issuer

Example: https://example.com

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

put/v2/issuers/ref/{issuerOpenBadgeIdBase64}

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: 959

{
  "badgrDomain": "text",
  "description": "This is the faculty of the Credentials University.",
  "email": "[e-mail]",
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==",
  "name": "Credentials Faculty",
  "preferences": {
    "customPropertyDefinitions": [
      {
        "choiceValues": [
          {
            "id": "65663ceb977692fcafcea0b9",
            "label": "text"
          }
        ],
        "label": "Award Type",
        "propertyId": "66bf8231d88b51901d49d637",
        "propertyType": "STRING_CHOICE",
        "public": true,
        "required": true,
        "subLabel": "Type of award",
        "targetEntityType": "BADGE_CLASS"
      }
    ],
    "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
    "enabledPrintCertTemplateIds": [
      "5f4e4e4e2dc038241ad01d83",
      "6f4e4e4e2dc038241ad01d83"
    ],
    "newBadgeEnabledPrintCertTemplateIds": [
      "5f4e4e4e2dc038241ad01d83"
    ],
    "ob3Enabled": false,
    "showOnOrgPublicPage": true
  },
  "staff": [
    {
      "role": "owner",
      "user": "Hey7J-GRSJeu6FNnHQwNyw"
    }
  ],
  "url": "https://example.com"
}

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

Delete a single Issuer

delete

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Responses

204

Issuer deleted

No content

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

delete/v2/issuers/{idOrEntityId}

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

No content

Get a single Issuer

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

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

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/issuers/{idOrEntityId}

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

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

Update a single Issuer

patch

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

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

badgrDomainstringOptional

descriptionstring · max: 16384Required

Short description of the Issuer

Example: This is the faculty of the Credentials University.

emailstring · email · max: 255 · nullableRequired

Contact email for the Issuer

Example: [e-mail]

imagestringOptional

Image of the issuer as a base64-encoded data URI. External URLs are not allowed.

Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==

namestring · max: 1024 · nullableRequired

Name of the issuer

Example: Credentials Faculty

urlstring · uri · max: 1024 · nullableRequired

Homepage or website associated with the Issuer

Example: https://example.com

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

patch/v2/issuers/{idOrEntityId}

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

{
  "badgrDomain": "text",
  "description": "This is the faculty of the Credentials University.",
  "email": "[e-mail]",
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==",
  "name": "Credentials Faculty",
  "preferences": {
    "customPropertyDefinitions": [
      {
        "choiceValues": [
          {
            "id": "65663ceb977692fcafcea0b9",
            "label": "text"
          }
        ],
        "label": "Award Type",
        "propertyId": "66bf8231d88b51901d49d637",
        "propertyType": "STRING_CHOICE",
        "public": true,
        "required": true,
        "subLabel": "Type of award",
        "targetEntityType": "BADGE_CLASS"
      }
    ],
    "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
    "enabledPrintCertTemplateIds": [
      "5f4e4e4e2dc038241ad01d83",
      "6f4e4e4e2dc038241ad01d83"
    ],
    "newBadgeEnabledPrintCertTemplateIds": [
      "5f4e4e4e2dc038241ad01d83"
    ],
    "ob3Enabled": false,
    "showOnOrgPublicPage": true
  },
  "staff": [
    {
      "role": "owner",
      "user": "Hey7J-GRSJeu6FNnHQwNyw"
    }
  ],
  "url": "https://example.com"
}

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

Update a single Issuer

put

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

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

badgrDomainstringOptional

descriptionstring · max: 16384Required

Short description of the Issuer

Example: This is the faculty of the Credentials University.

emailstring · email · max: 255 · nullableRequired

Contact email for the Issuer

Example: [e-mail]

imagestringOptional

Image of the issuer as a base64-encoded data URI. External URLs are not allowed.

Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==

namestring · max: 1024 · nullableRequired

Name of the issuer

Example: Credentials Faculty

urlstring · uri · max: 1024 · nullableRequired

Homepage or website associated with the Issuer

Example: https://example.com

Responses

200

OK

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

put/v2/issuers/{idOrEntityId}

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

{
  "badgrDomain": "text",
  "description": "This is the faculty of the Credentials University.",
  "email": "[e-mail]",
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==",
  "name": "Credentials Faculty",
  "preferences": {
    "customPropertyDefinitions": [
      {
        "choiceValues": [
          {
            "id": "65663ceb977692fcafcea0b9",
            "label": "text"
          }
        ],
        "label": "Award Type",
        "propertyId": "66bf8231d88b51901d49d637",
        "propertyType": "STRING_CHOICE",
        "public": true,
        "required": true,
        "subLabel": "Type of award",
        "targetEntityType": "BADGE_CLASS"
      }
    ],
    "defaultPrintCertTemplateId": "5f4e4e4e2dc038241ad01d83",
    "enabledPrintCertTemplateIds": [
      "5f4e4e4e2dc038241ad01d83",
      "6f4e4e4e2dc038241ad01d83"
    ],
    "newBadgeEnabledPrintCertTemplateIds": [
      "5f4e4e4e2dc038241ad01d83"
    ],
    "ob3Enabled": false,
    "showOnOrgPublicPage": true
  },
  "staff": [
    {
      "role": "owner",
      "user": "Hey7J-GRSJeu6FNnHQwNyw"
    }
  ],
  "url": "https://example.com"
}

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

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

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

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/issuers/{idOrEntityId}/badgeclasses

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

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

Create a new BadgeClass associated with an Issuer

post

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

achievementTypestring · nullableOptional

The type of achievement

Example: Course

criteriaNarrativestring · nullableOptional

Markdown formatted description of the criteria

criteriaUrlstring · uri · nullableOptional

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

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

descriptionstring · max: 16384 · nullableRequired

Short description of the BadgeClass

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

imagestring · nullableRequired

Image of the badge class as a base64-encoded data URI. External URLs are not allowed.

Example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==

imageAltTextstring · nullableOptional

issuerstring · nullableOptional

Entity ID of the issuer

Example: ZvYydoQhRtOKalNzFPZR2A-Q

namestring · max: 1024 · nullableRequired

Name of the BadgeClass

Example: Math Expert

tagsstring[] · nullableOptional

List of tags that describe the BadgeClass

Responses

201

Created

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post/v2/issuers/{idOrEntityId}/badgeclasses

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: 1087

{
  "achievementType": "Course",
  "alignments": [
    {
      "displayAsSkill": true,
      "targetCode": "text",
      "targetDescription": "text",
      "targetFramework": "text",
      "targetName": "text",
      "targetUrl": "text"
    }
  ],
  "criteriaNarrative": "text",
  "criteriaUrl": "https://example.com/badge-classes/1/criteria",
  "description": "This badge is awarded to students who have demonstrated mastery of Math.",
  "expires": {
    "amount": 30,
    "duration": "days"
  },
  "extensions": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhQJ/6+gQDQAAAABJRU5ErkJggg==",
  "imageAltText": "text",
  "issuer": "ZvYydoQhRtOKalNzFPZR2A-Q",
  "name": "Math Expert",
  "ob3Properties": {
    "creditHours": 36,
    "fieldOfStudy": "Research",
    "humanCode": "R1",
    "specialization": "Computer Science Research"
  },
  "preferences": {
    "customPropertyValues": [
      {
        "arrayValue": [
          "text"
        ],
        "doubleValue": 1,
        "propertyId": "67b32887e2a7a7d5f7adabf1",
        "public": true,
        "stringValue": "text"
      }
    ],
    "defaultPrintCertTemplateId": "61e9d238c5afe622816febb3",
    "enabledPrintCertTemplateIds": [
      "61e9d238c5afe622816febb3"
    ],
    "includeOnPublicPages": true
  },
  "tags": [
    "text"
  ]
}

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

List all pathways for the issuer

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

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

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/issuers/{idOrEntityId}/pathways

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

{
  "pathwayInfos": [
    {
      "draftCompletionBadgeUrl": "https://api.staging.badgr.dev/public/badges/ngurEbvbQiCAs5EkwEgIBw",
      "draftName": "Road",
      "issuerId": "62aa04adf5afe00d0a6dac72",
      "issuerName": "Springfield University",
      "issuerVerified": true,
      "lastPublishedAt": "2026-01-01T00:00:00.000Z",
      "pathwayGroupLtiToolCountsByLmsType": {
        "Blackboard": 3,
        "Canvas": 2,
        "Moodle": 4,
        "Other": 5
      },
      "pathwayId": "66aa04adf5afe00d0a6dac72",
      "publishedCompletionBadgeUrl": "https://api.staging.badgr.dev/public/badges/ngurEbvbQiCAs5EkwEgIBw",
      "publishedName": "Highway",
      "subscribedGroupCount": 2,
      "uniqueMemberCount": 100
    }
  ]
}

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

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

emailstring · email · nullableRequired

Email address of the staff member to remove

Example: [e-mail]

Responses

204

Staff member removed

*/*

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

delete/v2/issuers/{idOrEntityId}/staff

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

{
  "email": "[e-mail]"
}

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

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

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

emailstring · email · nullableRequired

Email address associated with the staff member

Example: [e-mail]

rolestring · enum · nullableRequired

Role of the user in the issuer.

Possible values:

Responses

200

OK

*/*

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

patch/v2/issuers/{idOrEntityId}/staff

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": "[e-mail]",
  "role": "owner"
}

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "result": [
    {
      "orgRole": "BillingAdmin",
      "role": "staff",
      "user": "Hey7J-GRSJeu6FNnHQwNyw",
      "userProfile": {
        "agreedTermsVersion": 4,
        "badgrDomain": "badgrsupportgroup.badgr.com",
        "emails": [
          {
            "email": "[e-mail]",
            "primary": true,
            "verified": true
          }
        ],
        "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
        "entityType": "BadgeUser",
        "firstName": "Jane",
        "hasPasswordSet": true,
        "lastName": "Doe",
        "marketingOptIn": true,
        "telephone": [
          "text"
        ],
        "url": [
          "https://example.com"
        ]
      }
    }
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

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

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

emailstring · email · nullableRequired

Email address associated with the staff member

Example: [e-mail]

rolestring · enum · nullableRequired

Role of the user in the issuer.

Possible values:

Responses

201

Staff member added

*/*

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post/v2/issuers/{idOrEntityId}/staff

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": "[e-mail]",
  "role": "owner"
}

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "result": [
    {
      "orgRole": "BillingAdmin",
      "role": "staff",
      "user": "Hey7J-GRSJeu6FNnHQwNyw",
      "userProfile": {
        "agreedTermsVersion": 4,
        "badgrDomain": "badgrsupportgroup.badgr.com",
        "emails": [
          {
            "email": "[e-mail]",
            "primary": true,
            "verified": true
          }
        ],
        "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
        "entityType": "BadgeUser",
        "firstName": "Jane",
        "hasPasswordSet": true,
        "lastName": "Doe",
        "marketingOptIn": true,
        "telephone": [
          "text"
        ],
        "url": [
          "https://example.com"
        ]
      }
    }
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

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

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

emailstring · email · nullableRequired

Email address associated with the staff member

Example: [e-mail]

rolestring · enum · nullableRequired

Role of the user in the issuer.

Possible values:

Responses

200

OK

*/*

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

put/v2/issuers/{idOrEntityId}/staff

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": "[e-mail]",
  "role": "owner"
}

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "result": [
    {
      "orgRole": "BillingAdmin",
      "role": "staff",
      "user": "Hey7J-GRSJeu6FNnHQwNyw",
      "userProfile": {
        "agreedTermsVersion": 4,
        "badgrDomain": "badgrsupportgroup.badgr.com",
        "emails": [
          {
            "email": "[e-mail]",
            "primary": true,
            "verified": true
          }
        ],
        "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
        "entityType": "BadgeUser",
        "firstName": "Jane",
        "hasPasswordSet": true,
        "lastName": "Doe",
        "marketingOptIn": true,
        "telephone": [
          "text"
        ],
        "url": [
          "https://example.com"
        ]
      }
    }
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

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

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

emailstring · email · nullableRequired

Email address associated with the staff member

Example: [e-mail]

rolestring · enum · nullableRequired

Role of the user in the issuer.

Possible values:

Responses

200

OK

*/*

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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": "[e-mail]",
  "role": "owner"
}

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "result": [
    {
      "email": "[e-mail]",
      "role": "owner",
      "status": "PENDING"
    }
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

Export badge data of the recipient groups for a given issuer.

get

Authorizations

HTTPRequired

Path parameters

issuerIdstringRequired

Query parameters

includeArchivedGroupsbooleanOptionalDefault: false

Responses

200

CSV file containing badge data

text/csv

stringOptionalExample: Group ID,Group Name,Course ID,Badge ID,Badge Name,Award Method,Course Item,Requirement with link,Trigger Type,Threshold,Evidence Needed,Date Restriction,Leaderboard Points,Learner Progress 68cd3f3a54e2f258d1aedcfa,Teacher epic course,66780,68e4bcd536627547e95edeed,Badge 2,Canvas,Course grade,https://zoltanfarkas.instructure.com/courses/66780,Percentage score,80%,no,,1,1 awarded

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/issuers/{issuerId}/group-export/badge-data

GET /v2/issuers/{issuerId}/group-export/badge-data HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

Group ID,Group Name,Course ID,Badge ID,Badge Name,Award Method,Course Item,Requirement with link,Trigger Type,Threshold,Evidence Needed,Date Restriction,Leaderboard Points,Learner Progress
68cd3f3a54e2f258d1aedcfa,Teacher epic course,66780,68e4bcd536627547e95edeed,Badge 2,Canvas,Course grade,https://zoltanfarkas.instructure.com/courses/66780,Percentage score,80%,no,,1,1 awarded

Export learner progress data of the recipient groups for a given issuer.

get

Authorizations

HTTPRequired

Path parameters

issuerIdstringRequired

Query parameters

includeArchivedGroupsbooleanOptionalDefault: false

Responses

200

CSV file containing learner progress data

text/csv

stringOptionalExample: Group ID,Group Name,Learner Name,Learner ID,Last Badge Earned,Alignment Type,Alignment ID,Alignment Name,Status,Detailed Progress,Evidence 68cd3f3a54e2f258d1aedcfa,Teacher epic course,Canvas Student,[e-mail],Jan 20 2026,Badge,68e4bcd536627547e95edeed,Badge 2,Awarded,,https://evidence-1.com|https://evidence-2.com

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/issuers/{issuerId}/group-export/learner-progress-data

GET /v2/issuers/{issuerId}/group-export/learner-progress-data HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

Group ID,Group Name,Learner Name,Learner ID,Last Badge Earned,Alignment Type,Alignment ID,Alignment Name,Status,Detailed Progress,Evidence
68cd3f3a54e2f258d1aedcfa,Teacher epic course,Canvas Student,[e-mail],Jan 20 2026,Badge,68e4bcd536627547e95edeed,Badge 2,Awarded,,https://evidence-1.com|https://evidence-2.com

Get a list of Organizations where the authenticated user is admin

get

Required scopes

This endpoint requires the following scopes:

• : Read organization data

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Responses

200

OK

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/organizations

GET /v2/organizations HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "organizations": [
    {
      "frontendDomain": "university.badges.example.com",
      "id": "67ae3efe2ee1d96b56fc1957",
      "name": "University of Credentials",
      "ob3Enabled": false,
      "profile": {
        "description": "A university that issues credentials.",
        "email": "[e-mail]",
        "imageUrl": "https://www.example.com/logo.png",
        "url": "https://www.example.com"
      },
      "publicSkillsMenuEnabled": false
    }
  ]
}

List public issuers for the specified organization with pagination and optional name filtering

get

Authorizations

HTTPRequired

Path parameters

idstringRequired

Query parameters

nameQuerystring · max: 256Optional

Case-insensitive filter for the name of the issuers

numstring · min: 1 · max: 100Optional

Number of items to return per page

Default: 10Example: 10

pagestring · min: 1Optional

Index of the requested page (1-based)

Default: 1Example: 1

Responses

200

OK

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/organizations/{id}/public-issuers

GET /v2/organizations/{id}/public-issuers HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "badgeSkillLinkingPreferences": {
        "indeedRegion": "us",
        "linkMode": "DEFAULT",
        "serverUri": "https://example.com/",
        "type": "TALENT_NEURON"
      },
      "issuerId": "67e9d238c5afe622816febb3",
      "obIssuer": {
        "@context": "text",
        "description": "text",
        "email": "text",
        "extensions": {
          "ANY_ADDITIONAL_PROPERTY": {}
        },
        "id": "text",
        "image": "text",
        "name": "text",
        "url": "text"
      },
      "organizationId": "65e9d238c5afe622816febb3"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "hasNextPage": true,
    "nextLink": "text",
    "pageSize": 10,
    "previousLink": "text",
    "totalCount": 100,
    "totalPages": 6
  }
}

Export general data of the recipient groups for a given organization.

get

Authorizations

HTTPRequired

Path parameters

organizationIdstringRequired

Query parameters

issuerIdstringOptional

includeCreationDateAndMethodbooleanOptionalDefault: true

includeExpirationDateAndMethodbooleanOptionalDefault: true

includeStaffMembersbooleanOptionalDefault: true

includeArchivedGroupsbooleanOptionalDefault: false

Responses

200

CSV file containing general group data

text/csv

stringOptionalExample: Group ID,Group name,Course/Pathway ID,URL,Learners,Alignment type,Alignment ID,Alignment name,Creation date,Creation method,Expiration date,Expiration method,Staff member name,Staff member ID 68cd3f3a54e2f258d1aedcfa,Teacher epic course,66780,https://zoltanfarkas.instructure.com/courses/66780,1,Badge,68e4bcd536627547e95edeed,Badge 2,Sep 19 2025,Canvas,Sep 19 2026,Manual,Canvas Teacher,[e-mail]

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/organizations/{organizationId}/group-export/general-data

GET /v2/organizations/{organizationId}/group-export/general-data HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

Group ID,Group name,Course/Pathway ID,URL,Learners,Alignment type,Alignment ID,Alignment name,Creation date,Creation method,Expiration date,Expiration method,Staff member name,Staff member ID
68cd3f3a54e2f258d1aedcfa,Teacher epic course,66780,https://zoltanfarkas.instructure.com/courses/66780,1,Badge,68e4bcd536627547e95edeed,Badge 2,Sep 19 2025,Canvas,Sep 19 2026,Manual,Canvas Teacher,[e-mail]

Invite a staff member to an Organization

post

User must have write access to the organization.

Required scopes

This endpoint requires the following scopes:

• : Associate issuers with your organization and update organization data

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

organizationIdstringRequired

Body

emailstring · email · nullableRequired

Email address of the invited staff member

Example: [e-mail]

rolestring · enum · nullableRequired

Role of the user in the organization.

Possible values:

Responses

201

Invitation created

*/*

emailstringRequired

Email address of the invited staff member

Example: [e-mail]

rolestring · enumRequired

Role of the user in the organization.

Possible values:

statusstring · enumRequired

Status of the invitation

Possible values:

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post/v2/organizations/{organizationId}/staff/invitations

POST /v2/organizations/{organizationId}/staff/invitations HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 54

{
  "email": "[e-mail]",
  "role": "BillingAdmin"
}

{
  "email": "[e-mail]",
  "role": "BillingAdmin",
  "status": "pending"
}

Create pathway in draft state

post

Authorizations

HTTPRequired

Body

issuerIdstringRequired

ID of the issuer where the pathway will be created

Example: 62aa04adf5afe00d0a6dac72

Responses

200

OK

creationDatestring · date-timeRequired

draftLastUpdatedAtstring · date-timeRequired

draftStructureVersioninteger · int32Required

hasDraftChangesbooleanRequired

hasThirdPartyBadgesbooleanRequired

issuerIdstringRequired

ID of the issuer where the pathway was created

Example: 62aa04adf5afe00d0a6dac72

lastPublishedAtstring · date-time · nullableOptional

pathwayIdstring · nullableOptionalExample: 66aa04adf5afe00d0a6dac72

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post/v2/pathways

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

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

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

Delete pathway

delete

Authorizations

HTTPRequired

Path parameters

idstringRequired

Responses

204

Pathway deleted

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

delete/v2/pathways/{id}

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

No content

Get aggregate progress status for the entire pathway

get

Authorizations

HTTPRequired

Path parameters

idstringRequired

Responses

200

OK

idstringRequiredExample: 61aa04adf5afe00d0a6dac72

pathwayIdstringRequiredExample: 66aa04adf5afe00d0a6dac72

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

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

Get progress status for the recipient group

get

Authorizations

HTTPRequired

Path parameters

idstringRequired

recipientGroupIdstringRequired

Responses

200

OK

idstringRequiredExample: 61aa04adf5afe00d0a6dac72

pathwayIdstringRequiredExample: 66aa04adf5afe00d0a6dac72

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

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

Get progress status for the recipient

get

Authorizations

HTTPRequired

Path parameters

idstringRequired

Query parameters

recipientIdentifierstringRequired

Identifier of the recipient, format: recipientType:recipientId

Example: email:[e-mail]

Responses

200

OK

idstringRequiredExample: 61aa04adf5afe00d0a6dac72

pathwayIdstringRequiredExample: 66aa04adf5afe00d0a6dac72

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

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

Update pathway group subscriptions

post

Authorizations

HTTPRequired

Path parameters

idstringRequired

Body

groupIdsToAddstring[]RequiredExample: 61aa04adf5afe00d0a6dac72

groupIdsToRemovestring[]RequiredExample: 67aa04adf5afe00d0a6dac72

Responses

200

OK

No content

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

post/v2/pathways/{id}/subscriptions

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 draft version

get

Authorizations

HTTPRequired

Path parameters

idstringRequired

Responses

200

OK

creationDatestring · date-timeRequired

draftLastUpdatedAtstring · date-timeRequired

draftStructureVersioninteger · int32Required

hasDraftChangesbooleanRequired

hasThirdPartyBadgesbooleanRequired

issuerIdstringRequired

ID of the issuer where the pathway was created

Example: 62aa04adf5afe00d0a6dac72

lastPublishedAtstring · date-time · nullableOptional

pathwayIdstring · nullableOptionalExample: 66aa04adf5afe00d0a6dac72

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

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

Update pathway draft

put

Authorizations

HTTPRequired

Path parameters

idstringRequired

Body

issuerIdstringRequired

Responses

200

OK

creationDatestring · date-timeRequired

draftLastUpdatedAtstring · date-timeRequired

draftStructureVersioninteger · int32Required

hasDraftChangesbooleanRequired

hasThirdPartyBadgesbooleanRequired

issuerIdstringRequired

ID of the issuer where the pathway was created

Example: 62aa04adf5afe00d0a6dac72

lastPublishedAtstring · date-time · nullableOptional

pathwayIdstring · nullableOptionalExample: 66aa04adf5afe00d0a6dac72

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

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

Reverts pathway draft to the current published version

post

Authorizations

HTTPRequired

Path parameters

idstringRequired

Responses

200

OK

creationDatestring · date-timeRequired

draftLastUpdatedAtstring · date-timeRequired

draftStructureVersioninteger · int32Required

hasDraftChangesbooleanRequired

hasThirdPartyBadgesbooleanRequired

issuerIdstringRequired

ID of the issuer where the pathway was created

Example: 62aa04adf5afe00d0a6dac72

lastPublishedAtstring · date-time · nullableOptional

pathwayIdstring · nullableOptionalExample: 66aa04adf5afe00d0a6dac72

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

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

Get published version

get

Authorizations

HTTPRequired

Path parameters

idstringRequired

Responses

200

OK

creationDatestring · date-timeRequired

draftLastUpdatedAtstring · date-timeRequired

draftStructureVersioninteger · int32Required

hasDraftChangesbooleanRequired

hasThirdPartyBadgesbooleanRequired

issuerIdstringRequired

ID of the issuer where the pathway was created

Example: 62aa04adf5afe00d0a6dac72

lastPublishedAtstring · date-time · nullableOptional

pathwayIdstring · nullableOptionalExample: 66aa04adf5afe00d0a6dac72

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

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

Promote current draft version to published

post

Authorizations

HTTPRequired

Path parameters

idstringRequired

Responses

200

OK

creationDatestring · date-timeRequired

draftLastUpdatedAtstring · date-timeRequired

draftStructureVersioninteger · int32Required

hasDraftChangesbooleanRequired

hasThirdPartyBadgesbooleanRequired

issuerIdstringRequired

ID of the issuer where the pathway was created

Example: 62aa04adf5afe00d0a6dac72

lastPublishedAtstring · date-time · nullableOptional

pathwayIdstring · nullableOptionalExample: 66aa04adf5afe00d0a6dac72

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

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

List learners with enrollment gaps in pathway course requirements

get

Authorizations

HTTPRequired

Path parameters

pathwayIdstringRequired

Query parameters

pagestring · min: 1Optional

Index of the requested page (1-based)

Default: 1Example: 1

numstring · min: 1 · max: 50Optional

Number of items to return per page

Default: 10Example: 10

searchQuerystringOptional

Case-insensitive substring match against recipient name or identifier.

elementIdstringOptional

Restrict results to courses required by this pathway step.

groupIdstringOptional

Only return learners who are members of this group.

sortstring · enumOptional

Sort field. Defaults to RECIPIENT_IDENTIFIER.

Possible values:

sortGroupIdstringOptional

Required when sort=GROUP_ENROLLMENT. The course-requirement group to sort enrollment status by.

orderstring · enumOptional

Sort order. Defaults to ASC.

Possible values:

Responses

200

OK

*/*

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/pathways/{pathwayId}/enrollment-gaps

GET /v2/pathways/{pathwayId}/enrollment-gaps HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "courses": [
    {
      "courseId": "1234",
      "domain": "martintarjanyi.instructure.com",
      "groupId": "6816c84d1ff787222b6c4d15",
      "name": "Intro to Project Management"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "hasNextPage": true,
    "nextLink": "text",
    "pageSize": 10,
    "previousLink": "text",
    "totalCount": 100,
    "totalPages": 6
  },
  "recipients": [
    {
      "enrollments": [
        {
          "enrolled": true,
          "groupId": "6816c84d1ff787222b6c4d15"
        }
      ],
      "name": {
        "firstName": "John",
        "informalFullName": "John Doe",
        "lastName": "Doe"
      },
      "recipientIdentifier": {
        "@type": "email",
        "email": "[e-mail]"
      }
    }
  ]
}

Export learners with enrollment gaps in pathway course requirements as CSV

get

Authorizations

HTTPRequired

Path parameters

pathwayIdstringRequired

Query parameters

searchQuerystringOptional

Case-insensitive substring match against recipient name or identifier.

elementIdstringOptional

Restrict results to courses required by this pathway step.

groupIdstringOptional

Only return learners who are members of this group.

sortstring · enumOptional

Sort field. Defaults to RECIPIENT_IDENTIFIER.

Possible values:

sortGroupIdstringOptional

Required when sort=GROUP_ENROLLMENT. The course-requirement group to sort enrollment status by.

orderstring · enumOptional

Sort order. Defaults to ASC.

Possible values:

Responses

200

CSV file containing enrollment gap data, one column per course requirement

text/csv

stringOptionalExample: Learner,Email,Intro to PM,Become a PM Jane Doe,[e-mail],Not enrolled,Enrolled

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/pathways/{pathwayId}/enrollment-gaps/export

GET /v2/pathways/{pathwayId}/enrollment-gaps/export HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

Learner,Email,Intro to PM,Become a PM
Jane Doe,[e-mail],Not enrolled,Enrolled

Evaluate experience on the pathway for a user

post

Authorizations

HTTPRequired

Path parameters

pathwayIdstringRequired

experienceIdstring · uuidRequired

Body

passedbooleanRequired

recipientone ofRequired

or

or

Responses

204

No Content

No content

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

{
  "passed": true,
  "recipient": {
    "@type": "email",
    "email": "[e-mail]"
  }
}

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:[e-mail]) and a passed value (true/false) separated by a comma.

Authorizations

HTTPRequired

Path parameters

pathwayIdstringRequired

experienceIdstring · uuidRequired

Body

stringOptionalExample: recipientId,passed email:[e-mail],true

Responses

200

OK

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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: 49

"recipientId,passed\nemail:[e-mail],true"

{
  "errors": [
    {
      "error": "NOT_SUBSCRIBED",
      "recipientId": {
        "@type": "email",
        "email": "[e-mail]"
      }
    }
  ],
  "successes": [
    {
      "@type": "email",
      "email": "[e-mail]"
    }
  ]
}

Get your own BadgeUser profile

get

Required scopes

This endpoint requires the following scopes:

• : See who you are
• : Update your profile

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Responses

200

OK

application/json

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/users/self

GET /v2/users/self HTTP/1.1
Host: api.badges.parchment.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "result": [
    {
      "agreedTermsVersion": 4,
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "emails": [
        {
          "caseVariants": [
            "text"
          ],
          "email": "[e-mail]",
          "primary": true,
          "verified": true
        }
      ],
      "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
      "entityType": "BadgeUser",
      "firstName": "Jane",
      "hasAgreedToLatestTermsVersion": true,
      "hasPasswordSet": true,
      "id": "5f16c84d1ff787222b6c4d15",
      "informalName": "Jane Doe",
      "lastName": "Doe",
      "marketingOptIn": true,
      "preferredLanguage": "en",
      "recipient": {
        "identity": "[e-mail]",
        "type": "email"
      },
      "telephone": [
        "text"
      ],
      "url": [
        "https://example.com"
      ]
    }
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

Update your own BadgeUser

patch

Required scopes

This endpoint requires the following scopes:

• : See who you are
• : Update your profile

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Body

firstNamestringOptionalExample: Jane

lastNamestringOptionalExample: Doe

marketingOptInbooleanOptionalExample: true

Responses

200

OK

application/json

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

patch/v2/users/self

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
}

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "result": [
    {
      "agreedTermsVersion": 4,
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "emails": [
        {
          "caseVariants": [
            "text"
          ],
          "email": "[e-mail]",
          "primary": true,
          "verified": true
        }
      ],
      "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
      "entityType": "BadgeUser",
      "firstName": "Jane",
      "hasAgreedToLatestTermsVersion": true,
      "hasPasswordSet": true,
      "id": "5f16c84d1ff787222b6c4d15",
      "informalName": "Jane Doe",
      "lastName": "Doe",
      "marketingOptIn": true,
      "preferredLanguage": "en",
      "recipient": {
        "identity": "[e-mail]",
        "type": "email"
      },
      "telephone": [
        "text"
      ],
      "url": [
        "https://example.com"
      ]
    }
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

Update your own BadgeUser

put

Required scopes

This endpoint requires the following scopes:

• : See who you are
• : Update your profile

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Body

firstNamestringOptionalExample: Jane

lastNamestringOptionalExample: Doe

marketingOptInbooleanOptionalExample: true

Responses

200

OK

application/json

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

put/v2/users/self

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
}

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "result": [
    {
      "agreedTermsVersion": 4,
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "emails": [
        {
          "caseVariants": [
            "text"
          ],
          "email": "[e-mail]",
          "primary": true,
          "verified": true
        }
      ],
      "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
      "entityType": "BadgeUser",
      "firstName": "Jane",
      "hasAgreedToLatestTermsVersion": true,
      "hasPasswordSet": true,
      "id": "5f16c84d1ff787222b6c4d15",
      "informalName": "Jane Doe",
      "lastName": "Doe",
      "marketingOptIn": true,
      "preferredLanguage": "en",
      "recipient": {
        "identity": "[e-mail]",
        "type": "email"
      },
      "telephone": [
        "text"
      ],
      "url": [
        "https://example.com"
      ]
    }
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

Get a single BadgeUser profile

get

Required scopes

This endpoint requires the following scopes:

• : See who you are
• : Update your profile

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Responses

200

OK

application/json

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

get/v2/users/{idOrEntityId}

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

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "result": [
    {
      "agreedTermsVersion": 4,
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "emails": [
        {
          "caseVariants": [
            "text"
          ],
          "email": "[e-mail]",
          "primary": true,
          "verified": true
        }
      ],
      "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
      "entityType": "BadgeUser",
      "firstName": "Jane",
      "hasAgreedToLatestTermsVersion": true,
      "hasPasswordSet": true,
      "id": "5f16c84d1ff787222b6c4d15",
      "informalName": "Jane Doe",
      "lastName": "Doe",
      "marketingOptIn": true,
      "preferredLanguage": "en",
      "recipient": {
        "identity": "[e-mail]",
        "type": "email"
      },
      "telephone": [
        "text"
      ],
      "url": [
        "https://example.com"
      ]
    }
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

Update a BadgeUser

patch

Required scopes

This endpoint requires the following scopes:

• : See who you are
• : Update your profile

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

firstNamestringOptionalExample: Jane

lastNamestringOptionalExample: Doe

marketingOptInbooleanOptionalExample: true

Responses

200

OK

application/json

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

patch/v2/users/{idOrEntityId}

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
}

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "result": [
    {
      "agreedTermsVersion": 4,
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "emails": [
        {
          "caseVariants": [
            "text"
          ],
          "email": "[e-mail]",
          "primary": true,
          "verified": true
        }
      ],
      "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
      "entityType": "BadgeUser",
      "firstName": "Jane",
      "hasAgreedToLatestTermsVersion": true,
      "hasPasswordSet": true,
      "id": "5f16c84d1ff787222b6c4d15",
      "informalName": "Jane Doe",
      "lastName": "Doe",
      "marketingOptIn": true,
      "preferredLanguage": "en",
      "recipient": {
        "identity": "[e-mail]",
        "type": "email"
      },
      "telephone": [
        "text"
      ],
      "url": [
        "https://example.com"
      ]
    }
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

Update a BadgeUser

put

Required scopes

This endpoint requires the following scopes:

• : See who you are
• : Update your profile

Authorizations

OAuth2authorizationCodeRequired

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

Authorization URL: Token URL:

Path parameters

idOrEntityIdstringRequired

Body

firstNamestringOptionalExample: Jane

lastNamestringOptionalExample: Doe

marketingOptInbooleanOptionalExample: true

Responses

200

OK

application/json

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

put/v2/users/{idOrEntityId}

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
}

{
  "errorCode": "text",
  "fieldErrors": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  },
  "latestTermsVersion": 1,
  "nonFieldErrors": [
    "text"
  ],
  "result": [
    {
      "agreedTermsVersion": 4,
      "badgrDomain": "badgrsupportgroup.badgr.com",
      "emails": [
        {
          "caseVariants": [
            "text"
          ],
          "email": "[e-mail]",
          "primary": true,
          "verified": true
        }
      ],
      "entityId": "Hey7J-GRSJeu6FNnHQwNyw",
      "entityType": "BadgeUser",
      "firstName": "Jane",
      "hasAgreedToLatestTermsVersion": true,
      "hasPasswordSet": true,
      "id": "5f16c84d1ff787222b6c4d15",
      "informalName": "Jane Doe",
      "lastName": "Doe",
      "marketingOptIn": true,
      "preferredLanguage": "en",
      "recipient": {
        "identity": "[e-mail]",
        "type": "email"
      },
      "telephone": [
        "text"
      ],
      "url": [
        "https://example.com"
      ]
    }
  ],
  "status": {
    "description": "ok",
    "success": true
  },
  "timestamp": "2026-01-01T00:00:00.000Z",
  "validationErrors": [
    "text"
  ],
  "warnings": {
    "ANY_ADDITIONAL_PROPERTY": [
      "text"
    ]
  }
}

Get list of Assertions for the specified scope

get

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

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

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

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

Issue a new Assertion to a recipient

post

Required scopes

This endpoint requires the following scopes:

• : Award badges and update your issuers

Authorizations

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

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

allowDuplicateAwardsbooleanOptional

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

badgeclassstring · nullableOptional

ID or Entity ID of the badge class to be awarded

Example: K829IK8RS6ercwkpeFOn-Q

badgeclassOpenBadgeIdstring · uri · nullableOptional

OB URL of the badge class to be awarded

Example: https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q

expiresstring · date-time · nullableOptional

issuedOnstring · date-time · nullableOptional

Timestamp when the assertion was issued

narrativestring · nullableOptional

Markdown narrative of the achievement

Responses

201

Created

errorCodestring · nullableOptional

latestTermsVersioninteger · int32 · nullableOptional

nonFieldErrorsstring[]Required

timestampstring · date-time · nullableOptional

validationErrorsstring[]Required

400

Bad Request

*/*

404

Not Found

*/*

429

Too Many Requests

*/*

500

Internal Server Error

*/*

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

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

{
  "allowDuplicateAwards": true,
  "badgeclass": "K829IK8RS6ercwkpeFOn-Q",
  "badgeclassOpenBadgeId": "https://api.badgr.io/public/badges/K829IK8RS6ercwkpeFOn-Q",
  "evidence": [
    {
      "audience": "text",
      "description": "text",
      "genre": "text",
      "name": "text",
      "narrative": "text",
      "url": "https://example.com"
    }
  ],
  "expires": "2026-01-01T00:00:00.000Z",
  "extensions": {
    "value": {
      "ANY_ADDITIONAL_PROPERTY": {}
    }
  },
  "issuedOn": "2026-01-01T00:00:00.000Z",
  "narrative": "text",
  "ob3AwardProperties": {
    "activityEnd": "2026-01-01T00:00:00.000Z",
    "activityStart": "2026-01-01T00:00:00.000Z",
    "licenseNumber": "text",
    "role": "text"
  },
  "recipient": {
    "hashed": true,
    "identity": "[e-mail]",
    "type": "email"
  }
}

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