> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omneo.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Achievement Definitions
```json theme={null}
{
"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": "Become a Favourite
",
"terms_conditions": "Terms and Conditions
",
"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](/api-reference/achievement-definition/add-achievement-definition) to specify your new type of achievement. After this, you can then [Add a Profile Achievement](/api-reference/profile-achievement/add-profile-achievement) to a profile, using your newly created definition.
See [Achievements](/concepts/incentives/achievements) for a full explanation of how achievement definitions, levels, and profile achievement instances work.
## 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 |