POST /api/:space/achievements

Description:

Create Achievements and Achievements with Rewards attached to it using the CompetitionLabs API.

Resource URL:

https://<apphost>.competitionlabs.com/api/<your-space-name>/achievements

Request header

Key	Value	Required
X-API-KEY	Your unique API key	Yes
Content-Type	application/json	Yes

Request URL parameter

Parameter	Type	Required	Description
space	String	Yes	This is the space name which is linked to the account

Post body parameters

Parameter	Type	Required	Description
name	String	Yes	Name of the achievement
description	String	Optional	Description of the achievement
initialState	Integer	Yes	Informs the state of the achievement. Acceptable values are 1 or 0. Default value is 0
icon	String	Yes	A unique identifier for the Icon for Achievement. Achievement icon identifier retrieved from GET Achievement icons resource
ruleSets	Array [Object]	Yes	A Rule sets model. Rule sets POST body parameters can be found in Achievement rules.
deprecated	Boolean	Yes	A status of archived achievements. If true that means the achievement is archived. The default value is false (not archived)
dependantOn	Array [Object]	Optional	An Achievement link model	Type	Required	Description
			achievementId	String	Yes	An achievement identifier indicating which achievements will be dependant on the main achievement. Achievement identifier retrieved from GET Achievements resource
			linkType	Enum	Yes	Accepted values "Must", "Should" or "Must-Not". You can read more about dependencies here
minimumShouldMatch	Integer	Yes	A value indicating dependant on "Should" match - how many achievements will be dependant on with a linkType of should. Default value is 0
scheduling	Object	Yes	A model of Scheduling	Type	Required	Description
			scheduleType	Enum	Yes	Accepted values "Once", "Repeatedly" (the enums "Daily", "Weekly", "Monthly" - DISCONTINUED)
			scheduleOccurrencesLimit (DISCONTINUED)	Integer	Yes	A value indicating how many times it will be issued. Default value is 1
			every (DISCONTINUED)	Array [Integer]	Yes	A value for the parameter of the scheduleType that indicates the Daily, Weekly, Monthly repetition. EXAMPLE Monthly values - January is 1, March is 3 and so on.
			startDate	DateTime	Yes	The start date and time of a schedule. The date and time is sent in UTC. EXAMPLE "2019-11-05T12:41:00.000+0000 DateTime type parameters have an ISO8601 timestamp
			endDate	DateTime	Optional	The end date and time of a schedule. The date and time is sent in UTC. EXAMPLE "2019-11-05T12:41:00.000+0000" DateTime type parameters have an ISO8601 timestamp
achievementLiveStatus	String	Yes	A status of the Achievement. Acceptable values "Draft" or "Live" By creating the achievement with a Live status - the achievement will not be editable anymore. Only achievements that are in Draft status can be edited!
category	Array [String]	Optional	A list of categorised labels for the Achievements
memberGroups	Array [String]	Optional	A list of member groups participating in the Achievement. If the field is left empty then the Achievement is open to ALL.
metadata	Array [Object]	Optional	A list of Metadata	Type	Required	Description
			key	String	Yes	Is a unique identifier.
			value	String	Yes	The data that is identified.
translations	Map [LanguageCode, Seq [Object]]	Optional	The translations model.
*rewards	Array [Object]	Optional	A model of a Reward. *Multiple rewards can be created at the same time. No rewards added to the achievement means that the achievement is created without rewards
			Parameter	Type	Required	Description
			`entityType`	String	Yes	The value is "achievement"
			`entityId`	String	Yes	An achievement Id. The string has to be left empty as it will populate automatically when the achievement will be created
			`rewardRank`	String	Yes	It associates with the rank of the leaderboard. The string has to be left empty as the achievement doesn’t need to have a ranking system.
			`rewardName`	String	Yes	The name of a reward
			`value`	Double	Yes	Numerical value of the reward that will be issued based on the reward type
			`rewardType`	String	Yes	Reward type identifier retrieved from GET RewardTypes resource
			`description`	String	Optional	The description of a Reward
			`delay`	Integer	Optional	Delay of issuing a reward in minutes. Default value is 0
			`memberAcknowledgmentRequired`	Boolean	Yes	Requires member acknowledgement to claim a reward. If set to true reward will not be automatically issued. Default is false.
			`metadata`	Array [Object]	Optional	A list of Metadata	Type	Required	Description
						key	String	Yes	Is a unique identifier.
						value	String	Yes	The data that is identified.
			period	Integer	Optional	Reward available for a period of time from issuing. Value in minutes.
			pointInTime	DateTime	Optional	Reward is available until a specific point in time EXAMPLE 2019-11-05T12:41:00.000+0000 DateTime type parameters have an ISO8601 timestamp

EXAMPLE

Request achievement without a reward model

curl
--header "X-API-KEY: <your-api-key>"
--header "Content-Type: application/json"
--request POST https://app.competitionlabs.com/api/tester/achievements
-d '{"rewards": [],"achievement": {"jsonClass": "Achievement","name": "Your achievement name","accountId": "0sn4DmUBkPH_lz9GgxBM","description": "Your description","initialState": 0,"icon": "0ne5jGYB36Z7kpQy5AT9","ruleSets": [{"jsonClass": "RuleSet","priority": 1,"scope": "achievement","action": "member.achievement","conditions": [{"jsonClass": "MainConditionSet","matchCondition": "All","mustEvaluateTo": true,"rules": [{"jsonClass": "MainRule","fact": "event.count","operator": ">=","constant": "10","id": "GOZjIW0BzPEHrdkQtkCd","subConditions": [{"jsonClass": "SubConditionSet","matchCondition": "All","mustEvaluateTo": true,"subRules": [{"jsonClass": "SubRule","fact": "event.external.id","operator": "==","constant": "win"}]}]}]}]}],"deprecated": false,"dependantOn": [],"minimumShouldMatch": 0,"scheduling": {"scheduleType": "Once","scheduleOccurrencesLimit": 1,"every": [],"startDate": "2020-01-01T00:00:00.000+0000","onlyAggregateOnActiveDays": false},"achievementLiveStatus": "Draft","category": [],"memberGroups": [],"metadata": [],"translations": {},"translatableFields": ["name", "description"]}}'

Response for an achievement without a reward model

{
    "data": {
        "jsonClass": "Achievement",
        "name": "Your achievement name",
        "accountId": "0sn4DmUBkPH_lz9GgxBM",
        "description": "Your description",
        "initialState": 0,
        "icon": "0ne5jGYB36Z7kpQy5AT9",
        "ruleSets": [
            {
                "jsonClass": "RuleSet",
                "priority": 1,
                "scope": "achievement",
                "action": "member.achievement",
                "conditions": [
                    {
                        "jsonClass": "MainConditionSet",
                        "matchCondition": "All",
                        "mustEvaluateTo": true,
                        "rules": [
                            {
                                "jsonClass": "MainRule",
                                "fact": "event.count",
                                "operator": ">=",
                                "constant": "10",
                                "id": "GOZjIW0BzPEHrdkQtkCd",
                                "subConditions": [
                                    {
                                        "jsonClass": "SubConditionSet",
                                        "matchCondition": "All",
                                        "mustEvaluateTo": true,
                                        "subRules": [
                                            {
                                                "jsonClass": "SubRule",
                                                "fact": "event.external.id",
                                                "operator": "==",
                                                "constant": "win"
                                            }
                                        ]
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        ],
        "deprecated": false,
        "dependantOn": [],
        "minimumShouldMatch": 0,
        "scheduling": {
            "scheduleType": "Once",
            "scheduleOccurrencesLimit": 1,
            "every": [],
            "startDate": "2020-01-01T00:00:00.000+0000",
            "onlyAggregateOnActiveDays": false
        },
        "achievementLiveStatus": "Draft",
        "category": [],
        "memberGroups": [],
        "metadata": [],
        "created": "2019-11-06T14:38:59.549+0000",
        "id": "SrgnQW4Bl-kxmqaGhevd",
        "translations": {},
        "translatableFields": [
            "name",
            "description"
        ]
    }
}

Request achievement with a reward model

curl
--header "X-API-KEY: <your-api-key>"
--header "Content-Type: application/json"
--request POST https://app.competitionlabs.com/api/tester/achievements
-d '{"rewards": [{"jsonClass": "Reward","entityType": "achievement","entityId": "","rewardRank": "","rewardName": "Reward name","value": 1.0,"rewardType": "1cn4DmUBkPH_lz9GixDL","description": "This is the rewards description","delay": 0,"memberAcknowledgmentRequired": false,"metadata": [{"key": "Metadata_Key","value": "Metadata_Value"}],"pointInTime": "2020-01-01T00:00:00.000+0000","translations": {},"translatableFields": ["rewardName", "description"]}],"achievement": {"jsonClass": "Achievement","name": "Your achievement name","accountId": "0sn4DmUBkPH_lz9GgxBM","description": "Your description","initialState": 0,"icon": "0ne5jGYB36Z7kpQy5AT9","ruleSets": [{"jsonClass": "RuleSet","priority": 1,"scope": "achievement","action": "member.achievement","conditions": [{"jsonClass": "MainConditionSet","matchCondition": "All","mustEvaluateTo": true,"rules": [{"jsonClass": "MainRule","fact": "event.count","operator": ">=","constant": "10","id": "GOZjIW0BzPEHrdkQtkCd","subConditions": [{"jsonClass": "SubConditionSet","matchCondition": "All","mustEvaluateTo": true,"subRules": [{"jsonClass": "SubRule","fact": "event.external.id","operator": "==","constant": "win"}]}]}]}]}],"deprecated": false,"dependantOn": [],"minimumShouldMatch": 0,"scheduling": {"scheduleType": "Once","scheduleOccurrencesLimit": 1,"every": [],"startDate": "2020-01-01T00:00:00.000+0000","onlyAggregateOnActiveDays": false},"achievementLiveStatus": "Draft","category": [],"memberGroups": [],"metadata": [],"translations": {},"translatableFields": ["name", "description"]}}'

Response for an achievement with a reward model

{
    "data": {
        "jsonClass": "Achievement",
        "name": "Your achievement name",
        "accountId": "0sn4DmUBkPH_lz9GgxBM",
        "description": "Your description",
        "initialState": 0,
        "icon": "0ne5jGYB36Z7kpQy5AT9",
        "ruleSets": [
            {
                "jsonClass": "RuleSet",
                "priority": 1,
                "scope": "achievement",
                "action": "member.achievement",
                "conditions": [
                    {
                        "jsonClass": "MainConditionSet",
                        "matchCondition": "All",
                        "mustEvaluateTo": true,
                        "rules": [
                            {
                                "jsonClass": "MainRule",
                                "fact": "event.count",
                                "operator": ">=",
                                "constant": "10",
                                "id": "GOZjIW0BzPEHrdkQtkCd",
                                "subConditions": [
                                    {
                                        "jsonClass": "SubConditionSet",
                                        "matchCondition": "All",
                                        "mustEvaluateTo": true,
                                        "subRules": [
                                            {
                                                "jsonClass": "SubRule",
                                                "fact": "event.external.id",
                                                "operator": "==",
                                                "constant": "win"
                                            }
                                        ]
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        ],
        "deprecated": false,
        "dependantOn": [],
        "minimumShouldMatch": 0,
        "scheduling": {
            "scheduleType": "Once",
            "scheduleOccurrencesLimit": 1,
            "every": [],
            "startDate": "2020-01-01T00:00:00.000+0000",
            "onlyAggregateOnActiveDays": false
        },
        "achievementLiveStatus": "Draft",
        "category": [],
        "memberGroups": [],
        "metadata": [],
        "created": "2019-11-06T14:45:48.469+0000",
        "id": "yzctQW4BVkfsY3Zuw6Y1",
        "translations": {},
        "translatableFields": [
            "name",
            "description"
        ]
    }
}

ERROR CODES

Code	HTTP Status	Description	Example
2023	409	Rules cannot be empty	Error Response 409 Expand source { "errors": [ { "message": "Rules cannot be empty.", "code": 2023, "status": 409 } ] }
1002	404	`name` value is empty; `name` parameter was excluded; `icon` value is empty; `icon` parameter was excluded; `scheduleType` value is empty or incorrect; `achievementLiveStatus` value is empty or incorrect; Rewards `rewardName` was excluded; `rewardName` is empty; `rewardRank` was excluded; `entityId` was excluded; `value` was excluded; `rewardType` was excluded; `description` was excluded;	Error Response 404 Expand source { "errors": [ { "message": "Please enter a Name for the Achievement.", "code": 1002, "status": 404 } ] } Error Response 404 Expand source { "errors": [ { "message": "No usable value for name", "code": 1002, "status": 404 } ] } Error Response 404 Expand source { "errors": [ { "message": "No usable value for icon", "code": 1002, "status": 404 } ] } Error Response 404 Expand source { "errors": [ { "message": "Please insert an Icon into the Achievement.", "code": 1002, "status": 404 } ] } Error Response 404 Expand source { "errors": [ { "message": "No usable value for scheduling", "code": 1002, "status": 404 } ] } Error Response 404 Expand source { "errors": [ { "message": "No usable value for achievementLiveStatus", "code": 1002, "status": 404 } ] }
1008	406	`rewardType` value is empty	Error Response 406 Expand source { "errors": [ { "message": "Id cannot be empty", "code": 1008, "status": 406 } ] }
1007	404	The icon id is not in the system	Error Response 404 Expand source { "errors": [ { "message": "Invalid attachment ID [ad], record not found", "code": 1007, "status": 404 } ] }
1003	406	initialState parameter is incorrect `Name` is too long `Description` is too long	Error Response 406 Expand source { "errors": [ { "message": "The Initial state is not equal to the defined Initial state enums that are 0 or 1", "code": 1003, "status": 406 } ] } Error Response 406 Expand source { "errors": [ { "message": "The length of Name is too long. Valid length is under 10000 characters", "code": 1003, "status": 406 } ] } Error Response 406 Expand source { "errors": [ { "message": "The length of the Description is too long. Valid length is under 50000 characters", "code": 1003, "status": 406 } ] }
1001	400	`deprecated` value is incorrect	Error Response 400 Expand source { "errors": [ { "message": "unknown token a Near: }],\t\t\"deprecated\": a", "code": 1001, "status": 400 } ] }