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

KeyValueRequired
X-API-KEY
Your unique API keyYes
Content-Type
application/jsonYes

Request URL parameter

Parameter
Type
Required
Description
space
StringYesThis is the space name which is linked to the account

Post body parameters

Parameter
Type
Required
Description
name
StringYesName of the achievement
description
StringOptionalDescription of the achievement
initialState
IntegerYes

Informs the state of the achievement. Acceptable values are 1 or 0. Default value is 0

icon
StringYesA unique identifier for the Icon for Achievement. Achievement icon identifier retrieved from GET Achievement icons resource
ruleSets
Array [Object]Yes

Rule sets model. 

Rule sets POST body parameters can be found in Achievement rules


deprecated
BooleanYesA status of archived achievements. If true that means the achievement is archived. The default value is false (not archived)
dependantOn
Array [Object]OptionalAn Achievement link modelTypeRequiredDescription
achievementId
StringYesAn achievement identifier indicating which achievements will be dependant on the main achievement. Achievement identifier retrieved from GET Achievements resource
linkType
EnumYes

Accepted values "Must", "Should" or "Must-Not". 

You can read more about dependencies here

minimumShouldMatch
IntegerYesA value indicating dependant on "Should" match - how many achievements will be dependant on with a linkType of should. Default value is 0
scheduling
ObjectYesA model of SchedulingTypeRequiredDescription
scheduleType
EnumYesAccepted values "Once", "Repeatedly", "Daily", "Weekly", "Monthly"
scheduleOccurrencesLimit
IntegerYesA value indicating how many times it will be issued. Default value is 1
every
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
DateTimeYes

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
DateTimeOptional

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
StringYes

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]OptionalA list of categorised labels for the Achievements
memberGroups
Array [String]OptionalA list of member groups participating in the Achievement. If the field is left empty then the Achievement is open to ALL.
metadata
Array [Object]OptionalA list of MetaDataTypeRequiredDescription
key
StringYesIs a unique identifier.
value
StringYesThe data that is identified.
translations

Map [LanguageCode, Seq [Object]]

OptionalThe 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

ParameterTypeRequiredDescription
entityTypeStringYesThe value is "achievement"
entityIdStringYes

An achievement Id.

The string has to be left empty as it will populate automatically when the achievement will be created

rewardRankStringYes

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.

rewardNameStringYesThe name of a reward
valueDoubleYesNumerical value of the reward that will be issued based on the reward type
rewardTypeStringYesReward type identifier retrieved from GET RewardTypes resource
descriptionStringOptionalThe description of a Reward 
delayIntegerOptionalDelay of issuing a reward in minutes. Default value is 0
memberAcknowledgmentRequiredBooleanYesRequires member acknowledgement to claim a reward. If set to true reward will not be automatically issued. Default is false.
metadataArray [Object]OptionalA list of MetadataTypeRequiredDescription
key
StringYesIs a unique identifier.
value
StringYesThe data that is identified.
period
IntegerOptionalReward available for a period of time from issuing. Value in minutes.
pointInTime
DateTimeOptional

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

CodeHTTP StatusDescriptionExample
2023409Rules cannot be empty
Error Response 409
{
    "errors": [
        {
            "message": "Rules cannot be empty.",
            "code": 2023,
            "status": 409
        }
    ]
}
1002404
  • 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
{
    "errors": [
        {
            "message": "Please enter a Name for the Achievement.",
            "code": 1002,
            "status": 404
        }
    ]
}
Error Response 404
{
    "errors": [
        {
            "message": "No usable value for name",
            "code": 1002,
            "status": 404
        }
    ]
}
Error Response 404
{
    "errors": [
        {
            "message": "No usable value for icon",
            "code": 1002,
            "status": 404
        }
    ]
}
Error Response 404
{
    "errors": [
        {
            "message": "Please insert an Icon into the Achievement.",
            "code": 1002,
            "status": 404
        }
    ]
}
Error Response 404
{
    "errors": [
        {
            "message": "No usable value for scheduling",
            "code": 1002,
            "status": 404
        }
    ]
}
Error Response 404
{
    "errors": [
        {
            "message": "No usable value for achievementLiveStatus",
            "code": 1002,
            "status": 404
        }
    ]
}
1008406rewardType value is empty
Error Response 406
{
    "errors": [
        {
            "message": "Id cannot be empty",
            "code": 1008,
            "status": 406
        }
    ]
}
1007404The icon id is not in the system
Error Response 404
{
    "errors": [
        {
            "message": "Invalid attachment ID [ad], record not found",
            "code": 1007,
            "status": 404
        }
    ]
}
1003406
  • initialState parameter is incorrect
  • Name is too long
  • Description is too long


Error Response 406
{
    "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
{
    "errors": [
        {
            "message": "The length of Name is too long. Valid length is under 10000 characters",
            "code": 1003,
            "status": 406
        }
    ]
}
Error Response 406
{
    "errors": [
        {
            "message": "The length of the Description is too long. Valid length is under 50000 characters",
            "code": 1003,
            "status": 406
        }
    ]
}
1001400

deprecated value is incorrect

Error Response 400
{
    "errors": [
        {
            "message": "unknown token a Near: }],\t\t\"deprecated\": a",
            "code": 1001,
            "status": 400
        }
    ]
}