Achievement Definitions

{
    "data": [
        {
            "id": 1,
            "name": "Become a favourite",
            "handle": "favourite",
            "description": "Unlocks special rewards for favourites",
            "internal_notes": null,
            "type": null,
            "starts_at": "2020-03-10T00:00:00.000000Z",
            "ends_at": "2021-06-25T00:00:00.000000Z",
            "is_published": true,
            "display_level": true,
            "display_option": "visible",
            "short_description": "favourite",
            "long_description": "<h3><strong>Become a Favourite</strong></h3>",
            "terms_conditions": "<p>Terms and Conditions</p>",
            "earn_instructions": null,
            "icon": "https://icons.example.com/1",
            "image_url": "https://images.example.com/1",
            "levels": [
                {
                    "id": 7,
                    "name": "favourite 1",
                    "achievement_definition_id": 1,
                    "display_number": 1,
                    "description": null,
                    "trigger": 5000,
                    "repeats": 0,
                    "repeat_interval": null,
                    "allow_multiple_earn": true,
                    "computed_display_number": null,
                    "computed_trigger": null,
                    "meta": {
                        "unlocks": [
                            {
                                "id": "level-1",
                                "type": "benefit_definition",
                                "id_type": "handle"
                            }
                        ]
                    }
                },
                {
                    "id": 8,
                    "name": "Level 2",
                    "achievement_definition_id": 1,
                    "display_number": 2,
                    "description": null,
                    "trigger": 8000,
                    "repeats": 0,
                    "repeat_interval": null,
                    "allow_multiple_earn": true,
                    "computed_display_number": null,
                    "computed_trigger": null,
                    "meta": {
                        "unlocks": [
                            {
                                "id": "favourite-2",
                                "type": "benefit_definition",
                                "id_type": "handle"
                            }
                        ]
                    }
                }
            ],
            "tags": [],
            "meta": null,
            "created_at": "2019-12-09 11:29:04",
            "updated_at": "2020-05-14 12:33:44"
        }
    ],
    "links": {
        "first": "http://api.example-tenant.getomneo.com/api/v3/achievements/definitions?page.number=1",
        "last": "http://api.example-tenant.getomneo.com/api/v3/achievements/definitions?page.number=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "http://api.example-tenant.getomneo.com/api/v3/achievements/definitions",
        "per_page": 15,
        "to": 3,
        "total": 3
    }
}

What is an achievement definition?

Much like point definitions, achievement definitions are a configurable 'template' used when adding a profile achievement. Use Add Achievement Definition to specify your new type of achievement. After this, you can then Add a Profile Achievement to a profile, using your newly created definition.

📘

More about Achievements

Further information about achievements can be found in our helpcenter [here] (https://help.omneo.io/hc/en-au/articles/360000426075-Achievements)

Achievement definition properties

AttributeDescription
id
READ-ONLY
INTEGER
The unique Omneo ID for the definition
name
STRING
The display name of the definition
handle
STRING
A unique handle for the definition
description
STRING
The internal description for the definition
internal_notes
STRING
Internal notes attached to the definition
type
STRING
A basic string displaying the type of definition.
starts_at
DATE-TIME
The start date of the achievement. Achievement will become active after this date if the is_published is true
ends_at
DATE-TIME
The end date of the achievement. Achievement will become active after this date.
is_published
BOOLEAN
Denotes whether this achievement is active
display_level
BOOLEAN
Display the achievement levels to users
display_option
STRING
ENUM
Standard - can be seen by the customer along with instructions on how to earn
Hidden - are not seen until 'unlocked' by the customer receiving a count of 1 or more
Mystery - are seen as earnable with optional 'hint' copy but not revealed until unlocked
System - are never seen by customers, but can be used to power more advanced incentive logic or reporting
short_description
STRING
A publicly available short description for this definition
long_description
STRING
A publicly available full HTML description of the definition
terms_conditions
STRING
The terms and conditions associated with the achievement
earn_instructions
STRING
Instructions displayed to the customer, on how to earn this achievement
icon
URL
A valid URL for the icon associated with this definition
image_url
URL
A valid URL for the cover image associated with this definition
levels
ARRAY
Achievement levels attached to this definition.
Review the below 'Creating Achievement Levels' Sec

Creating Achievement Levels

Triggers

Triggers type levels will grant a level when the achievement count reaches the trigger value. These are granted only once and are used for a fixed achievement path.

Repeating

Repeat type levels will grant an achievement sequentially based on repeat interval. Used for campaigned such as 'Earn achievement for every 5 shops' etc.
A repeats value of 0 will continue indefinitely. Any other number will stop granting levels after that number is reached.

Achievement Level Fields

AttributeDescription
id
READ-ONLY
The unique Omneo ID of the achievement level
nameThe display name of the level
achievement_definition_idThe attached achievement definition for this level
display_number
INTEGER
The display order of the level
description
STRING
The primary description for the level
trigger
INTEGER
The value the achievement count must reach to grant the level
repeats
BOOLEAN
Denotes whether this level is repeatable
repeat_interval
INTEGER
A repeats value of 0 will continue indefinitely. Any other number will stop granting levels after that number is reached.
allow_multiple_earn
BOOLEAN
Can this level be earned multiple times
meta
ARRAY
Metadata attached to this level