API Documentation

Bullfrog Tech API v1.0.0

Introduction

The following document details the Bullfrog public API for interacting with the Bullfrog Cloud Office and Point of Sale system. The API is a JSON based REST service using token authentication.

Versioning

This API follows SemVer so you can be assured that changes will be backwards compatible within major versions. All routes start with the major version number to ensure a clear and easy transition between API versions.

The API will always support the current and last major versions.

Authentication

Authorization: Token token="YOUR API TOKEN"

Alternatively, if you must, you can send the token in via a auth_token parameter.

API tokens are unique to a customer, so if you interact with more than one Bullfrog customer, you may require more than one API token. The API token identifies the customer you are making the requests on.

If you do not include a valid API token in your request, you will receive a 401 Unauthorized. If you include a valid API token but are not authorized to perform the attempted action, you will receive a 403 Forbidden.

Error Handling

Error handling attempts to be consistent and clear if you encounter errors on the API. HTTP response codes generally detail the success or failure of a request and give some indication of what went wrong.

In general:

2xx range indicate success.
4xx range indicate an error based on information received by the API (either a required parameter was missing, or the request failed to complete successfully).
5xx range indicate an error on the API (which we will then be notified of).

Common response codes used by this API:

200 OK
201 Created,
202 Accepted
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
422 Unprocessable Entity

In addition, each error response will contain a friendly message you can display to your end users, a unique code and a description for developers to help troubleshoot or script what went wrong, and any other context relevant information.

For example:

{
  "code":"401",
  "message":"Please sign in to access that resource.",
  "description":"The authentication header or token could not be found or was incorrect and we could not authenticate you. Ensure you are sending the correct authentication information either by the Authorization header or auth_token parameter.",
  "more_info":"https://bullfrogtech.com/docs/api#authentication"
}

Dates and Times

All dates and times returned by the API are in UTC formatted as ISO 8601. This is an unambiguous timezone-aware format that should be easily parseable by most languages.

Any dates send to the API that do not contain timezone information will be interpretted as UTC.

Pagination

Collection routes, such as GET /clients, provide pagination help for displaying paginated views on the client. The pagination helpers will come in a standardized pagination block within the meta block in the response.

page – Indicates the current page you have requested.
per_page – The maximum number of records that will be returned per page.
next_page – The number of the next page in the results. Will be null if there is no next page.
prev_page – The number of the previous page in the resutls. Will be null if there is no previous page.
page_count – Total number of pages in the result.
total_count – Total number of records in the result.

{
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 5,
      "next_page": 2,
      "prev_page": null,
      "page_count": 10,
      "total_count": 50
    }
  }
}

Routes

Client

Clients represent an end user of the system. They are expected to be uniquely identified by an ID number (known as the uid) across all your locations and at the point of sale.

`GET /clients`

Get a paginated list of clients.

Parameters :

name – optional – Filter results for clients with a name matching this string.
tags – optional – Filter results for clients with a matching tag. Multiple, comma separated tags return the subset of clients matching all tags.
updated_since – optional – Only returns clients that have been updated since the date stamp.
page – optional – Used to select the paged list of results. Default: 1
per_page – optional – How many results per page. Default: 10. Maximum: 100

Example Request :

GET https://api.bullfrogtech.com/v1/clients?name=Jeff&per_page=5&tags=example,tags

Example Response:

{
  "clients": [
    {
      "uid": "00123abcd",
      "name": "Jeff Smith",
      "balance": 12.34,
      "memo": "",
      "pin": "1234",
      "daily_spending_limit": 10.23,
      "tags": ["example", "tags"],
      "created_at": "2015-01-01T14:00:00Z",
      "updated_at": "2015-02-28T14:00:00Z",
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 5,
      "next_page": 2,
      "prev_page": null,
      "page_count": 1,
      "total_count": 1
    }
  }
}

`GET /clients/:uid`

Retrieve a particular client’s details.

Example Request :

GET https://api.bullfrogtech.com/v1/clients/00123abcd

Example Response:

{
  "uid": "00123abcd",
  "name": "Jeff Smith",
  "balance": 12.34,
  "memo": "",
  "pin": "1234",
  "daily_spending_limit": 10.23,
  "tags": ["example", "tags"],
  "created_at": "2015-01-01T14:00:00Z",
  "updated_at": "2015-02-28T14:00:00Z",
}

`PATCH/PUT /clients/:uid`

Update a client record. Clients do not have to be specifically created before updating.

Parameters :

name – optional – The client’s name.
memo – optional – A message to be displayed on the point of sale screen, to the operator, when this client makes a in-person purchase.
pin – optional – The client’s access code to make a purchase at the POS. May or may not be enforced at the POS depending on the location’s settings.
daily_spending_limit – optional – The allowed daily spending limit. Note: A value of null means no daily spending limit, a value of 0 is a daily spending limit of $0.00 and will not allow the client to make purchases.
tags – optional – A list of strings we will tag the client with. You can then filter clients by these tags.

Example Request :

PATCH https://api.bullfrogtech.com/v1/clients/55443?name=Jill Garcia

Example Response:

{
  "uid": "55443",
  "name": "Jill Garcia",
  "balance": 0.00,
  "memo": "",
  "pin": "1234",
  "daily_spending_limit": 10.23,
  "tags": ["example", "tags"],
  "created_at": "2015-03-01T14:00:00Z",
  "updated_at": "2015-04-15T14:00:00Z",
}

Ping

Ping routes can be used debugging the connection and ensuring there is a active connection to the API. Both ping methods respond to both GET and POST routes.

`GET/PUT /ping`

Pings the API servers and responds with a Pong!, the current time and a list of the parameters it received in the ping request.

Parameters :

Anything sent to the server as a parameter will be mirrored back in the output.

Example Request :

GET https://api.bullfrogtech.com/v1/ping?example=test

Example Response:

{
  "message": "Pong!",
  "time": "2015-03-01T14:00:00Z",
  "received": {
    "example": "test"
  }
}

`GET/PUT /authenticated_ping`

Same as the ping method, but requires that the user be authenticated, otherwise it will return an unauthenticated response: 401 Unauthorized.

Parameters :

Anything sent to the server as a parameter will be mirrored back in the output.

Example Request :

GET https://api.bullfrogtech.com/v1/authenticated_ping?auth=example

Example Response:

{
  "message": "Pong! You are authenticated as YOUR_USER_NAME",
  "time": "2015-03-01T14:00:00Z",
  "received": {
    "auth": "example"
  }
}

Transaction

Transaction are entries that occur on the wallet’s balance. These can come in the form of deposits and withdrawals via the 3rd Party or purchases and refunds via the point of sale.

`POST /clients/:uid/deposits`

Creates a deposit transaction for the client.

Parameters :

amount – required – The dollar amount of the transaction.
memo – optional – A field to enter custom values or references.

Example Request :

POST https://api.bullfrogtech.com/v1/clients/55443/deposits?amount=5.50

Example Response:

{
  "id": 12345,
  "type": "deposit",
  "amount": 5.50,
  "net_amount": 5.50,
  "memo": "",
  "occurred_at": "2015-03-01T14:00:00Z",
  "client": {
    "uid": "12345",
    "name": "Jill Garcia",
    "balance": 5.50,
    "memo": "",
    "pin": "1234",
    "daily_spending_limit": 10.23,
    "tags": ["example", "tags"],
    "created_at": "2015-03-01T14:00:00Z",
    "updated_at": "2015-04-15T14:00:00Z"
  }
}

`POST /clients/:uid/withdrawals`

Creates a withdrawal transaction for the client.

Parameters :

amount – required – The dollar amount of the transaction.
memo – optional – A field to enter custom values or references.

Example Request :

POST https://api.bullfrogtech.com/v1/clients/55443/withdrawals?amount=1.00

Example Response:

{
  "id": 23456,
  "type": "withdrawal",
  "amount": 1.00,
  "net_amount": -1.00,
  "memo": "",
  "occurred_at": "2015-03-01T14:00:00Z",
  "client": {
    "uid": "12345",
    "name": "Jill Garcia",
    "balance": 4.50,
    "memo": "",
    "pin": "1234",
    "daily_spending_limit": 10.23,
    "tags": ["example", "tags"],
    "created_at": "2015-03-01T14:00:00Z",
    "updated_at": "2015-04-15T14:00:00Z"
  }
}

`GET /clients/:uid/transactions`

Get a paginated list of a client’s transactions.

Parameters :

type – optional – Filter response only to the specified types. Separate multiple types by a comma. Example: type=deposit,purchase. Defaults to all types.
occurred_since – optional – Only returns transactions that have occurred since the date stamp.
page – optional – Used to select the paged list of results. Default: 1
per_page – optional – How many results per page. Default: 10. Maximum: 100

Response :

id – The transaction’s unique ID.
type – Type of transaction as it occurred for the wallet. Allowed values are: deposit, withdrawal, purchase, refund.
total – Dollar amount of the transaction via Wallet payment method.
net_total – Dollar amount of the transaction as it effected the balance. For withdrawal and purchase type transactions, this number will be the same as total but negative. Can be useful if you want to output the amount as it affected the balance without having to look at type.
memo – Field for custom value. Available for deposit and withdrawal types, blank for others.
occurred_at – Time the transaction occurred.
client_uid – A tenant-wide unique identifier for this client.
transaction – A structure that details the full transaction at the POS. Only applicable to purchase and refund types.
- id – The transaction’s unique ID.
- total – Total amount of the transaction.
- reset_id – The unique ID of the reset. May be null if it hasn’t yet been reset.
- lane
  - id – The lane’s ID.
  - name – Name of the lane the transaction occurred on.
- location
  - id – The location’s ID.
  - name – Name of the location the transaction occurred on.
- items – An array of line items that were purchased or refunded.
  - description – A text description of the item.
  - total – The total amount of this line item.
  - amount – The per unit amount.
  - quantity – Number of units purchased.
  - order – The order of the units as purchased.
- taxes – An array of taxes.
  - name – Name of the tax.
  - amount – Amount of the tax.
- payments – An array of payments.
  - by – The method of payment. A string indicating “Wallet”, “Cash”, “Cheque”, “Visa”, etc.
  - amount – Amount of payment.

Example Request :

GET https://api.bullfrogtech.com/v1/clients/55443/transactions?per_page=5

Example Response:

{
  "transactions": [
    {
      "id": 12345,
      "type": "deposit",
      "total": 45.00,
      "net_total": 45.00,
      "memo": "Custom string.",
      "occurred_at": "2015-02-28T14:00:00Z",
      "client_uid": "1234abcd"
    },
    {
      "id": 23456,
      "type": "withdrawal",
      "total": 45.00,
      "net_total": -45.00,
      "memo": "Custom string.",
      "occurred_at": "2015-02-28T14:00:00Z",
      "client_uid": "1234abcd"
    },
    {
      "id": 34567,
      "type": "purchase",
      "total": 4.67,
      "net_total": -4.67,
      "memo": "",
      "occurred_at": "2015-02-28T14:00:00Z",
      "client_uid": "1234abcd",
      "transaction": {
        "id": 998877,
        "total": 5.67,
        "reset_id": 3242,
        "lane": {
          "id": 1234,
          "name": "Lane Name"
        },
        "location": {
          "id": 4567,
          "name": "Location Name"
        },
        "items": [
          {
            "description": "Small Milk",
            "total": 5.00,
            "amount": 2.50,
            "quantity": 2.0,
            "order": 1
          }
        ],
        "taxes": [
          {
            "name": "GST",
            "amount": 0.67
          }
        ],
        "payments": [
          {
            "by": "Wallet",
            "amount": 4.67,
          },
          {
            "by": "Cash",
            "amount": 1
          }
        ]
      }
    },
    {
      "id": 45678,
      "type": "refund",
      "total": 1.00,
      "net_total": 1.00,
      "occurred_at": "2015-02-28T14:00:00Z",
      "client_uid": "1234abcd",
      "transaction": {
        "id": 665544,
        "total": -1.00,
        "reset_id": 3243,
        "lane": {
          "id": 1234,
          "name": "Lane Name"
        },
        "location": {
          "id": 4567,
          "name": "Location Name"
        },
        "items": [
          {
            "plu": "1234abcd",
            "description": "Pop",
            "total": -0.93,
            "amount": 0.93,
            "quantity": -1.0,
            "order": 1
          }
        ],
        "taxes": [
          {
            "name": "GST",
            "amount": -0.07
          }
        ],
        "payments": [
          {
            "by": "Wallet",
            "amount": -1,
          }
        ]
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 5,
      "next_page": 2,
      "prev_page": null,
      "page_count": 1,
      "total_count": 1
    }
  }
}

Ping

A reset represents a closing of a fiscal period of a lane or group of lanes.

`GET /resets`

Get a paginated list of resets.

Parameters :

occurred_since – optional – Only returns resets that have occurred since the date stamp.
page – optional – Used to select the paged list of results. Default: 1
per_page – optional – How many results per page. Default: 10. Maximum: 100

Response :

id – Uniquely identifies this reset across all lanes, locations, and tenants. Used to query reset details.
number – This is the reset number as reported by the POS and may only be unique to the lane or group of lanes. It is generally sequential for the affected lanes but not globally. May be used to aid in accounting and reporting.
total – The total sum of wallet transactions contained in this reset.
count – The number of wallet transactions included in this reset.
lane
- id – The lane’s ID.
- name – Name of the lane the transaction occurred on.
location
- id – The location’s ID.
- name – Name of the location the transaction occurred on.
occurred_at – The time the reset occurred at.

Example Request :

GET https://api.bullfrogtech.com/v1/resets?page=2&per_page=5

Example Response:

{
  "resets": [
    {
      "id": 34234,
      "number": "2342abc",
      "total": 512.34,
      "count": 53,
      "lane": {
        "id": 1234,
        "name": "Lane Name"
      },
      "location": {
        "id": 4567,
        "name": "Location Name"
      },
      "occurred_at": "2015-01-01T14:00:00Z",
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 5,
      "next_page": 2,
      "prev_page": null,
      "page_count": 1,
      "total_count": 1
    }
  }
}

`GET /resets/:uid`

Retrieve a particular reset’s details.

Response :

id – Uniquely identifies this reset across all lanes, locations, and tenants. Used to query reset details.
number – This is the reset number as reported by the POS and may only be unique to the lane or group of lanes. It is generally sequential for the affected lanes but not globally. May be used to aid in accounting.
total – The total sum of wallet transactions contained in this reset.
count – The number of wallet transactions included in this reset.
lane
- id – The lane’s ID.
- name – Name of the lane the transaction occurred on.
location
- id – The location’s ID.
- name – Name of the location the transaction occurred on.
occurred_at – The time the reset occurred at.
transactions – An array of wallet transactions (purchase and refunds only) included in the reset.
- id – The transaction’s unique ID.
- type – Type of transaction. Only purchase or refund types will be returned.
- total – Dollar amount of the transaction.
- client_uid – A tenant-wide unique identifier for this client.
- occurred_at – Time transaction occurred.
- reset_id – The unique ID of the reset. May be null if it hasn’t yet been reset.
- lane
  - id – The lane’s ID.
  - name – Name of the lane the transaction occurred on.
- location
  - id – The location’s ID.
  - name – Name of the location the transaction occurred on.
- payments – An array of payments.
  - by – The method of payment. Will only contain ‘Wallet’ transactions.
  - amount – Amount of payment.

Example Request :

GET https://api.bullfrogtech.com/v1/resets/34234

Example Response:

{
  "id": 34234,
  "number": "2342abc",
  "total": 4.67,
  "count": 2,
  "lane": {
    "id": 1234,
    "name": "Lane Name"
  },
  "location": {
    "id": 4567,
    "name": "Location Name"
  },
  "occurred_at": "2015-01-01T14:00:00Z",
  "transactions": [
    {
      "id": 34567,
      "type": "purchase",
      "total": 5.67,
      "client_uid": "1234abcd",
      "occurred_at": "2015-02-28T14:00:00Z",
      "reset_id": 34234,
      "lane": {
        "id": 1234,
        "name": "Lane Name"
      },
      "location": {
        "id": 4567,
        "name": "Location Name"
      },
      "payments": [
        {
          "by": "Wallet",
          "amount": 5.67,
        }
      ]
    },
    {
      "id": 45678,
      "type": "refund",
      "total": -1.00,
      "client_uid": "1234abcd",
      "occurred_at": "2015-02-28T14:00:00Z",
      "reset_id": 34234,
      "lane": {
        "id": 1234,
        "name": "Lane Name"
      },
      "location": {
        "id": 4567,
        "name": "Location Name"
      },
      "payments": [
        {
          "by": "Wallet",
          "amount": -1,
        }
      ]
    }
  ]
}

API Documentation

Bullfrog Tech API v1.0.0

Introduction

Versioning

Authentication

Error Handling

Dates and Times

Pagination

Routes

Client

GET /clients

GET /clients/:uid

PATCH/PUT /clients/:uid

Ping

GET/PUT /ping

GET/PUT /authenticated_ping

Transaction

POST /clients/:uid/deposits

POST /clients/:uid/withdrawals

GET /clients/:uid/transactions

Ping

GET /resets

GET /resets/:uid

Ready to move your Point of Sale into the future?

`GET /clients`

`GET /clients/:uid`

`PATCH/PUT /clients/:uid`

`GET/PUT /ping`

`GET/PUT /authenticated_ping`

`POST /clients/:uid/deposits`

`POST /clients/:uid/withdrawals`

`GET /clients/:uid/transactions`

`GET /resets`

`GET /resets/:uid`