API

Development API Information

Achievmint API

Overview
User identity
API version
API user account
Sandbox API
Data types
Methods

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'