Getting Started

The information and diagrams below will give you a basic overview of how the Credly 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 Credly Platform REST API. Requests and responses are formatted as JSON.
  • The Credly Platform consists of a database, REST web service, and the Credly website.
  • The Credly Platform communicates with earners via email. Earners interact with the Credly 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 Credly web service responds with HTTP status 201 Created if the badge was issued successfully.
  3. The Credly web service sends an email notification to the Earner containing a link to the Credly 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 Credly 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 Credly web site.
  7. The Credly 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 Credly 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 Credly platform sends the Employer a share badge email, which contains a link to the Credly 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 Credly web service via the Issued Badges API endpoint filtering by user ID. Example URL: /organizations/99/badges.json?filter=user_id::2
  • The Credly 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 Credly web service via the Issued Badges API endpoint filtering by email address. Example URL: /organizations/99/badges.json?filter=query::
  • The Credly 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 Credly web service via the Issued Badges API endpoint filtering by email address. Example URL: /organizations/99/badges//revoke.json
  • The Credly web service responds with 200 OK status and JSON describing badge with ID , including its updated state of "revoked".