Betpalz Web API

The Betpalz Web API is a rest-style api. All you need is an HTTP client to interact with the Betpalz System. You should be familiar with how HTTP works and be able to read and write JSON objects.

Throughout the documentation, we will have BASE_URL be defined as the base URL of the betpalz web API, where BASE_URL = https://developer.betpalz.com/api/1-0/

All calls must be made over HTTPS for security reasons. Calls made over HTTP will not work and will fail.

To gain a more general understanding of how the system works, it's recommended that you take a look at the general betpalz system documentation for a more general overview.

Authentication

System authentication is token based. Secured calls make reference to authToken which is an authentication token that the betpalz system keeps track of to identify users after they have provided their credentials.

Also, all interaction with the web API require an apiKey to be provided. The apiKey identifies your developer account to betpalz. You will receive this apiKey once you have created your betpalz developer program account. Don't share this key with anybody and keep it secure!

Web API Call Documentation

Validate User Credentials

Description:

Validate a users credentials, and receive an authentication token for subsequent requests if the users credentials are valid. In the example below, message will contain the authToken that must be used to identify the user for other calls that require user authentication.

Request:

HTTP POST - BASE_URL/{apiKey}/{username}/{password}/isUserValid

Response example:

{"success":true,"message":"authenticationTokenForUser"}
or
{"success":false,"message":"badAuth"}

Check Auth Token

description:

Check if an authentication token is valid.

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/isTokenValid

response example:

{"success":true,"message":"success"}

Get User From Token

description:

Given an authentication token, retrieve the User details for the user currently bound to this authentication token.

request:

HTTP GET - BASE_URL/{apiKey}/{authToken}/getUser

response example:

{
	"id":"userId",
	"type":"user/administrator/developper",
	"email":"email-adress",
	"blocked":"false/true",
	"firstName":"First Name",
	"lastName":"Last Name",
	"phoneNumber":"+00-000-000-000-00",
	"avatarImage":"image URL",
	"marblesBalance":38535,
	"netWorth":1362341,
	"virtualStatus":"Peasant/Millinaire/...",
	"dateJoined":1302469200000
}

Get User Coins Balance

description:

Get the number of coins/currency units a user has available for betting and purchasing items. This represents the number of coins which are not on hold. For example, some coins may be currently tied up in active bets, and therefore are not available for use.

request:

HTTP GET - BASE_URL/{apiKey}/{userName}/getAvailableMarbles

response example:

An long (64-bit integer) representing the number of coins/currency. Example: 1000

Get Friend Ids

description:

Get the user's friends list identified by the authToken. The friends list will be a list of user ids and not the full details.

request:

HTTP GET - BASE_URL/{apiKey}/users/{authToken}/friendIds/

response example:

["friend1Id","friend2Id"]

Get Friends

description:

Get a listing of friend objects for the user identified by the authToken.

request:

HTTP GET - BASE_URL/{apiKey}/users/{authToken}/friends/

response example:

[{
	"id": "friendId",
	"type":"user",
	"email": "friendEmail@hotmail.com",
	"blocked":false,
	"firstName": "justin",
	"lastName": "simonelis",
	"phoneNumber":"+00-000-000-000-00",
	"avatarImage":"image URL",
	"marblesBalance": 10,
	"netWorth": 12,
	"virtualStatus": "Merchant",
	"dateJoined": 1296850889000
},
{
	"id":"userId",
	"type":"user/administrator/developper",
	"email":"email-adress",
	"blocked":false,
	"firstName":"First Name",
	"lastName":"Last Name",
	"phoneNumber":"+00-000-000-000-00",
	"avatarImage":"image URL",
	"marblesBalance":38535,
	"netWorth":1362341,
	"virtualStatus":"Peasant/Millinaire/...",
	"dateJoined":1302469200000
}]

Get User

description:

Get a user object by user id

request:

HTTP GET - BASE_URL/{apiKey}/users/{username}

response example:

{
	"id":"felino",
	"type":"user",
	"email":"felino@briskmobile.com",
	"blocked":false,
	"firstName":"felino",
	"lastName":"salac",
	"phoneNumber":"12345678",
	"avatarImage":"http://imageUrl",
	"marblesBalance":100,
	"netWorth":100,
	"virtualStatus":"Peasant",
	"dateJoined":1296850889000
}

Get Net Worth

description:

Get the net worth of the user represented by the authToken. The returned value is a long (64-bit integer).

request:

HTTP GET - BASE_URL/{apiKey}/users/{authToken}/networth

response example:

Get Virtual Items

description:

Retrieve all of the virtual item records that belong to a user.

request:

HTTP GET - BASE_URL/{apiKey}/users/{username}/virtualItems/

response example:

[{
    "quantity": 2,
    "userId": "userId",
    "virtualItemId": 1
}, {
    "quantity": 1,
    "userId": "userId",
    "virtualItemId": 2
}]

Get Friend Requests

description:

Get friend requests. Returns a list of userIds of those user that are attempting to request friendship with you.

request:

HTTP GET - BASE_URL/{apiKey}/{authToken}/friendRequests

response example:

 ["justin", "bob", "bill"]

Get All Virtual Statuses

description:

Get a list of all virtual statuses in the system.

request:

HTTP GET - BASE_URL/{apiKey}/virtualStatuses

response example:

 [{
     "id": 1,
     "name": "Merchant",
     "minNetWorth": 1000,
     "image": "http://imageUrl"
 }, {
     "id": 2,
     "name": "Merchant2",
     "minNetWorth": 10000,
     "image": "http://imageUrl"
 }]

Find Users

description:

Search for users with search criteria, matching users on their user names and email addresses. At least 4 characters must be supplied as the search criteria. A list of user summary elements will be returned.

request:

HTTP GET - BASE_URL/{apiKey}/{authToken}/findUsers/{query}

response example:

[{
    "id": "friendId",
    "type":"user",
    "email": "friendEmail@hotmail.com",
    "firstName": "justin",
    "lastName": "xxx",
  	"phoneNumber":"+00-000-000-000-00",
    "marblesBalance": 10,
    "netWorth": 12,
    "avatarImage": "http://imageUrl",
    "virtualStatus": "Merchant",
    "dateJoined": 1296850889000
}, {
	"id":"userId",
	"type":"user/administrator/developper",
	"email":"email-adress",
	"firstName":"First Name",
	"lastName":"Last Name",
	"phoneNumber":"+00-000-000-000-00",
	"avatarImage":"image URL",
	"marblesBalance":38535,
	"netWorth":1362341,
	"virtualStatus":"Peasant/Millinaire/...",
	"dateJoined":1302469200000
}]

Request Friendship

description:

Request friendship with anothjer betpalz user.

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/requestFriendship/{requestedFriendId}

response example:

{"success":true,"message":"success"}

Accept Friendship

description:

Accept the friendship of a user requesting friendship with you.

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/acceptFriendship/{acceptedFriendId}

response example:

{"success":true,"message":"success"}

Decline Friendship

description:

Decline a request for friendship.

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/declineFriendship/{declinedFriendId}

response example:

{"success":true,"message":"success"}

Remove Friend

description:

Remove a friend from friends list.

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/removeFriend/{friendId}

response example:

{"success":true,"message":"success"}

Purchase Virtual Items

description:

The user will purchase quantity unit(s) of the virtual item identified by itemId provided that there is enough currency that is not on hold.

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/purchaseVirtualItem/{itemId}/{amount}

response example:

{"success":true,"message":"success"}

Sell Virtual Items

description:

The user will sell quantity unit(s) of the virtual item identified by itemId provided that there are enough items that are not on hold.

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/sellVirtualItem/{itemId}/{amount}

response example:

{"success":true,"message":"success"}

Get All Virtual Items

description:

Get a list of all virtual items that are available in the system.

request:

HTTP GET - BASE_URL/{apiKey}/virtualItems/

response example:

[{
    "name": "someItem",
    "id": 1,
    "description": "descr of someItem",
    "category": "stuff",
    "marblesCost": 1,
    "image": "http: //imageUrl",
    "bigImage":"https://imageUrl"
}, {
    "name": "anotherItem",
    "id": 2,
    "description": "desc of another item",
    "category": "otherStuff",
    "marblesCost": 1,
    "image": "http://imageUrl",
    "bigImage":"https://imageUrl"
}]

Get Virtual Items On Hold

description:

Get a list of all virtual items that are on hold for a user. Items are on hold if they are currently being wagered. Returns an array of items, may contain several entries of the same viritual item

request:

HTTP GET - BASE_URL/{apiKey}/VirtualItemsOnHold/{userId}

response example:

[{
    "name": "someItem",
    "id": 1,
    "description": "descr of someItem",
    "category": "stuff",
    "marblesCost": 1,
    "image": http: //imageUrl",
    "bigImage":"https://imageUrl"
}, {
    "name": "anotherItem",
    "id": 2,
    "description": "desc of another item",
    "category": "otherStuff",
    "marblesCost": 1,
    "image": "http://imageUrl",
    "bigImage":"https://imageUrl"
}]

Get Virtual Item

description:

HTTP GET - BASE_URL/{apiKey}/virtualItems/{id}

request:

response example:

{
    "name": "someItem",
    "id": 1,
    "description": "descr of someItem",
    "category": "stuff",
    "marblesCost": 1,
    "image": "http://imageUrl",
    "bigImage":"https://imageUrl"
}

Get Applications

description:

Get a list of all applications that are available for challenging.

request:

HTTP GET - BASE_URL/{apiKey}/applications/

response example:


[{
    "id": 1,
    "available": true,
    "developerId": "Brisk Mobile Inc.",
    "applicationName": "Medieval",
    "applicationDescription": "Medieval by Brisk",
    "image" : "http://www.google.com/logos/classicplus.png",
    "dateAdded": null
}]

Get Application

description:

Get an application by its ID

request:

HTTP GET - BASE_URL/{apiKey}/applications/{id}

response example:

{
    "id": 1,
    "available": true,
    "developerId": "brisk",
    "applicationName": "Medieval",
    "applicationDescription": "Medieval by Brisk",
    "image" : "http://www.google.com/logos/classicplus.png",
    "dateAdded": null
}

Get Challenge Types

description:

Get a listing of challenge types that are available for an application.

request:

HTTP GET - BASE_URL/{apiKey}/applications/{id}/betTypes

response example:

 [{
     "name": "DEFAULT challenge",
     "id": 1,
     "description": "This is a default challenge type for the application"
 }]

Get Platforms

description:

Get a listing of platforms supported that an application supports.

parameters:

id - application id

request:

HTTP GET - BASE_URL/{apiKey}/applications/{id}/platforms

response example:

[{
    "id": 1,
    "platformId": "ANDROID",
    "applicationUrl": "http://android.com/app",
    "notes": "Blah"
}]

Create Application Challenge

description:

Create an application challenge against an opponent.

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/createApplicationBet/

post body example:

{
    "description": "description of the challenge",
    "applicationId": 1,
    "applicationBetTypeId": 1,
    "oponentUserName": "oponentUserId",
    "creatorWagerMarbles": 1,
    "oponentWagerMarbles": 1
}

notes:

an applicationId must be specified
an application challenge type id must be specified
the oponentUserName specified is the oponent you wish to place a challenge against
creatorWagerMarbles is the number of coins that the user that created the challenge wishes to wager
oponentWagerMarbles is the number of coins that the opponent will wager. Note that this can be later changed by the oponent.

post body example:

{
    "description": "desc",
    "applicationId": 1,
    "applicationBetTypeId": 1,
    "oponentUserName": "jsimonelis",
    "creatorWagerItemId": 1,
    "creatorWagerItemCount": 1,
    "oponentWagerMarbles": 1
}

notes:

in this example the creator of the wager chooses to wager an item instead of coins. creatorWagerItemId contains the ID of the item he wishes to wager and creatorWagerItemCount is the number of units of the item that will be wagered.

The JSON Object being passed in these cases is a BetDetails object. The full definition of this object is as follows:


{
    "applicationId": 1,
    "applicationBetTypeId": 1,
    "description": "",
    "opponentUserName": "",
    "creatorWagerMarbles": 1,
    "creatorWagerItemId": 1,
    "creatorWagerItemCount": 1,
    "opponentWagerMarbles": 1,
    "opponentWagerItemId": 1,
    "opponentWagerItemCount": 1,
    "moderatorUserName: "",
     "expiry": ms since 1970
}

each user participating in the challenge must bet either coins or items, for example user A may bet coins and user B may bet item(s), but user A cannot use as his wager both coins and items.
a challenge expiry date can be specified optionally. If the challenge isn't closed by this date it will be cancelled.
in an application challenge a moderator id isn't used. this is only available for freeform challenges.

response example:

{
    "id": 10,
    "status": "activation-pending",
    "description": "desc",
    "applicationId": 1,
    "applicationBetTypeId": 1,
    "betType": "application",
    "moderatorId": null,
    "creationDate": 1297205359000,
    "expiryDate": null
}

Create Freeform Challenge

description:

Create a freeform challenge. A freeform challenge is not tied to any particular application. It requires that each user "manully" score their challenge as opposed to some application performing the scoring for them.. An example would be some user challenging another user that he can jump farther etc. Afterwards, they would decide the winner through the betpalz application (or through the application you've developed by using this call). Free form challenges are different than application challenges in that they can optionally specify a moderator who will decide the outcome of the challenge. This is not possible in application challenges since it is the responsibility of the implementor in that case to provide the application logic to provide the challenge results.

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/createFreeformBet/

post body example:

{
    "description": "i can jump farther than you!",
    "oponentUserName": "jsimonelis2",
    "creatorWagerMarbles": 1,
    "oponentWagerMarbles": 1,
}

a freeform challenge is created and each participant wagers 1 coin

post body example:

{
    "description": "i can hold my breath longer",
    "oponentUserName": "jsimonelis",
    "creatorWagerItemId": 1,
    "creatorWagerItemCount": 1,
    "oponentWagerItemId": 1,
    "opponentWagerItemCount": 1,
    "moderatorUserName": "bill",
    "expiry": 1328125949000
}

in this case a free form challenge was created with both participants wagering items.
a moderator was specified. The moderator will determine the outcome of the challenge.
an expiry date was specified in ms since 1970. In the java world this is the time value in the format produced by System.currentTimeMillis();
see the application challenge instructions as well for a better understanding of this.

response example:

{
    "id": 10,
    "status": "activation-pending",
    "description": "desc",
    "applicationId": -1,
    "applicationBetTypeId": 1,
    "betType": "freeform",
    "moderatorId": null,
    "creationDate": 1297205359000,
    "expiryDate": null
}

Get Challenges By Status

description:

Get a list of all of the challenges a user has by challenge status. Valid betStatus's are: active, cancelled, activation-pending, closed-pending, closed, expired

request:

HTTP GET - BASE_URL/{apiKey}/{authToken}/bets/status/{betStatus}

response example:

 [{
     "id": 10,
     "status": "activation-pending",
     "description": "desc",
     "applicationId": 1,
     "applicationBetTypeId": 1,
     "betType": "application",
     "moderatorId": null,
     "creationDate": 1297205359000,
     "expiryDate": null
 }, {
     "id": 8,
     "status": "activation-pending",
     "description": "desc",
     "applicationId": -1,
     "applicationBetTypeId": -1,
     "betType": "freeform",
     "moderatorId": "jsimonelis2",
     "creationDate": 1297108819000,
     "expiryDate": 1328125949000
 }]

Get Challenges By Status -- Limit the number of results returned, the results are ordered by creation date.

description:

Get a list of all of the challenges a user has by challenge status. Valid betStatus's are: active, cancelled, activation-pending, closed-pending, closed, expired

request:

HTTP GET - BASE_URL/{apiKey}/{authToken}/bets/status/{betStatus}/{maxResults}

response example:

 [{
     "id": 10,
     "status": "activation-pending",
     "description": "desc",
     "applicationId": 1,
     "applicationBetTypeId": 1,
     "betType": "application",
     "moderatorId": null,
     "creationDate": 1297205359000,
     "expiryDate": null
 }, {
     "id": 8,
     "status": "closed",
     "description": "desc",
     "applicationId": -1,
     "applicationBetTypeId": -1,
     "betType": "freeform",
     "moderatorId": "jsimonelis2",
     "creationDate": 1297108819000,
     "expiryDate": 1328125949000
 }]

Get unseen challenges.

description:

Get a list of challenges which are new for user.

request:

HTTP GET - BASE_URL/{apiKey}/{authToken}/unseenBets

response example:

 [{
 		"id":661,
 		"description":"",
 		"creationDate":1311078844000,
 		"status":"cancelled",
 		"applicationId":-1,
 		"applicationBetTypeId":-1,
 		"betType":"freeform",
 		"moderatorId":null,
 		"expiryDate":null
 	},{
 		"id":666,
 		"description":"",
 		"creationDate":1311096954000,
 		"status":"cancelled",
 		"applicationId":-1,
 		"applicationBetTypeId":-1,
 		"betType":"freeform",
 		"moderatorId":null,
 		"expiryDate":null
 }]

Find Challenge

description:

Find a challenge by it's ID. The user identified by the authToken must be a participant in this challenge.

request:

HTTP GET - BASE_URL/{apiKey}/{authToken}/bets/{id}

response example:

{
    "id": 10,
    "status": "activation-pending",
    "description": "desc",
    "applicationId": 1,
    "applicationBetTypeId": 1,
    "betType": "application",
    "moderatorId": null,
    "creationDate": 1297205359000,
    "expiryDate": null
}

Get Challenge Wagers

description:

Get the wagers that make up a challenge. Each challenge is composed of 2 wagers, one for each of the participants that represent the collateral put up for the challenge. The collateral will be transfered to the winner of the challenge upon completion.

request:

HTTP GET - BASE_URL/{apiKey}/{authToken}/bets/{id}/wagers

response example:

 [{
     "id": 19,
     "wagerVirtualItem": null,
     "wagerMarblesAmount": 1,
     "accepted": false,
     "score": -1,
     "resultApproved": false,
     "wagererId": "jsimonelis"
 }, {
     "id": 20,
     "wagerVirtualItem": null,
     "wagerMarblesAmount": 1,
     "accepted": false,
     "score": -1,
     "resultApproved": false,
     "wagererId": "jsimonelis"
 }]

Get Moderator Challenges By Status

description:

Get a listing of challenges that the user identified by the authToken is moderating, by status.

request:

HTTP GET - BASE_URL/{apiKey}/{authToken}/betsModerating/{betStatus}

response example:

[{
    "id": 10,
    "status": "activation-pending",
    "description": "desc",
    "applicationId": 1,
    "applicationBetTypeId": 1,
    "betType": "application",
    "moderatorId": "bill",
    "creationDate": 1297205359000,
    "expiryDate": null
}]

Accept Challenge

description:

Accept a challenge and make active.

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/bets/{betId}/accept

response example:

{"success":true,"message":"success"}

Change Wager Amount

description:

Change amount of coins wagered

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/bets/{betId}/setMarblesWagerAmount/{newMarblesAmount}

response example:

{"success":true,"message":"success"}

Change Wager Item

description:

Change the item on a challenges wager. newItemId: is the id of the virtual item that will now be wagered. quantity: is the number of units of the virtual item

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/bets/{betId}/setWagerItemId/{newItemId}/{quantity}

response example:

 {"success":true,"message":"success"}

Cancel Challenge

description:

Cancel a challenge. Any participant of the challenge can cancel the challenge. Moderators can also cancel a challenge.

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/bets/{betId}/cancel

response example:

{"success":true,"message":"success"}

Register Challenge Score

description:

Allow a user to register their score on a challenge. This is for self scoring. The user associated with the authToken identifies the challenge and sets his score on it. In order to win the challenge, his score should be greater than the score of the other participant. If this is operation performed on a freeform challenge, the next state will be the closed-pending state so users will have to approve results first. If this is performed on an application challenge, then once both challenges are scored, the challenge will be closed. betId: the identifier of the challenge that the user is scoring. score: an integer value. in order to win the challenge, this score must be higher than the score of the oponent.

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/bets/{betId}/setScore/{score}

response example:

{"success":true,"message":"success"}

Reset Challenge To Active State

description:

On an unmoderated freeform challenge, a user can take a challenge that is closed-pending and reset it to active. they would need to do this in order to change their scores on a closed-pending challenge.

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/bets/{betId}/resetActive

response example:

{"success":true,"message":"success"}

Accept Challenge Results

description:

User will accept a challenge result for an unmoderated freeform challenge.

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/bets/{betId}/acceptResult

response example:

 {"success":true,"message":"success"}

Moderator Score Challenge

description:

A moderator will provide a score card for a challenge that he is moderating. userId1, userId2 -> these should be replaced with the user Id's of the participants of the challenge that the moderator is scoring. - the score values are integers. in the example above, userId1 wins the challenge 1:0

request:

HTTP POST - BASE_URL/{apiKey}/{authToken}/bets/{betId}/moderatorRegisterScore

response example:

 {"success":true,"message":"success"}

Reward User for watching ads

description:

Reward user with coins for watching ads. User can receive this type of reward again after 24 hours passed

request:

HTTP GET - BASE_URL/{apiKey}/{authToken}/userWatchedAds

response example:

{"success":true,"message":"success"}

or

{"success":false,"message":"Ads watching already done in last 24 hours."}

Confirm action

Betpalz Web API

Authentication

Web API Call Documentation

Validate User Credentials

Check Auth Token

Get User From Token

Get User Coins Balance

Get Friend Ids

Get Friends

Get User

Get Net Worth

Get Virtual Items

Get Friend Requests

Get All Virtual Statuses

Find Users

Request Friendship

Accept Friendship

Decline Friendship

Remove Friend

Purchase Virtual Items

Sell Virtual Items

Get All Virtual Items

Get Virtual Items On Hold

Get Virtual Item

Get Applications

Get Application

Get Challenge Types

Get Platforms

Create Application Challenge

Create Freeform Challenge

Get Challenges By Status

Get Challenges By Status -- Limit the number of results returned, the results are ordered by creation date.

Get unseen challenges.

Find Challenge

Get Challenge Wagers

Get Moderator Challenges By Status

Accept Challenge

Change Wager Amount

Change Wager Item

Cancel Challenge

Register Challenge Score

Reset Challenge To Active State

Accept Challenge Results

Moderator Score Challenge

Reward User for watching ads

Control Panel