API Reference Documentation

Version: 1.0

The BitPoints Club expose a REST API allowing access to BitPoints account resources. Each resource type has one or more data representations and one or more methods.

Also see our code example page here

1.0 Versioning

Breaking changes will result in a new version number allowing access to the old versions. The current version is 1.0 and can be accessed from https://bitpoints.club/api/v1/

2.0 Authentication

Requests need to pass an Authorization header with a value key=Account API Key. The Account API Key is accessed from the online ACCOUNT > API Development menu item.

3.0 HTTP Verbs

Each resource can be manipulated with the following HTTP Verbs.

  • GET Returns one or more resource data representations
  • POST Adds one or more resource
  • PUT Updates a single resource
  • DELETE Deletes a single resource

3.1 GET resource (return single)

Request:
URL: GET /api/v1/resource/resource_identifier Headers:     Authorization: key=Account API Key     Content-Type: application/json
Response:
Status: 200 OK Headers: Content-Type: application/json Body: Resource data representations (see Resource References section below for resource specific fields) i.e.     {         "resource1_field_name": "data",         "resource1 field array": {             "resource1 field array - field name": "data"         }     }

3.2 GET resource (return multiple)

Result limits
Please note by default only the latest 20 records will be returned. To request more/less results pass a query string parameter count=[number] i.e. /api/v1/resource/list?count=200

Request:
URL: GET /api/v1/resource/list[optional Query String] Query String: Filters results (see Query String Operators section below for details) i.e.     ?resource1_field_name1={"eq":"value"}&resource1_field_name2={"eq":"value"} (filters list to only records resource1_field_name1 = value and resource1_field_name2 = value)     ?resource1_field_name1={"lt":"100","gte":"30"} (filters list to only records where resource1_field_name1 < 100 and >= 30)     ?resource1_field_name1={"start":"value"} (filters list to only records where resource1_field_name1 starting with value)     ?resource1_field_name1={"end":"value"} (filters list to only records where resource1_field_name1 ending with value) Headers:     Authorization: key=Account API Key     Content-Type: application/json
Response:
Status: 200 OK Headers: Content-Type: application/json Body: Array of resource data representations (see Resource References section below for resource specific fields) i.e.     [         {             "resource1_field_name": "data",             "resource1 field array": {                 "resource1 field array - field name": "data"             }         },         {             "resource1_field_name": "data",             "resource1 field array": {                 "resource1 field array - field name": "data"             }         }     [

3.3 POST resource (add multiple)

Request:
URL: POST /api/v1/resource Headers:     Authorization: key=Account API Key     Content-Type: application/json Body: Array of resource data representations (see Resource References section below for resource specific fields) i.e.     [         {             "resource1_field_name": "data",             "resource1 field array": {                 "resource1 field array - field name": "data"             }         },         {             "resource1_field_name": "data",             "resource1 field array": {                 "resource1 field array - field name": "data"             }         }     [
Response:
Status: 201 Created Headers: Content-Type: application/json Body: Request data returned with additional resource_identifier field

3.4 PUT resource (update single)

Request:
URL: PUT /api/v1/resource/resource_identifier Headers:     Authorization: key=Account API Key     Content-Type: application/json Body: Resource data representations (see Resource References section below for resource specific fields) i.e.     {         "resource1_field_name": "data",         "resource1 field array": {             "resource1 field array - field name": "data"         }     }
Response:
Status: 204 No Content

3.5 DELETE resource (delete single)

Request:
URL: DELETE /api/v1/resource/resource_identifier Headers:     Authorization: key=Account API Key     Content-Type: application/json
Response:
Status: 204 No Content

4.0 Query String Operators

Filter GET multiple requests by adding a query string to the url i.e. /api/v1/resource/list?resource1_field_name1={"eq":"value"}&resource1_field_name2={"gte":"value","lt":"value"}

Each query string parameter is a JSON object containing one or many of these fields:
{     "eq": "data", Equals (=)     "lt": "data", Less than (<)     "lte": "data", Less than equal (<=)     "gt": "data", Greater than (>)     "gte": "data", Greater than equal (>=)     "start": "data", Starts with text     "end": "data", Ends with test     "contains": "data" Contains text }

Result limits
Please note by default only the latest 20 records will be returned. To request more/less results pass a query string parameter count=[number] i.e. /api/v1/resource/list?count=200

5.0 Error Response HTTP Status Codes

Failed requests will return one of the follwoing HTTP Status Codes

  • 400 Bad Request
    The request could not be understood by the server due to malformed syntax
  • 401 Unauthorized
    Authorization header not passed or invalid
  • 403 Forbidden
    The server understood the request, but is refusing to fulfill it (i.e. Account suspended or demo account limit reached)
  • 404 Not Found
    The server has not found anything matching the request (i.e. resource or resource_identifier not found)
  • 405 Method Not Allowed
    The method specified in the Request is not allowed for the resource or resource_identifier
  • 409 Conflict
    The request could not be completed due to a conflict with the current state of the resource
  • 413 Request Entity Too Large
    The server is refusing to process a request because the request entity is larger than the server is willing or able to process
  • 500 Internal Server Error
    The server encountered an unexpected condition which prevented it from fulfilling the request
  • 503 Service Unavailable
    The server is currently unable to handle the request due to a temporary overloading or maintenance of the server

6.0 Resource References

6.1 Customer

{     "customer_id": int,     "email": string,     "password": string,     "first_name": string,     "last_name": string,     "phone": string,     "address": string,     "birthdate": string, YYYY-MM-DD     "programs": string array of program_id's }
Field GET PUT POST
customer_id Returned Ignored Ignored
email Returned Field required but will be ignored if value blank Mandatory
password Not returned Field required but will be ignored if value blank Mandatory
first_name Returned Field required but value optional Field required but value optional
last_name Returned Field required but value optional Field required but value optional
phone Returned Field required but value optional Field required but value optional
address Returned Field required but value optional Field required but value optional
birthdate Returned Field required but value optional Field required but value optional
programs Returned Ignored Ignored

URL Examples:

Method URL
GET /api/v1/customer/list
GET /api/v1/customer/list?first_name={"eq":"Joe"}&last_name={"eq":"Bloggs"}
GET /api/v1/customer/111
PUT /api/v1/customer/111
DELETE /api/v1/customer/111 (removes customer/111 from all programs)
POST Not allowed  /api/v1/customer
GET /api/v1/program/222/customer/list
GET /api/v1/program/222/customer/list?first_name={"start":"Joe"}
GET /api/v1/program/222/customer/111
PUT /api/v1/program/222/customer/111
DELETE /api/v1/program/222/customer/111 (removes customer/111 from program/222)
POST /api/v1/program/222/customer (adds new and associates customer to program/222)

6.2 Program

If accessed via /api/v1/program
{     "program_id": int,     "target": int,     "program_name": string,     "program_type": string, Points, Target or Pre Pay     "stores": string, array of store_id's     "promotions": string, array of promotion_id's     "customers": string array of customer_id's }
Field GET PUT POST
program_id Returned Not allowed Not allowed
target Returned Not allowed Not allowed
program_name Returned Not allowed Not allowed
program_type Returned Not allowed Not allowed
stores Returned Not allowed Not allowed
promotions Returned Not allowed Not allowed
customers Returned Not allowed Not allowed

URL Examples:

Method URL
GET /api/v1/program/list
GET /api/v1/program/list?program_name={"eq":"Foo%20Bar"}
GET /api/v1/program/222
PUT Not allowed  /api/v1/program/222
DELETE /api/v1/program/222 (removes all customers from program/222)
POST Not allowed  /api/v1/program
If accessed via /api/v1/customer/111/program
{     "program_id": int,     "target": int,     "program_name": string,     "program_type": string, Points, Target or Pre Pay     "stores": string, array of store_id's     "promotions": string, array of promotion_id's     "customer_id": int,     "balance": int,     "value": decimal,     "messages_blocked": string, True or False     "unread_messages": string, array of unread message_id's     "messages": string, array of all message_id's     "transactions": string array of transaction_id's }
Field GET PUT POST
program_id Returned Not allowed Not allowed
target Returned Not allowed Not allowed
program_name Returned Not allowed Not allowed
program_type Returned Not allowed Not allowed
stores Returned Not allowed Not allowed
promotions Returned Not allowed Not allowed
customer_id Returned Not allowed Not allowed
balance Returned Not allowed Not allowed
value Returned Not allowed Not allowed
messages_blocked Returned Not allowed Not allowed
unread_messages Returned Not allowed Not allowed
messages Returned Not allowed Not allowed
transactions Returned Not allowed Not allowed

URL Examples:

Method URL
GET /api/v1/customer/111/program/list
GET /api/v1/customer/111/program/list?program_name={"eq":"Foo%20Bar"}
GET /api/v1/customer/111/program/222
PUT Not allowed  /api/v1/customer/111/program/222
DELETE /api/v1/customer/111/program/222 (removes customer/111 from program/222)
POST Not allowed  /api/v1/customer/111/program

6.3 Message

If accessed via /api/v1/program
{     "program_id": int,     "created": string, YYYY-MM-DD HH:mm:ss     "message": string,     "subject": string,     "sent_count": int,     "read_count": int }
Field GET PUT POST
program_id Returned Not allowed Ignored
created Returned Not allowed Ignored
message Returned Not allowed Mandatory
subject Returned Not allowed Mandatory
status Returned Not allowed Mandatory
sent_count Returned Not allowed Ignored
read_count Returned Not allowed Ignored

URL Examples:

Method URL
GET /api/v1/program/222/message/list
GET /api/v1/program/222/message/list?subject={"contains":"Foo%20Bar"}
GET /api/v1/program/222/message/333
PUT Not allowed  /api/v1/program/222/message/333
DELETE /api/v1/program/222 (removes all customers from program/222)
POST /api/v1/program/222/message (adds message to all current customers for program/222)
If accessed via /api/v1/customer/111/program/222 or /api/v1/program/222/customer/111
{     "message_id": int,     "program_id": int,     "customer_id": int,     "created": string, YYYY-MM-DD HH:mm:ss     "message": string,     "subject": string,     "status": string Unread or Read }
Field GET PUT POST
message_id Returned Ignored Ignored
program_id Returned Ignored Ignored
customer_id Returned Ignored Ignored
created Returned Ignored Ignored
message Returned Ignored Mandatory
subject Returned Ignored Mandatory
status Returned Mandatory Mandatory

URL Examples:

Method URL
GET /api/v1/customer/111/program/222/message/list
GET /api/v1/customer/111/program/222/message/list?subject={"contains":"Foo%20Bar"}
GET /api/v1/customer/111/program/222/message/333
PUT /api/v1/customer/111/program/222/message/333
DELETE Not allowed  /api/v1/customer/111/program/222/message/333
POST /api/v1/customer/111/program/222/message
GET /api/v1/customer/111/message/list
GET /api/v1/customer/111/message/list?subject={"contains":"Foo%20Bar"}
GET /api/v1/customer/111/message/333
PUT /api/v1/customer/111/message/333
DELETE Not allowed  /api/v1/customer/111/message/333
POST Not allowed  /api/v1/customer/111/message
GET /api/v1/program/222/customer/111/message/list
GET /api/v1/program/222/customer/111/message/list?subject={"contains":"Foo%20Bar"}
GET /api/v1/program/222/customer/111/message/333
PUT /api/v1/program/222/customer/111/message/333
DELETE Not allowed  /api/v1/program/222/customer/111/message/333
POST /api/v1/program/222/customer/111/message

6.4 Transaction

{     "transaction_id": int,     "customer_id": int,     "program_id": int,     "created": string, YYYY-MM-DD HH:mm:ss     "transaction_type": string, Join, Earn, Credit, Redeem, Refund, Promotion, Expired, Adjustment     "amount": decimal,     "points": int,     "expiry": string, YYYY-MM-DD HH:mm:ss     "promotion_id": int     "description": string }
Field GET PUT POST
transaction_id Returned Not allowed Ignored
customer_id Returned Not allowed Ignored
program_id Returned Not allowed Ignored
created Returned Not allowed Ignored
transaction_type Returned Not allowed Mandatory
amount Returned Not allowed Mandatory (for Earn, Credit, Redeem and Refund transaction_types otherwise ignored)
points Returned Not allowed Mandatory (for Adjustment transaction_types otherwise ignored)
expiry Returned Not allowed Ignored
promotion_id Returned Not allowed Ignored
description Returned Not allowed Mandatory

URL Examples:

Method URL
GET /api/v1/customer/111/program/222/transaction/list
GET /api/v1/customer/111/program/222/transaction/list?created={"gte":"2016-06-01","lte":"2016-06-30"}
GET /api/v1/customer/111/program/222/transaction/444
PUT Not allowed  /api/v1/customer/111/program/222/transaction/444
DELETE Not allowed  /api/v1/customer/111/program/222/transaction/444
POST /api/v1/customer/111/program/222/transaction
GET /api/v1/customer/111/transaction/list
GET /api/v1/customer/111/transaction/list?created={"gte":"2016-06-01","lte":"2016-06-30"}
GET /api/v1/customer/111/transaction/444
PUT Not allowed  /api/v1/customer/111/transaction/444
DELETE Not allowed  /api/v1/customer/111/transaction/444
POST Not allowed  /api/v1/customer/111/transaction
GET /api/v1/program/222/customer/111/transaction/list
GET /api/v1/program/222/customer/111/transaction/list?created={"gte":"2016-06-01","lte":"2016-06-30"}
GET /api/v1/program/222/customer/111/transaction/444
PUT Not allowed  /api/v1/program/222/customer/111/transaction/444
DELETE Not allowed  /api/v1/program/222/customer/111/transaction/444
POST /api/v1/program/222/customer/111/transaction

6.5 Promotion

{     "promotion_id": int,     "program_id": int,     "promotion_name": string,     "promotion_type": string, Join, Birthday or Period     "start": string, YYYY-MM-DD     "end": string, YYYY-MM-DD     "bonus_type": string, Set Amount or Multiplier     "bonus": int,     "duration_type": string, Days, Weeks, Months, Years or Scans     "duration": int,     "message": string }
Field GET PUT POST
promotion_id Returned Ignored Ignored
program_id Returned Ignored Ignored
promotion_name Returned Field required but will be ignored if value blank Mandatory
promotion_type Returned Ignored Mandatory
start Returned Field required but value optional Field required but value optional
end Returned Field required but value optional Field required but value optional
bonus_type Returned Ignored Mandatory
bonus Returned Ignored Mandatory
duration_type Returned Ignored Mandatory
duration Returned Ignored Mandatory
message Returned Field required but will be ignored if value blank Mandatory

URL Examples:

Method URL
GET /api/v1/program/222/promotion/list
GET /api/v1/program/222/promotion/list?created={"gte":"2016-06-01","lte":"2016-06-30"}
GET /api/v1/program/222/promotion/555
PUT /api/v1/program/222/promotion/555
DELETE Not allowed  /api/v1/program/222/promotion/555
POST /api/v1/program/222/promotion
GET /api/v1/customer/111/program/222/promotion/list
GET /api/v1/customer/111/program/222/promotion/list?created={"gte":"2016-06-01","lte":"2016-06-30"}
GET /api/v1/customer/111/program/222/promotion/555
PUT /api/v1/customer/111/program/222/promotion/555
DELETE Not allowed  /api/v1/customer/111/program/222/promotion/555
POST Not allowed  /api/v1/customer/111/program/222/promotion

6.6 Store

{     "store_id": int,     "program_id": int,     "address": string,     "longitude": decimal,     "latitude": decimal }
Field GET PUT POST
store_id Returned Ignored Ignored
program_id Returned Ignored Ignored
store_id Returned Field required but will be ignored if value blank Mandatory
store_id Returned Field required but will be ignored if value blank Mandatory
store_id Returned Field required but will be ignored if value blank Mandatory

URL Examples:

Method URL
GET /api/v1/program/222/store/list
GET /api/v1/program/222/store/list?created={"gte":"2016-06-01","lte":"2016-06-30"}
GET /api/v1/program/222/store/666
PUT /api/v1/program/222/store/666
DELETE /api/v1/program/222/store/666
POST /api/v1/program/222/store
GET /api/v1/customer/111/program/222/store/list
GET /api/v1/customer/111/program/222/store/list?created={"gte":"2016-06-01","lte":"2016-06-30"}
GET /api/v1/customer/111/program/222/store/666
PUT /api/v1/customer/111/program/222/store/666
DELETE /api/v1/customer/111/program/222/store/666
POST Not allowed  /api/v1/customer/111/program/222/store