API Documentation

Introduction
Welcome to the Enjin API The Enjin Website API is a JSON-RPC service that exposes data from your website in JSON format for creating your own features and website integrations. The API is currently in beta and will be receiving several updates as we come out with them. This being said, please be sure to check this source for any new features or updates as often as possible. If you feel our API is lacking certain features, please feel free to send us suggestions here. To retrieve data from our API, you'll be given a base URL, this is generally "yourwebsite.com/api/v1/api.php". To use SSL, make sure to use https:// instead of http:// (SSL is currently supported on *.enjin.com domains only). In addition to the full URL, some API calls require parameters and some of these parameters may be optional. Every possible parameter will be listed in each specific API section. Some API calls will require your secret API key. This is used to ensure the protection of sensitive data and prevent unknown users from executing certain actions (such as tagging or untagging a user). Your API key is only shown once when it is generated. Please write down the code and make sure your key is not being shared with other individuals. You can generate a new key if needed in your Admin Panel | Settings | API area. Finally, some API calls will also require a module ID, such as the shopping module. To learn where to find this information, please read this section. To get started, read over the following sections. After that, begin reading through some of the API calls. Enabling the API Making Requests Authentication Module IDs Have questions or suggestions? Send us a ticket.
Enable the Enjin API
To enable your API, visit your admin panel / settings / API area. The content on this page includes your base API URL, your secret API key, and the API mode. Ensure that the API mode is set to "Public". The three API modes currently available are public, disabled, and read only.
Public
Using "Public" means that all API functions are active and the authentication methods can be used to retrieve or modify your website data. Usually, this means using your Secret API Key or being logged in to Enjin.
Disabled
Disabled means that the api is off entirely for anyone trying to access it.
Read Only
If the mode is set to "Read Only", the only calls to the API that will work are those that are not modifying data. For example, methods such as Points.get will work, but Points.set will not. Each API section will detail whether or not read-only is available.
Request format
The API uses JSON-RPC which requires a POST request containing a JSON string with a few parameters:
  • "jsonrpc" must be "2.0"
  • "id" is a random integer that will be returned in the API response
  • "params" is an object containing the parameters for each request
  • "method" is the name of the API class and method, for example "Friends.getList"
Example Request
{
	"jsonrpc":"2.0",
	"id":"12345",
	"params":{
		"api_key": "1a2a3a4a5a6a7a8a9a1b2b3b4b5b6b7b8b9b1c2c3c4c5c6c",
		"preset_id": "12345678"
	},
	"method":"Shop.get"
}
API testing tools
Postman is a user-friendly REST client you can use to test API calls. Note: If you are testing the User.login method, Postman will remember your login cookie. If you prefer to only send “clean” requests without cookies, consider using Fiddler (below) which does not store cookies. Fiddler is a free web debugging proxy Finally, you can use the Try It section under each method of this documentation to test your API requests. Fill in the fields and click “Send API Query!” to test any API method.
Module IDs
Some API calls require you to provide a module id. For instance, if you wanted to get the latest purchases for your shopping module, this call requires the module id parameter. The module id can be located in your admin panel by visiting your modules area, editing the specific module, and looking at the URL. It should look something like this: "/admin/editmodule/index/preset/xxxx". Copy down this last set of numbers. This is your module id.
Authentication
Each API method in the documentation lists the types of authentication available for it:
Secret Key
  • Specify "api_key" in the request params.
  • This uses the global Secret API Key or Custom API Key found in Admin - Settings - API.
Secret API Key Your secret API key is used as a parameter in some API calls to prevent unknown users from retrieving sensitive data or executing actions (such as tagging a user). If the secret API key is required in an API call, it will be listed in the parameters box. The key will only be shown once when it is generated. Make sure to write down the key while you have it. If you happen to lose it, simply generate a new key. If for any reason you need to generate a new key, you can do this in your admin panel, settings, API area. Simply click the "Change" button next to your current API key. Custom API Keys Custom API Keys are available on the Advanced and Ultimate plans and let you limit the types of functions you can access with the key. For example, you might give a developer an API Key that is only allowed to get data from your Shop and add/remove Points from users. Advanced Plan
  • 1 custom key
Ultimate Plan
  • Up to 10 custom keys
Minecraft Key
  • Specify "authkey" in the request params.
  • This uses the Minecraft server key found in Admin - Minecraft - Servers.
  • This method is useful if you are building Enjin extensions to your Minecraft server.
Session
  • Specify "session_id" in the request params.
  • You can obtain a session_id by calling "User.login"
  • Session IDs will only last for a limited amount of time (typically 30 days, but this is not guaranteed) after which you need to call User.login again for a new Session ID.
Cookie
  • A session cookie will need to be present on the web browser / client - this means the user has to be logged in to Enjin on your domain.
No authentication required
  • This API method can be accessed without any authentication or user login required.
Example: User Info
This simple example widget will display info about the user. HTML
<div id="api-widget-userinfo">
	<div class="avatar"></div>
	<p class="message"></p>
</div>
JavaScript
var url = "/api/v1/api.php";

var request = {
	"jsonrpc": "2.0",
	"id": Math.round(Math.random() * (999999 - 100000) + 100000),
	"method": "User.get",
	"params": {
	}
};

$(document).ready(function(){
	var widget = $('#api-widget-userinfo');

	$.post(url, JSON.stringify(request), function(response) {
		if (response.result) {
			if(response.result.logged_in == true) {
				var html = "Welcome " + response.result.link;
				html += "<br>Access: <b>" + response.result.registered + "</b>"
				widget.find(".message").html(html);
				widget.find(".avatar").html("<img src='" + response.result.avatar_medium + "'>");
			}
			else {
				widget.find(".message").html("Please <a href='login'>login</a> to the website!");
			}
		}
		else if (response.error)
			widget.text("Request Error: " + response.error.message);
	}, "json");
});
Example: Check if the user plays a Game
This example widget will detect if the user is playing a certain game (in this case, Minecraft) and also display the total users on your website. HTML
<div id="api-widget-gameinfo">
	<p class="message"></p>
</div>
JavaScript
var url = "/api/v1/api.php";

$(document).ready(function(){
	var request = {
		"jsonrpc": "2.0",
		"id": Math.round(Math.random() * (999999 - 100000) + 100000),
		"method": "Profile.getGames",
		"params": {
		}
	};

	var request2 = {
		"jsonrpc": "2.0",
		"id": Math.round(Math.random() * (999999 - 100000) + 100000),
		"method": "Site.getStats",
		"params": {
		}
	};

	var widget = $('#api-widget-gameinfo');

	$.post(url, JSON.stringify(request), function(response) {
		if (response.result) {
			var found_game = false;
			for(var i in response.result.games) {
				if(response.result.games[i].game_id == 4923) {
					$.post(url, JSON.stringify(request2), function(response2) {
						if (response2.result) {
							widget.find(".message").html("Hey, it looks like you play <b>" + response.result.games[i].name + "</b>! Join our community of " + response2.result.total_users + " members who play too.");
						}
					});
					found_game = true;
					break;
				}
			}
			if(!found_game) {
				widget.find(".message").text("It looks like you don't play Minecraft - please add it to your Dashboard Games to participate in our community.");
			}
		}
		else if (response.error)
			widget.text("Please login");
	}, "json");
});
Example: Simple Shop
This example widget will display a simple list of shop categories and items, along with their prices. You can click on an item to purchase it. HTML
<div id="api-widget-shop">
	<div class='shop'>Loading shop ...</div>
	<div class='points' style='margin-top: 15px;'></div>
</div>
Javascript
var url = "/api/v1/api.php";

$(document).ready(function(){
	var request = {
		"jsonrpc": "2.0",
		"id": Math.round(Math.random() * (999999 - 100000) + 100000),
		"method": "Shop.get",
		"params": {
			"preset_id": "28108588"
		}
	};

	var request_points = {
		"jsonrpc": "2.0",
		"id": Math.round(Math.random() * (999999 - 100000) + 100000),
		"method": "Points.get",
		"params": {
		}
	};

	var widget_shop = $('#api-widget-shop .shop');
	var widget_points = $('#api-widget-shop .points');

	// Get the shop data
	$.post(url, JSON.stringify(request), function(response) {
		if (response.result) {
			var html = '';
			html += renderShop(response.result, '');
			widget_shop.html(html);
		}
		else if (response.error)
			widget_shop.text("Please login");
	}, "json");

	// Get the user's points
	$.post(url, JSON.stringify(request_points), function(response) {
		if (response.result) widget_points.html("You have <b>" + response.result + "</b> points to spend.");
		else widget_points.html("You do not have any points to spend.");
	}, "json");
});

function renderShop(data, html) {
	html += "<li><h3 class='category-name'>" + data.name + "</h3><ul>";
	if(data.categories !== undefined && data.categories.length) {
		for(var c in data.categories) {
			html = renderShop(data.categories[c], html);
		}
	}
	if(data.items !== undefined && data.items.length) {
		for(var i in data.items) {
			var price = '';
			if(data.items[i].price != undefined) price = "$" + data.items[i].price;

			var points = '';
			if(data.items[i].points != undefined) points = data.items[i].points + ' points';

			var ortext = '';
			if(price != '' && points != '') ortext = ' OR ';

			html += "<li class='item-name'><a href='/buy/" + data.items[i].id + "'>" + data.items[i].name + "</a> - " + price + ortext + points + "</li>";
		}
	}
	html += "</ul></li>";
	return html;
}