PUT /api/:space/achievements/:id

Description:

Update achievement details in the CompetitionLabs system for a given achievement identifier.

By updating the achievement and leaving the parameter empty - means that the updated achievement will have the field updated to an empty field.

By updating the achievements parameter achievementLiveStatus to Live - the achievement will not be editable anymore. Only achievements that are in Draft status can be edited!

A reward can not be updated with an achievement. All the rewards that need to be updated within an achievement have to be deleted by inserting the reward Id in the "deleteRewards" parameter and new ones will be created by inserting the reward model in the "rewards" parameter.

The reward Id's for the parameter "deleteRewards" can be found using this URL

https://<apphost>.competitionlabs.com/api/<your-space-name>/reward/entity/<achievementId>

Resource URL:

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

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
id	String	Yes	Achievement identifier retrieved from GET Achievements resource

Put body parameters

Parameter	Type	Required	Description
name	String	Yes	Name of the achievement
description	String	Yes	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]	Yes	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" (Enum values - "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 editing the achievement to a Live status - the achievement will not be editable anymore. Only achievements that are in Draft status can be edited!
category	Array [String]	Yes	A list of categorised labels for the Achievements
memberGroups	Array [String]	Yes	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]	Yes	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]]	Yes	The translations model.
id	String	Yes	Achievement identifier retrieved from GET Achievements resource
deleteRewards	Array [String]	Yes	A list of reward Id's. A reward can not be updated. It must be deleted first and then created again. The reward Id's can be found using this URL https://<apphost>.competitionlabs.com/api/<your-space-name>/reward/entity/<achievementId>
*rewards	Array [Object]	Yes	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 for updating an achievement, creating a new reward and deleting an old reward

curl
--header "X-API-KEY: <your-api-key>"
--header "Content-Type: application/json"
--request PUT https://app.competitionlabs.com/api/tester/achievements/uD7RVWUBeag0_3vrPam5
-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+00:00","translations": {},"translatableFields": ["rewardName", "description"]}],"deleteRewards": ["ADd_QW4BVkfsY3Zu5Kdx"],"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"],"id": "uD7RVWUBeag0_3vrPam5"}}'

Response for updating an achievement, creating a new reward and deleting an old reward

{
    "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:52:23.507+0000",
        "id": "0jczQW4BVkfsY3ZuyqZT",
        "translations": {},
        "translatableFields": [
            "name",
            "description"
        ]
    }
}

ERROR CODES

Code	HTTP Status	Description	Example
1007	404	A record with requested id was not found	Error Response 404 Expand source { "errors": [ { "message": "A record with requested id was not found.", "code": 1007, "status": 404 } ] }
1001	400	`name` parameter was excluded	Error Response 400 Expand source { "errors": [ { "message": "Could not extract achievement, make sure that the model is correctly defined", "code": 1001, "status": 400 } ] }
2023	409	Rules cannot be empty	Error Response 409 Expand source { "errors": [ { "message": "Rules cannot be empty.", "code": 2023, "status": 409 } ] }
6001	406	Updating a Live achievement	Error Response 406 Expand source { "errors": [ { "message": "The achievement cannot be changed once it is live.", "code": 6001, "status": 406 } ] }