Overview
The Achieve Mint API will work with the JSON format for input and output parameters. Available data structures to use as method parameters are described below in the “Data types” section. Non-primitive data types must be passed to the server as plain JSON objects of structure defined in this document.
Method parameters must be submitted via an HTTP POST to the API server as fields of a single object in the request body. URL to the call method should be in the following format
https://www.AchieveMint.net/api/method.json?token=AUTH_TOKEN
AUTH_TOKEN is the authentication token returned by the “auth” method. The “auth” method itself is the only method that can be called without providing this token.
The output for every method is a single JSON-object with the method call results as separate fields. If some error occurred during the method call, this object will contain a single field named “error” containing an object of type Error.
User identity
Achieve Mint API utilizes a special data type “Identity” that consists of a number of fields that Achieve Mint user might be identified with. When using an object of this data type only one field is required to be provided but it can be any of the fields listed. Currently the API supports identifying a user by Achieve Mint ID and email address. New types of identifiers (like Facebook or Twitter ID) will be added in future versions). The main purpose of this data type is to allow 3rd party systems to grant achievements to users and not worry if these users actually have an Achieve Mint account. Upon awarding an achievement to an identity, the API will first look for a user matching the provided identity and grant an achievement offer if user is found. If there is no such user in the Achieve Mint system, the identity will be stored along with the achievement to be offered and a newly registered user will receive these offers right when their registration confirmation is complete and their identity matches the one stored in the database. An example of this workflow can be found on a diagram below.
Figure 1 - External identifiers usage example
API version
Additional global prefix for “version” might be used in any request to force the API server to use any currently supported concrete version to service the request, for example:
https://www.AchieveMint.net/api/1.0/method.json?token=AUTH_TOKEN
If no version is set in the request the latest version will be used by the server. A special method “available_version” may be used without authentication token to retrieve a list of available versions.
API user account
The authentication token received via the “auth” method for account usage is bound to the account whose credentials were used for authentication (initial account). When initial account creates a new (sub) account it cannot act on its behalf immediately. To do this, the 3rd party system must request a new token bound to the subaccount (re-authenticate) to use the API on its behalf.
Sandbox API
Sandbox API endpoint available at following URL: http://api.achievemint.net/. All requests that executed with this address will be processed at separate server and will not affect real site data.
Sandbox API has a set of predefined users, who can create another tests users and perform any API operations. Access to sandbox API can be obtained by request to Achievemint Administrator via contact page or email to development@achievemint.net.
All operations that require administration approval, such as template publishing or updating are approved automatically. Created by sandbox API users will be approved automatically because mail system in Sandbox API is disabled.
Data types
Identity |
Field |
Type |
Description |
id |
Number |
Internal Achieve Mint user unique identifier |
email |
String |
User email |
User |
Field |
Type |
Description |
id |
Number |
Internal Achieve Mint user unique identifier |
email |
String |
User email |
token |
String |
32-symbol hash code for authenticating subsequent API calls |
authority_categories |
Array |
Array of user authority categories |
status |
String |
User activity status. Possible values: “active”, “inactive” |
avatar |
String |
50x50 user picture URL |
online |
Boolean |
User online status |
last_visited |
Number |
User last visited time (Unix timestamp) |
Template |
Field |
Type |
Description |
id |
Number |
Internal Achieve Mint template unique identifier |
name |
String |
Template name |
description |
String |
Template description |
icon |
String |
Template icon URL |
categories |
Array |
Template categories list |
difficulty |
Number |
Difficulty Rating. Possible values: [0.0, 5.0] |
credibility |
Number |
Credibility Ration. Possible values: [0.0, 5.0] |
status |
String |
Template publishing status. Possible values: “published”, “draft” |
attachments |
Array(‘name’,’url’) |
Array of the files attached to the template |
featured |
Boolean |
Featured status |
publish_date |
Number |
Template publishing date. Unix timestamp |
Achievement |
Field |
Type |
Description |
id |
Number |
Internal Achieve Mint achievement unique identifier |
user |
User |
Achievement receiver |
template |
Template |
Achievement template |
award_date |
Number |
Achievement award date. Unix timestamp |
Achievement Offer |
Field |
Type |
Description |
id |
Number |
Internal Achieve Mint achievement offer unique identifier |
user |
User |
Achievement receiver |
template |
Template |
Achievement template |
Achievement Request |
Field |
Type |
Description |
id |
Number |
Internal Achieve Mint achievement offer unique identifier |
user |
User |
Achievement receiver |
template |
Template |
Achievement template |
Error |
Field |
Type |
Description |
code |
Number |
Error code |
description |
String |
Error description |
Category |
Field |
Type |
Description |
id |
Number |
Internal Achieve Mint category unique identifier |
name |
String |
Category name |
Image |
Field |
Type |
Description |
format |
String |
Image format, available values are: “png”, “jpg” |
data |
String |
Base64 encoded image content |
url |
String |
Optional URL for the image, if no data is specified, Achieve Mint server will download image from this URL. |
File |
Field |
Type |
Description |
format |
String |
File format, available values are: “jpg”, “png”, “gif”, “doc”, “docx”, “xls”, “xlsx”, “ppt”, “pptx”, “zip”, “rar”, “html”. |
name |
String |
File name as provided by user |
data |
String |
Base64 encoded file content |
url |
String |
Optional url for the file, if no data is specified, Achieve Mint server will download file from this url. |
Methods
Authorization and user management
auth |
This is the main authentication method that must be called first to acquire user object with generated authentication token to use in subsequent method calls. |
INPUT |
Field |
Type |
Description |
identity |
Identity |
User identity |
password |
String |
User password |
OUTPUT |
Field |
Type |
Description |
user |
User |
User object with generated auth token |
Example Call |
curl https://www.achievemint.net/api/1.0/auth.json -d 'identity={"email":"email_string"}&password=password_string' |
user |
Method returns user object that is found by email |
INPUT |
Field |
Type |
Description |
identity |
Identity |
User email to look for |
OUTPUT |
Field |
Type |
Description |
user |
User |
User object |
Example Call |
curl https://www.achievemint.net/api/1.0/user.json -d 'identity={"email":"email_string"}&token=token' |
create_user |
User registration method. If some part of the provided data is invalid a validation error will be returned. |
INPUT |
Field |
Type |
Description |
email |
String |
User email, max length 128 |
password |
String |
User password, max length 128 |
name |
String |
Full user name, max length 50 |
nickname |
String |
User nickname, max length 50, optional |
avatar |
Image |
User avatar image file, optional |
OUTPUT |
Field |
Type |
Description |
user |
User |
Registered user |
Example Call |
curl https://www.achievemint.net/api/1.0/create_user.json -d 'email=email_string&password=password_string&name=name_string &nickname=nickname_string&avatar={"format":"png","data":null,"url":"full_image_web_address"}&token=token' |
Achievements and Templates management
achievement |
Returns an achievement object by its id |
INPUT |
Field |
Type |
Description |
id |
Number |
Achievement internal id |
OUTPUT |
Field |
Type |
Description |
achievement |
Achievement |
Found achievement object. |
Example Call |
curl https://www.achievemint.net/api/1.0/achievement.json -d 'id=achievement_id&token=token' |
find_achievements |
Returns a list of achievement objects filtered by provided criteria |
INPUT |
Field |
Type |
Description |
user_identity |
Identity |
Achievement owner as a filter |
type |
String |
Achievements type. Possible values: “awarded”, “received” |
categories |
Array |
List of categories identifiers to look for |
awarded_from |
Number |
Lower bound of creation time to search |
awarded _to |
Number |
Upper bound of creation time to search |
new |
Boolean |
Get only new (not viewed) achievements |
sort |
String |
Sort type for achievements. Possible values: “id”, “name”, “awarded” |
order |
String |
Sorting order. Possible values: “asc”, “desc” |
limit |
Number |
|
offset |
Number |
|
OUTPUT |
Field |
Type |
Description |
achievement |
Array |
Found achievement objects. |
Example Call |
curl https://www.achievemint.net/api/1.0/find_achievements.json -d 'user_identity={"email":"email_string"}&type=awarded&categories=[1,2,3]&awarded_from=1375086214&awarded_to=1375286214&new=1&sort=id&order=asc&limit=10&offset=0&token=token' |
export_achievements |
This method is the only method that returns a ZIP-archive with the exported achievements in the XML format instead of a standard JSON response. |
INPUT |
Field |
Type |
Description |
user_identity |
Identity |
Achievement owner as a filter |
achievement_ids |
Array |
List of user achievements to be exported |
OUTPUT |
ZIP-archive with requested achievements as XML-files |
Example Call |
curl https://www.achievemint.net/api/1.0/export_achievements.json -d 'user_identity={"email":"email_string"}&achievement_ids=[1,2,3]&token=token' |
template |
Returns achievement template object by its id |
INPUT |
Field |
Type |
Description |
id |
Number |
Template internal id |
OUTPUT |
Field |
Type |
Description |
template |
Template |
Found template object. |
Example Call |
curl https://www.achievemint.net/api/1.0/template.json -d 'id=template_id&token=token' |
find_templates |
Returns list of achievement template objects filtered by provided criteria |
INPUT |
Field |
Type |
Description |
categories |
Array |
List of categories identifiers to look for |
status |
String |
Template publishing status. Possible values: “published”, “draft” |
sort |
String |
Sort type for achievements. Possible values: “id”, “name”, “created” |
order |
String |
Sorting order. Possible values: “asc”, “desc” |
limit |
Number |
|
offset |
Number |
|
OUTPUT |
Field |
Type |
Description |
templates |
Array<Template> |
Found template objects. |
Example Call |
curl https://www.achievemint.net/api/1.0/find_templates.json -d 'user_identity={"email":"email_string"}&status=published&categories=[1,2,3] &sort=id&order=asc&limit=10&offset=0&token=token' |
create_template |
Creates a new achievement template object |
INPUT |
Field |
Type |
Description |
categories |
Array |
List of categories identifiers to link to template |
title |
String |
Template title, max length 200 |
description |
String |
Template descriptions, max length 1000 |
attachments |
Array |
Template file attachments |
icon |
Image |
Template icon image file, optional |
New template will be created in draft state and must be approved by administrator to become available for awarding. Template will be automatically sent to moderation queue upon creation. |
OUTPUT |
Field |
Type |
Description |
template |
Template |
Created template object. |
Example Call |
curl https://www.achievemint.net/api/1.0/create_template.json -d 'categories=[1,2,3]&title=title_string&description=description_string&attachments=[{"format":"png","name":"attachment_name","data":null,"url":"full_image_web_address"}]&icon={"format":"png","data":null,"url":"full_image_web_address"}&token=token' |
update_template |
Updatestoke existing achievement template object |
INPUT |
Field |
Type |
Description |
id |
integer |
Template version ID |
categories |
Array |
List of categories identifiers to link to template |
title |
String |
Template title, max length 200 |
description |
String |
Template descriptions, max length 1000 |
attachments |
Array |
Template file attachments |
remove_attachment |
boolean |
If true, removes all attachments from the template |
icon |
Image |
Template icon image file, optional |
New template will be created in draft state and must be approved by administrator to become available for awarding. Template will be automatically sent to moderation queue upon creation. |
OUTPUT |
Field |
Type |
Description |
template |
Template |
Created template object. |
Example Call |
curl https://www.achievemint.net/api/1.0/update_template.json -d 'id=template_id&categories=[1,2,3]&title=title_string&description=description_string&attachments=[{"format":"png","name":"attachment_name","data":null,"url":"full_image_web_address"}]&remove_attachment=1&icon={"format":"png","data":null,"url":"full_image_web_address"}&token=token' |
award |
Awards the user with an achievement, the achievement offer instance is created following a provided template ID. If provided user does not exists in the system yet, he/she will receive awarded achievement offers upon registration. |
INPUT |
Field |
Type |
Description |
user_identity |
Identity |
Identity of the user that is to receive an achievement |
template_id |
Number |
Internal template id to award |
callback_url |
String |
Optional. Valid url to be called on achievement offer accept or reject. This url will be called by Achieve Mint system when user accepts or rejects provided offer. Unique token will be passed to this url to identify that caller is Achieve Mint. |
OUTPUT |
Field |
Type |
Description |
offer |
AchievementOffer |
Achievement offer pending user request |
callback_token |
String |
Unique 32-symbols token that is to be passed to callback url |
Example Call |
curl https://www.achievemint.net/api/1.0/award.json -d 'user_identity={"email":"email_string"}&template_id=template_id&callback_url=full_callback_web_address&token=token' |
cancel_offer |
Cancels pending achievement offer |
INPUT |
Field |
Type |
Description |
id |
Number |
Internal Achieve Mint achievement offer identifier |
OUTPUT |
Field |
Type |
Description |
success |
Boolean |
Operation result |
Example Call |
curl https://www.achievemint.net/api/1.0/cancel_offer.json -d 'id=offer_id&token=token' |
find_requests |
Cancels pending achievement offer |
INPUT |
Field |
Type |
Description |
limit |
Number |
|
offset |
Number |
|
OUTPUT |
Field |
Type |
Description |
requests |
Array |
Operation result |
Example Call |
curl https://www.achievemint.net/api/1.0/find_requests.json -d 'limit=10&offset=0&token=token' |
accept_request |
Accepts pending achievement request |
INPUT |
Field |
Type |
Description |
id |
Number |
Internal Achieve Mint achievement request identifier |
OUTPUT |
Field |
Type |
Description |
success |
Boolean |
Operation result |
Example Call |
curl https://www.achievemint.net/api/1.0/accept_request.json -d 'id=request_id&token=token' |
reject_request |
Rejects pending achievement request |
INPUT |
Field |
Type |
Description |
id |
Number |
Internal Achieve Mint achievement request identifier |
OUTPUT |
Field |
Type |
Description |
success |
Boolean |
Operation result |
Example Call |
curl https://www.achievemint.net/api/1.0/reject_request.json -d 'id=request_id&token=token' |
find_offers |
Returns list of pending achievement offers for current owner templates |
INPUT |
Field |
Type |
Description |
limit |
Number |
|
offset |
Number |
|
OUTPUT |
Field |
Type |
Description |
requests |
Array |
Operation result |
Example Call |
curl https://www.achievemint.net/api/1.0/find_offers.json -d 'limit=10&offset=0&token=token' |
accept_offer |
Accepts pending achievement offer |
INPUT |
Field |
Type |
Description |
limit |
Number |
Internal Achieve Mint achievement request identifier |
OUTPUT |
Field |
Type |
Description |
success |
Boolean |
Operation result |
Example Call |
curl https://www.achievemint.net/api/1.0/accept_offer.json -d 'id=request_id&token=token' |
reject_offer |
Accepts pending achievement offer |
INPUT |
Field |
Type |
Description |
limit |
Number |
Internal Achieve Mint achievement request identifier |
OUTPUT |
Field |
Type |
Description |
success |
Boolean |
Operation result |
Example Call |
curl https://www.achievemint.net/api/1.0/reject_offer.json -d 'id=request_id&token=token' |
Utilities
available_versions |
Returns list of API versions available for use |
OUTPUT |
Field |
Type |
Description |
versions |
Array |
List of available API versions |
Example Call |
curl https://www.achievemint.net/api/1.0/available_versions.json |
current_version |
Returns current API version |
OUTPUT |
Field |
Type |
Description |
version |
String |
Current API verion, e.g. “1.6” |
Example Call |
curl https://www.achievemint.net/api/1.0/current_version.jsonn |
category_hierarchy |
Returns related categories according to relation type |
INPUT |
Field |
Type |
Description |
category_id |
Number |
Internal category identifier |
relation |
String |
Type of category hierarchy relation. Available options are:
- “parents” (returns a parent chain starting from immediate parent up to the root category)
- “children” (returns a list of immediate children)
- “siblings-next” (returns a list of all siblings that are following this category)
- “siblings-prev” (returns a list of all siblings that are preceding this category)
- “siblings” (returns al ist of all siblings of this category)
|
OUTPUT |
Field |
Type |
Description |
categories |
Array |
List of requested categories according to relation field |
Example Call |
curl https://www.achievemint.net/api/1.0/category_hierarchy.json -d 'category_id=1&relation=children&token=token' |