Create a Badge Template
An image, at least three skills, criteria URL (global_activity_url), and at least one activity
(badge_template_activities) are required. Note that the method used to send an image in the request body
uses a remote url, however one can also send the image as Base64 encoded data.
Documentation on how to include image data as part of the
request body can be found in the Badge Template Images section.
Request
POST /organizations/<organization_id>/badge_templates
Request Body
{
"image": {
"remote_upload_url": "https://cdn.example.com/path/to/image.png"
},
"alignments": [
{
"name": "Educational Standard Name",
"url": "https://www.example.com/educational_standard_details",
"description": "Consectetur adipisicing elit, sed do eiusmod tempor."
}
],
"description": "Fencing club champion.",
"global_activity_url": "https://www.example.com/bar",
"name": "Fencing",
"cost": "Paid",
"level": "Advanced",
"lock_badge_state": false,
"time_to_earn": "Years",
"translatable": false,
"type_category": "Experience",
"recommendations": [
{
"title": "foo",
"type": "information",
"activity_url": "http://www.example.com/recommendation"
}
],
"skills": [
"Fencing"
],
"badge_template_activities": [
{
"activity_type": "Award",
"title": "Placed in annual tournament",
"activity_url": "https://www.example.com/award"
},
{
"activity_type": "Badge",
"required_badge_template_id": "e37c0539-5039-47ee-9b44-82dad63f8d59"
}
]
}
Response
201 Created
Location: <badge_template_url>
{
"data": {
"id": "804c7c23-d414-4e01-a5b3-d4b66d0fd758",
"allow_duplicate_badges": false,
"cost": "Paid",
"description": "Fencing club champion.",
"default_expires_at": null,
"default_expires_at_date": null,
"default_expires_at_type": null,
"earn_this_badge_url": null,
"enable_earn_this_badge": false,
"enable_detail_attribute_visibility": true,
"global_activity_url": "https://www.example.com/bar",
"level": "Advanced",
"lock_badge_state": false,
"name": "Fencing",
"state": "active",
"public": true,
"badges_count": 0,
"recipient_type": "User",
"send_expiring_badge_notifications": false,
"settings_enable_related_badges": true,
"show_badge_lmi": false,
"show_lmi_jobs": false,
"show_skill_tag_links": true,
"vanity_slug": "fencing",
"record_to_blockchain": null,
"time_to_earn": "Years",
"translatable": false,
"type_category": "Experience",
"printing_disabled": false,
"visibility": "public",
"variants_allowed": false,
"variant_type": null,
"allow_delete": true,
"allow_archive": false,
"available_locales": [
],
"only_one_skill_required": false,
"criteria_url_name": null,
"criteria_url": null,
"certification": true,
"state_updated_at": null,
"created_at": "2014-04-01T14:41:00.000Z",
"updated_at": "2014-04-01T14:41:00.000Z",
"show_template_settings": true,
"get_issue_count": 0,
"image": {
"id": "d2e58f21-76f5-4f42-8d43-74cba0db25aa",
"url": "https://cdn.example.com/path/to/image.png"
},
"image_url": "https://cdn.example.com/path/to/image.png",
"url": "https://www.credly.com/org/organization-1/badge/fencing",
"owner": {
"type": "Organization",
"id": "365d1819-2da0-4fdf-b769-288beb465a01",
"name": "Organization 1",
"url": "https://api.credly.com/v1/organizations/365d1819-2da0-4fdf-b769-288beb465a01",
"vanity_url": "https://www.credly.com/org/organization-1",
"vanity_slug": "organization-1",
"verified": true,
"viewable": true
},
"alignments": [
{
"id": "f44d695c-0261-454b-8e4b-199bac4a4a5a",
"name": "Educational Standard Name",
"url": "https://www.example.com/educational_standard_details",
"description": "Consectetur adipisicing elit, sed do eiusmod tempor."
}
],
"recommendations": [
{
"id": "05aa9552-67a9-4d31-8170-52d65485feb7",
"title": "foo",
"type": "information",
"activity_url": "http://www.example.com/recommendation"
}
],
"required_badge_templates": [
],
"badge_template_activities": [
{
"id": "af035331-2bbf-48c7-adc3-86c15f1be5a7",
"title": "Placed in annual tournament",
"activity_type": "Award",
"activity_url": "https://www.example.com/award",
"required_badge_template_id": null
},
{
"id": "571eca70-c8c5-4976-81df-d9ba6eac0d97",
"title": "Badge Template 2",
"activity_type": "Badge",
"activity_url": null,
"required_badge_template_id": "bbd1413f-a174-42b6-8be4-fe4701763040",
"required_badge_template_name": "Badge Template 2",
"required_badge_template_url": "https://www.credly.com/org/organization-1/badge/badge-template-2"
}
],
"skills": [
"Fencing"
],
"reporting_tags": [
]
},
"metadata": {
}
}
Badge Template Images
Published Badge Templates require an image. Images can be sent via curl or a multipart-aware library such as HTTMultiParty. Images can also be sent via a JSON payload.
For example:
curl -u 'YiGpgYUfl5lTAmDDa5T2':'' \
-F description="The earner of this badge won the fencing club championship." \
-F name="Fencing Club Champion" \
-F image=@fencing.png \
https://api.credly.com/v1/organizations/99/badge_templates
To send an image via a url. Set the image param in your JSON payload to a hash
{ remote_upload_url: <remote_upload_url> }. Be sure to prepend the scheme, http:// or
https://, to your url.
//Badge Template Request Body
{
"image": { "remote_upload_url": 'https://cdn.example.com/path/to/image.png}
//rest of payload
}
To send an image via a data uri. Set the image param in your JSOn payload to a hash
{ remote_upload_url: data:image/png;base64,<base64_encoded_data> }.
//Badge Template Request Body
{
"image": { remote_upload_url: 'data:image/gif;base64,' + <base64_encoded_data> }
//rest of payload
}
Badge Template Enumerated Attributes
Several Badge Template attributes take values from lists, they are:
| Attribute | Possible Values |
|---|---|
cost |
Free, Paid
|
level |
Foundational, Intermediate, Advanced
|
time_to_earn |
Hours, Days, Weeks, Months, Years
|
type_category |
Experience, Learning, Validation, Certification
|
Badge Template Recommendations
When creating or updating a Badge Template, recommendations may be included in the outgoing data.
Recommendations are related badges or URLs -- "next steps" the user can consider after earning
a badge.
Including this section when updating will replace the entire list of Recommendations. However, Recommendations created by other issuers will not be changed. (Note: the ability for multiple issuers to add recommendations to the same template may not yet be supported).
The example below ennumerates the three ways to add a recommendation:
1. By id. This will add an already-created recommendation to the Badge Template (see the
Recommendations API.
2. By Badge Template id. This will use an already-created recommendation if one exists, or create a
new one based on the given template id. This type recommends another badge template as the
"next step." The recommended_badge_template_id property is required. All other properties
will be derived from the badge template.
3. By type. This will use an already-created recommendation if one exists, or create a new one.
These types recommend a URL as the "next step." The type, activity_url and title properties
are required. description is optional.
Valid types include: - badge - information - education - employment - participation - offer
{
"data": {
"recommendations": [
{
"id": "670e7174-4a04-4e80-8ebb-6369c406990d"
},
{
"recommended_badge_template_id": "8c982b0f-bf24-4281-839a-0ddfc6a2c809"
},
{
"type": "information",
"activity_url": "http://example.com",
"title": "Sample recommendation",
"description": "Recommendation description"
}
]
}
}
Update a Badge Template
Request
PUT /organizations/<organization_id>/badge_templates/<badge_template_id>
Request Body
{
"image": {
"remote_upload_url": "https://cdn.example.com/path/to/image.png"
},
"alignments": [
{
"name": "Educational Standard Name",
"url": "https://www.example.com/educational_standard_details",
"description": "Consectetur adipisicing elit, sed do eiusmod tempor."
}
],
"description": "Fencing club grand champion.",
"global_activity_url": "https://www.example.com/biz",
"name": "Fencing",
"owner_id": "1b60d19e-b024-4c7b-aa82-722f3267a7b1",
"linkedin_share_default_message": "Take a look at this badge I just received @Org_Name",
"recommendations": [
{
"title": "foo",
"type": "information",
"activity_url": "http://www.example.com/alt-activity"
}
],
"skills": [
"Fencing"
],
"reporting_tags": [
"Expert",
"Retail"
],
"badge_template_activities": [
{
"title": "Kickboxing Activity",
"activity_type": "Schedule / Registration",
"activity_url": "http://www.example.com/awesomepage"
},
{
"activity_type": "Badge",
"required_badge_template_id": "25a02c66-8f72-4863-9748-130b6fd4d210"
}
]
}
Response
200 OK
{
"data": {
"id": "e66ec1d8-276f-4ae9-877c-6c7ddbf840a3",
"allow_duplicate_badges": true,
"cost": null,
"description": "Fencing club grand champion.",
"default_expires_at": null,
"default_expires_at_date": null,
"default_expires_at_type": null,
"earn_this_badge_url": null,
"enable_earn_this_badge": false,
"enable_detail_attribute_visibility": true,
"global_activity_url": "https://www.example.com/biz",
"level": null,
"lock_badge_state": false,
"name": "Fencing",
"state": "active",
"public": true,
"badges_count": 0,
"recipient_type": "User",
"send_expiring_badge_notifications": false,
"settings_enable_related_badges": true,
"show_badge_lmi": false,
"show_lmi_jobs": false,
"show_skill_tag_links": true,
"vanity_slug": "fencing",
"record_to_blockchain": null,
"time_to_earn": null,
"translatable": false,
"type_category": null,
"printing_disabled": false,
"visibility": "public",
"variants_allowed": false,
"variant_type": null,
"allow_delete": true,
"allow_archive": false,
"available_locales": [
],
"only_one_skill_required": false,
"criteria_url_name": null,
"criteria_url": null,
"certification": true,
"state_updated_at": null,
"created_at": "2014-04-01T14:41:00.000Z",
"updated_at": "2014-04-01T14:41:00.000Z",
"show_template_settings": true,
"get_issue_count": 0,
"image": {
"id": "7286898b-d5c8-48fa-a07b-6f61f31e49e2",
"url": "https://cdn.example.com/path/to/image.png"
},
"image_url": "https://cdn.example.com/path/to/image.png",
"url": "https://www.credly.com/org/organization-1/badge/fencing",
"owner": {
"type": "Organization",
"id": "0c4a7718-5c5a-4555-adf8-cd61532b6dab",
"name": "Organization 1",
"url": "https://api.credly.com/v1/organizations/0c4a7718-5c5a-4555-adf8-cd61532b6dab",
"vanity_url": "https://www.credly.com/org/organization-1",
"vanity_slug": "organization-1",
"verified": true,
"viewable": true
},
"alignments": [
{
"id": "39b3d58e-f4b7-4307-b39e-792921b95d68",
"name": "Educational Standard Name",
"url": "https://www.example.com/educational_standard_details",
"description": "Consectetur adipisicing elit, sed do eiusmod tempor."
}
],
"recommendations": [
{
"id": "b22b9820-262a-44b2-bc44-9f0c3f5ab7e4",
"title": "foo",
"type": "information",
"activity_url": "http://www.example.com/alt-activity"
}
],
"required_badge_templates": [],
"badge_template_activities": [
{
"id": "31613922-4878-4da7-b550-e533e14aa218",
"title": "Kickboxing Activity",
"activity_type": "Schedule / Registration",
"activity_url": "http://www.example.com/awesomepage",
"required_badge_template_id": null
},
{
"id": "571eca70-c8c5-4976-81df-d9ba6eac0d97",
"title": "Badge Template 2",
"activity_type": "Badge",
"activity_url": null,
"required_badge_template_id": "bbd1413f-a174-42b6-8be4-fe4701763040",
"required_badge_template_name": "Badge Template 2",
"required_badge_template_url": "https://www.credly.com/org/organization-1/badge/badge-template-2"
}
],
"skills": [
"Fencing"
],
"reporting_tags": [
"expert",
"retail"
]
},
"metadata": {
"permissions": {
"5a5a94d7-05e6-4550-baa7-8cbaf6acb7b4": [
]
}
}
}
Archive a Badge Template
This will prevent further badges from being issued for this template.
Request
PUT /organizations/<organization_id>/badge_templates/<badge_template_id>/archive
Response
200 OK
{
"data": {
"primary_badge_template_id": null,
"variant_name": null,
"id": "ddb76b9a-bdf4-4ae7-a6b8-be91d9499345",
"allow_duplicate_badges": true,
"description": "Dynamically deliver go forward e-tailers",
"default_expires_at": null,
"default_expires_at_date": null,
"default_expires_at_type": null,
"earn_this_badge_url": null,
"enable_earn_this_badge": false,
"enable_detail_attribute_visibility": true,
"global_activity_url": "https://www.example.com/foo",
"lock_badge_state": false,
"name": "Badge Template 1",
"state": "archived",
"public": true,
"badges_count": 0,
"recipient_type": "User",
"send_expiring_badge_notifications": false,
"settings_enable_related_badges": true,
"show_badge_lmi": false,
"show_lmi_jobs": false,
"show_skill_tag_links": true,
"vanity_slug": "badge-template-1",
"record_to_blockchain": null,
"translatable": false,
"printing_disabled": false,
"visibility": "public",
"variants_allowed": false,
"variant_type": null,
"allow_delete": true,
"allow_archive": false,
"available_locales": [
],
"only_one_skill_required": false,
"linkedin_share_default_message": "View my verified achievement from @Org_Name.",
"level": null,
"time_to_earn": null,
"cost": null,
"type_category": null,
"criteria_url_name": null,
"criteria_url": null,
"certification": true,
"state_updated_at": "2014-04-01T14:41:00.000Z",
"created_at": "2014-04-01T14:41:00.000Z",
"updated_at": "2014-04-01T14:41:00.000Z",
"show_template_settings": false,
"get_issue_count": 0,
"get_variants_issue_count": 0,
"image": {
"id": "8f17cc58-d3db-49da-a58f-c8a2b0c518b8",
"url": "/system/test/images/8f17cc58-d3db-49da-a58f-c8a2b0c518b8/fake-600x600.png"
},
"image_url": "https://cdn.example.com/path/to/image.png",
"url": "https://www.credly.com/org/organization-4/badge/badge-template-1",
"owner": {
"type": "Organization",
"id": "5faaa7a9-886b-4d70-92a2-0bd8e73860ea",
"name": "Organization 4",
"enable_blockchain": false,
"url": "https://api.credly.com/v1/organizations/5faaa7a9-886b-4d70-92a2-0bd8e73860ea",
"vanity_url": "https://www.credly.com/org/organization-4",
"vanity_slug": "organization-4",
"verified": true,
"viewable": true
},
"alignments": [
{
"id": "d471420d-8c7f-47ff-85b7-ccbdfd4aa3a5",
"name": "Alignment 6",
"url": "http://www.example.com/alignment",
"description": "Self-enabling cohesive task-force"
}
],
"recommendations": [
{
"id": "35f4d757-fc87-48c0-a374-a0bdaa7a59b8",
"title": "Recommendation Title",
"type": "information",
"activity_url": "http://www.example.com/recommendation"
}
],
"required_badge_templates": [
],
"badge_template_activities": [
{
"id": "24d57d55-fd40-4d03-91e8-876ea23122ae",
"title": "Kickboxing Activity",
"activity_type": "Schedule / Registration",
"activity_url": "http://www.example.com/awesomepage",
"required_badge_template_id": null
}
],
"skills": [
"Skill 7",
"Skill 8",
"Skill 9"
],
"endorsements": [
]
},
"metadata": {
}
}
Unarchive a Badge Template
This will allow badges to be issued for this template again.
Request
PUT /organizations/<organization_id>/badge_templates/<badge_template_id>/unarchive
Response
200 OK
{
"data": {
"primary_badge_template_id": null,
"variant_name": null,
"id": "691921e1-77ad-494c-9825-eb7df8fab9d3",
"allow_duplicate_badges": true,
"description": "Dynamically deliver go forward e-tailers",
"default_expires_at": null,
"default_expires_at_date": null,
"default_expires_at_type": null,
"earn_this_badge_url": null,
"enable_earn_this_badge": false,
"enable_detail_attribute_visibility": true,
"global_activity_url": "https://www.example.com/foo",
"lock_badge_state": false,
"name": "Badge Template 4",
"state": "active",
"public": true,
"badges_count": 0,
"recipient_type": "User",
"send_expiring_badge_notifications": false,
"settings_enable_related_badges": true,
"show_badge_lmi": false,
"show_lmi_jobs": false,
"show_skill_tag_links": true,
"vanity_slug": "badge-template-4",
"record_to_blockchain": null,
"translatable": false,
"printing_disabled": false,
"visibility": "public",
"variants_allowed": false,
"variant_type": null,
"allow_delete": true,
"allow_archive": false,
"available_locales": [
],
"only_one_skill_required": false,
"linkedin_share_default_message": "View my verified achievement from @Org_Name.",
"level": null,
"time_to_earn": null,
"cost": null,
"type_category": null,
"criteria_url_name": null,
"criteria_url": null,
"certification": true,
"state_updated_at": "2014-04-01T14:41:00.000Z",
"created_at": "2014-04-01T14:41:00.000Z",
"updated_at": "2014-04-01T14:41:00.000Z",
"show_template_settings": false,
"get_issue_count": 0,
"get_variants_issue_count": 0,
"image": {
"id": "cfe6ae57-54fa-4a3b-9aad-1c35a0a89142",
"url": "/system/test/images/cfe6ae57-54fa-4a3b-9aad-1c35a0a89142/fake-600x600.png"
},
"image_url": "https://cdn.example.com/path/to/image.png",
"url": "https://www.credly.com/org/organization-10/badge/badge-template-4",
"owner": {
"type": "Organization",
"id": "4497215f-e958-4f41-a9fd-f121c4e60c18",
"name": "Organization 10",
"enable_blockchain": false,
"url": "https://api.credly.com/v1/organizations/4497215f-e958-4f41-a9fd-f121c4e60c18",
"vanity_url": "https://www.credly.com/org/organization-10",
"vanity_slug": "organization-10",
"verified": true,
"viewable": true
},
"alignments": [
{
"id": "d43e5fb1-2e81-479f-9b3e-b3eec06b0724",
"name": "Alignment 12",
"url": "http://www.example.com/alignment",
"description": "Self-enabling cohesive task-force"
}
],
"recommendations": [
{
"id": "569f0003-d99d-4085-9185-f7722c821e6f",
"title": "Recommendation Title",
"type": "information",
"activity_url": "http://www.example.com/recommendation"
}
],
"required_badge_templates": [
],
"badge_template_activities": [
{
"id": "c1d89bc3-15c6-449f-87d8-8c41229f7d80",
"title": "Kickboxing Activity",
"activity_type": "Schedule / Registration",
"activity_url": "http://www.example.com/awesomepage",
"required_badge_template_id": null
}
],
"skills": [
"Skill 16",
"Skill 17",
"Skill 18"
],
"endorsements": [
]
},
"metadata": {
}
}
Delete a Badge Template
Request
DELETE /organizations/<organization_id>/badge_templates/<badge_template_id>
Response
204 No Content