Openbadges.me allows you to issue badges using a powerful set of Application program interfaces (APIs). These APIs support the direct issuing of a specific badge to a specific recipient or the automatic event rules-based issuing of badges.
Calls to the API services can easily be integrated into organisational application software to trigger the awarding and issuing of Openbadges.me badges.
Getting Started
Before you can start using the APIs you must set-up a developer key and have a security authentication token. These will ensure your data is protected and secure within openbadges.me.
To set these up just go to the API keys section within System settings of Openbadges.me account.
All API service calls are called from https://events.openbadges.me
A developer guide to using the API is available on the following link:
https://events.openbadges.me/swagger/index.html?url=/swagger/v1/swagger.json
Issue badge API
Issuing a badge to a recipient
Every badge within Openbadges.me has a unique identifier that can be used to directly issue a badge to single or multiple recipients via the Events API.
The badge identifier can be found on the Openbadges.me badge summary screen (bottom left corner).
With the unique badge identifier, you can use the API ‘/api/ActivityEvents’ service to issue that badge: https//events.openbadges.me/api/ActivityEvents
To issue a badge, you will need to pass the following fields to the API:
ActivityId: The unique badge identifier
ActivityTime: The date and time the badge was achieved
UserId: Unique recipient id, which can be an email or reference number
Email: The email address of the recipient
FirstName: The first name of the recipient
LastName: The surname name of the recipient
Example JSON used
Issuing multiple badges to multiple recipients
Using the API, with one service call, a single badge can be issued to multiple recipients, a single recipient can be issued multiple different badges, or a collection of different badges could be issue to a collection of differing recipients.
To use this bulk badge issuing service use the ‘/api/ActivityEvents/bulk’ service endpoint: https//events.openbadges.me/api/ActivityEvents/bulk
The JSON data object used to pass data into the service call is a collection of JSON data objects (attribute-value pairs) used for the single badge issuing service call.
For example, in the JSON data block below, Jane is being awarded two badges, Numeracy Essentials Parts 1 and 2, while Simon is being awarded Numeracy Essentials Part 1.
For further document on the how to use this API, go to:
https://events.openbadges.me/swagger/index.html?url=/swagger/v1/swagger.json
Reporting API
Using the Events API reporting services, you can:
- Get the recipients of all awarded badges
- Get the recipients of a single badge
Get recipients for all badges
If your organisation has been issuing badges using the Events API, you can get a listing of all the awarded badges, for a specified date range, by calling the Events API ‘/api/ActivityEvents/entries’ service endpoint:
https://events.openbadges.me/api/ActivityEvents/entries
To call this service you need to provide a ‘From’ and ‘To’ date to the service call.
Example returned JSON data object:
The ‘ActivityId’ field is the badge identifier. The “UserId” field contains who the badge was issued to. The ‘CreatedOn’ field holds the date the badge was issued.
Get recipients for a single badge
There is another service endpoint that lets you get a listing of all the badge recipients for a single badge. The Events API service endpoint is ‘api/{id}/entries’.
For example, to get a listing of all the recipients of the Numeracy Essentials Part 1 badge, the Events API service endpoint would look like this:
https://events.openbadges.me/api/OB-60ff00b6-aca0-4860-aa1e-3112251739bf/entries
Example returned JSON data object: