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]
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
- Bears.png
- Bulls.png
- Cobras.png
- Lions.png
- Raccons.png
- Sharks.png
- 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.
