Skip to content

Badge Templates (Extended)

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