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

Attribute

Description

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

Attribute

Description

id READ-ONLY

The unique Omneo ID of the achievement level

name

The display name of the level

achievement_definition_id

The 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