Skip to content

Getting Started

The information and diagrams below will give you a basic overview of how the Acclaim system works and how to integrate with the API.

Architecture Diagram

This diagram shows how all of the components of the Badging Platform fit together.

Diagram
  • The external platform makes calls to the Acclaim Acclaim Platform REST API. Requests and responses are formatted as JSON.
  • The Acclaim Platform consists of a database, REST web service, and the Acclaim website.
  • The Acclaim Platform communicates with earners via email. Earners interact with the Acclaim website using a web browser.

Issuing a Badge

This process diagram illustrates how an External Platform can issue a badge to a new user and how the user can share their badge via social media.

  1. The External Platform makes a POST request to the badges API endpoint with a JSON payload describing the badge to be issued.
  2. The Acclaim web service responds with HTTP status 201 Created if the badge was issued successfully.
  3. The Acclaim web service sends an email notification to the Earner containing a link to the Acclaim web site, which can be used to accept the badge.
  4. The Earner clicks on the accept badge link from the email notification.
  5. The Acclaim web site responds to the Earner's web browser request by requiring the Earner to register a new account.
  6. The Earner fills in the registration form and submits it to the Acclaim web site.
  7. The Acclaim web site sends an email to the address provided by the Earner, which contains a link that the Earner must click to confirm their account.
  8. The Earner clicks the email confirmation link, which confirms their registration.
  9. The Acclaim web site displays the Earner's profile, where the Earner can accept the new badge.
  10. After accepting the badge, the Earner can share the badge to social media or by email. For example, the Earner may choose to share by email with an Employer.
  11. The Acclaim platform sends the Employer a share badge email, which contains a link to the Acclaim web site, where the Employer can verify the badge information.

Getting Issued Badges

This process diagram shows how an External Platform can retrieve a list of badges issued to a user. Refer to the API documentation for a full list of filter options.

Getting Issued Badges by User ID

  • The External platform issues a GET request to the Acclaim web service via the Issued Badges API endpoint filtering by user ID. Example URL: /organizations/99/badges.json?filter=user_id::2
  • The Acclaim web service responds with JSON describing badges issued to user ID 2.

Getting Issued Badges by Email Address

  • The External platform issues a GET request to the Acclaim web service via the Issued Badges API endpoint filtering by email address. Example URL: /organizations/99/badges.json?filter=query::
  • The Acclaim web service responds with JSON describing badges issued to user with

Revoking a Badge

This process diagram illustrates how an External Platform can revoke a badge that has been issued to a user.

  • The External platform issues a POST request to the Acclaim web service via the Issued Badges API endpoint filtering by email address. Example URL: /organizations/99/badges//revoke.json
  • The Acclaim web service responds with 200 OK status and JSON describing badge with ID , including its updated state of "revoked".