Certifier Credential Templates API

openapi: 3.2.0
info:
  title: Certifier Credential Templates API
  version: '2022-10-26'
  description: 'The Certifier API uses access tokens to authenticate requests. You can view and manage your access tokens in the Certifier Dashboard.


    Your access tokens carry many privileges, so be sure to keep them secure! Do not share your secret access tokens in publicly accessible areas such as GitHub, client-side code, and so forth.


    **Authentication** is performed via HTTP Bearer Auth. Provide your access token in the `Authorization` header with Bearer auth-scheme and `Certifier-Version` header:


    ```

    Authorization: Bearer

    Certifier-Version: 2022-10-26

    ```


    All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.'
servers:
- url: https://api.certifier.io
  description: Production server
security:
- BearerAuth: []
tags:
- name: Credential Templates
  description: Endpoints for managing credential templates (groups)
paths:
  /v1/groups:
    post:
      tags:
      - Credential Templates
      summary: Create a credential template
      description: 'Use this endpoint to create a credential template (group).


        Groups are being renamed to Credential Templates to better reflect their purpose. This is a **naming update only** — all functionality remains the same.


        During the transition, you may still see both terms used interchangeably across the API, app, and existing integrations.


        For backward compatibility, this endpoint still accepts the legacy `certificateDesignId` and `badgeDesignId` request fields for the time being. Those fields are deprecated, intentionally omitted from the request schema below, and may be removed without notice. Use `designIds` for all new integrations.


        If you use the legacy request shape, the response will also temporarily include legacy `certificateDesignId` and `badgeDesignId` fields for compatibility.'
      security:
      - BearerAuth: []
      parameters:
      - schema:
          type: string
          default: '2022-10-26'
          example: '2022-10-26'
          description: API version header. Required for all requests.
        required: true
        description: API version header. Required for all requests.
        name: Certifier-Version
        in: header
        example: '2022-10-26'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroup'
      responses:
        '201':
          description: Credential template (group) created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          description: Bad Request - Missing version, invalid version, invalid JSON, or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_version:
                  value:
                    error:
                      code: missing_version
                      message: The request is missing the required Certifier-Version header
                invalid_version:
                  value:
                    error:
                      code: invalid_version
                      message: The Certifier-Version header's value is invalid
                invalid_json:
                  value:
                    error:
                      code: invalid_json
                      message: The request body can not be decoded as JSON
                validation_error:
                  value:
                    error:
                      code: validation_error
                      message: This usually occurs because of a missing or malformed parameter
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: unauthorized
                  message: A valid authentication token was not provided with the request
        '402':
          description: Payment Required - Feature requires premium subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: payment_required
                  message: The requested feature is only available to premium organizations
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: not_found
                  message: The requested resource does not exist
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limited
                  message: You have exceeded the rate limit
        '500':
          description: Internal Server Error - Problem on Certifier's end
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_server_error
                  message: There was a problem on Certifier's end
      operationId: postV1Groups
      x-operation-id-source: derived
    get:
      tags:
      - Credential Templates
      summary: List credential templates
      description: 'Use this endpoint to list credential templates (groups).


        Groups are being renamed to Credential Templates to better reflect their purpose. This is a **naming update only** — all functionality remains the same.


        During the transition, you may still see both terms used interchangeably across the API, app, and existing integrations.'
      security:
      - BearerAuth: []
      parameters:
      - schema:
          type: string
          description: Cursor for pagination
        required: false
        description: Cursor for pagination
        name: cursor
        in: query
      - schema:
          type: integer
          nullable: true
          maximum: 100
          description: 'Number of items to return (default: 20)'
          example: 20
        required: false
        description: 'Number of items to return (default: 20)'
        name: limit
        in: query
      - schema:
          type: string
          default: '2022-10-26'
          example: '2022-10-26'
          description: API version header. Required for all requests.
        required: true
        description: API version header. Required for all requests.
        name: Certifier-Version
        in: header
        example: '2022-10-26'
      responses:
        '200':
          description: List of credential templates (groups)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Group'
                  pagination:
                    type: object
                    properties:
                      prev:
                        type: string
                        nullable: true
                        example: null
                        description: Cursor for previous page
                      next:
                        type: string
                        nullable: true
                        example: null
                        description: Cursor for next page
                    required:
                    - prev
                    - next
                required:
                - data
                - pagination
        '400':
          description: Bad Request - Missing version, invalid version, invalid JSON, or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_version:
                  value:
                    error:
                      code: missing_version
                      message: The request is missing the required Certifier-Version header
                invalid_version:
                  value:
                    error:
                      code: invalid_version
                      message: The Certifier-Version header's value is invalid
                invalid_json:
                  value:
                    error:
                      code: invalid_json
                      message: The request body can not be decoded as JSON
                validation_error:
                  value:
                    error:
                      code: validation_error
                      message: This usually occurs because of a missing or malformed parameter
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: unauthorized
                  message: A valid authentication token was not provided with the request
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limited
                  message: You have exceeded the rate limit
        '500':
          description: Internal Server Error - Problem on Certifier's end
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_server_error
                  message: There was a problem on Certifier's end
      operationId: getV1Groups
      x-operation-id-source: derived
  /v1/groups/{id}:
    delete:
      tags:
      - Credential Templates
      summary: Delete a credential template
      description: 'Permanently deletes a credential template (group). This cannot be undone.


        Groups are being renamed to Credential Templates to better reflect their purpose. This is a **naming update only** — all functionality remains the same.


        During the transition, you may still see both terms used interchangeably across the API, app, and existing integrations.'
      security:
      - BearerAuth: []
      parameters:
      - schema:
          type: string
          description: The unique ID of the credential template (group).
          example: 01g90279gp5sbmfek7wymcsvec
        required: true
        description: The unique ID of the credential template (group).
        name: id
        in: path
      - schema:
          type: string
          default: '2022-10-26'
          example: '2022-10-26'
          description: API version header. Required for all requests.
        required: true
        description: API version header. Required for all requests.
        name: Certifier-Version
        in: header
        example: '2022-10-26'
      responses:
        '204':
          description: Credential template (group) deleted successfully
        '400':
          description: Bad Request - Missing version, invalid version, invalid JSON, or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_version:
                  value:
                    error:
                      code: missing_version
                      message: The request is missing the required Certifier-Version header
                invalid_version:
                  value:
                    error:
                      code: invalid_version
                      message: The Certifier-Version header's value is invalid
                invalid_json:
                  value:
                    error:
                      code: invalid_json
                      message: The request body can not be decoded as JSON
                validation_error:
                  value:
                    error:
                      code: validation_error
                      message: This usually occurs because of a missing or malformed parameter
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: unauthorized
                  message: A valid authentication token was not provided with the request
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: not_found
                  message: The requested resource does not exist
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limited
                  message: You have exceeded the rate limit
        '500':
          description: Internal Server Error - Problem on Certifier's end
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_server_error
                  message: There was a problem on Certifier's end
      operationId: deleteV1GroupsById
      x-operation-id-source: derived
    get:
      tags:
      - Credential Templates
      summary: Get a credential template
      description: 'Use this endpoint to get a specific credential template (group).


        Groups are being renamed to Credential Templates to better reflect their purpose. This is a **naming update only** — all functionality remains the same.


        During the transition, you may still see both terms used interchangeably across the API, app, and existing integrations.'
      security:
      - BearerAuth: []
      parameters:
      - schema:
          type: string
          description: The unique ID of the credential template (group).
          example: 01g90279gp5sbmfek7wymcsvec
        required: true
        description: The unique ID of the credential template (group).
        name: id
        in: path
      - schema:
          type: string
          default: '2022-10-26'
          example: '2022-10-26'
          description: API version header. Required for all requests.
        required: true
        description: API version header. Required for all requests.
        name: Certifier-Version
        in: header
        example: '2022-10-26'
      responses:
        '200':
          description: Credential template (group) details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          description: Bad Request - Missing version, invalid version, invalid JSON, or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_version:
                  value:
                    error:
                      code: missing_version
                      message: The request is missing the required Certifier-Version header
                invalid_version:
                  value:
                    error:
                      code: invalid_version
                      message: The Certifier-Version header's value is invalid
                invalid_json:
                  value:
                    error:
                      code: invalid_json
                      message: The request body can not be decoded as JSON
                validation_error:
                  value:
                    error:
                      code: validation_error
                      message: This usually occurs because of a missing or malformed parameter
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: unauthorized
                  message: A valid authentication token was not provided with the request
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: not_found
                  message: The requested resource does not exist
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limited
                  message: You have exceeded the rate limit
        '500':
          description: Internal Server Error - Problem on Certifier's end
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_server_error
                  message: There was a problem on Certifier's end
      operationId: getV1GroupsById
      x-operation-id-source: derived
    patch:
      tags:
      - Credential Templates
      summary: Update a credential template
      description: 'Updates the specified credential template (group) by setting the values of the parameters passed. Any parameters not provided will be left unchanged.


        Groups are being renamed to Credential Templates to better reflect their purpose. This is a **naming update only** — all functionality remains the same.


        During the transition, you may still see both terms used interchangeably across the API, app, and existing integrations.


        For backward compatibility, this endpoint still accepts the legacy `certificateDesignId` and `badgeDesignId` request fields for the time being. Those fields are deprecated, intentionally omitted from the request schema below, and may be removed without notice. Do not send both `designIds` and the legacy fields in the same request.


        If you use the legacy request shape, the response will also temporarily include legacy `certificateDesignId` and `badgeDesignId` fields for compatibility.'
      security:
      - BearerAuth: []
      parameters:
      - schema:
          type: string
          description: The unique ID of the credential template (group).
          example: 01g90279gp5sbmfek7wymcsvec
        required: true
        description: The unique ID of the credential template (group).
        name: id
        in: path
      - schema:
          type: string
          default: '2022-10-26'
          example: '2022-10-26'
          description: API version header. Required for all requests.
        required: true
        description: API version header. Required for all requests.
        name: Certifier-Version
        in: header
        example: '2022-10-26'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGroup'
      responses:
        '200':
          description: Credential template (group) updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          description: Bad Request - Missing version, invalid version, invalid JSON, or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_version:
                  value:
                    error:
                      code: missing_version
                      message: The request is missing the required Certifier-Version header
                invalid_version:
                  value:
                    error:
                      code: invalid_version
                      message: The Certifier-Version header's value is invalid
                invalid_json:
                  value:
                    error:
                      code: invalid_json
                      message: The request body can not be decoded as JSON
                validation_error:
                  value:
                    error:
                      code: validation_error
                      message: This usually occurs because of a missing or malformed parameter
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: unauthorized
                  message: A valid authentication token was not provided with the request
        '402':
          description: Payment Required - Feature requires premium subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: payment_required
                  message: The requested feature is only available to premium organizations
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: not_found
                  message: The requested resource does not exist
        '429':
          description: Rate Limited - Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limited
                  message: You have exceeded the rate limit
        '500':
          description: Internal Server Error - Problem on Certifier's end
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_server_error
                  message: There was a problem on Certifier's end
      operationId: patchV1GroupsById
      x-operation-id-source: derived
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
              example: validation_error
            message:
              type: string
              description: Human-readable error message
              example: The request body contains invalid or missing fields
          required:
          - code
          - message
      required:
      - error
    UpdateGroup:
      type: object
      properties:
        name:
          type: string
          description: The name of the credential template (group) that is used as [group.name] attribute later on
          example: Updated Financial Markets
        designIds:
          type: array
          items:
            type: string
          minItems: 1
          description: Replaces the ordered list of design template IDs associated with the credential template.
          example:
          - 01fpwtztwf7sacca5r0c483mnm
          - 01hz2ej4yzdcfkq9fa78nhyj0x
        learningEventUrl:
          type: string
          format: uri
          description: The learning event's URL that is shown in the digital wallet
          example: https://www.coursera.org/learn/financial-markets-global
    Group:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the credential template (group).
          example: 01g90279gp5sbmfek7wymcsvec
        name:
          type: string
          description: The name of the credential template (group) that is used as [group.name] attribute later on
          example: Financial Markets
        learningEventUrl:
          type: string
          nullable: true
          format: uri
          description: The learning event's URL that is shown in the digital wallet
          example: https://www.coursera.org/learn/financial-markets-global
        designIds:
          type: array
          items:
            type: string
          description: The ordered list of design template IDs associated with this credential template.
          example:
          - 01fpwtztwf7sacca5r0c483mnm
          - 01hz2ej4yzdcfkq9fa78nhyj0x
        certificateDesignId:
          type: string
          nullable: true
          description: Legacy field, to be removed. Returns the first ordered certificate design ID from designIds, or null when no certificate design is associated. Present only when the legacy request shape was used.
          example: 01fpwtztwf7sacca5r0c483mnm
          deprecated: true
        badgeDesignId:
          type: string
          nullable: true
          description: Legacy field, to be removed. Returns the first ordered badge design ID from designIds, or null when no badge design is associated. Present only when the legacy request shape was used.
          example: 01hz2ej4yzdcfkq9fa78nhyj0x
          deprecated: true
        createdAt:
          type: string
          format: date-time
          description: The date and time when this credential template (group) was created. Formatted as an ISO 8601 date and time string
          example: '2022-01-01T00:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: The date and time when this credential template (group) was updated. Formatted as an ISO 8601 date and time string
          example: '2022-01-01T00:00:00.000Z'
      required:
      - id
      - name
      - learningEventUrl
      - designIds
      - certificateDesignId
      - badgeDesignId
      - createdAt
      - updatedAt
    CreateGroup:
      type: object
      properties:
        name:
          type: string
          description: The name of the credential template (group) that is used as [group.name] attribute later on
          example: Financial Markets
        designIds:
          type: array
          items:
            type: string
          minItems: 1
          description: The ordered list of design template IDs associated with the credential template..
          example:
          - 01fpwtztwf7sacca5r0c483mnm
          - 01hz2ej4yzdcfkq9fa78nhyj0x
        learningEventUrl:
          type: string
          format: uri
          description: The learning event's URL that is shown in the digital wallet
          example: https://www.coursera.org/learn/financial-markets-global
      required:
      - name
      - designIds
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Provide your access token in the Authorization header with Bearer auth-scheme. You can view and manage your access tokens in the Certifier Dashboard.