Warning: This version (v1) of the API will be deprecated on May 1st 2015



Achievements add social and competitive components to a game. Clay.io makes it easy to implement achievements, and adds a social component to them - rather than achievements only affecting the player in the game itself, their achievements matter on their Clay.io profile - similar to the importance of GamerScore for Xbox Live users.

Creating an Achievement

Before writing any code, you must create an achievement here. Click "Achievements", then "Add an Achievement". Once it's added, note the ID it assigns that achievement.

You can create as many achievements as you'd like, but can only use a total of 100 points that contribute to a user's Clay.io score.

Awarding an Achievement

Once the reference to the achievement has been created, here's an example of how to award an achievement (replacing 1 with whatever the ID of your achievement is. If you would prefer to use something more memorable than a number to reference the achievement, you can set the "Unique Identifier" when creating your achievement, and use that { id: "something-unique" }.

// For an achievement with ID # one
var achievement = new Clay.Achievement( { id: 1 } );
achievement.award( function( response ) {
    // Optional callback on completion
    console.log( response );
} );

Alternatively, for shorthand you can of course use the following:

( new Clay.Achievement( { id: 1 } ) ).award();

You don't have to worry about awarding achievements multiple times, that's all done on our end. If they already have the achievement, nothing happens.

Set the options property noUI to true to have the achievement awarded box not show (you'll be able to parse the data yourself with the callback function)

Displaying All Achievements

To bring up a list of all the possible achievements, and display which the user has earned (and has yet to earn), simply use:


Fetching All Achievements

If you would rather just grab an object containing all achievements and information on whether or not they have been earned, use:

Clay.Achievement.fetchAll( {}, function( response ) {
    console.log( response );
} );

Full Documentation

Click here for the full documentation of leaderboards

Provide Feedback

We take customer support, and the quality of our developer tools and documentation very seriously. We want to hear how you think we can improve our documentation! Let us know if anything is missing, or unclear on this documentation page, and we'll get that fixed!