Skip to main content
{
    "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.
See Achievements for a full explanation of how achievement definitions, levels, and profile achievement instances work.

​
Achievement definition properties

AttributeDescription
id READ-ONLY INTEGERThe unique Omneo ID for the definition
name STRINGThe display name of the definition
handle STRINGA unique handle for the definition
description STRINGThe internal description for the definition
internal_notes STRINGInternal notes attached to the definition
type STRINGA basic string displaying the type of definition.
starts_at DATE-TIMEThe start date of the achievement. Achievement will become active after this date if the is_published is true
ends_at DATE-TIMEThe end date of the achievement. Achievement will become active after this date.
is_published BOOLEANDenotes whether this achievement is active
display_level BOOLEANDisplay 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 STRINGA publicly available short description for this definition
long_description STRINGA publicly available full HTML description of the definition
terms_conditions STRINGThe terms and conditions associated with the achievement
earn_instructions STRINGInstructions displayed to the customer, on how to earn this achievement
icon URLA valid URL for the icon associated with this definition
image_url URLA valid URL for the cover image associated with this definition
levels ARRAYAchievement 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-ONLYThe unique Omneo ID of the achievement level
nameThe display name of the level
achievement_definition_idThe attached achievement definition for this level
display_number INTEGERThe display order of the level
description STRINGThe primary description for the level
trigger INTEGERThe value the achievement count must reach to grant the level
repeats BOOLEANDenotes whether this level is repeatable
repeat_interval INTEGERA repeats value of 0 will continue indefinitely. Any other number will stop granting levels after that number is reached.
allow_multiple_earn BOOLEANCan this level be earned multiple times
meta ARRAYMetadata attached to this level