fbpx
Login

Custom Integration

Use our Custom Api to connect your system to Pointagram.

Basics

Custom Api basics

You can Create Players and add points to Pointagram using our Custom Api. First you’ll need an Api key and then you’ll need to be able to POST Json data to our Api endpoint.

Get your Api-key

Go to your profile and click Settings and then Integrations. Add a Custom Integration and click Create Credentials. Name your integration and click ‘Show Key’ to get your key and remember to keep it in a safe place. This key is the equivalent to a password. Click save and you’re done.

Api header

All calls to our Api endpoint must contain a header that identifies the caller. The header should contain the following attributes:

api_key: Your key.

Content-Type: application/json.

api_user: Your Pointagram login (email-address).

 

Test Endpoint

This is just a test endpoint. Use it to try out your credentials.

Endpoint address: https://app.pointagram.com/server/externalapi.php/test

Verb: POST

Body: [None]

test_call_api

Endpoints for managing players

Create Player

This endpoint is used to create new players in Pointagram. If a player already exists the endpoint will return an HTTP conflict error. A call needs to at least contain a player name.

				
					{
"player_name": "Axl Rose",
"player_email": "axl@pointagram.com",
"player_external_id": "121212",
"offline": "1"
}

 

Endpoint address: https://app.pointagram.com/server/externalapi.php/create_player

Verb: POST

JSON Body example:

{
“player_name”: “Axl Rose”,
“player_email”: “axl@pointagram.com”,
“player_external_id”: “121212”,
“offline”: “1”
}

Attributes

Player_name: The name of the player in Pointagram

Player_email: The email address of the player. Used for sending invitation.

Player_external_id: Optional id you can provide as an unique identifier for the player.

offline: Set 1 for offline or 0 for online player. An online player will receive an invitation to log on to Pointagram. Note, you can create players as offline players and convert them later in Pointagram.

List Players

This endpoint fetches players in Pointagram.

Endpoint address: https://app.pointagram.com/server/externalapi.php/list_players

Verb: GET

Attributes

search_by: Email, Name or External Id

filter: Search value.

JSON Result:

				
					[
{
"id": "18667",
"Name": "Johnny",
"emailaddress": "johnny@example.com",
"external_id": "ff:3168822"
},
{
"id": "18831",
"Name": "Peter",
"emailaddress": "peter@example.com",
"external_id": "peter@example.com"
}
]

Remove Player 

This endpoint is used to remove players. Players will be soft deleted. In order to completely remove and anonymize the players you have to look up the deleted players in Pointagram and anonymize them. 

If player isn’t found the endpoint responds with http ok and an error message. 

Admin users can’t be removed, calls to remove admin users are ignored, 

Endpoint address: https://app.pointagram.com/server/externalapi.php/remove_player 

Verb: POST 

JSON Body example: 

				
					{ 
"player_name": "Axl Rose", 
"player_email": "axl@pointagram.com", 
"player_external_id": "121212"
}

Attributes 

These attributes are only used to identify the player to be removed. 

Player_name: The name of the player in Pointagram.  

Player_email: The email address of the player. Used for sending invitation. 

Player_external_id: Optional id you can provide as an unique identifier for the player. 

Create Team

This endpoint creates teams in Pointagram.

Endpoint address: https://app.pointagram.com/server/externalapi.php/add_team

Verb: POST

				
					{ 
"team_name": "The Bulls", 
"icon": "Bull.png", 
"filter_ignore": "1"
}

Attributes 

Team_name: The name of the team in Pointagram.  

Icon: Team icon is mandatory. Use custom icons by uploading an icon image to Pointagram from the add team settings before creating the team.  

Filter ignore: Should this team be exempt from the filter settings. 

Standard Pointagram Icon names

  1. Bears.png
  2. Bulls.png
  3. Cobras.png
  4. Lions.png
  5. Raccons.png
  6. Sharks.png
  7. Tigers.png

List Teams

This endpoint fetches teams in Pointagram.

Endpoint address: https://app.pointagram.com/server/externalapi.php/list_teams

Verb: GET

JSON Result:

				
					
[
{
     "id": "80",
     "name": "Red Eyed Bear",
     "icon": "Bears.png"
   },
   {
     "id": "84",
     "name": "Mighty Sharks",
     "icon": "Sharks.png"
   }
]

Add player to team

This endpoint is used to add players to a team in Pointagram.

Endpoint address: https://app.pointagram.com/server/externalapi.php/add_to_team

Verb: POST

JSON Body example:

				
					{
“player_id”: “121212”,
“teamid”: “1”
}

Attributes

player_id: Players id.

team_id: The team id.

player_external_id: You can pass external id instead of player_id.

player_email: You can pass players email instead of player_id.

Remove player from team

This endpoint is used to remove a player from a team in Pointagram.

Endpoints address: https://app.pointagram.com/server/externalapi.php/remove_from_team

Verb: DELETE

JSON Body example:

				
					{
"player_id": "121212",
"teamid": "1"
}

Attributes

player_id: Players id.

teamiid: The team id.

player_external_id: You can pass external id instead of player_id.

player_email: You can pass players email instead of player_id.

Endpoints for adding points

This endpoint is used to add points to Pointagram. A call needs to at least contain information on:

  • Who scored.
  • What Score Series.
  • How many points.

Endpoint address: https://app.pointagram.com/server/externalapi.php/add_score

Verb: POST

Json body example:

				
					{ 
 "player_external_id": "121212",
 "points": 120, 
 "scoreseries_name": "Points"
}

Attributes

Player attributes, supply at least one:

player_id:

player_name:

player_email:

player_external_id:

Score attributes:

scoreseries_name: Name of the score series to add points to.

scoreseries_id: Id of the score series to add points to. Use either this attribute or scoreseries_name.

points: Number of points to add to the Score Series.

pointtype_name: Name of the point type to set. Use either this or the points attribute.

source_score_id: Optional field that identifies this transaction. If you call again using a matching score_source_id it will revoke (delete) the old transaction and add a new one.

comment: Optional field that describes this score. Will be visible in the news feed.

score_time: Optional field that sets the date and time of the transaction.

tags: Optional field where you can add tags to be displayed along with the scored point. The tag attribute must be in an array like this: “tags”: [{“name”:”North”},{“name”:”Services”}].

create_player: Players will be created automatically if they are missing in Pointagram if you set this attribute to 1.

Endpoint for competitions

List Competitions

This endpoint fetches competitions in Pointagram.

Endpoint address: https://app.pointagram.com/server/externalapi.php/list_competitions

Verb: GET

Attributes

search_by: Email, Name or External Id

filter: Search value. Lists only competitions for the given player.

competition_id: List only competitions for the given competition id.

accesskey: List only competitions for the given access id.

List Competition Players

This endpoint fetches competitions in Pointagram.

End point address: https://app.pointagram.com/server/externalapi.php/list_competition_players

Verb: GET

Endpoint for score series

List score series in Pointagram

Endpoint address: https://app.pointagram.com/server/externalapi.php/list_score_series

Verb: GET

List score series point types

This endpoint fetches point types for a specific score series in Pointagram.

Endpoint address: https://app.pointagram.com/server/externalapi.php/list_score_series_point_types

Verb: GET

Attributes

Scoreseries: Id of the score series to fetch Point Types for.

List score series history

Endpoint address: https://app.pointagram.com/server/externalapi.php/list_score_series_history

Verb: GET

Attributes

scoreseriesid: mandatory

tags_filter:
JSON string like this: [{“id”:”13″,”type”:1},{“id”:”14″,”type”:1}]
type 1 => tags, type 2 => point type

tags_or_filter
See above

teams_filter
JSON string of team ids like this: [“20”]

player_filter
JSON string of player profile ids like this: [“19145”]

time_from
UTC time like this 2022-12-05 23:00:00

show_revoked
0 or 1. If 1 revoked points will be returned as well.

time_to
UTC time like this 2022-12-05 23:00:00

limit
Max number of rows to be fetched (page size). Default is 50. Max is 1000.

offset_timestamp
offset_id
When fetching several pages of data. Set offset_timestamp to last fetched row’s timestamp and timestamp_id to last row’s id.

Profile sharing

You can allow profile sharing for certain integrations. Profile sharing lets you embed parts of Pointagram into your own site and show information for a certain player. In order to request data from Pointagram your web site needs to create a hash message authentication code (HAMC) using a shared secret.

				
					<iframe src="https://tv.pointagram.com/v/?showprofile=1&hidebanner={{hidebanner}}&{{tabparam}}={{tab}}&extid={{player_prefix}}{{playerid}}&ts={{now}}&client={{appid}}&code={{my_secret_string}}" title="Pointagram" style="border:0; margin: 0; height: 100vh; width: 100vw;"> </iframe>

Note, keep the App Shared Secret safe and not accessible in your client code.

You need to replace values within curly brackets as follows:

hidebanner 0 or 1, where a value of 1 will hide the profile screen banner.

tabparam Either ‘tab’ or ‘fstab’. Fstab forces a single tab layout.

tab 0-indexed value that set the active tab.

player_prefix Your external player id prefix if you’re constructing the player external id by adding a prefix, otherwise empty.

playerid The playerid in your system. This should match the external id in Pointagram.

now Current time as a unix timestamp.

appid The app id as defined in the custom integration screen.

Code The HMAC string of the following string:

				
					 "{{player_prefix}}{{playerid}} {{appid}} {{now}}". Note the spaces between {{playerid}} and {{appid}} and between {{appid}} and {{now}}.

The example above assumes that you want to use the player external id as identification for which player to display. If you prefer to use Pointagram internal id you can do so by adjusting the example above as follows:

				
					<iframe src="https://tv.pointagram.com/v/?showprofile=1&hidebanner={{hidebanner}}&{{tabparam}}={{tab}}&prid={{playerid}}&ts={{now}}&client={{appid}}&code={{my_secret_string}}" title="Pointagram" style="border:0; margin: 0; height: 100vh; width: 100vw;"> </iframe>

Where playerid is the Pointagram player id.

Code should be built up as follows:

				
					"{{playerid}} {{appid}} {{now}}". Note the spaces between {{playerid}} and {{appid}} and between {{appid}} and {{now}}.

Competition sharing

You can allow Competition sharing for certain integrations. Competition sharing lets you embed competitions into your own site. In order to request data from Pointagram your web site needs to create a hash message authentication code (HAMC) using a shared secret.

Please read profile sharing first. 

				
					<iframe src="https://tv.pointagram.com/v/?showprofile=1&extid={{player_prefix}}{{playerid}}&ts={{now}}&client={{appid}}&code={{my_secret_string}}&show=competition&id={{competition_id}}" title="Pointagram" style="border:0; margin: 0; height: 100vh; width: 100vw;"> </iframe>

You need to replace values within curly brackets as follows:

player_prefix Your external player id prefix if you’re constructing the player external id by adding a prefix, otherwise empty.

playerid The playerid in your system. This should match the external id in Pointagram.

now Current time as a unix timestamp.

appid The app id as defined in the custom integration screen.

Code The HMAC string of the following string: Read the section Profile sharing.

competition_id the id of the competition.

Widgetboard sharing

You can allow Widgetboard sharing for certain integrations. Widgetboard sharing lets you embed Widgetboards into your own site. In order to request data from Pointagram your web site needs to create a hash message authentication code (HAMC) using a shared secret.

Please read profile sharing first. 

				
					<iframe src="https://tv.pointagram.com/v/?showprofile=1&extid={{player_prefix}}{{playerid}}&ts={{now}}&client={{appid}}&code={{my_secret_string}}&show=widgetboard&id={{widgetboard_id}}" title="Pointagram" style="border:0; margin: 0; height: 100vh; width: 100vw;"> </iframe>

You need to replace values within curly brackets as follows:

player_prefix Your external player id prefix if you’re constructing the player external id by adding a prefix, otherwise empty.

playerid The playerid in your system. This should match the external id in Pointagram.

now Current time as a unix timestamp.

appid The app id as defined in the custom integration screen.

Code The HMAC string of the following string: Read the section Profile sharing.

widgetboard_id the id of the competition.

Reward store sharing

You can allow Reward store sharing for certain integrations. Reward store sharing lets you embed the reward store into your own site. In order to request data from Pointagram your web site needs to create a hash message authentication code (HAMC) using a shared secret.

Please read profile sharing first. 

				
					<iframe src="https://tv.pointagram.com/v/?showprofile=1&extid={{player_prefix}}{{playerid}}&ts={{now}}&client={{appid}}&code={{my_secret_string}}&show=rewardstore" title="Pointagram" style="border:0; margin: 0; height: 100vh; width: 100vw;"> </iframe>

You need to replace values within curly brackets as follows:

player_prefix Your external player id prefix if you’re constructing the player external id by adding a prefix, otherwise empty.

playerid The playerid in your system. This should match the external id in Pointagram.

now Current time as a unix timestamp.

appid The app id as defined in the custom integration screen.

Code The HMAC string of the following string: Read the section Profile sharing.

Content

Pointagram AB provides a gamification platform with a mission to help organizations to grow and nurture players. Inspiring organizations and entrepreneurs to build effective engagement programs.
Youtube Facebook-f Linkedin Twitter

Get Started

About

Gamification