Badges

The Opigno Enterprise API provides queries retrieve the available achievements information, along with the user’s current earning status. Each badge represents a specific goal or condition that a user may fulfill such as completing an action, reaching a defined threshold, or maintaining a certain level of engagement.

Data Structure

Badge

An achievement object that might be earned by user.

Field	Type	Description
`id`	`ID!`	The Badge entity ID.
`title`	`String!`	The title of the Badge.
`picture`	`MediaImage!`	`MediaImage` object representing the Badge picture.
`status`	`BadgeStatus!`	The status of the badge.
`earned(format: String)`	`String`	A string showing the badge earning time, formatted according to the optional `format` argument (default: `d/m/Y`). Empty if the badge status is not `EARNED`.
`earningCriteria`	`BadgeEarningCriteria!`	An earning criteria definition for the badge.

BadgeEarningCriteria

A union of available criteria types that describes a condition for badge earning

BadgeEarningCriteriaLpComplete

Represents criteria for badge earning by Learning Path accomplishment.

Field	Type	Description
`learningPathId`	`ID!`	The Learning Path ID required to accomplish.

BadgeEarningCriteriaLpPassed

Represents criteria for badge earning by successful Learning Path accomplishment.

Field	Type	Description
`learningPathId`	`ID!`	The Learning Path ID required to successfully accomplish.

BadgeEarningCriteriaLpEnroll

Represents criteria for badge earning by Learning Path enrollment.

Field	Type	Description
`learningPathId`	`ID!`	The Learning Path ID required for enrollment.

BadgeEarningCriteriaSocialConnection

Represents criteria for badge earning by reaching the required number of established social connections.

Field	Type	Description
`threshold`	`Int!`	The number of connections required to be established.
`currentThreshold`	`Int!`	The number of social connections already established.
`period`	`Int`	Optional period parameter. If specified, the badge can be earned only if the threshold has been reached within the number of seconds defined by this period.

BadgeEarningCriteriaSocialEngagement

Represents criteria for badge earning based on the total number of social posts created.

Field	Type	Description
`threshold`	`Int!`	The number of social posts required to be created.
`currentThreshold`	`Int!`	The number of social posts already created.

BadgeEarningCriteriaRegisteredFor

Represents criteria for badge earning based on the user’s registration duration, requiring the user account to exist for a specified period of time.

Field	Type	Description
`threshold`	`Int!`	The number of seconds the user account must exist.
`currentThreshold`	`Int!`	The number of seconds the user account has already existed.

Queries

getBadge

This query is used to retrieve a single badge information.

You must have AUTHENTICATED scope to access badges. Anonymous users cannot retrieve badges data.
The API user context must be present and valid - otherwise, access is denied.

The following arguments can be used in the query:

Argument	Type	Description
`badgeId`	`ID`	The badge entity ID.
`userContextUuid`	`ID`	The user context UUID. If omitted, the user context from the API request will be used.

query getBadges {
  getBadges(
    badgeId: 2,
  ) {
    id
    title
    picture {
      url
    }
    status
    earned(format: "d/m/y")
  }
}

{
  "data": {
    "getBadge": {
      "id": "2",
      "title": "Training passed!",
      "picture": {
        "url": "http://backoffice-site.url/path-to-badge-icon/icon.png"
      },
      "status": "EARNED",
      "earned": "22/10/25"
    }
  }
}

getBadges

This query is used to retrieve the full badges list available and supports cursor-based pagination (after, before) or limit-based (first, last).

You must have AUTHENTICATED scope to access badges. Anonymous users cannot retrieve badges data.
The API user context must be present and valid - otherwise, access is denied.

The following arguments can be used in the query:

Argument	Type	Description
`userContextUuid`	`ID`	The user context UUID. If omitted, the user context from the API request will be used.
`status`	`BadgeStatus`	The earning status of the badge.
`title`	`String`	Allows to search by the badge title; operator “CONTAINS”.
`after`	`Cursor`	Returns the elements that come before the specified cursor.
`before`	`Cursor`	Returns results that come before the specified cursor. Should be used together with `last` parameter. Cannot be used if `after` is set.
`first`	`Integer`	Returns up to the first N elements from the list. Required if `after` parameter is set. Cannot be used together with `last`.
`last`	`Integer`	Returns up to the first N elements from the list. Required if `before` parameter is set. Cannot be used together with `first`.
`reverse`	`Boolean`	Allows to change the order of the sorting to `DESC`.
`sortKey`	`BadgeSortKey`	Sort the underlying list by the given key. By default badges will be sorted by the creation date.

query getBadges {
  getBadges(
    first: 3,
    status: EARNED,
  ) {
    edges {
      node {
        id
        title
        picture {
          url
        }
        status
        earned(format: "d/m/y")
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalItems
  }
}

{
  "data": {
    "getBadges": {
      "edges": [
        {
          "node": {
            "id": "1",
            "title": "Training completed",
            "picture": {
              "url": "http://backoffice-site.url/path-to-badge-icon/icon.png"
            },
            "status": "EARNED",
            "earned": "22/10/25"
          }
        },
        {
          "node": {
            "id": "2",
            "title": "Training passed!",
            "picture": {
              "url": "http://backoffice-site.url/path-to-badge-icon/icon.png"
            },
            "status": "EARNED",
            "earned": "22/10/25"
          }
        },
        {
          "node": {
            "id": "3",
            "title": "Registered to training",
            "picture": {
              "url": "http://backoffice-site.url/path-to-badge-icon/icon.png"
            },
            "status": "EARNED",
            "earned": "22/10/25"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "TzozMzoiRHJ1cGFsXG9waWdub19hcGlcV3JhcHBlcnNcQ3Vyc29yIjo0OntzOjE0OiIAKgBiYWNraW5nVHlwZSI7czoxMjoib3BpZ25vX2JhZGdlIjtzOjEyOiIAKgBiYWNraW5nSWQiO2k6MztzOjEwOiIAKgBzb3J0S2V5IjtzOjc6IkNSRUFURUQiO3M6MTI6IgAqAHNvcnRWYWx1ZSI7czoxMDoiMTc2MTEyMjA2OSI7fQ=="
      },
      "totalItems": 4
    }
  }
}

The getBadges query supports the same advanced features as other catalog queries:

Pagination

Learn how to efficiently navigate through large sets of badges using cursor-based pagination.

Authentication

Understand the authentication requirements and how to properly authenticate your requests.

Common error scenarios and solutions:

Authentication Errors

401 Unauthorized: Ensure you’re using a valid authentication token with AUTHENTICATED scope
403 Forbidden: Verify your user account has the necessary permissions to access badges data

Pagination Errors

Missing cursor parameter: When using after, you must also specify first
Invalid cursor: Ensure cursor values are valid and not expired
Conflicting parameters: Don’t use both first/after and last/before together

Getting started

Integration & Concepts

Use cases

Hierarchy Management

Zapier Integration

Mobile application

Data Structure

Badge

BadgeEarningCriteria

BadgeEarningCriteriaLpComplete

BadgeEarningCriteriaLpPassed

BadgeEarningCriteriaLpEnroll

BadgeEarningCriteriaSocialConnection

BadgeEarningCriteriaSocialEngagement

BadgeEarningCriteriaRegisteredFor

Queries

getBadge

getBadges

Pagination

Authentication

​Data Structure

​Badge

​BadgeEarningCriteria

​BadgeEarningCriteriaLpComplete

​BadgeEarningCriteriaLpPassed

​BadgeEarningCriteriaLpEnroll

​BadgeEarningCriteriaSocialConnection

​BadgeEarningCriteriaSocialEngagement

​BadgeEarningCriteriaRegisteredFor

​Queries

​getBadge

​getBadges

​Related Features

Pagination

Authentication

Data Structure

Badge

BadgeEarningCriteria

BadgeEarningCriteriaLpComplete

BadgeEarningCriteriaLpPassed

BadgeEarningCriteriaLpEnroll

BadgeEarningCriteriaSocialConnection

BadgeEarningCriteriaSocialEngagement

BadgeEarningCriteriaRegisteredFor

Queries

getBadge

getBadges

Related Features