What is Custom Assertion and how do I use it?

The Custom Assertion Location feature allows Credly Premier  members to redirect accepted badges they issue to their own website.  This means that badges shown on a user’s Credly profile or that they share on various social networks will redirect when clicked to the website URL the issuer provides, instead of to Credly. In this manner, issuers can enjoy several benefits, such as: 
  • Extra Validity: The validity and authenticity of the credit is reinforced, as the badge assertion is displayed on your domain.
  • Enhanced Branding: White label the badge assertion page by placing it on your site.
  • Additional Context: Customize where and how you display credit on your site, offering additional information about your programs and offerings, enrollment opportunities, or other information for observers when they click through to learn about earned badges.
  • Your Analytics: With badges redirected to your site, you can leverage your own web site analytics to track traffic directly to your site from badges you issue.
What does a Custom Assertion Location look like in action?

When a Custom Assertion Location is in place, click-throughs from accepted badges that you have issued are redirected to the website you specify in your Account Settings. Credly appends the ID number of the badge to the URL string you provide.

Here is an example of a Custom Assertion Location, whereby the Credly badge was redirected to a non-Credly website:

How does this work?

Credly Premier members will see a Custom Assertion Location option in the “Account Settings” area of their account:

 The format of a Custom Assertion Location URL string is:

In the Custom Assertion Location field, you can add the URL where you would like badges to redirect when clicked.  In the above example, the Custom Assertion Location provided by the Credly issuer in their Account Settings area was:

When you enter a URL containing the pattern {id}, and “Save Changes” to accept the settings, the Credly Open Credit API will dynamically substitute the {id} token with the IDs of the badges you issue. From that moment forth, all badges issued by your Credly account -- past and future -- will redirect to your URL when clicked from Credly profiles or from any social networks or sites where they are shared by the earner.

Here are live links as an example, based on the above illustration: https://credly.com/credit/8058 redirects to http://aaslhcommunity.org/cert/?ID=8058

How does the Custom Assertion Location make use of the {id} token?

Once we redirect the badge assertion to your site, you have several options. You can pull the {id} value from the URL string and use one of these approaches to dynamically customize what you display to visitors: 
  • Use our special “embed” assertion link to easily embed the credit’s assertion information on your site, usually using an iframe (details below)
  • Retrieve the {id} token value Credly passes to your site and do a look-up using the Credly Open Credit API to get any or all metadata about the particular credit (i.e. title, issuer, description, issue and expiration date, badge image, evidence link, testimonial, etc.), and then display all or select data in any style or manner you choose on your site.
  • Retrieve the {id} token value Credly passes to your site and customize the display based on information stored on your own site (i.e. based on the badge ID and its relation to information stored in your own database, you could cater the display to show additional context specific to programs you offer).
None of these options are mutually exclusive. The Open Credit API is documented elsewhere and its use will vary from issuer to issuer in the context of how you wish to implement Custom Assertion Locations, so we will focus here on the first option listed above: Use of the Credly Assertion “Embed” URL.

Using the Custom Assertion Location “Embed” Link: 

The Custom Assertion Location “Embed” link essentially provides you with a white labeled version of the assertion page for a credit on Credly.  It is designed to be suitable for embedding an issued credit assertion on any web page on your site, and is especially helpful for the Custom Assertion Location redirects we’ve been describing here.

The format for the assertion “embed” link is:


where {id} is the ID for an accepted member badge. For example, if this is the standard link to a badge:


then this is the embed link to that badge: 


Note: The content width of Credly’s special embed link is 590 pixels. One of the most common ways to make use of this “embed” link with Custom Assertion Location Links activated, is to place it in an iframe on your own website, and then to retrieve the {id} token from your page URL and place it in the iframe in your page.  For example:
<iframe align='top' marginwidth ='0' src='http://credly.com/credit/$val/embed' width='590' height='1000' scrolling='no' frameborder='no'></iframe>

where $val is the placeholder for the {id} token value received from Credly’s redirect.

Example for Retrieving the ID token: 

The approach you use to retrieve and embed the {id} value into the iframe will depend on the programming languages and web protocols you use in your particular context.  But here is an example of a simple script for those who use php:

<?php $val = $_GET['ID']; echo "<iframe align='top' marginwidth ='0' src='http://credly.com/credit/$val/embed' width='590' height='1000' scrolling='no' frameborder='no'></iframe>"; ?>

In the above example, the Custom Assertion Location you place in your Credly Account Settings would contain the parameter “ID”.  In Credly, the link you provide might look something like this:


where http://example.com/certifications is the page on your site where you’d like to direct custom Credly credit assertions and where you have the php script embedded and ready to accept the parameter “ID”.

Feedback and Knowledge Base