Playoff API v2.0

The Playoff API works over HTTP Secure (HTTPS) connections, and uses the OAuth2.0 protocol for authentication.

If you are looking to use Playoff platform to start creating your own gamified apps, have a look at our Getting Started Manual or do it by yourself using one of our SDKs to connect your app with Playoff.

Game

Game Examples

Get Game's status

GET/admin/

Returns the game's status along with details such as the game's ID, title, description and type.

Get Game's status

Request
GET https://api.playoffgamification.io/v2/admin/ HTTP/1.1
Response
{
  "name": "Playoff Hermes",
  "version": "v2",
  "status": "ok",
  "game": {
    "id": "test",
    "title": "The Test Game",
    "description": "This is a test game",
    "listed": false,
    "type": "native",
    "created":"2012-04-11T08:00:00.500Z"
  }
}

Get a Game's Activity Feed

GET/admin/activity

Get the complete activity feed for a game.

By default, last 24 hour activity is returned. A period can be specified by passing start and end time stamps as query parameters.

Parameters
NameDescription
start

Earliest possible activity time stamp. Unit: UNIX time stamp or ISO time stamp

end

Latest possible activity time stamp. Unit: UNIX time stamp or ISO time stamp

 Query Parameter Request Body Required

Get a Game's Activity Feed

Request
GET https://api.playoffgamification.io/v2/admin/activity HTTP/1.1
Response
[
  {
    "event": "level",
    "actor": {
      "id": "po",
      "alias": "Po, the Dragon Warrior"
    },
    "changes": [
      {
        "metric": {
          "id": "rank",
          "name": "rank",
          "type": "state"
        },
        "delta": {
          "old": "panda",
          "new": "warrior"
        }
      }
    ],
    "timestamp": "2012-04-11T08:00:00.500Z",
    "id": "c5465c41-a15d-11e3-84ab-ebaad0c03951"
  }
]

List All Game Requests

GET/admin/requests

Lists out all pending join requests requests.

Parameters
NameDescription
skip

Number of entries to be skipped.

Defaults to0
limit

Limit the number of results returned by the query.

Defaults to10
 Query Parameter Request Body Required

List All Game Requests

There are no examples yet for this route. You can Try It yourself though!

Accept a Game Join Request

POST/admin/requests/:request_id

Accept a game join request with the given ID.

Accept a Game Join Request

There are no examples yet for this route. You can Try It yourself though!

Reject a Game Join Request

DELETE/admin/requests/:request_id

Reject a request to join the game with the given request ID.

Reject a Game Join Request

There are no examples yet for this route. You can Try It yourself though!

List All Game Invites

GET/admin/invites

Get a list of all the game's pending invitations.

Parameters
NameDescription
skip

Number of entries to be skipped.

Defaults to0
limit

Limit of the number of results returned.

Defaults to10
 Query Parameter Request Body Required

List All Game Invites

There are no examples yet for this route. You can Try It yourself though!

Send Game Invitation

POST/admin/invites

Send out invitations to join the game.

The data to be send in the body of the request should match the schema.

Send Game Invitation

There are no examples yet for this route. You can Try It yourself though!

Cancel Game Invitation

DELETE/admin/invites

Cancel a sent game invitation.

Parameters
NameDescription
email

Email ID string of the player whose invitation is to be cancelled.

 Query Parameter Request Body Required

Cancel Game Invitation

There are no examples yet for this route. You can Try It yourself though!

Player

Player Examples

List All Players

GET/admin/players

Returns a listing of all players in the game. This route can only be used with the game or debug scope.

Parameters
NameDescription
skip

Number of players to skip. Default value: 0

limit

Maximum number of players to return. Default value: 10

 Query Parameter Request Body Required

List All Players

Request
GET https://api.playoffgamification.io/v2/admin/players HTTP/1.1
Response
{
  "data": [
    {
      "id": "morpheus",
      "alias": "Morpheus",
      "enabled": true
    },
    {
      "alias": "Neo",
      "enabled": true,
      "id": "neo"
    },
    {
      "id": "trinity",
      "alias": "Trinity",
      "enabled": true
    }
  ],
  "total": 3
}

Check If a Player Exists

GET/admin/validation/player/available

Checks if a player with the provided ID exists. Returns success if the player does not exist, else throws an error with status 409.

Parameters
NameDescription
value

player ID that needs to be checked.

 Query Parameter Request Body Required

Check If a Player Exists

There are no examples yet for this route. You can Try It yourself though!

Possible Errors
409player_exists

A player with the given ID already exists.

Create a Player

POST/admin/players

Create a new player. This route can only be used in game and debug scope to add new players to a game.

The other way users can join a game is by approving the game and adding it on the Playoff Platform.

The route returns the newly created player profile.

Parameters
NameDescription
id

ID of the new player. The ID is an alpha numeric string. It should not start with a number.

alias

Alias of the new player

 Query Parameter Request Body Required

Create a Player

Request
POST https://api.playoffgamification.io/v2/admin/players HTTP/1.1
Request Body
{
  "id": "rob",
  "alias": "RVD"
}
Response
{
  "id": "rob",
  "alias": "RVD",
  "created": "2014-03-01T16:34:57.402Z",
  "scores": [],
  "teams": [],
  "enabled": true,
  "bootstrap": true
}
Possible Errors
400validation_exception

Thrown when the request body is badly formed.

408temporary_failure

Thrown when there is some sort of temporary failure.

409player_exists

Thrown when another player with the same id already exists.

Delete a Player

DELETE/admin/players/:player_id

Delete a player and all his game information. This can only be used with the game or debug scope.

Delete a Player

Request
DELETE https://api.playoffgamification.io/v2/admin/players/rob HTTP/1.1
Response
{
   "message":  "Player removed successfully"
}
Possible Errors
404player_not_found

Thrown when the player with specified ID is not found.

Reset a Player

POST/admin/players/:player_id/reset

Reset a player's score. This route can only be used on dummy players in the staging environment.

Reset a Player

Request
POST https://api.playoffgamification.io/v2/admin/players/neo/reset HTTP/1.1
Response
{
  "first_name": "Johny",
  "last_name": "Jose",
  "id": "neo",
  "alias": "Neo",
  "created": "2014-03-01T16:22:43.751Z",
  "scores": [],
  "enabled": true,
  "teams": [
    {
      "id": "53120aea188101a72a668a5e",
      "definition": {
        "id": "immortals",
        "name": "Immortals"
      },
      "roles": [
        "God"
      ],
      "name": "The Gaurdians"
    }
  ]
}

Get a Player's Profile

GET/admin/players/:player_id

Returns another player's profile information.

Get a Player's Profile

Request
GET https://api.playoffgamification.io/v2/admin/players/neo HTTP/1.1
Response
{
  "first_name": "Johny",
  "last_name": "Jose",
  "id": "neo",
  "alias": "Neo",
  "created": "2014-03-01T16:22:43.751Z",
  "scores": [
    {
      "metric": {
        "id": "existential_plane",
        "name": "Existential Plane",
        "type": "state"
      },
      "value": {
        "name": "Hell",
        "description": "The plane of demons"
      }
    },
    {
      "metric": {
        "id": "karma",
        "name": "Karma",
        "type": "point"
      },
      "value": "-1000000000"
    },
    {
      "metric": {
        "id": "weapons",
        "name": "Weapons",
        "type": "set"
      },
      "value": {
        "Bhramastra": {
          "description": "The Ultimate Weapon of mass destruction",
          "count": "1"
        }
      }
    }
  ],
  "enabled": true,
  "teams": [
    {
      "id": "53120aea188101a72a668a5e",
      "definition": {
        "id": "immortals",
        "name": "Immortals"
      },
      "roles": [
        "God"
      ],
      "name": "The Gaurdians"
    }
  ]
}
Possible Errors
404player_not_found

Thrown when no player with the specified player_id is found.

Get a Player's Activity Feed

GET/admin/players/:player_id/activity

Get a player's activity feed.

By default, last 24 hour activity is returned. A period can be specified by passing start and end time stamps as query parameters.

Parameters
NameDescription
start

Earliest possible activity time stamp. Unit: UNIX time stamp or ISO time stamp

end

Latest possible activity time stamp. Unit: UNIX time stamp or ISO time stamp

 Query Parameter Request Body Required

Get a Player's Activity Feed

Request
GET https://api.playoffgamification.io/v2/admin/players/tony/activity HTTP/1.1
Response
[
  {
    "event": "action",
    "action": {
      "id": "rescue",
      "name": "Rescue"
    },
    "count": 1,
    "changes": [
      {
        "metric": {
          "id": "fans",
          "name": "fan count",
          "type": "point"
        },
        "delta": {
          "old": "65000",
          "new": "85000"
        }
      }
    ],
    "timestamp": "2012-04-11T08:00:00.500Z",
    "id": "c5465c41-a15d-11e3-84ab-ebaad0c03951"
  }
]

Disable a Player

PUT/admin/players/:player_id/disable

Disable a player profile.

Disable a Player

There are no examples yet for this route. You can Try It yourself though!

Enable a player

PUT/admin/players/:player_id/enable

Enable a player profile.

Enable a player

There are no examples yet for this route. You can Try It yourself though!

Update Player Scores

PATCH/admin/players/:player_id/scores

Manually update a player's scores.

The data passed in the request body should satisfy the schema.

Update Player Scores

There are no examples yet for this route. You can Try It yourself though!

Revert Player's Score

POST/admin/players/:player_id/revert

Reverts player's score players/by rolling back the effects of the specified events.

Event IDs are returned in response of playing an action or execution of custom rules. Only 'action' and 'custom_rule' events can be reverted.

Parameters
NameDescription
event_ids

Array of event Ids that need to be reverted.

 Query Parameter Request Body Required

Revert Player's Score

Reverting multiple events

Request
POST https://api.playoffgamification.io/v2/admin/players/clone/revert HTTP/1.1
Request Body
{
  "event_ids": [
    "abcdef-pqrst-asdfg-uvwxyz",
    "uvwxyz-pqrst-asdfg-abcdef"
  ]
}
Response
[
  {
    "event": "abcdef-pqrst-asdfg-uvwxyz",
    "changes": [
      {
        "metric": {
          "id": "exp",
          "name": "experience",
          "type": "point"
        },
        "delta": {
          "old": "110",
          "new": "60"
        }
      },
      {
        "metric": {
          "id": "exp",
          "name": "experience",
          "type": "point"
        },
        "delta": {
          "old": "60",
          "new": "50"
        }
      }
    ],
    "status": "reverted"
  },
  {
    "event": "uvwxyz-pqrst-asdfg-abcdef",
    "changes": [
      {
        "metric": {
          "id": "rank",
          "name": "rank",
          "type": "state"
        },
        "delta": {
          "old": "Recruit",
          "new": null
        }
      }
    ],
    "status": "reverted"
  }
]

Process

Process Examples

List All Processes

GET/admin/processes

Get a list of all process instances in the game.

List All Processes

Request
GET https://api.playoffgamification.io/v2/admin/processes HTTP/1.1
Response
{
  "data": [
    {
      "id": "po/training",
      "name": "shefoo special",
      "definition": "rule",
      "access": "PRIVATE",
      "created": "20014-11-03T18:00:00.000Z",
      "game_id": "test",
      "owner": {
        "id": "po",
        "alias": "Po, the Dragon Warrior"
      },
      "state": "ACTIVE",
      "performers": [
        {
          "id": "po",
          "alias": "Po, the Dragon Warrior"
        },
       {
          "id":"shefoo",
          "alias": "master"
      ]
    }
  ],
  "total": 1
}

Create a Process Instance

POST/admin/processes

Create a process instance. The data in the body of the request should satisfy the schema.

Parameters
NameDescription
id

required ID of the process

Defaults toAuto generated identifier
name

Name of the process

definition

ID of the process definition that is to be used to create the instance.

owner_id

ID of the player who is to be assigned as the owner of the process.

 Query Parameter Request Body Required

Create a Process Instance

Request
POST https://api.playoffgamification.io/v2/admin/processes HTTP/1.1
Request Body
{
  "id": "practice_fight",
  "name": "practice fight",
  "definition": "fight",
  "owner_id": "po"
}
Response
{
  "id": "po/practice_fight",
  "definition": {
    "id": "rule",
    "name": "rule"
  },
  "state": "ACTIVE",
  "created": "2008-6-24T18:30:00.000Z",
  "name": "practice fight",
  "access": "PRIVATE",
  "performers": [
    {
      "id": "po",
      "alias": "Po, the Dragon Warrior",
      "lanes": [
        {
          "name": "street",
          "role": "player"
        }
      ]
    }
  ],
  "owner": {
    "id": "po",
    "alias": "Po, the Dragon Warrior"
  },
  "lanes": [
    "street"
  ]
}

Get a Process Instance

GET/admin/processes/:process_id

Get details of a process instance with the specified id.

Get a Process Instance

Request
GET https://api.playoffgamification.io/v2/admin/processes/practice_fight HTTP/1.1
Response
{
  "id": "po/practice_fight",
  "definition": {
    "id": "rule",
    "name": "rule"
  },
  "state": "ACTIVE",
  "created": "2008-6-24T18:30:00.000Z",
  "name": "practice fight",
  "access": "PRIVATE",
  "performers": [
    {
      "id": "po",
      "alias": "Po, the Dragon Warrior",
      "lanes": [
        {
          "name": "street",
          "role": "player"
        }
      ]
    }
  ],
  "owner": {
    "id": "po",
    "alias": "Po, the Dragon Warrior"
  },
  "lanes": [
    "street"
  ]
}

Delete a Process

DELETE/admin/processes/:process_id

Delete a process instance with the specified process ID.

Delete a Process

Request
DELETE https://api.playoffgamification.io/v2/admin/processes/po/practice_fight HTTP/1.1
Response
{
  "message": "Process 'po/practice_fight' has been deleted"
}

List All Performers of a Process

GET/admin/processes/:process_id/performers

Get a list of all the performers in the specified process.

List All Performers of a Process

Request
GET https://api.playoffgamification.io/v2/admin/processes/po/practice_fight HTTP/1.1
Response
[
  {
    "id": "po",
    "alias": "Po, the Dragon Warrior"
  },
  {
    "id": "shefoo",
    "alias": "master!"
  }
]

Join a process

POST/admin/processes/:process_id/join

Add a new player to the process.

Parameters
NameDescription
player_id

ID of the player to be added.

requested_roles

Roles of the player in the process.

 Query Parameter Request Body Required

Join a process

Request
POST https://api.playoffgamification.io/v2/admin/processes/practice_fight/join HTTP/1.1
Request Body
{
  "player_id": "mantis",
  "requested_roles": {
    "street": "observer"
  }
}
Response
{
  "street": "observer"
}

Leave a process

POST/admin/processes/:process_id/leave

An admin removes a player from the process.

Parameters
NameDescription
player_id

ID of the player to be removed from the process.

 Query Parameter Request Body Required

Leave a process

Request
POST https://api.playoffgamification.io/v2/admin/processes/po/practice_fight/leave HTTP/1.1
Request Body
{
  "player_id": "mantis"
}
Response
{
  "message": "The player 'mantis' has been removed from process 'po/practice_fight'"
}

Change roles in a process

POST/admin/processes/:process_id/roles

Change the roles of a player in a process.

Parameters
NameDescription
player_id

ID of the player whose roles are to be changed.

requested_roles

New roles of the player in the process.

 Query Parameter Request Body Required

Change roles in a process

Request
POST https://api.playoffgamification.io/v2/admin/processes/po/practice_fight/roles HTTP/1.1
Request Body
{
  "player_id": "mantis",
  "requested_roles": {
      "street": "player"
  }
}
Response
{
    "street": "player"
}

Get a Process's Activity Feed

GET/admin/processes/:process_id/activity

Get process activity feed.

By default, if no start and end parameters are provided, the activity feed for the last 24 hours is provided.

Parameters
NameDescription
start

Earliest possible activity timestamp. Timestamp to be provided in either UNIX or ISO timestamp

end

Latest possible activity timestamp. Timestamp to be provided in either UNIX or ISO timestamp

 Query Parameter Request Body Required

Get a Process's Activity Feed

There are no examples yet for this route. You can Try It yourself though!

Transfer Process Ownership

POST/admin/processes/:process_id/transfer

Transfer the ownership of the process to another player.

Parameters
NameDescription
id

ID of the new owner.

roles

Roles given to the new owner.

 Query Parameter Request Body Required

Transfer Process Ownership

Request
POST https://api.playoffgamification.io/v2/admin/processes/po/practice_fight/transfer HTTP/1.1
Request Body
{
  "id": "mantis",
  "roles": {
      "street": "player"
  }
}
Response
{
  "id": "po/test_process",
  "definition": {
    "id": "rule",
    "name": "rule"
  },
  "state": "ACTIVE",
  "created": "2008-6-24T18:30:00.000Z",
  "name": "process test",
  "access": "PRIVATE",
  "performers": [
    {
      "id": "po",
      "alias": "Po, the Dragon Warrior",
      "lanes": [
        {
          "name": "street",
          "role": "player"
        }
      ]
    }
    {
      "id": "mantis",
      "alias": "The Giant Mantis!",
      "lanes": [
        {
          "name": "street",
          "role": "player"
        }
      ]
    }
  ],
  "owner": {
    "id": "mantis",
    "alias": "The Giant Mantis!"
  },
  "lanes": [
    "street"
  ]
}

Team

Team Examples

List All Teams

GET/admin/teams

Returns a list of all teams in the game.

List All Teams

Request
GET https://api.playoffgamification.io/v2/admin/teams HTTP/1.1
Response
{
  "data": [
    {
      "id": "con_artists",
      "name": "Danny's 11",
      "definition": {
        "id": "international",
        "name": "international"
      },
      "access": "PRIVATE",
      "created": "2001-12-06T18:30:00.000Z",
      "game_id": "test",
      "owner": {
        "id": "droid",
        "alias": "Droid!"
      },
      "roles": [
        "member",
        "admin",
        "super_admin",
        "owner"
      ]
    },
    {
      "id": "musicians",
      "name": "Sound of",
      "definition": {
        "id": "local",
        "name": "local"
      },
      "access": "PUBLIC",
      "created": "1965-3-02T18:30:00.000Z",
      "game_id": "test",
      "owner": {
        "id": "droid",
        "alias": "Droid!"
      },
      "roles": [
        "member",
        "admin",
        "super_admin",
        "owner"
      ]
    }
  ],
  "total": 2
}

Create a Team

POST/admin/teams

Create a team instance by specifying a team definition.

It returns the state of the newly created team.

Parameters
NameDescription
id

The ID of the newly created team instance

Defaults toAuto generated
access

The access setting of the team instance. It can be either PUBLIC, PROTECTED or PRIVATE

Defaults toStrictest access setting allowed by the definition
name

Name of the team.

definition

The ID of the team definition to be used.

 Query Parameter Request Body Required

Create a Team

Request
POST https://api.playoffgamification.io/v2/admin/teams HTTP/1.1
Request Body
{
   "id": "navi",
   "name": "navi us",
   "access": "PRIVATE",
   "definition": "international"
}
Response
{
  "id": "navi",
  "name": "navi us",
  "definition": {
    "id": "international",
    "name": "international"
  },
  "created": "20014-11-03T18:00:00.000Z",
  "access": "PRIVATE",
  "owner": null,
  "locked": false,
  "member_count": [
    {
      "name": "member",
      "count": 0
    },
    {
      "name": "manager",
      "count": 0
    }
  ],
  "total_members": 0,
  "roles": [
    "admin",
    "member",
    "owner",
    "super_admin"
  ]
}

Get a Team

GET/admin/teams/:team_id

Get information about a particular team instance.

Get a Team

Request
GET https://api.playoffgamification.io/v2/admin/teams/con_artists HTTP/1.1
Response
{
  "id": "con_artists",
  "name": "Danny's 11",
  "definition": {
    "id": "international",
    "name": "international"
  },
  "created": "2001-12-06T18:30:00.000Z",
  "access": "PRIVATE",
  "owner": {
    "id": "danny_ocean",
    "alias": "danny"
  },
  "locked": false,
  "member_count": [
    {
      "name": "member",
      "count": 10
    },
    {
      "name": "admin",
      "count": 0
    },
    {
      "name": "super_admin",
      "count": 0
    },
    {
      "name": "owner",
      "count": 1
    }
  ],
  "total_members": 11,
  "roles": [
    "admin",
    "member",
    "owner",
    "super_admin"
  ]
}

Delete a Team

DELETE/admin/teams/:team_id

Disband a team.

All members of the team will be removed from the team.

Delete a Team

Request
DELETE https://api.playoffgamification.io/v2/admin/teams/con_artists HTTP/1.1
Response
{
  "message": "Team 'con_artists' disbanded successfully"
}

Join a Team

POST/admin/teams/:team_id/join

Add a player to a particular team.

Parameters
NameDescription
player_id

ID of the member who is to be added to the team.

requested_roles

Roles of the new member in the team

 Query Parameter Request Body Required

Join a Team

Request
POST https://api.playoffgamification.io/v2/admin/teams/con_artists/join HTTP/1.1
Request Body
{
  "requested_roles": {
    "member": true
  },
  "player_id": "isabel_lahiri"
}
Response
{
  "member": 0
}

Leave a team

POST/admin/teams/:team_id/leave

Leave a team instance who's id is specified. The ID of the player can be specified in the body of the request.

Parameters
NameDescription
player_id

ID of the player who is to be removed from the team.

 Query Parameter Request Body Required

Leave a team

Request
POST https://api.playoffgamification.io/v2/admin/teams/con_artists/leave HTTP/1.1
Request Body
{
  "player_id": "linus"
}
Response
{
  "message": "The player 'linus' has been removed from team 'con_artists'"
}

List All Members of a Team

GET/admin/teams/:team_id/members

Get a list of all the players who are members of a team

List All Members of a Team

Request
GET https://api.playoffgamification.io/v2/admin/teams/batman/members HTTP/1.1
Response
{
  "data": [
    {
      "id": "batman",
      "alias": "Batman!"
    },
    {
      "id": "robin",
      "alias": "Robin"
    }
  ],
  "total": 2
}

Change Member Roles

POST/admin/teams/:team_id/roles

Update roles of a member.

To perform the role update, the player must have sufficient privileges within the team else an error is returned. All members in the team must have at least 1 role.

The required roles should be specified in the request body.

Parameters
NameDescription
player_id

ID of the player whose roles are to be changed.

requested_roles

The requested roles of the member.

 Query Parameter Request Body Required

Change Member Roles

Request
POST https://api.playoffgamification.io/v2/admin/pearson_specter/roles HTTP/1.1
Request Body
{
  "player_id": "harvey",
  "requested_roles": {
      "managing_partner": true,
      "senior_partner": false
  }
}
Response
{
  "message": "You have successfully changed your roles in team pearson_specter",
  "roles": [
    "managing_partner"
  ]
}

Get a Team's Activity Feed

GET/admin/teams/:team_id/activity

Get the team activity feed.

By default, if start and end are not defined, the activity feed of the last 24 hours is returned.

The start and end timestamps can be specified as an ISO Timestamp or UNIX timestamp.

Parameters
NameDescription
start

Earliest possible activity timestamp.

end

Latest possible activity timestamp.

 Query Parameter Request Body Required

Get a Team's Activity Feed

There are no examples yet for this route. You can Try It yourself though!

Transfer ownership of a team

POST/admin/teams/:team_id/transfer

Transfer ownership of a team to another player.

Parameters
NameDescription
id

player_id of the new owner

roles

Team roles for the new owner.

Defaults toTeam's creator roles
 Query Parameter Request Body Required

Transfer ownership of a team

Request
POST https://api.playoffgamification.io/v2/admin/teams/con_artists/transfer HTTP/1.1
Request Body
{
  "id": "rusty"
}
Response
{
  "id": "con_artists",
  "name": "Danny's 11",
  "definition": {
    "id": "international",
    "name": "international"
  },
  "created": "2001-12-06T18:30:00.000Z",
  "access": "PRIVATE",
  "owner": {
    "id": "rusty",
    "alias": "Rusty"
  },
  "locked": false,
  "member_count": [
    {
      "name": "member",
      "count": 10
    },
    {
      "name": "admin",
      "count": 0
    },
    {
      "name": "super_admin",
      "count": 0
    },
    {
      "name": "owner",
      "count": 1
    }
  ],
  "total_members": 11,
  "roles": [
    "admin",
    "member",
    "owner",
    "super_admin"
  ]
}

Rule

Rule Examples

List All Custom Rules

GET/admin/rules

Get a list of all available custom rules in the game.

List All Custom Rules

Request
GET https://api.playoffgamification.io/v2/admin/rules HTTP/1.1
Response
[
  {
    "id": "performance_review",
    "name": "Employee performance review",
    "type": "custom",
    "variables": [
      {
      },
        "name": "target",
        "type": "int",
        "default": 50000,
        "required": true
      {
        "name": "x",
        "type": "string",
        "default": "",
        "required": false
      },
      {
        "name": "y",
        "type": "string",
        "default": "",
        "required": false
      }
    ]
  },
  {
    "id": "bonus",
    "name": "performance bonus",
    "type": "custom",
    "variables": [
      {
        "name": "threshold",
        "type": "int",
        "default": 0,
        "required": true
      }
    ]
  }
]

Evaluate a Custom Rule

POST/admin/rules/:rule_id

Execute a custom rule with the given rule_id.

The body of the request should be an object with a key data. data is an array of objects containing objects with a key player_ids, which is an array of player IDs on whom the rule needs to be applied on. The object also needs a variables key which is an object containing the rule variables and their values as key value pairs.

The response is the changes of each player after a particular rule is applied.

The rules are applied in the same order as the objects in the request array.

Parameters
NameDescription
data

Information about how the rule should be executed.

scopes

Scope in which the scores will be counted.

 Query Parameter Request Body Required

Evaluate a Custom Rule

Request
POST https://api.playoffgamification.io/v2/admin/rules/bonus HTTP/1.1
Request Body
{
  "data": [
    {
      "player_ids": ["jane_doe","john_doe", "jonnie_doe"],
      "variables": {
       "threshold": 200000
      }
    }
  ]  
}
Response
[
  [
    {
      "player_id": "jane_doe",
      "events": {
        "local": [
          {
            "event": "custom_rule",
            "actor": {
              "id": "jane_doe",
              "alias": "Jane!"
            },
            "changes": [
              {
                "metric": {
                  "id": "salary",
                  "name": "salary",
                  "type": "point"
                },
                "delta": {
                  "old": "5000",
                  "new": "7000"
                }
              }
            ]
          }
        ],
        "global": [
          {
            "event": "level",
            "actor": {
              "id": "jane_doe",
              "alias": "Jane!"
            },
            "changes": [
              {
                "metric": {
                  "id": "rank",
                  "name": "rank",
                  "type": "state"
                },
                "delta": {
                  "old": "ast_manager",
                  "new": "manager"
                }
              }
            ]
          }
        ]
      }
    },
    {
      "player_id": "jonnie_doe",
      "events": {
        "local": [
          {
            "event": "custom_rule",
            "actor": {
              "id": "jonnie_doe",
              "alias": "jonnie_jonnie"
            },
            "changes": [
              {
                "metric": {
                  "id": "salary",
                  "name": "salary",
                  "type": "point"
                },
                "delta": {
                  "old": "8000",
                  "new": "11000"
                }
              }
            ]
          }
        ],
        "global": [
          {
            "event": "level",
            "actor": {
              "id": "jonnie_doe",
              "alias": "jonnie_jonnie"
            },
            "changes": [
              {
                "metric": {
                  "id": "rank",
                  "name": "rank",
                  "type": "state"
                },
                "delta": {
                  "old": "manager",
                  "new": "gen_manager"
                }
              }
            ]
          }
        ]
      }
    }
  ]
]

Leaderboard

Leaderboard Examples

Register Players on a Custom Leaderboard

POST/admin/leaderboards/:leaderboard_definition_id/register

Register players or teams on a custom scoped leaderboard so that they will show up on that leaderboard with a score 0.

Parameters
NameDescription
entity_ids

The ids of the players or teams you want to register on the custom leadearboard.

scopes

The scopes of the custom leaderboard you would like to register your player on.

 Query Parameter Request Body Required

Register Players on a Custom Leaderboard

Request
POST https://api.playoffgamification.io/v2/admin/leaderboards/custom_leaderboard/register HTTP/1.1
Request Body
{
  "entity_ids": ["ripley", "po"],
  "scopes": ["course_1", "course_quiz_1"]
}
Response
{
  "ok": 1
}
Possible Errors
404player_not_found

Thrown when the player with specified ID is not found.

404team_not_found

Thrown when the team with specified ID is not found.

400invalid_request

You can register players only on custom leaderboards.

404leaderboard_definition_not_found

The leaderboard definition does not exist in game

Deregister Players on a Custom Leaderboard

POST/admin/leaderboards/:leaderboard_definition_id/deregister

Deregister players or teams on a custom scoped leaderboard so that they will be removed from the leaderboard.

Parameters
NameDescription
entity_ids

The ids of the players or teams you want to deregister on the custom leadearboard.

scopes

The scopes of the custom leaderboard you would like to deregister your player on.

 Query Parameter Request Body Required

Deregister Players on a Custom Leaderboard

Request
POST https://api.playoffgamification.io/v2/admin/leaderboards/custom_leaderboard/deregister HTTP/1.1
Request Body
{
  "entity_ids": ["ripley", "po"],
  "scopes": ["course_1", "course_quiz_1"]
}
Response
{
  "ok": 1
}
Possible Errors
404player_not_found

Thrown when the player with specified ID is not found.

404team_not_found

Thrown when the team with specified ID is not found.

400invalid_request

You can register players only on custom leaderboards.

404leaderboard_definition_not_found

The leaderboard definition does not exist in game

Misc

Misc Examples

Search for a Player

GET/admin/query/players

Search for players using auto complete. The pattern is matched against player the alias.

Parameters
NameDescription
pattern

The pattern to match with the player alias.

skip

The number of results to skip.

Defaults to0
limit

The maximum number of results returned.

Defaults to10
 Query Parameter Request Body Required

Search for a Player

Request
GET https://api.playoffgamification.io/v2/admin/query/players?pattern=jo HTTP/1.1
Response
[
  {
    "alias": "John Galt",
    "id": "johngalt"
  },
  {
    "alias": "Johny Jose",
    "id": "520e240316f4a95a0f000001"
  }
]

Search for a Team

GET/admin/query/teams

Search for a team using auto complete. The search is made against the team name or id.

Parameters
NameDescription
pattern

The pattern to match.

skip

The number of results to skip.

limit

The maximum number of results returned.

 Query Parameter Request Body Required

Search for a Team

There are no examples yet for this route. You can Try It yourself though!

Search for a Process

GET/admin/query/processes

Search for a process instance. The pattern is matched against the process ID or name.

Parameters
NameDescription
pattern

The pattern to match.

skip

The number of results to skip.

limit

The maximum number of results returned.

 Query Parameter Request Body Required

Search for a Process

There are no examples yet for this route. You can Try It yourself though!