Web Service API

This document describes the Credly web service API, a REST service that allows organizations to manage their badges and issue badges on behalf of other organizations.

API Conventions

• All requests must use SSL.
• Authentication is handled via HTTP Basic Authentication or via OAuth 2.0 as described below.
• All requests must be in JSON format with Content-Type: application/json
• Clients of the web service must accept JSON as response data.
• All references to static assets (e.g. image_url in Get Badges response and photo_url in List Organization responses) are subject to change. These resource locations can always be found by calling the appropriate API.

API Versions

• 1.0 is the current version.

Backwards Compatibility

We won't introduce backwards-incompatible changes to a specific version of the API. If backwards-incompatible changes are necessary to support new features, then a new version of the API will be introduced. When a new version is introduced, both the new version and the prior version will be supported simultaneously. The prior version of the API will eventually be deprecated and removed.

Backwards- compatible changes include:

• Adding a new attribute to an existing object is backwards-compatible.
• Adding a new API path is backwards-compatible.

Backwards- incompatible changes include:

• Changing or removing an existing path name is backwards-incompatible.
• Changing or removing an existing object name is backwards-incompatible.
• Changing or removing an existing attribute name is backwards-incompatible.

URL Construction

Web service URLs are constructed as follows:

Production Environment

https://api.credly.com/v1/<endpoint_path>

Sandbox Environment

We recommend that you develop and test your integration against our sandbox environment before moving to production. URLs for requests to the sandbox environment are constructed as follows:

https://sandbox-api.credly.com/v1/<endpoint_path>

Authentication

Authentication can be done by using Authorization Tokens or OAuth 2.0. Please see the relevant documentation for each authentication mechanism for more information.

• Authorization Tokens
• OAuth 2.0

Web Service Responses

Wrapped Responses

The web service wraps responses with the following format:

{
  data: {
    <response data>
  },
  metadata: {
    <response metadata>
  }
}

Only certain responses contain <response metadata>. It's used for returning relevant info for paged results. In particular, Badge Templates and Issued Badges responses are paged and include <response metadata>. Refer to the documentation for those endpoints for details.

Common Errors

If you get the response...

Validation Failures

The web service will validate data when creating and updating a resource. If validation fails, the server will return a 422 status code with a list of attributes that failed validation. The message value will contain a comma-separated list of validation errors, and an array of errors and their respective attribute names will also be included. For example:

{
  data: {
    "message": "Validation failed: Email can't be blank, ...",
    "errors": [
      {
        "attribute": "email",
        "messages": [
          "can't be blank",
          ...
        ]
      },
      ...
    ]
  }
}