Certifier Credential Interactions API

openapi: 3.2.0
info:
  title: Certifier Credential Interactions 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 Interactions
  description: Endpoints for tracking and managing credential interaction events
paths:
  /v1/credential-interactions:
    post:
      tags:
      - Credential Interactions
      summary: Create a credential interaction
      description: 'Creates a new credential interaction event.


        This feature uses the browser''s `LocalStorage` to identify the actions made by the recipient of the credential. When the user accesses the page with `?recipient=true` query parameter, the application saves that information in `LocalStorage` and removes the parameter from the URL. Actions taken afterwards in the same browser are recorded as the recipient''s, until the `LocalStorage` data is cleared.


        If you are distributing the credential links independently and wish to track events as originating from the recipient, be sure to include the `?recipient=true` parameter. Without this parameter, we won''t be able to mark this person as the recipient, and their actions will be marked under the `guest` actor category.


        This approach may not capture every scenario. For example, if a recipient opens a link with `?recipient=true` on one device, then shares the link without the parameter (or opens it on a different device without the stored flag), those subsequent views will be categorized as `guest`. Similarly, if the user clears their `LocalStorage` or uses an incognito session, the system can no longer confirm that they are the recipient.'
      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/CreateCredentialInteraction'
      responses:
        '200':
          description: Credential interaction created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialInteraction'
        '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: postV1CredentialInteractions
      x-operation-id-source: derived
    get:
      tags:
      - Credential Interactions
      summary: List credential interactions
      description: Returns a list of credential interactions, optionally filtered by credential ID.
      security:
      - BearerAuth: []
      parameters:
      - schema:
          type: string
          description: The unique credential's identifier
          example: 01hrsvjp560yksep2a3bek3z97
        required: false
        description: The unique credential's identifier
        name: credentialId
        in: query
      - schema:
          type: string
          description: Cursor for pagination
          example: null
        required: false
        description: Cursor for pagination
        name: cursor
        in: query
      - schema:
          type: integer
          nullable: true
          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 interactions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CredentialInteraction'
                  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: getV1CredentialInteractions
      x-operation-id-source: derived
components:
  schemas:
    CreateCredentialInteraction:
      type: object
      properties:
        credentialId:
          type: string
          description: The unique credential's identifier, to which this credential interaction belongs
          example: 01hrsvjp560yksep2a3bek3z97
        eventType:
          type: string
          enum:
          - credential_viewed
          - credential_shared_to_linkedin
          - credential_added_to_linkedin_profile
          - credential_shared_to_facebook
          - credential_shared_to_twitter
          - credential_shared_to_messenger
          - credential_shared_to_whatsapp
          - credential_shared_to_pinterest
          - credential_shared_to_telegram
          - credential_shared_to_weibo
          - credential_downloaded
          - credential_link_copied
          - credential_verified
          description: Specifies the type of user interaction event related to the credential
          example: credential_viewed
        triggeredBy:
          type: string
          enum:
          - recipient
          - guest
          description: 'The actor that triggered this credential interaction. Currently one of two values: recipient or guest'
          example: recipient
        triggeredAt:
          type: string
          format: date-time
          description: The date and time when this credential interaction happened. Formatted as an ISO 8601 date and time string
          example: '2024-03-12T17:33:05.784Z'
      required:
      - credentialId
      - eventType
      - triggeredBy
      - triggeredAt
    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
    CredentialInteraction:
      type: object
      properties:
        id:
          type: string
          description: The unique credential interaction's identifier
          example: 01hrsvk8xnj8vkt8p1e2tc1jt7
        credentialId:
          type: string
          description: The unique credential's identifier, to which this credential interaction belongs
          example: 01hrsvjp560yksep2a3bek3z97
        eventType:
          type: string
          enum:
          - credential_viewed
          - credential_shared_to_linkedin
          - credential_added_to_linkedin_profile
          - credential_shared_to_facebook
          - credential_shared_to_twitter
          - credential_shared_to_messenger
          - credential_shared_to_whatsapp
          - credential_shared_to_pinterest
          - credential_shared_to_telegram
          - credential_shared_to_weibo
          - credential_downloaded
          - credential_link_copied
          - credential_verified
          description: Specifies the type of user interaction event related to the credential
          example: credential_viewed
        triggeredBy:
          type: string
          enum:
          - recipient
          - guest
          description: 'The actor that triggered this credential interaction. Currently one of two values: recipient or guest'
          example: recipient
        triggeredAt:
          type: string
          format: date-time
          description: The date and time when this credential interaction happened. Formatted as an ISO 8601 date and time string
          example: '2024-03-12T17:33:05.784Z'
      required:
      - id
      - credentialId
      - eventType
      - triggeredBy
      - triggeredAt
  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.