Purpose: This article explains how the built-in Acclaim by Credly integration issues digital badges from Administrate, how to set it up in the Control Panel, and how to check and retry a badge that did not reach Credly.
Administrate can issue a Credly digital badge automatically whenever a learner is awarded an Achievement. Once the integration is connected and an Achievement Type carries a Credly badge template ID, every award of that Achievement Type sends a badge to Credly without anyone having to do anything else.
This integration is set up by your own administrators in the Control Panel. It replaces the earlier arrangement where Administrate held your Credly settings on your behalf and badge templates were linked to Achievement Types through the API. See Moving from the API-linked integration if your instance was set up that way.
Preview feature. The Acclaim by Credly integration is released behind a feature flag. If you do not see the tile described below, contact your Account Manager or the Administrate support team to have it enabled on your instance.
On this page
- What the integration does
- Before you start
- Step 1: Add a badge template custom field
- Step 2: Connect Administrate to Credly
- Step 3: Put a badge template ID on each Achievement Type
- How badges are issued
- Checking a learner's badge
- Retrying a failed badge
- Why badges fail
- Reviewing badge activity in the External Log
- Permissions
- Anonymised learners
- Using the API
- Moving from the API-linked integration
What the integration does
Digital badges give learners a verifiable, shareable credential for what they have completed. Credly is the platform that holds the badge template, issues the badge and manages the learner's acceptance and sharing. Administrate's job is to decide who earns which badge and when, and to tell Credly.
The flow is:
- A learner is awarded an Achievement in Administrate, by passing an Event, completing a Learning Path, or by an administrator awarding it manually.
- Administrate reads the Credly badge template ID from the Achievement Type that was awarded.
- Administrate asks Credly to issue that badge template to the learner, using their first name, last name and primary email address.
- Credly issues the badge and takes over from there, inviting the learner to accept it and share it.
- Administrate records the outcome against the Achievement, so you can see at a glance whether the badge reached Credly.
Achievement Types with no badge template ID issue no badge. They are simply left alone, and nothing is recorded against them.
Awarding an Achievement never depends on Credly. If Credly cannot be reached, or rejects the badge, the learner still keeps the Achievement they earned. The badge failure is recorded separately so that someone can correct it and try again.
Before you start
You will need:
- A Credly organization, with the badge templates you want to issue already created and published in Credly.
- Your Credly organization ID, which Credly shows on your organization's settings page.
- A Credly API token for that organization, generated in Credly.
- Super User access in Administrate, which is required to open the integration settings screen.
- The feature enabled on your instance (see the note at the top of this article).
Administrate only ever sends your API token to Credly's own API. Two destinations are permitted: Credly's production API, and Credly's sandbox API for testing. No other address can be configured.
Step 1: Add a badge template custom field
Each Achievement Type needs somewhere to record which Credly badge template it issues. That is held in a custom field on Achievement Types, which you create once and then fill in per Achievement Type.
- Go to Control Panel → Custom Fields.
- Select Achievement Type in the Entities panel on the left.
- Click Create Field and add a Single Line Text field, for example named
Badge Template ID. - Save the field.
You only need one such field. Which field the integration reads is chosen in the next step, so the name is yours to pick. See Custom Fields for the full detail on creating and permissioning custom fields.
Tip: Give the field a name that makes its purpose obvious to whoever maintains your Achievement Types. They will be pasting Credly template IDs into it.
Step 2: Connect Administrate to Credly
- Go to Control Panel → Integrations.
- Find the Acclaim by Credly tile. It reads Activate until the integration has been set up, and Edit afterwards.
- Complete the settings:
| Setting | What to enter |
|---|---|
| Organization ID | The Credly organization badges are issued from. Credly shows this on your organization's settings page. |
| API Token | The Credly API token used to issue badges. |
| Badge Template Field | The Achievement Type custom field you created in Step 1. Achievement Types with no value in that field issue no badge. |
| Acclaim API URL | Production unless you are testing against Credly's sandbox. |
- Select Save.
A few things worth knowing about this screen:
- The API token is write-only. Once saved it is never shown again, and the field is labelled Replace API Token from then on. Leave it blank when you are correcting another setting; the stored token is kept.
- Changing the API URL means re-entering the token. The stored token is sent to whichever API the URL names, so switching between Production and Sandbox requires the token for that environment.
- Until all of the organization ID, badge template field and API token are saved, no badges are issued. The screen says so explicitly while any of them is missing.
- If the chosen badge template field is later deleted, the screen warns you that it no longer exists on Achievement Types, and no badges are issued until another field is chosen.
Step 3: Put a badge template ID on each Achievement Type
For every Achievement Type that should issue a badge:
- Find the badge template in Credly and copy its template ID.
- Go to Control Panel → Achievements and select the Achievement Types tab.
- Click the Achievement Type to open Update Achievement Type.
- Paste the template ID into the badge template field under Custom Fields, then select OK.
Achievement Types you leave blank issue no badge, which is how you keep badging to the subset of Achievements that warrant a credential. You can add and remove template IDs at any time; the value is read fresh each time an Achievement is awarded.
See Achievements for how to create and configure Achievement Types, and how to have them awarded automatically when a learner passes.
How badges are issued
A badge is issued the moment the Achievement is awarded. There is nothing to schedule and no batch to run.
Administrate sends Credly the learner's first name, last name, primary email address, the badge template ID and the issue date. The learner then accepts the badge in Credly in the usual way.
Some behaviours worth understanding:
- Already-issued badges are not duplicated. Before issuing, Administrate asks Credly whether that badge template has already been issued to that email address. If it has, the existing badge is recorded rather than a second one being created.
- Successful badges are never re-sent. Once a badge is recorded as synced, nothing in Administrate will ask Credly for it again, so a learner cannot end up with two.
- A learner with no name or no email address cannot be badged. This happens where an Achievement has been awarded against a booked seat with nobody named in it. The badge is recorded as failed, explaining exactly that, and the Achievement stands.
- Revoking an Achievement does not withdraw the badge. A badge issued at Credly is managed in Credly, so withdrawing it is done there.
Checking a learner's badge
Badge outcomes appear on the learner's record.
- Open the Contact.
- Go to the Achievements tab.
- Read the Badge column.
| What you see | What it means |
|---|---|
| A tick | The badge reached Credly. Where you have permission to see the learner, the tick links to their badge acceptance page in Credly. |
| An amber warning | The badge did not reach Credly. Hover or focus it to read why. |
| Nothing | This Achievement Type issues no badge, so nothing was attempted. |
A failed badge shows the warning instead, and the tooltip carries the reason:
The Badge column only appears on instances using the Acclaim integration.
Retrying a failed badge
Most badge failures are a data problem at the Administrate end: a learner with no email address, a mistyped or retired Credly template ID, a token that has expired. Correct the data, then retry.
- Open the Contact and go to the Achievements tab.
- Open the row's actions menu and select Retry Badge Sync.
- Confirm in the dialog.
The action is only offered on Achievements whose badge failed. Retrying a badge that already synced would issue the learner a second one, so it is not offered.
The retry re-reads the Achievement as it stands now. It does not replay the details that failed, so any correction you have made since — to the learner's email address, to the Achievement Type's badge template ID, or to the integration settings — is used.
If Credly refuses the badge again, the dialog stays open and tells you so, and the row stays marked as failed.
A retry is refused outright, with an explanation, when:
- The Achievement no longer exists.
- The Achievement has been revoked. A badge issued at Credly cannot be withdrawn from Administrate, so Administrate will not issue one for a revoked Achievement either.
- The learner has been anonymised. See Anonymised learners.
- Acclaim is not set up on this instance, or its settings are incomplete. Check the integration settings in the Control Panel.
- The badge has already synced to Credly.
Why badges fail
| Reported problem | What to do |
|---|---|
| The learner has no name or no email address | Add the learner's name and primary email address to the Contact, then retry. |
| "Credly rejected the badge details. Check the badge template ID on the Achievement Type." | Check the template ID on the Achievement Type against Credly, and confirm the template is published in your Credly organization. |
| Credly rejects the credentials | Check the organization ID and generate a fresh API token in Credly, then save it in the integration settings and retry. |
| Credly could not be reached | A transient outage. Retry once Credly is available again. |
| Nothing at all is issued, with no failures recorded | Check that the integration settings are complete, and that the Achievement Type carries a value in the badge template field. |
Reviewing badge activity in the External Log
Every badge attempt — successful or not — is also written to the External Log, under the Acclaim Integration category. This is the record to use when you want to review badging across your instance rather than learner by learner.
A failure entry names the learner, links to their Achievements tab where the Retry Badge Sync action is, names the Achievement Type and links to the Achievement Types screen, and shows the badge template ID, the problem and Credly's own response where there was one.
A success entry names the learner, the badge template and Credly's identifier for the badge.
Permissions
- Integration settings are Super User only. The Acclaim by Credly tile and its settings screen are not available to other users.
- Retrying a badge requires permission to edit the learner the badge belongs to.
- Badge details are scoped to the learner. A user who may not see a Contact does not see that learner's badge acceptance URL, email address or failure detail.
Anonymised learners
Anonymising a Contact redacts the email address recorded against their badges, as well as on the Contact itself.
Achievements survive anonymisation, so an anonymised learner's Achievements and their badge outcomes remain visible. A badge for an anonymised learner cannot be retried: Credly would be sent the placeholder details anonymisation left behind rather than the learner's own.
Using the API
The integration is fully available through Administrate's GraphQL API.
Read the integration settings. The API token is never returned; hasAuthorizationToken tells you whether one is stored, and isConfigured whether badges are being issued at all.
query acclaimSettings {
acclaimIntegrationSettings {
organizationId
badgeTemplateDefinitionKey
baseUrl
hasAuthorizationToken
isConfigured
}
}
Set the integration settings. Omit authorizationToken to keep the token already stored.
mutation setAcclaimSettings {
acclaimIntegrationSettings {
set(
input: {
organizationId: "YOUR CREDLY ORGANIZATION ID"
badgeTemplateDefinitionKey: "YOUR CUSTOM FIELD KEY"
baseUrl: "https://api.credly.com"
authorizationToken: "YOUR CREDLY API TOKEN"
}
) {
errors {
label
message
value
}
settings {
isConfigured
}
}
}
}
The custom field keys available for badgeTemplateDefinitionKey come from customFieldTemplate(type: AchievementType).
Read an Achievement's badge. acclaimBadge is null where the Achievement Type issues no badge.
query achievementBadges {
achievements {
edges {
node {
id
acclaimBadge {
id
status
badgeUrl
errorDetail
attemptCount
isRetryable
}
}
}
}
}
Retry a failed badge.
mutation retryAcclaimBadge {
acclaimBadge {
retry(input: { acclaimBadgeId: "ACCLAIM BADGE ID" }) {
errors {
label
message
value
}
acclaimBadge {
status
badgeUrl
errorDetail
}
}
}
}
Moving from the API-linked integration
Instances set up before this integration linked badge templates to Achievement Types by storing an external ID named acclaimBadgeTemplateId against the Achievement Type through the API, and had their Credly credentials configured by Administrate on request.
Under this integration:
- Your Credly credentials move into the Control Panel, where your own administrators manage them. Your existing organization ID and API token continue to work.
- Badge templates move from an external ID to a custom field on the Achievement Type. Populate the custom field for each Achievement Type that should issue a badge; the external ID is no longer read.
- Badge outcomes become visible in Administrate, on the learner's Achievements tab and in the External Log, with a retry action for failures.
If you are moving an existing instance across, speak to your Account Manager so the changeover can be planned around your Achievement Types.
If you have any questions about the Acclaim by Credly integration, please contact our support team.