Skip to main content

Credly Learning Edition (CLE) SDK

Introduction

This section explains how how to integrate your LTI or oauth-compatible environment, such as Canvas, Moodle or Desire2Learn, with your Credly Enterprise account. Using the Credly CLE SDK, you can manage student badges, create rules to award badges as the result of student achievements, and display a badge-management UI.


Getting Set Up

If You Are a Credly Enterprise Customer

  1. Sign up for a Credly Enterprise account.
  2. Find your API Key and App Secret. You will need these for authentication.
  3. Authenticate as an administrator (see Authentication below), to get a token.
  4. Use the Integration API (documented below) to create one or more integrations (courses), and get integration ids to be used in future requests.
  5. As an Enterprise customer, you have access to the pre-built Credly badge management interface, which can be displayed in an IFrame.

If You Are Not an Enterprise Customer

  1. Create a Credly issuer account at https://credly.com.
  2. After verifying your account, go to https://developers.credly.com.
  3. Choose “My Apps” in the top navigation.
  4. Create an app, request production access, and wait for your app to be approved.
  5. Save the API Key, and App Secret. You will need these for authentication.
  6. Authenticate as an administrator (see Authentication below), to get a token.
  7. Use the Integration API (documented below) to create one or more integrations (courses), and get integration ids to be used in future requests.

Common Use Cases

Displaying the Badge-Management Interface

The CLE SDK comes with a pre-built user interface created by Credly. This UI allows course administrators (teachers) to manage courses, create rules, and assign badges to students. Students can list and claim badges. To display this UI, just complete the Authentication Flow, described below.

Full API Integration

Alternatively, you can fine-tune the user experience by creating your own user interface.

  • If the user is an administrator or teacher, ask for Credly login information (email address and password).
  • Follow the steps of the Authentication Flow, but do not display an IFrame to the user. Instead, use the Credly API to create rules, assign and list badges, etc. Provide the email address and password when appropriate

Awarding Badges

Badges are awarded to students based on the grades they receive in courses.

  • Create a badge, using your credly account, or the Credly API.
  • Add one or more students, using the Students API. These can be added one-by-one, or by uploading a CSV file exported by your LMS.
  • Add one or more gradable objects, using the Gradable API. These are anything that can have an associated grade. For example, tests, quizzes, exams and essays.
  • Add a rule, using the Rules API. This includes the requirements that must be fulfilled to receive a badge. For example, students might need a passing grade on a quiz, and a B or higher on the final exam
  • Using the Eligibility API, submit student grades.
  • When it is time to award the badge, use the Eligibility API again to evaluate the rule you created. The badge will be issued to all eligible students.

Integration into an LMS

An LMS developer can use this API to create a configurable interface, usable by any school.

  • Request a Credly Enterprise account to be used for development purposes.
  • Credly enterprise domain (or oauth root).
  • In your LMS’s administrative interface, make these settings configurable:
    • Credly API Key
    • Credly App Secret
  • Write your integration code such that each course generates its own integration. See the Integration API for more details.
  • Either display the Credly badge management interface in an IFrame, or integrate more deeply with the API, synchronizing students and grades.
  • Each school using your LMS will set the proper configuration settings to have its own, unique integration.

Authentication

Credly supports authentication using the LTI protocol from the IMS Learning Consortium (http://www.imsglobal.org/specs/ltiv1p0/implementation-guide) via oauth 1.0a (https://oauth.net/core/1.0a/)

The oauth root is https://[domain]/auth/lti for Credly IFrame integrations, and https://[domain]/cle_auth/authenticate for custom integrations. Replace [domain] with your Credly Enterprise domain. If you are developing an application or plugin that will be used by multiple clients, it is recommended that this be a configurable setting.

Authentication Flow with IFrame

This flow allows you to view the badge management UI, as well as to obtain a token for use in the Credly API. This flow is only available to Credly Enterprise customers.

  • Create an integration, using the Integrations API.
  • Create the OAuth and other parameters described below.
  • Send them to the OAuth root (e.g., https://domain.credly.com/auth/lti) with the proper signature (see Creating the OAuth Signature below). Parameters can be sent in one of two ways:
    • HTTP Authorization header. See Creating the Authorization Header below.
    • HTTP POST parameters in the body
  • If authentication fails, the response will include an HTTP Location header, which will redirect to an error page.
  • If authentication succeeds:
    • The response will redirect to a new URL, which will include a token parameter which may be used for requests to the Credly API. The token lasts for three years. When it expires and the API returns a 401 Unauthorized response, it can be renewed with another oauth request. This token is equivalent to a password, so it should be stored securely, and not displayed on a web page.
    • If the user has claimed to be an administrator using the roles parameter (this usually applies to administrators and teachers)
      • This redirect may result in a sign-in page, where a Credly username and password are required.
      • The user will then be redirected to the badge-management interface.
    • If the user is a student:
      • A Credly account will be automatically created if one does not exist.
      • The user will be redirected to a view of current and claimable badges.

Authentication Flow with Custom UI

The first form of authentication ends with a Credly-designed user interface. If your product uses an in-house UI, this flow is preferred.

  • Using the /authenticate request from the Credly API (http://developers.credly.com/api/user-management), supply the username and password of the app owner’s account and receive a token.
  • Using this token, create an integration (or course), using the Integrations API. Using the same token, make a /v1.1/cle_auth/connect request, using the proper OAuth parameters and signature (see Creating the OAuth Signature below). Parameters can be sent in one of two ways:
    • HTTP Authorization header. See Creating the Authorization Header below.
    • HTTP POST parameters in the body
  • Extract the token from the JSON response (data->token).
  • Use the new token in future requests for the integration.

OAuth Parameters

The authentication request requires all of these parameters except oauth_consumer_secret:

  • oauth_consumer_key: Your API key.
  • oauth_consumer_secret: Your App Secret. This is a secure token, and should not be included in the request. Nor should it ever appear on a web page, or in content delivered to end users. It should only be used to sign the request.
  • oauth_version: This should always be “1.0”
  • oauth_nonce: A unique ID for the request. Credly will remember your nonce for several minutes and will not permit reuse within that time period. Avoid using pseudo-random-number generators, which can repeat values.
  • oauth_timestamp: The time of the request, in UTC seconds. This value should be generated by a server with an accurate timestamp, since it will be compared with the time on the Credy server, and must match plus or minus a few minutes.
  • oauth_signature_method: As per the LTI specification, this should always be “HMAC-SHA1.”
  • oauth_signature: See Creating the OAuth Signature below.

LTI Parameters

These additional parameters from the LTI specification are supported.

Required Parameters:

  • user_id: An identifier for the current user. This does not have to be the user’s Credly ID, but must be unique to the user within the LTI system.
  • tool_consumer_info_product_family_code: This should always be set to “cle” context_id: An identifier for the application’s context. Typically, this is the course id.
  • lis_person_contact_email_primary: The user’s email address. If the user does not yet have a Credly account, this will be used to create one.
  • roles: A comma-separated list of URN values for roles. Valid roles are documented in the LTI specification: http://www.imsglobal.org/specs/ltiv1p0/implementation-guide#toc-6

Optional Parameters:

  • context_label: The Human-readable name of the context or course.
  • lis_person_name_given: The first name of the user.
  • lis_person_name_family: The last name of the user.
  • lis_person_name_full: The full name of the user.
  • All other LTI parameters are permitted, but will be ignored in the current version of this API.

Credly Parameters

  • integration_id: Required. The CLE integration ID obtained using the Integrations API, described below.

Creating the OAuth Signature

There are a variety of free oauth libraries which can do this for you, but given the many minor variations in this process, this guide can be used for troubleshooting.

  1. Create the content: Combine these with ampersands (&) between them, and url-encode each one. Note that some values will end up doubly-encoded.
    • The uppercase HTTP method
    • The request URL
    • All parameters in the request, including non-oauth parameters, but excluding oauth_signature. Sort the keys alphabetically, combine with ampersands, and urlencode both the key and the value. For example:param1=my value1&param2=my value2
  2. Create the encryption key, by appending an ampersand (&) to oauth_consumer_secret.
  3. Encrypt the content using hmac_sha1.
  4. Base64-encode the encrypted value.

Creating the Authorization Header

Most OAuth implementations send data in the HTTP Authorization header. If you are creating an OAuth implementation from scratch, construct the header as follows:

  1. Start with: Authorization: OAuth followed by one or more whitespace characters.
  2. Parameters are of one of these two forms:
    name1="value1" name2="value2" ...
    name1=value1, name2=value2, ...
    Values should be url encoded, and parameters should be separated by one or more whitespace characters. Newlines are acceptable.
  3. The header should include all parameters, including oauth_signature, and no parameters should appear in the POST body.

Errors

If authentication happens early on, there will be an HTTP 404 error. After the initial redirect, other errors are possible:

  • 400 LTI_APP_NOT_FOUND: The Credly app associated with the key and secret does not exist.
  • 400 LTI_DATA_MISSING: A required parameter was missing from the oauth request.
  • 401 LTI_UNAUTHORIZED: The oauth signature was invalid.
  • 400 LTI_NO_CONNECTION: The LMS is not supported.
  • 400 LTI_EMAIL_BELONGS_TO_ANOTHER: The supplied lis_person_contact_email_primary parameter matches an existing Credly account, so a new account could not be created.
  • 400 LTI_MEMBER_ID_DOES_NOT_EXIST: A new member could not be created, or the provided information did not correspond to a valid Credly user.
  • 400 LTI_MEMBER_CREATION_FAILED: The new Credly account could not be created.

API Endpoints

Using the Credly API

Complete API documentation can be found at http://developers.credly.com/api . Once you have completed the oauth process and have a token, you can use the Credly API by providing the appropriate HTTP headers and parameters. For example:

GET /v1.1/endpoint?access_token=[token from oauth response]
X-Api-Key: [Your API key]
X-Api-Secret: [Your app secret]

Common Parameters

All CLE requests support these parameters.

  • access_token=string: Required. The token acquired through authentication.
  • integration_account_id=integer: The id for the integration, or course, created by the Integrations API documented below. Either this or course_id must be included with every request.
  • course_id=string: The id for the course, used when requesting an integration id. Either this or integration_account_id must be included with every request.

Errors

Errors appear in the “meta” section of the output. The general description of an error comes from the “status” and “status_code” fields, while the details of specific errors can be found in “more_info.”

"paging": {
 "meta": {
  "status_code": 400,
  "status": "INVALID_API_PARAMETERS",
  "message": "The posted data did not pass validation",
  "more_info": {
   "error_name1": "Error Description",
   "error_name2": "Error Description"
  },
  "token_owner": 888
 },
 "data": null
}

See the Credly API documentation for more details.

Pagination

When a request supports pagination, these additional parameters are permitted.

  • page=integer: The page to request. This is multiplied by per_page to determine the first requested item.
  • per_page=integer: By default, a maximum of 10 items will be returned. This can be used to change that limit. The larger the limit, the longer the request will take to complete.
  • order_direction={ASC, DESC}: The sort order, based on the order in which items were added. Either ASC (ascending) or DESC (descending)

Pagination output will appear in the response. For example:

"paging": {
 "page": 1,
 "per_page": 10,
 "order_direction": "DESC",
 "multi_result_count": null
}

See the Credly API documentation for more details.

Parameter Types

In this document, parameters are listed with their allowed data types. All parameter keys and values must be URL-encoded if they appear in a URL or an x-www-form-urlencoded POST body.

  • param=string: The value must be a UTF-8 string, without any nulls or other non-printable characters.
  • param=integer: The value must be a 32-bit integer.
  • param=array<string>: The value may be a single string, or an HTTP array of strings. HTTP arrays are specified by putting empty square brackets after the key, and repeating key-value pairs. For example: param[]=1&param[]=2.
  • param=file: The value is a base64-encoded file object, as part of a multipart POST request.>
  • param=JSONArray: A JSON-encoded, array. For example: “[1, 2, 3, {\”a\”: 5}]”<
  • param=JSON: A JSON-encoded object. For example: “{\”a\”: 5}”
  • param=Date: The value is a date, in one of these formats:
    • SQL DATETIME: “Fri, 01 Dec 2017 09:51:11 +0000.” The day of the week is optional.
    • “yyyy-mm-dd hh:mm:ss timezone.” For example, “2017-01-01 5:30:00 US/Eastern.”

Authentication API

This API allows for a variety of features aside from basic OAuth authentication.

Connect

Connect an oauth-authenticated user account with an integration, and get back a token valid for future requests in the integration. The token sent to this request comes from a standard Credly API login.

This should be used for non-Enterprise accounts, or when the Credly badge-management UI is not desired. The token is valid for three years.

POST /v1.1/cle_auth/connect

Parameters:

  • All OAuth parameters, described in Authentication, above.
  • user_id=string: The LMS user’s ID.
  • integration_id=integer: The integration ID obtained from the Integrations API.
  • The common parameters are not required.

Output

"data": {
 "token": "456def",
 "Refresh_token": "123abc"
}

Errors

  • missing_param_integration_id: The user_id parameter is required.
  • missing_param_user_id: The integration_id parameter is required.

Authorize

Allow another Credly app to manage integrations in this app. This request returns a code which can be exchanged for an access token. Use this code with the Exchange request.

POST /v1.1/cle_auth/authorize

Parameters:

  • oauth_consumer_key=string: The API key of the other app.
  • redirect_url=string: The URL to return to after authorization.
  • integration_ids=array / string: Authorize the app to manage these integrations.

Output

"data": {
 "code": 123
}

Errors

  • invalid_param_oauth_consumer_key: The oauth_consumer_key was invalid.
  • unauthorized_user: The authenticated user is not allowed to authorize this integration.

Exchange

Exchange the code received from the Authorize request for a token which can be used for other CLE requests.

POST /v1.1/cle_auth/exchange

Parameters:

  • code=string: The code from the Authorize request.

Output

"data": {
 "token": "456def",
 "Refresh_token": "123abc"
}

Errors

  • 401 API_ACCESS_UNAUTHORIZED: The current app or the current user is not allowed to make this request.

Reconnect

Assign an organization to this integration.

Parameters:

  • organization_id: The organization (app) that should be connected to this integration.

Output

"data": {
 "id": 1,
 "organization": 123,
 "integration": 12,
 "member": 888
}

Deauthenticate

Permanently delete the current integration, along with all students, grades and other data. Only the common parameters are supported.

Output

"data": {
 "integration_account_id": 12,
 "message": "CLE Account: 12 deleted"
}

Integrations API

The integrations API is used to add top-level elements (usually courses) which can contain students, grades and rules. The common “integration_account_id” and “course_id” parameters are not required for this API, except when specified.

List

Get all integrations owned by the current user.

GET /v1.1/cle_integrations

Pagination parameters are supported.

Output

"data": {
 "12345": {
  "id": 12345,
  "course_id": "algebra_2",
  "name": "Algebra II"
 }
}

The “id” property is a generated value, which can be used as the “integration_account_id” in future API requests.

Create

Create a new integration. Only users who are authorized to manage the Credly App can make this request.

POST /v1.1/cle_integrations/create

Parameters:

  • name=string: The name of the integration.
  • course_id=string: The course id.

Output

Output is the same as for the List request.

Errors

  • missing_param_name: The “name” parameter is required.
  • missing_param_course_id: The “course_id” parameter is required.

Delete

Delete an integration. Only users who are authorized to manage the Credly App can make this request. When you delete an integration, all students, grades and other data will be deleted as well.

DELETE /v1.1/cle_integrations/delete
or
POST /v1.1/cle_integrations/delete

Parameters:

  • course_id=string: The course id to delete.

Output

If the integration is successfully deleted, output is the same as for the List request.

Errors

  • missing_param_course_id: The “course_id” parameter is required.
  • invalid_integration: The integration doesn’t exist, or the current user does not own the integration.

Students API

The students API is used to add, remove and list students. These students can then be given grades and badges through the Eligibility API.

List

List students based on request criteria. Listed students will come from the current integration defined by the common parameters.

GET /v1.1/cle_students

Parameters:

  • extern_id=array<string>: A list of student ids.>
  • first=array<string>: A list of first names.
  • last=array<string>: A list of last names.
  • email=array<string>: A list of email addresses.

Values within a list are combined with “or,” while separate lists are combined with “and.” For example, this query:

extern_id[]=1&extern_id[]=2&email=a@b.c

requests all students whose email is a@b.c, and whose external id is either 1 or 2.

Omit all of the above parameters to get the complete list of students in the course.

Pagination parameters are supported.

Output

"data": [
 {
  "id": 77,
  "extern_id": "11",
  "first": "Moe",
  "last": "Howard",
  "email": "moe@credlyschool.com",
  "integration_id": 1
 },
 ...
]

Create

Add one or more students.

POST /v1.1/cle_students/create

To add a single student, provide these parameters:

  • extern_id=string: Required. The student id.
  • first=string: Required. The student’s first name.
  • last=string: Required. The student’s last name.
  • email=string: Required. The student’s email address.

To add multiple students at once:

  • students=Array: An HTTP array of student objects, in this form:
    • students[0][extern_id]=string: Required. The student id.
    • students[0][first]=string: Required. The student’s first name.
    • students[0][last]=string: Required. The student’s last name.
    • students[0][email]=string: Required. The student’s email address.
    • students[1][extern_id]=string: Any number of students can be added.

To upload a CSV file which lists students:

  • students=File: A CSV file provided in a multipart POST request. Valid column headers include:
    • extern_id or id
    • first or firstname
    • last or lastname
    • email

For example:

id,first,last,email
100,Moe,Howard,moe@credlyschool.com
101,Larry,Fine,larry@credlyschool.com
102,Curly,Howard,curly@credlyschool.com

Output

Output is the same as for the List action.

Errors

  • invalid_student_[extern_id]: A student was invalid, or already existed.
  • missing_column_[column name]: A required column was missing from the csv file.
  • invalid_csv: The uploaded file was not a valid csv file. Often, the “missing_column” error will be received instead.
  • missing_param_extern_id: When adding a single student, the “extern_id” parameter is required.
  • missing_param_email: When adding a single student, the “email” parameter is required.

Delete

Remove one or more students.

DELETE /v1.1/cle_students/delete
or
POST /v1.1/cle_students/delete

Parameters:

  • extern_id=array / all: semicolon-delimited list of student ids to delete. Use the special value “all” to delete all students.

Output

If 100 or fewer students are being deleted, there will be verification for each one. Otherwise, only “deleted_count” will appear.

"data": [
 "deleted_count": 12,
 "deleted": {
  "extern_id": "11",
  "email": "moe@credlyschool.com"
 },
 ...
]

Errors

  • "output_truncated": More than 100 deletions were requested, so limited output was returned. This is a non-fatal error.

Gradable API

The gradable API is used to create objects that can be graded. For example, exams, quizzes and essays. These can later be used as criteria to grant badges to students.

List

List gradable objects in the current course.

GET /v1.1/cle_gradable

Pagination parameters are supported.

Output

"data": {
 "100": {
  "id": 0,
  "extern_id": "100",
  "name": "Algebra II",
  "callback": "pass",
  "min_pass_requirement": "Pass",
  "creator_id": 888
 },
 ...
]

Create

Add one or more gradable objects.

POST /v1.1/cle_gradable/create

Gradable objects can only be added using a CSV file.

Parameters:

  • grades=File: A CSV file provided in a multipart POST request. Valid column headers include:
    • extern_id=string: The id of the gradable object.
    • name=string: The name of the gradable object.
    • callback={letterGrade, points, complete, pass}: The method used to validate the grade. Currently, only built-in callbacks are supported.
    • min_pass_requirement=string: The minimum passing grade. Values depend on the callback parameter:
      • letterGrade: One of {A, B, C, D, F}.
      • points: A number between 0 and 1000.
      • complete: “Completed”
      • pass: “Pass” or “Pass or Fail.” The later value is equivalent to the “complete” requirement.

For example:

extern_id,name,callback,min_pass_requirement
100,Variables,pass,Pass
101,Solving for X,letterGrade,D
102,Quadratic Equations,letterGrade,D

Output

Output is the same as for the List request.

Errors

  • invalid_student_[extern_id]: A student was invalid, or already existed.

Delete

Remove one or more gradable objects.

DELETE /v1.1/cle_gradable/delete
or
POST /v1.1/cle_gradable/delete

Parameters:

  • extern_id=array / all: semicolon-delimited list of gradable ids to delete. Use the special value “all” to delete all students.

Output

If 100 or fewer students are being deleted, there will be verification for each one. Otherwise, only “deleted_count” will appear.

"data": [
 "deleted_count": 12,
 "deleted": {
  "extern_id": "101",
  "name": "Solving for X"
 },
 ...
]

Errors

  • "output_truncated": More than 100 deletions were requested, so limited output was returned. This is a non-fatal error.

Rules API

This API is used to determine the criteria needed to award badges to students. Badges can be awarded using the Eligibility API.

View Badge Criteria

List the grade requirements needed to award a badge.

GET /v1.1/cle_rules

Parameters:

  • badge_id=integer: Required. The Credly badge id.

Output

"data": [
 {
  "id": 3,
  "badge_id": "1823",
  "name": "Algebra II rule"
  "desc": "Master of Algebra",
  "requirements": [
   {
    "grade_object_id": "101",
    "gradable": {
     "id": 10,
     "extern_id": "101",
     "name": "Algebra II",
     "callback": "letterGrade",
     "min_pass_requirement": "D",
     "creator_id": 888
    },
    "operator": "greaterThan",
    "value": "B"
   }
  ]
 }
]

Errors

  • badge_not_found: The requested badge does not exist.
  • missing_param_badge_id: The badge_id parameter is required.

View Rule Description

View the Human-readable text description of the rules for a badge.

GET /v1.1/cle_rules/desc

Parameters:

  • badge_id=integer: Required. The Credly badge id.

Output

"data": {
 "desc": "Algebra Mastery"
}

Errors

  • badge_not_found: The requested badge does not exist.
  • missing_param_badge_id: The badge_id parameter is required.

Create Rules

Set or update the rules required to be awarded a badge.

UPDATE /v1.1/cle_rules/update
or
POST /v1.1/cle_rules/update

Parameters:

  • badge_id=integer / ”new”: Required. The Credly badge id.
  • rules=JSONArray / array: Required unless clear_all is used. Either a form array, or a JSON-encoded string, containing an array of rule definitions. All rules must be provided for the badge to be awarded. This object includes:
    • id=string: Required. The Credly badge id which will be awarded when the requirements are met. To create a new rule, use the special value “new.”
    • requirements=JSONArray: Required. A JSON array containing the grade requirements to qualify for this badge. This object requires the following members:
      • grade_object_id=integer: The id of a Gradable object. See the Gradable API.
      • operator: One of:
        • gte / greaterThanOrEqualTo: The grade must be greater than or equal to the value. For example, 95 is greater than 85, and A is greater than B.
        • gt / greaterThan: The grade must be greater than the value.
        • eq / equalTo: The grade must equal to the value.
        • lte / lessThanOrEqualTo: The grade must be less than or equal to the value.
        • lt / lessThan: The grade must be less than the value.
      • value: A grade value, which must made the grade type used by the Gradable object.
    • desc=string: The text-based description of the set of rules.
    • clear_all: Include this parameter to clear all rules from the badge. New rules cannot be added with the same request.

Output

Output is the same as the View Rule Description request.

Errors

  • badge_not_found: The requested badge does not exist.
  • missing_param_badge_id: The badge_id parameter is required.
  • missing_param_rules: The rules parameter is required.
  • invalid_param_rules: The rules parameter was invalid.
  • missing_param_rules_requirements: The rules parameter needs a ‘requirements’ element.
  • invalid_param_rules_requirements: The ‘requirements’ member of the rules parameter is invalid.

Eligibility API

This API is used to add student grades, and award badges. Note that Credly will not automatically award badges based on criteria. The Award Badges request must be used, below.

List Grades

List grades based on request criteria.

GET /v1.1/cle_eligibility/grade

Parameters:

  • gradable_id=integer: Only return items with this gradable id, as returned by the Gradable API.
  • student_id=integer: Only return items with this student id, as returned by the Students API.
  • score=string: Only return items with this score.
  • gradable_extern_id=string: Only return items with this gradable external id.
  • student_extern_id=string: Only return items with this student external id.
  • start=Date: Limit results to grades completed on this date/time or later.
  • end=Date: Limit results to grades completed on this date/time or earlier.

Output

"data": [
 "grades": [
  {
   "id": 6,
   "gradeable_id": 10,
   "student_id": 1,
   "score": "C",
   "student_extern_id": "107",
   "gradable_extern_id": "101"
  },
  ...
]

Register Grade

Record or replace a student’s grade, so it can later be used to trigger rules and award badges.

POST /v1.1/cle_eligibility/grade/register

Parameters:

  • gradable_id=integer:  Required. The extern_id of a gradable object. See the Gradable API for more details.
  • student_id=integer: Required. The extern_id of a student object. See the Student API for more details.
  • score=string: Required. The grade or score received. This must be a valid score for the specified gradable object.
  • date=Date: The date and optional time when the score was received. defaults to current date and time.

Output

Output is the same as for the List Grades request.

Errors

  • missing_param_gradable_id: The gradable_id parameter is required.
  • missing_param_student_id: The student_id parameter is required.
  • missing_param_score: The score parameter is required.
  • invalid_param_student_id: The student id is invalid.
  • invalid_param_gradeable_id: The grade id is invalid.

List Eligible Students

List students whose grades make them eligible for a badge.

GET /cle_eligibility/students

Parameters:

  • rule_id=integer: The id of the rule to evaluate, as generated by the Rules API.

Output

This request returns Student objects. See the Students API for sample output.

Errors

  • missing_param_rule_id: The rule_id parameter is required.

Award Badges

Evaluate a specific rule, and award badges to all qualifying students.

POST /cle_eligibility/evaluate/rule

Parameters:

  • rule_id=integer: The id of the rule to evaluate, as generated by the Rules API.

Output

"data": {
 "student_count": 123
}

Errors

  • missing_param_rule_id: The rule_id parameter is required.
  • invalid_param_rule_id: The rule id is invalid.

Logs API

Whenever students and other elements are added through this SDK, logs are created. This API is used to view and manage those logs.

List

List all logs, or logs within a time range.

GET /v1.1/cle_logs

Parameters:

  • start=Date: A date and optional time. Only logs created after this date will be returned. If neither “start” nor “end” is provided, all logs will be returned.
  • end=Date: A date and optional time. Only logs created before this date will be returned.

Pagination parameters are supported.

Output

"data": [
 {
  "id": 79,
  "date": "Wed, 29 Nov 2017 16:09:00 +0000",
  "action": "delete",
  "type": "student",
  "error_id": "",
  "data": {
   "deleted": 1,
   "count": 1
  }
 },
  ...
]

Output fields include:

  • id=integer: The internal log id.
  • date=GMT Date: The GMT date string representing the time at which the log entry was created.
  • action={create, delete, bulk_delete}: The action that was recorded.
  • type={student, gradable, etc}: The API request that created the record.
  • error_id=string: The error that occurred, if any. Errors include:
    • missing_column_[attribute]: A CSV file was uploaded with a missing column.
    • invalid_csv: An invalid CSV file was uploaded.
    • invalid_item: A student, gradable or other object could not be created. The “data” field will be “extern_id”: “the failed id.”
    • not_all_deleted: A delete request was received, and not all items were deleted, either due to errors or because the data did not exist.
  • data=JSON: Arbitrary data related to the logged operation.

 

Remove log entries.

DELETE /v1.1/cle_logs/delete

or

POST /v1.1/cle_logs/delete

Parameters:

  • start=Date: A date and optional time. Only logs created after this date will be deleted. If neither “start” nor “end” is provided, all logs will be deleted.
  • end=Date: A date and optional time. Only logs created before this date will be deleted.

Omit both parameters to delete all logs.

Output

"data": [
 "deleted_count": 145,
]

Sample Code and SDK

SDK

https://github.com/CredlyDev/cle-sdk

A project written in PHP which implements the basic functionality of this API. It includes helper functions which can assist in integrations, as well as sample code.

Moodle Plugin

https://github.com/CredlyDev/moodle_credlylti

This plugin for the open-source Moodle LMS demonstrates a basic integration. A “My Credentials” option is added to courses, and clicking on the option displays the Credly badge management UI.

This very basic integration may only function properly for the first course that uses it.