Gamification

Badges

Get badges

GET /gamification/badges

Response
Status code 200

{
  "badges": [
    {
      "id": 1,
      "name": "nice_and_tidy",
      "achieved": false,
      "achieved_at": null
    },
    {
      "id": 2,
      "name": "clean_sheet",
      "achieved": true,
      "achieved_at": "2016-06-01 13:34:12"
    },
    {
      "id": 3,
      "name": "the_communicator",
      "achieved": false,
      "achieved_at": null
    },
    {
      "id": 4,
      "name": "the_fast_and_furious",
      "achieved": false,
      "achieved_at": null
    },
    {
      "id": 5,
      "name": "the_consistent",
      "achieved": true,
      "achieved_at": "2016-06-02 04:35:19"
    },
    {
      "id": 6,
      "name": "the_explorer",
      "achieved": false,
      "achieved_at": null
    },
    {
      "id": 7,
      "name": "the_seller",
      "achieved": true,
      "achieved_at": "2016-06-01 19:00:22"
    },
    {
      "id": 8,
      "name": "the_helper",
      "achieved": false,
      "achieved_at": null
    },
    {
      "id": 9,
      "name": "the_notifier",
      "achieved": false,
      "achieved_at": null
    },
    {
      "id": 10,
      "name": "the_early_bird",
      "achieved": false,
      "achieved_at": null
    },
    {
      "id": 11,
      "name": "the_fisherman",
      "achieved": false,
      "achieved_at": null
    },
    {
      "id": 12,
      "name": "the_hard_worker",
      "achieved": false,
      "achieved_at": null
    },
    {
      "id": 13,
      "name": "the_workaholic",
      "achieved": false,
      "achieved_at": null
    }
  ],
  "special_badges": [
    {
      "id": 14,
      "name": "the_off_duty_performer",
      "achieved": false,
      "achieved_at": null
    },
    {
      "id": 15,
      "name": "lead_commander",
      "achieved": false,
      "achieved_at": null
    }
  ]
}

Levels

See your level

GET /gamification/level

Response
Status code 200

{
  "name": "level_8",
  "points": 5,
  "progress_pct": 64,
  "level_threshold": 3.90625,
  "next_level": {
    "name": "level_9",
    "level_threshold": 7.8125
  }
}

Ranks

Create a rank

POST /gamification/ranks

You can create your own ranks from a predefined set of rules.

Parameters

  • name string
    • Between 1 and 255 characters
    • Required
  • icon string
    • Between 1 and 255 characters
    • Required
  • rule string
    • Required
    • One of the following: conversion_rate, emails_sent or total_sales

If rule is conversion_rate you must also provide a settings object.

  • settings.relations_path_id UUID
    • Required if rule is conversion_rate
  • settings.milestone_id UUID
    • Must belong to the specified relations path and must not set case status to closed
    • Required if rule is conversion_rate

Payload

{
  "name": "Top sellers",
  "icon": "rocket",
  "rule": "total_sales"
}

Response
Status code 201

{
  "id": "6877f678-0024-4ddd-b5cb-f060a7d18252",
  "team_id": 1,
  "name": "Top sellers",
  "icon": "rocket",
  "rule": {
    "name": "total_sales"
  },
  "created_at": "2016-03-03 08:23:51",
  "updated_at": "2016-03-03 08:23:51"
}

Get all ranks

GET /gamification/ranks

Query string parameters

Response
Status code 200

{
  "data": [
    {
      "id": "86e0b7be-6f01-41f9-a8ca-b4b081052bcd",
      "team_id": 1,
      "name": "Converters",
      "icon": "duck",
      "rule": {
        "name": "conversion_rate"
      },
      "created_at": "2016-03-03 08:30:12",
      "updated_at": "2016-03-03 08:30:12"
    },
    {
      "id": "4d283cbc-116c-4c3d-b23c-fe93c0f41d79",
      "team_id": 1,
      "name": "Email masters",
      "icon": "horse",
      "rule": {
        "name": "total_sales"
      },
      "created_at": "2016-03-03 08:20:30",
      "updated_at": "2016-03-03 08:20:30"
    },
    {
      "id": "8206d020-53e0-4ed2-bcc6-4b5cae6e496d",
      "team_id": null,
      "name": "Top sellers",
      "icon": "rocket",
      "rule": {
        "name": "total_sales"
      },
      "created_at": "2016-03-03 08:26:31",
      "updated_at": "2016-03-03 08:26:31"
    }
  ],
  "pagination": {
    "total": 3,
    "page": 1,
    "per_page": 15,
    "urls": {
      "previous": null,
      "next": null
    }
  }
}

Get a rank

GET /gamification/ranks/:rank_id

Response
Status code 200

{
  "id": "86e0b7be-6f01-41f9-a8ca-b4b081052bcd",
  "team_id": 1,
  "name": "Converters",
  "icon": "duck",
  "rule": {
    "name": "conversion_rate"
  },
  "settings": {
    "relations_path": {
      "id": "1eae431b-3d0f-4528-9c59-e9d1a40fcd04",
      "name": "TEST RELATIONS PATH",
      "is_sales_type": true,
      "activity_types": {
        "milestones": [
          {
            "id": "1203539b-f06c-442c-8ad0-f5a56f0615f6",
            "name": "Contract"
          },
          {
            "id": "143cef92-f9b4-4fcb-b4e4-834f34915973",
            "name": "Milestone 2"
          }
        ],
        "supportive": [
          {
            "id": "14aaf74a-59c6-409b-8990-54b78eae1c75",
            "name": "Supportive"
          },
          {
            "id": "14aaf74a-409b-59c6-4a28-54b78eae1c75",
            "name": "Supportive"
          }
        ]
      },
      "created_at": "2015-03-04 11:51:19",
      "updated_at": "2015-03-05 08:47:27"
    },
    "milestone_id": "143cef92-f9b4-4fcb-b4e4-834f34915973"
  },
  "created_at": "2016-03-03 08:30:12",
  "updated_at": "2016-03-03 08:30:12"
}

Update a rank

You can only change the name of an existing rank

PUT /gamification/ranks/:rank_id

Parameters

  • name string
    • Between 1 and 255 characters
    • Required

Payload

{
  "name": "Best salesman"
}

Response
Status code 200

{
  "name": "Best salesman"
}

Delete a rank

DELETE /gamification/ranks/:rank_id

Response
Status code 204

Get scores of rank

GET /gamification/ranks/:rank_id/scores

Response
Status code 200

{
  "scores": [
    {
      "rank": 1,
      "score": 62.5,
      "user": {
        "id": 1,
        "first_name": "Jane",
        "last_name": "Doe",
        "phone_number": "+4588888888",
        "job_title": "Sales Executive",
        "email": "demo@easir.com",
        "email_notifications": false,
        "profile_picture": "https://randomuser.me/api/portraits/thumb/women/5.jpg",
        "created_at": "2014-01-01 12:45:56",
        "updated_at": "2014-01-02 00:11:22"
      }
    }
  ],
  "current_rank": {
    "rank": 1,
    "score": 62.5,
    "user": {
      "id": 1,
      "first_name": "Jane",
      "last_name": "Doe",
      "phone_number": "+4588888888",
      "job_title": "Sales Executive",
      "email": "demo@easir.com",
      "email_notifications": false,
      "profile_picture": "https://randomuser.me/api/portraits/thumb/women/5.jpg",
      "created_at": "2014-01-01 12:45:56",
      "updated_at": "2014-01-02 00:11:22"
    }
  }
}

Social stream

Get Social stream

GET /gamification/stream

Query string parameters

Response
Status code 200

{
  "data": [
    {
      "id": 33,
      "event_type": "new_level",
      "event_data": {
        "level": {
          "name": "Some level name",
        }
      },
      "high_fived": true,
      "user": {
        "id": 1,
        "first_name": "Jane",
        "last_name": "Doe",
        "phone_number": "+4588888888",
        "job_title": "Sales Executive",
        "email": "demo@easir.com",
        "email_notifications": false,
        "profile_picture": "https://randomuser.me/api/portraits/thumb/women/5.jpg",
        "created_at": "2014-01-01 12:45:56",
        "updated_at": "2014-01-02 00:11:22"
      },
      "created_at": "2016-03-16 07:56:42",
      "updated_at": "2016-03-16 07:56:42"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "per_page": 15,
    "urls": {
      "previous": null,
      "next": null
    }
  }
}

High five an event

PUT /gamification/stream/:event_id/high-five

Response
Status code 204

Get users that high fived an event

GET /gamification/stream/:event_id/high-five/users

Response
Status code 200

{
  "data": [
    {
      "id": 1,
      "first_name": "Jane",
      "last_name": "Doe",
      "phone_number": "+4588888888",
      "job_title": "Sales Executive",
      "email": "demo@easir.com",
      "email_notifications": false,
      "profile_picture": "https://randomuser.me/api/portraits/thumb/women/5.jpg",
      "created_at": "2014-01-01 12:45:56",
      "updated_at": "2014-01-02 00:11:22"
    }
  ]
}

Targets

Targets (also known as Progress) is a way to define targets for specific actions, for a specific period.

For example, a target can be created that specifies users will reach a sales target if they perform 5 product tours per week, and 10 per month.

Only admins and team admins within a Company can configure Targets. After Targets are created, the system will start to count immediately.

Team admins can set Target Settings, which override the Target's value, so each team can decide their own target thresholds.

When a user meets Target goal, a Social Stream event added to the timeline.

Social stream target event sample

{
  "id": 12,
  "event_type": "target_reached",
  "event_data": {
    "target_type": {
      "id": 1,
      "name": "Milestone",
      "entity_type": "milestone"
    },
    "target": {
      "id": 7,
      "title": "Product sold",
      "entity_id": "6cdbf9c6-45ca-4e30-82bb-2730b1660f9d",
      "value_week": 1,
      "value_month": 10
    },
    "target_setting": {
      "value_week": 1,
      "value_month": 5
    },
    "target_count": {
      "count": 1,
      "period_type": "week",
      "week": 24
    }
  }
}

Target Types

Get Target Types list

GET /gamification/target-types

Response
Status code 200

NOTE: This is a sample response. The list may be updated. The full list can be retrieved from the API.

{
  "data": [
    {
      "id": 1,
      "name": "Milestone"
    }
  ]
}

Targets

Get all Targets

GET /gamification/targets

Response
Status code 200

{
  "data": [
    {
      "id": 1,
      "title": "Weekly user product tour target reached",
      "target_type": {
        "id": 1,
        "name": "Milestone"
      },
      "entity_id": "a203539b-f06c-442c-8ad0-f5a56f0615f6_test",
      "value_week": 1,
      "value_month": 10
    },
    {
      "id": 2,
      "title": "Monthly products sold target reached",
      "target_type": {
        "id": 1,
        "name": "Milestone"
      },
      "entity_id": "02005930-39ba-4113-b32e-cc80226cec25",
      "value_week": 1,
      "value_month": 10
    }
  ]
}

Get a Target

GET /gamification/targets/:targetId

Response
Status code 200

{
  "id": 2,
  "title": "Monthly products sold target reached",
  "target_type": {
    "id": 1,
    "name": "Milestone"
  },
  "entity_id": "02005930-39ba-4113-b32e-cc80226cec25",
  "value_week": 1,
  "value_month": 10
}

Create a Target

POST /gamification/targets

Parameters

  • target_type.id integer
    • Required
  • title string - A title for the target goal.
    • Required
  • value_week integer
    • Required
    • Min 1
    • default: weekly target goal.
  • value_month integer
    • Required
    • Min 1
    • default: monthly target goal.
  • entity_id UUID - ID of which entity should trigger the target. For example, for the Milestone Target Type, it should be a Milestone ID from a Relations Path.

Deprecated parameters

  • target_type_id in favor of target_type.id
    • Removal: 2018/04/01

Payload

{
  "target_type": {
    "id": 1
  },
  "entity_id": "79409b85-e17f-4081-b5b8-cc88789a8563",
  "title": "Product sold",
  "value_week": 1,
  "value_month": 10
}

Response
Status code 201

{
  "target_type": {
    "id": 1,
    "name": "Milestone"
  },
  "entity_id": "79409b85-e17f-4081-b5b8-cc88789a8563",
  "duration": "week",
  "title": "Product sold"
}

Delete a Target

DELETE /gamification/targets/:targetId

Response
Status code 204

Target Team Settings

Get Target Team Settings

GET /gamification/targets/:targetId/settings

Response
Status code 200

{
  "value_week": 5,
  "value_month": 10,
  "disabled": false
}

Update Target Team Settings

PUT /gamification/targets/:targetId/settings

Parameters

  • value_week integer
    • Required
    • Min 1
    • default: weekly target goal.
  • value_month integer
    • Required
    • Min 1
    • default: monthly target goal.

Payload

{
  "value_week": 5,
  "value_month": 10,
}

Response
Status code 201

{
  "value_week": 5,
  "value_month": 10,
  "disabled": true,
}