CINXE.COM

<!DOCTYPE html> <html class='legacy-css' lang='en'> <head> <meta charset='UTF-8'> <script src="https://cdn.cookielaw.org/scripttemplates/otSDKStub.js" data-document-language="true" type="text/javascript" charset="UTF-8" data-domain-script="01939cd7-7f26-7c87-af17-d2bfc69700b9" ></script> <script nonce="FjSzqTn5KFWlDzbVUXyQsi8PKc37fy2gfXAnb3sUjU8="> //<![CDATA[ function OptanonWrapper() { } //]]> </script> <script nonce="FjSzqTn5KFWlDzbVUXyQsi8PKc37fy2gfXAnb3sUjU8="> //<![CDATA[ window._trackJs = { token: 'e43bb3a0b11a469ba1ef2ec2b79c6b11', application: 'acclaim-production', version: '1.131.0'}; //]]> </script><script type="text/javascript" src="https://cdn.trackjs.com/releases/current/tracker.js"></script> <script nonce="FjSzqTn5KFWlDzbVUXyQsi8PKc37fy2gfXAnb3sUjU8="> //<![CDATA[ (function(apiKey){ (function(p,e,n,d,o){var v,w,x,y,z;o=p[d]=p[d]||{};o._q=[]; v=['initialize','identify','updateOptions','pageLoad'];for(w=0,x=v.length;w < x;++w)(function(m){ o[m]=o[m]||function(){o._q[m===v[0]?'unshift':'push']([m].concat([].slice.call(arguments,0)));};})(v[w]); y=e.createElement(n);y.async=!0;y.src='https://cdn.pendo.io/agent/static/'+apiKey+'/pendo.js'; z=e.getElementsByTagName(n)[0];z.parentNode.insertBefore(y,z);})(window,document,'script','pendo'); })("65460ef3-56d0-45a3-7b3b-fe1ec0463054") //]]> </script> <meta content='Credly is a global Open Badge platform that closes the gap between skills and opportunities. We work with academic institutions, corporations, and professional associations to translate learning outcomes into digital credentials that are immediately validated, managed, and shared.' name='description'> <meta content='Credly badges, Credly, Acclaim, open badges, digital badges, badges, web-enabled credentials, Badge Alliance, Mozilla Open Badge standards, Mozilla Open Badges, verified credentials, learning outcomes' name='keywords'> <meta content='width=device-width,initial-scale=1.0' name='viewport'> <meta content='1B97012E4CB3B07611090D1A0B4D9D19' name='msvalidate.01'> <meta content='d20lZjrSJJ_n0jc1HHlADZBDmn5wZfiBDucFzzOzHCY' name='google-site-verification'> <meta name="csrf-param" content="authenticity_token" /> <meta name="csrf-token" content="R5ymXNbob8OyC42paE5838N4NOAhs-F2MZlNVUTYquNCD2zJittioIr9Kx_Vg1yKHyFDaokG4776x_V6v5UubQ" /> <link rel="stylesheet" href="//fonts.googleapis.com/css?family=Open+Sans:400,300,600,700" media="all" /> <link rel="stylesheet" href="//use.typekit.net/bcc0eop.css" media="all" /> <link as='font' crossorigin='crossorigin' href='https://cdn.credly.com/assets/icons-525b616afff484c26342b59ecf539e7dbc2fa6225a9c281ed81f52e345669b40.woff2' rel='preload'> <script nonce="FjSzqTn5KFWlDzbVUXyQsi8PKc37fy2gfXAnb3sUjU8="> //<![CDATA[ (function(i,s,o,g,r,a,m) { i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)})(window,document,'script','//www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-41547114-1', 'credly.com'); ga('require', 'displayfeatures'); ga('send', 'pageview'); //]]> </script><title>Getting Started - Developer API - Credly</title> <link rel="stylesheet" href="https://cdn.credly.com/assets/screen-24ed6a41e63909dd5bc6b6b26a86e832a0214c4193795e8e1023b11208947d11.css" media="all" /> </head> <body class=''> <div id='unsupported-browser-message'></div> <script nonce="FjSzqTn5KFWlDzbVUXyQsi8PKc37fy2gfXAnb3sUjU8="> //<![CDATA[ pendo.initialize({"visitor":{},"account":{}}); //]]> </script><header id='website-header' style=''> <div class='website-header-main-links-container website-header-placeholder'></div> <div> <a href='#skip-target' id='skip-to-content'>Skip to content</a> </div> <div class='website-header-main-links-container non-react-header'> <div class='grid website-header-main-links'> <a class="acclaim-logo" href="https://www.credly.com/">Credly</a> <nav data-behavior='container' name='main_navigation'> <div class='header-nav-item header-nav-item--btn-container header-nav-item--btn-container--create-account-btn-container'> <a class='create-account-btn button white' href='/users/sign_up'> Create Account </a> </div> <div class='header-nav-item header-nav-item--btn-container header-nav-item--btn-container--sign-in-btn-container'> <a class='sign-in-btn button' href='/users/sign_in'> Sign In </a> </div> </nav> </div> </div> </header> <div class='search-bar search-bar--legacy' data-container='search-bar'></div> <div class='docs' id='flash'> <div class='grid'> <div class='l1-0 r1-0' data-behavior='flash-container'> <noscript> <div class='flash notice'> <i class='icon-error'></i> <div> We've detected that your browser has JavaScript disabled. Some features of Credly require Javascript to be enabled. For the best experience, please enable JavaScript in your browser settings or try using a different browser. </div> </div> </noscript> </div> </div> </div> <div id='docs'> <div class='grid' id='skip-target'> <div data-behavior='auto-sidebar fixed-element nav-container' id='sidebar'> <a href='#skip-nav-target' id='skip-nav'>Skip navigation</a> <nav data-behavior='section-nav'> <ul> <li> <a href="/docs">Overview</a> </li> <li> <a href="/docs/getting_started">Getting Started</a> </li> <li class='subnavigation'> <ul> <li class='active'> <a href='#architecture-diagram'>Architecture Diagram</a> </li> <li> <a href='#issuing-a-badge'>Issuing a Badge</a> </li> <li> <a href='#getting-issued-badges'>Getting Issued Badges</a> </li> <li> <a href='#revoking-a-badge'>Revoking a Badge</a> </li> </ul> </li> <li> <a href="/docs/web_service_api">Web Service API</a> </li> <li class='subnavigation'> <ul> <li class='active'> <a href='#api-conventions'>API Conventions</a> </li> <li> <a href='#api-versions'>API Versions</a> </li> <li> <a href='#url-construction'>URL Construction</a> </li> <li> <a href='#authentication'>Authentication</a> </li> <li> <a href='#viewing-auth-tokens'>Retrieving Authentication Tokens</a> </li> <li> <a href='#create-auth-tokens'>Create Authentication Tokens</a> </li> <li> <a href='#rotate-auth-tokens'>Rotate Authentication Tokens</a> </li> <li> <a href='#oauth-authentication'>OAuth2 Authentication</a> </li> <li> <a href='#web-service-responses'>Web Service Responses</a> </li> </ul> </li> <li> <a href="/docs/badge_templates">Badge Templates</a> </li> <li class='subnavigation'> <ul data-container="subnavigation"> <li><a href="#get-badge-templates">Get Badge Templates</a></li> <li><a href="#get-a-single-badge-template">Get a Single Badge Template</a></li> </ul> </li> <li> <a href="/docs/badge_templates_extended">Badge Templates (Extended)</a> </li> <li class='subnavigation'> <ul data-container="subnavigation"> <li><a href="#create-a-badge-template">Create a Badge Template</a></li> <li><a href="#update-a-badge-template">Update a Badge Template</a></li> <li><a href="#archive-a-badge-template">Archive a Badge Template</a></li> <li><a href="#unarchive-a-badge-template">Unarchive a Badge Template</a></li> <li><a href="#delete-a-badge-template">Delete a Badge Template</a></li> </ul> </li> <li> <a href="/docs/recommendations">Recommendations</a> </li> <li class='subnavigation'> <ul data-container="subnavigation"> <li><a href="#list-recommendations">List Recommendations</a></li> <li><a href="#recommendation-details">Recommendation Details</a></li> <li><a href="#list-badge-templates">List Badge Templates</a></li> <li><a href="#create-badge-recommendation">Create Badge Recommendation</a></li> <li><a href="#create-url-recommendation">Create URL Recommendation</a></li> <li><a href="#update-an-existing-recommendation">Update an Existing Recommendation</a></li> <li><a href="#delete-a-recommendation">Delete a Recommendation</a></li> </ul> </li> <li> <a href="/docs/issued_badges">Issued Badges</a> </li> <li class='subnavigation'> <ul data-container="subnavigation"> <li><a href="#issue-a-badge">Issue a Badge</a></li> <li><a href="#get-issued-badges">Get Issued Badges</a></li> <li><a href="#get-badges-in-bulk">Get Badges in Bulk</a></li> <li><a href="#replace-a-badge">Replace an Issued Badge</a></li> <li><a href="#revoke-a-badge">Revoke an Issued Badge</a></li> <li><a href="#delete-a-badge">Delete an Issued Badge</a></li> </ul> </li> <li class='subnavigation'> <ul data-container="subnavigation"> <li><a href="#overview">Overview</a></li> <li><a href="#requesting-a-client-id-and-client-secret">Requesting a Client ID and Client Secret</a></li> <li><a href="#reference-client">Reference Client</a></li> <li><a href="#allowing-users-to-authorize-your-application">Allowing Users to Authorize your Application</a></li> <li><a href="#getting-an-access-token">Getting an Access Token</a></li> <li><a href="#accessing-the-credly-api">Accessing the Credly API</a></li> </ul> </li> <li> <a href="/docs/obi_specified_endpoints">OBI Specified Endpoints</a> </li> <li class='subnavigation'> <ul data-container="subnavigation"> <li><a href="#get-badge-assertion">Get Badge Assertion</a></li> <li><a href="#get-badge-class">Get Badge Class</a></li> <li><a href="#get-issuer">Get Issuer</a></li> </ul> </li> <li> <a href="/docs/organizations">Organizations</a> </li> <li class='subnavigation'> <ul data-container="subnavigation"> <li><a href="#list-organizations">List Organizations</a></li> <li><a href="#get-an-organization">Get an Organization</a></li> <li><a href="#update-an-organization">Update an Organization</a></li> <li><a href="#list-an-organizations-authorization-tokens">List an Organization's Authorization Tokens</a></li> </ul> </li> <li> <a href="/docs/issuer_authorizations">Issuer Authorizations</a> </li> <li class='subnavigation'> <ul data-container="subnavigation"> <li><a href="#get-issuers">Get Issuers</a></li> <li><a href="#get-grantors">Get Grantors</a></li> <li><a href="#deauthorize-an-issuer">Deauthorize an Issuer</a></li> </ul> </li> <li> <a href="/docs/webhooks">Webhooks</a> </li> <li class='subnavigation'> <ul data-container="subnavigation"> <li><a href="#overview">Overview</a></li> <li><a href="#configuration">Configuration</a></li> <li><a href="#event-types">Event Types</a></li> <li><a href="#example-event-detail-responses">Example Event Detail Responses</a></li> <li><a href="#examples">Examples</a></li> <li><a href="#workforce">Workforce Webhooks</a></li> </ul> </li> <li> <a href="/docs/workforce">Workforce</a> </li> <li class='subnavigation'> <ul data-container="subnavigation"> <li><a href="#get-employees">Get Employees</a></li> <li><a href="#get-a-single-employee">Get a Single Employee</a></li> <li><a href="#create-an-employee">Create an Employee</a></li> <li><a href="#update-an-employee">Update an Employee</a></li> <li><a href="#invite-an-employee">Invite an Employee</a></li> <li><a href="#delete-an-employee">Delete an Employee</a></li> <li><a href="#employee-data-api">Employee Data API</a></li> <li><a href="#employee-external-badges-api">Employee External Badges API</a></li> </ul> </li> </ul> </nav> </div> <main id='skip-nav-target'> <h1 class='toggle-nav' data-behavior='toggle-nav'>Getting Started</h1> <div class='content'> <section> <p> The information and diagrams below will give you a basic overview of how the Credly system works and how to integrate with the API. </p> </section> <section class='hr'> <h2 id='architecture-diagram'>Architecture Diagram</h2> <p>This diagram shows how all of the components of the Badging Platform fit together.</p> <img width="100%" alt="Diagram" longdesc="#architecture-diagram-explained" src="https://cdn.credly.com/assets/docs/diagram-architecture-876eb8a58bc1eb17c4e0df73b7f902c20f2b45b3b5cdfdc3a1ae00d433810a7c.png" /> <ul class='sr-only' id='archictecture-diagram-explained'> <li> The external platform makes calls to the Credly Platform REST API. Requests and responses are formatted as JSON. </li> <li> The Credly Platform consists of a database, REST web service, and the Credly website. </li> <li> The Credly Platform communicates with earners via email. Earners interact with the Credly website using a web browser. </li> </ul> </section> <section> <h2 id='issuing-a-badge'>Issuing a Badge</h2> <p> This process diagram illustrates how an External Platform can issue a badge to a new user and how the user can share their badge via social media. </p> <img width="100%" alt="" longdesc="#issuing-a-badge-explained" src="https://cdn.credly.com/assets/docs/diagram-issuing-badge-dc6377b8bb03799fbc0e848a6381275c6a7f752c52629d6e896bef6c966afa48.png" /> <ol class='sr-only' id='issuing-a-badge-explained'> <li> The External Platform makes a POST request to the badges API endpoint with a JSON payload describing the badge to be issued. </li> <li> The Credly web service responds with HTTP status 201 Created if the badge was issued successfully. </li> <li> The Credly web service sends an email notification to the Earner containing a link to the Credly web site, which can be used to accept the badge. </li> <li> The Earner clicks on the accept badge link from the email notification. </li> <li> The Credly web site responds to the Earner's web browser request by requiring the Earner to register a new account. </li> <li> The Earner fills in the registration form and submits it to the Credly web site. </li> <li> The Credly web site sends an email to the address provided by the Earner, which contains a link that the Earner must click to confirm their account. </li> <li> The Earner clicks the email confirmation link, which confirms their registration. </li> <li> The Credly web site displays the Earner's profile, where the Earner can accept the new badge. </li> <li> After accepting the badge, the Earner can share the badge to social media or by email. For example, the Earner may choose to share by email with an Employer. </li> <li> The Credly platform sends the Employer a share badge email, which contains a link to the Credly web site, where the Employer can verify the badge information. </li> </ol> </section> <section> <h2 id='getting-issued-badges'>Getting Issued Badges</h2> <p> This process diagram shows how an External Platform can retrieve a list of badges issued to a user. Refer to the API documentation for a full list of filter options. </p> <img width="100%" alt="" londesc="#getting-issued-badges-explained" src="https://cdn.credly.com/assets/docs/diagram-getting-issued-badges-94b1cb4fa64b5398b14f7fa9da947e5fc8b8ade2abd3031f6ffe8a465a41defe.png" /> <div class='sr-only' id='getting-issued-badges-explained'> <h3>Getting Issued Badges by User ID</h3> <ul> <li> The External platform issues a GET request to the Credly web service via the <a href='/docs/issued_badges'>Issued Badges</a> API endpoint filtering by user ID. Example URL: <code>/organizations/99/badges.json?filter=user_id::2</code> </li> <li> The Credly web service responds with JSON describing badges issued to user ID 2. </li> </ul> <h3>Getting Issued Badges by Email Address</h3> <ul> <li> The External platform issues a GET request to the Credly web service via the <a href='/docs/issued_badges'>Issued Badges</a> API endpoint filtering by email address. Example URL: <code>/organizations/99/badges.json?filter=query::<email address></code> </li> <li> The Credly web service responds with JSON describing badges issued to user with <email address> </li> </ul> </div> </section> <section> <h2 id='revoking-a-badge'>Revoking a Badge</h2> <p> This process diagram illustrates how an External Platform can revoke a badge that has been issued to a user. </p> <img width="100%" alt="" longdesc="#revoking-a-badge-explained" src="https://cdn.credly.com/assets/docs/diagram-revoking-badge-d913689d3a65324874ec864333fed6cc076b446d5c7d4678e526cd488f203aa2.png" /> <ul class='sr-only' id='revoking-a-badge-explained'> <li> The External platform issues a POST request to the Credly web service via the <a href='/docs/issued_badges'>Issued Badges</a> API endpoint filtering by email address. Example URL: <code>/organizations/99/badges/<badge_id>/revoke.json</code> </li> <li> The Credly web service responds with 200 OK status and JSON describing badge with ID <badge_id>, including its updated state of "revoked". </li> </ul> </section> </div> </main> </div> </div> <div data-container='global-search-results'></div> <footer id='footer' style=''> <div class='grid non-react-footer'> <section class='l1-0 r1-0 footer-margin'> <div class='links'> <div class='footer-link-wrapper'> <a class="footer-link" href="https://resources.credly.com/schedule-a-demo">Request Demo</a> </div> <div class='footer-link-wrapper'> <a class="footer-link" href="https://info.credly.com/about-us">About Credly</a> </div> <div class='footer-link-wrapper'> <a class="footer-link" href="https://info.credly.com/legal">Terms</a> </div> <div class='footer-link-wrapper'> <a class="footer-link" href="https://info.credly.com/privacy-policy">Privacy</a> </div> <div class='footer-link-wrapper'> <a class="footer-link" href="/docs">Developers</a> </div> <div class='footer-link-wrapper'> <a class="footer-link" target="_blank" href="/support">Support</a> </div> </div> <div class='cookie-links'> <div class='cookie-link-wrapper'> <a class="footer-link" target="_blank" href="https://info.credly.com/cookie-policy">Cookies</a> </div> <div class='cookie-link-wrapper'> <a class="footer-link" target="_blank" href="https://info.credly.com/cookie-policy">Do Not Sell My Personal Information</a> </div> </div> <div class='app-store-links'> <a class='app-store-link app-store-link-google' href='https://play.google.com/store/apps/details?id=com.credly.android'></a> <a class='app-store-link app-store-link-apple' href='https://apps.apple.com/us/app/credly/id1630234370'></a> </div> </section> </div> </footer> <div aria-live='assertive' class='sr-only' data-behavior='screen-reader-announcements' role='alert'> <span></span> </div> <script nonce="FjSzqTn5KFWlDzbVUXyQsi8PKc37fy2gfXAnb3sUjU8="> //<![CDATA[ (function(){ document.addEventListener('click', function(e){ var eventTarget = e.target; if (eventTarget.id == 'skip-to-content' || eventTarget.id == 'skip-nav'){ var href, target; href = eventTarget.getAttribute('href').substr(1); target = document.getElementById(href); if (!target.getAttribute('tabindex')){ target.setAttribute('tabindex', '-1'); } target.focus(); } }); })(); //]]> </script><script src="https://cdn.credly.com/assets/legacy_application-ed3230df6745b5785532c292eb69a9a503dab0bd052d50fa449666a59577540f.js" crossorigin="anonymous"></script> <script src="https://cdn.credly.com/assets/utilities/set_time_zone_cookie-aca1fcb79ea4e90d8e963d7850b867a9bbeb077b05a6cad141c1ce7d945fd20d.js" crossorigin="anonymous"></script> <script src="https://cdn.credly.com/assets/utilities/set_supported_browser_flag-4358d3fc13a018a9a17a468d8a96f4ea4cb8b3489224d4c4e3fc6b23b9e09f45.js" crossorigin="anonymous"></script> <script nonce="FjSzqTn5KFWlDzbVUXyQsi8PKc37fy2gfXAnb3sUjU8="> //<![CDATA[ (function(){ if (typeof(App) !== 'undefined' && App.Behaviors && App.Behaviors.TrackStat) { App.Behaviors.TrackStat.init( {"url":"https:\/\/stats.credly.com\/stats\/interaction","request_data":{"session_id":"2f16e999-c255-4464-b4d5-8d34424281c6","flexible_params_auth":["snapshot_json","stat_object_id","stat_object_type","stat_type"],"auth_version":"1.0","auth_key":"user:8d768abb-4e6a-4f38-8cb3-86dc95196f75","auth_timestamp":"1739797029","auth_signature":"3964018556e491b2e2af379a84154320599408d45a3e2b9cd32840ed064799c9"}}, null ); } })(); //]]> </script><script src="https://cdn.credly.com/assets/utilities/warn_unsupported_browsers-74a87b5eae33bb6b05d13d276a337fcfb531f763344fa6bb30b70ecbf01cb3e2.js" crossorigin="anonymous"></script> </body> </html>