Credly Issued Badges API

openapi: 3.2.0
info:
  title: Credly Web Service Issued Badges API
  description: The Credly Web Service API lets an issuing organization manage verifiable digital credentials (Open Badges) on the Credly platform, owned by Pearson.
  version: '1.0'
  contact:
    name: Credly (Pearson)
    url: https://credly.com
servers:
- url: https://api.credly.com/v1
  description: Production
- url: https://sandbox-api.credly.com/v1
  description: Sandbox
security:
- basicAuth: []
- oauth2: []
tags:
- name: Issued Badges
  description: Badges issued to recipients from a badge template.
paths:
  /organizations/{organization_id}/badges:
    get:
      operationId: listIssuedBadges
      tags:
      - Issued Badges
      summary: List issued badges
      description: Returns a paginated list of issued badges for the organization. Supports filtering (for example by recipient_email) and sorting. (confirmed)
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      - $ref: '#/components/parameters/Page'
      - name: filter
        in: query
        required: false
        schema:
          type: string
        description: Filter expression, e.g. recipient_email::user@example.com.
      - name: sort
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A paginated list of issued badges.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssuedBadgeList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: issueBadge
      tags:
      - Issued Badges
      summary: Issue a badge
      description: Issues a badge to a recipient from a badge template. Requires recipient_email and badge_template_id. (confirmed)
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssueBadgeInput'
      responses:
        '200':
          description: The issued badge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssuedBadgeEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /organizations/{organization_id}/badges/{id}:
    get:
      operationId: getIssuedBadge
      tags:
      - Issued Badges
      summary: Retrieve an issued badge
      description: Returns a single issued badge by ID. (modeled)
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: The issued badge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssuedBadgeEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /organizations/{organization_id}/badges/{id}/replace:
    put:
      operationId: replaceIssuedBadge
      tags:
      - Issued Badges
      summary: Replace an issued badge
      description: Replaces an issued badge (for example, to correct recipient details or move it to a different template), superseding the original. (modeled)
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssueBadgeInput'
      responses:
        '200':
          description: The replacement issued badge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssuedBadgeEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /organizations/{organization_id}/badges/{id}/revoke:
    put:
      operationId: revokeIssuedBadge
      tags:
      - Issued Badges
      summary: Revoke an issued badge
      description: Revokes an issued badge with an optional reason. A badge that has been replaced cannot be revoked. (confirmed)
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      - $ref: '#/components/parameters/Id'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: Reason the badge is being revoked.
                suppress_revoke_notification_email:
                  type: boolean
      responses:
        '200':
          description: The revoked issued badge.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssuedBadgeEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    IssuedBadgeList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/IssuedBadge'
        metadata:
          $ref: '#/components/schemas/Metadata'
    IssuedBadge:
      type: object
      properties:
        id:
          type: string
        state:
          type: string
          enum:
          - accepted
          - pending
          - rejected
          - revoked
        recipient_email:
          type: string
        issued_at:
          type: string
          format: date-time
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
        issuer_earner_id:
          type:
          - string
          - 'null'
        badge_template:
          $ref: '#/components/schemas/BadgeTemplate'
    IssueBadgeInput:
      type: object
      required:
      - recipient_email
      - badge_template_id
      properties:
        recipient_email:
          type: string
          format: email
        badge_template_id:
          type: string
        issued_at:
          type: string
          format: date-time
        issued_to_first_name:
          type: string
        issued_to_last_name:
          type: string
        issuer_earner_id:
          type: string
        expires_at:
          type: string
          format: date-time
        locale:
          type: string
          enum:
          - en
          - fr
          - de
          - ko
          - ja
          - zh-CN
          - pt
          - es-ES
          - es-US
          - fr-CA
          - pt-BR
        suppress_badge_notification_email:
          type: boolean
    Metadata:
      type: object
      description: Pagination and response metadata.
      properties:
        count:
          type: integer
        current_page:
          type: integer
        total_count:
          type: integer
        total_pages:
          type: integer
        per:
          type: integer
    IssuedBadgeEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/IssuedBadge'
    BadgeTemplate:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        image_url:
          type: string
        state:
          type: string
          enum:
          - active
          - archived
          - draft
        skills:
          type: array
          items:
            type: object
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
              field:
                type: string
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The resource ID.
      schema:
        type: string
    OrganizationId:
      name: organization_id
      in: path
      required: true
      description: The ID of the issuing organization.
      schema:
        type: string
    Page:
      name: page
      in: query
      required: false
      description: The page number of paginated results.
      schema:
        type: integer
        minimum: 1
        default: 1
  responses:
    UnprocessableEntity:
      description: The request was well-formed but could not be processed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication failed or was not provided.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using the organization's authorization_token as the username and a blank password.
    oauth2:
      type: oauth2
      description: OAuth 2.0 client_credentials grant. Tokens are short-lived (2 hours) and sent as a Bearer token.
      flows:
        clientCredentials:
          tokenUrl: https://api.credly.com/oauth/token
          scopes:
            read: Read access to organization resources.
            issue: Issue and manage badges.
            workforce: Access to employee/workforce data.