Overview

The Circumvend API is a RESTful API that uses standard HTTP methods and returns JSON responses.

Send parameters in the request path, query string, headers, or JSON body as documented for each endpoint.
Use standard HTTP response codes to determine whether a request succeeded.
All API responses use JSON.

Circumvend provides this API to authorised customers and integration partners.

How to get an API key

Log in to https://www.circumvend.com.au/vmms/.
Select Help from the top navigation.
Select Developer Center.
Open the Basic tab.
Copy the value displayed next to API Key.

API limits

Minute limit: 60 calls per minute.
Daily limit: 2,000 calls per day.

These limits are governed by the API Fair Use Policy

Header parameters

Include the following headers with each request.

Method: GET, DELETE

Name	Required	Description
key	Mandatory	Your API key.

Method: POST

Name	Required	Description
Content-Type	Mandatory	application/json
key	Mandatory	Your API key.

Common query parameters for HTTP GET

1. Paged results.

Name	Description
record_per_page	Page size. Default: 30
current_page	Current page number.

2. Ordering of results.

Name	Description
order_by_field	Order by field. Any field in results.
order_by_direction	Sort direction. Supported values: `asc`, `desc`.

3. Retrieving a filtered set of results using the "where" parameter.

The where parameter allows you to filter resources and response fields that do not have explicit query parameters.

It can reference most fields in the response.
It must be percent-encoded before being appended to the URL.

Please note: Although the where filter supports complex expressions, we recommend keeping queries as simple as possible. Long, complex where queries can cause timeouts. To improve performance on larger organisations, prefer simple == comparisons.
Allowed operations: ==, >, <, !=

Example 1: Retrieve Locations by postcode.

post_code=='3000'

This would translate to the following URL once percent encoded.

https://api.circumvend.com.au/api/v1/vmms/locations?where=post_code%3D%3D%223000%22

Example 2: Retrieve results with a date.

date >= '2019-01-01'

Example 3: Retrieve results with multiple conditions.

first_condition == 'test' and second_condition == 'test'

Get a list of cards

Description:

Retrieve all cards for your company.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/cards

Method:

GET

Allowed Query Parameters:

Name	Format	Required	Description
card_status	int	Optional	Card status. Accepted values: "1": enabled, "2": disabled, "4": cancelled.
card_type	String	Optional	Card type. Accepted values: "0": normal, "1": staff card, "2": visitor card.
start_date	String(yyyy-MM-dd)	Optional	Issue date from.
end_date	String(yyyy-MM-dd)	Optional	Issue date to.
search_condition	String	Optional	Search by card number, cardholder ID, cardholder name, or department.

Response:

{
   "status": "1",
   "info": "success",
   "page_info": {
        "record_per_page": "30",//page size
        "total_records": "7", //total records count   
        "current_page": "1",//current page number
        "total_page": "1" //pages count
    },
    "records": [
        {
            "card_id": "178862",
            "card_no": "0123456789",
            "card_amount": "200.0",
            "daily_limit": "500.0",
            "issue_date": "2017-09-27 16:59:32.0",
            "department": "department",
            "holder_name": "holderName",
            "holder_id": "0",
            "card_type": "Normal",
            "card_status": "1",
            "prev_card_account_id": "1",
            "is_additional": "1",
            "card_account_name": "1",
            "card_account_id": "1",
            "primary_card_no": "1",
            "auto_top_up": "0",
        },
        ... ...
    ]
}

Get a card

Description:

Retrieve a card by card ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/cards/{card_id}

Method:

GET

Path Parameters

Name	Format	Required	Description
card_id	int	Mandatory	Card ID.

Response:

{
    "status": "1",
    "info": "success",
    "record": [
        {
            "card_amount": "0.0",
            "holder_name": "",
            "card_id": "123456",
            "daily_limit": "500.0",
            "card_type": "Normal",
            "card_status": "1",
            "department": "",
            "issue_date": "01/03/2018 12:34:56",
            "holder_id": "",
            "card_no": "0123456789",
            "prev_card_account_id": "1",
            "is_additional": "1",
            "card_account_name": "1",
            "card_account_id": "1",
            "primary_card_no": "1",
            "auto_top_up": "0"
        }
    ]
}

Insert card

Description:

Create a new card.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/cards

Method:

POST

Header parameters

Content-Type: application/json

Body Parameters (application/json)

Name	Format	Required	Description
card_no	String	Mandatory	Card number.
global_unique	String	Optional	Default value is "1". If global_unique = "0" "companyId-" will be prefixed to the card number. e.g. 123456-CARDNO
daily_limit	String	Optional	Daily limit. Default: 500.00.
card_type	String	Optional	Card type. Accepted values: "0": normal (default), "1": staff card, "2": visitor card.
credit	String	Optional	Card amount.
holder_name	String	Optional	Holder name.
holder_id	String	Optional	Holder number.
department	String	Optional	Department.
is_additional	String	Optional	Default: 0. Set to 1 to create an additional card.
primary_card_no	String	Optional	Card number of the primary card in your company.
auto_top_up	String	Optional	Set if auto top up. Allowed value: "0": false, "1": true.

Response:

{
    "status": "1",
    "info": "success",
    "id": "719532",//Unique Id of card 
    "card_no": "1234567890",
    "card_amount": "5.5",
    "daily_limit": "500.00",
    "issue_date": "2017-10-09 14:47:13",
    "department": "department",
    "holder_name": "holderName",
    "holder_id": "2",
    "card_status": "1",
    "auto_top_up": "0"
}

Update card

Description:

Update a card by card ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/cards/{card_id}

Method:

POST

Path Parameters

Name	Format	Required	Description
card_id	int	Mandatory	Card ID.

Header Parameters

Content-Type: application/json

Body Parameters(application/json)

Name	Format	Required	Description
daily_limit	String	Mandatory	Daily limit.
card_type	String	Optional	Card type. Accepted values: "0": normal, "1": staff card, "2": visitor card.
holder_name	String	Optional	Holder name.
holder_id	String	Optional	Holder id.
department	String	Optional	department.
card_status	String	Optional	Accepted values: 1: enabled, 2: disabled.
is_additional	String	Optional	Default: 0. Set to 1 to create an additional card.
primary_card_no	String	Optional	Card number of the primary card in your company.
auto_top_up	String	Optional	Set if auto top up. Allowed value: "0": false, "1": true.

Response:

{
    "status": "1",
    "info": "success",
    "id": "1234", 
    "card_no": "1234567890",
    "card_amount": "5.5",
    "daily_limit": "500.00",
    "issue_date": "2017-10-09 14:47:13",
    "department": "department",
    "holder_name": "holderName",
    "holder_id": "2",
    "card_status": "1",
    "card_type": "0",
    "auto_top_up": "1"
}

Delete card

Description:

Delete a card by card ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/cards/{card_id}

Method:

DELETE

Path Parameters

Name	Format	Required	Description
card_id	int	Mandatory	Card ID.

Response:

{
    "status": "1",
    "info": "success" 
}

Card top-up

Description:

Add credit to a card using its card number or card ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/cards/topup

Method:

POST

Header Parameters

Content-Type: application/json

Body Parameters

Name	Format	Required	Description
card_no	String	Mandatory	Card Number.
card_id	String	Optional	Card ID. Provide at least one of `card_no` or `card_id`.
credit	String	Mandatory	Credit amount. For example, "10.00".

Response:

{
    "status": "1",
    "info": "success",    
    "card_id": "427431",
    "credit": "10.00"   
}

Create a PIN code

Description:

Create a PIN code for use as card_no, using the specified length and credit amount. The system generates the PIN code and returns it in the response.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/cards/new_pincode

Method:

POST

Header Parameters

Content-Type: application/json

Body Parameters

Name	Format	Required	Description
credit	String	Mandatory	The card credit (e.g. "10.00").
length	String	Optional	The length of the PIN code. The valid range is 5 to 9, and the default value is 6.
imei	String	Optional	Device IMEI.
card_type	String	Optional	Card type. Accepted values: "0": Normal, "1": Staff card, "2": Visitor card, "3": Credit card. The default value is 0.
holder_id	String	Optional	Card holder ID.
holder_name	String	Optional	Card holder name.

Request Example (cURL):

curl -X POST "https://api.circumvend.com.au/api/v1/vmms/cards/new_pincode" \
    -H "Content-Type: application/json" \
    -H "key: YOUR_API_KEY_HERE" \
    -d '{
        "imei": "E89F6D075904A",
        "credit": "15",
        "length": "8",
        "card_type": "2",
        "holder_id": "holder id",
        "holder_name": "holder name"
    }'

Response:

Success Response Example

{
    "status": "1",
    "info": "success",
    "pin_code": "4191855130",
    "card_amount": "11",
    "issue_date": "2025-12-02 13:14:15",
    "department": "PINCODE",
    "holder_id": "holder id",
    "holder_name": "holder name"
}

Failure Response Example

{
    "status": "0",
    "info": "fail"
}

The "info" field contains the error message when the request fails.

Error messages include:

"credit is required" — The credit field is missing.
"invalid credit" — Credit value is not a valid positive number.
"create pin code failed, please try later" — PIN code generation failed due to an internal issue.
"internal error" — Unexpected server-side error.

Get a list of card accounts

Description:

Retrieve all card accounts for your company.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/card_accounts

Method:

GET

Allowed Query Parameters:

Name	Format	Required	Description
search_condition	String	Optional	Search by card account name, first name, last name, or organisation.

Response:

{
   "status": "1",
   "info": "success",
   "page_info": {
        "record_per_page": "30",//page size
        "total_records": "7", //total records count   
        "current_page": "1",//current page number
        "total_page": "1" //pages count
    },
    "records": [
        {
            "card_account_name": "123456",
            "password": "",
            "email": "",
            "first_name": "",
            "last_name": "",
            "mobile": "",
            "card_account_id": "",
            "organization": "",
            "cards_count": "1",
            "state": "1"
        },
        ... ...
    ]
}
}

Get a card account

Description:

Retrieve a card account by card account ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/card_accounts/{card_account_id}

Method:

GET

Path Parameters

Name	Format	Required	Description
card_account_id	int	Mandatory	Card account id.

Response:

{
    "status": "1",
    "info": "success",
    "record": [
        {
            "card_account_name": "",
            "password": "",
            "email": "",
            "first_name": "",
            "last_name": "",
            "mobile": "",
            "card_account_id": "",
            "organization": "",
            "cards_count": "1",
            "state": "1"
        }
    ]
}

Insert card account

Description:

Create a new card account.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/card_accounts

Method:

POST

Header Parameters

Content-Type: application/json

Body Parameters (application/json)

Name	Format	Required	Description
card_account_name	String	Mandatory	Card account name. Must be unique within VMMS.
password	String	Mandatory	Password.
repeat_password	String	Mandatory	Password confirmation. Must match `password`.
email	String	Optional	Email address.
mobile	String	Optional	Mobile number of card account.
first_name	String	Optional	First name of card account.
last_name	String	Optional	Last name of card account.
organization	String	Optional	Organization of card account.

Response:

{
    "status": "1",
    "info": "success",
    "id": "123456",//Card account ID. 
    "card_account_name": "",
    "password": "",
}

Update card account

Description:

Update a card account by card account ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/card_accounts/{card_account_id}

Method:

POST

Path Parameters

Name	Format	Required	Description
card_account_id	int	Mandatory	Card account id.

Header Parameters

Content-Type: application/json

Body Parameters(application/json)

Name	Format	Required	Description
password	String	Optional	Password.
repeat_password	String	Optional	Password confirmation. Must match `password`.
email	String	Optional	Email address.
mobile	String	Optional	Mobile number of card account.
first_name	String	Optional	First name of card account.
last_name	String	Optional	Last name of card account.
organization	String	Optional	Organization of card account.

Response:

{
    "status": "1",
    "info": "success",
    "id": "1234"
}

Get a list of card vends

Description:

Retrieve card vend records. By default, the API returns records for the current day only. To retrieve earlier records, provide the start_date parameter.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/cardvends

Method:

GET

Query Parameters:

Name	Format	Required	Description
start_date	String(dd/MM/yyyy)	Optional	Start date. Default: current date. By default, the API returns data only for the current day.
end_date	String(dd/MM/yyyy)	Optional	End date. Default: current date.
card_type	String	Optional	Card type. Accepted values: "0": normal, "1": staff card, "2": visitor card , "3": credit card.
imei	String	Optional	Imei number.
machine_id	String	Optional	Machine ID.
start_time	String(dd/MM/yyyy HH:mm:ss)	Optional	For example, 03/10/2019 10:11:12.
end_time	String(dd/MM/yyyy HH:mm:ss)	Optional	For example, 04/03/2020 10:11:12.
vend_id	String	Optional	Vend id.
txn_id	String	Optional	Transaction id.
sum_only	String	Optional	Return vends summary, if sum_only = 1.
search_condition	String	Optional	Search by vend ID, machine ID, IMEI, card number, cardholder ID, cardholder name, or department.

Response:

Name	Format	Required	Description
vend_type	String	Optional	0: contactless credit card, 1: contact credit card, 2: RFID, 10: Circumpay balance, 11: Circumpay membership card, 12: Circumpay credit card

{
    "status": "1",
    "info": "success",
    "page_info": {
        "total_records": "5",
        "record_per_page": "30",
        "total_page": "1",
        "current_page": "1"
    },
    "records": [
        {
          "unit_price": "3.0",
          "product_name": "Mt Franklin Water",
          "card_no": "123456******1234",
          "vend_id": "1",
          "coil_no": "2",
          "vend_time": "12/06/2018 02:25:05",
          "machine_id": "3",
          "imei": "0123456789abcdef",
          "item_no": "4",
          "sur_charge": "0.3",
          "vend_type": "0"
        }
    ]
}

Refund a vend

Description:

Refund a vend using vend_id, or using imei together with txn_id.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/cardvends

Method:

GET

Query Parameters

Name	Format	Required	Description
action	String	Mandatory	action=refund
vend_id	String	Optional	Cardvend ID.
txn_id	String	Optional	Transaction ID of vend.
imei	String	Optional	DTU IMEI.

Usage:

1. Refund by vend_id:

https://api.circumvend.com.au/api/v1/vmms/cardvends?action=refund&vend_id=123456

2. Refund by imei and txn_id:

https://api.circumvend.com.au/api/v1/vmms/cardvends?action=refund&imei=A123456789&txn_id=txnid20240624105533

Response:

{
                    "status": "1",
                
    "info": "success",
                
    "vend_id": "123456"
                
}

Get a list of locations

Description:

Retrieve all locations for your company.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/locations

Method:

GET

Query Parameters:

Name

Format

Required

Description

Response:

{
    "status": "1",
    "info": "success",
    "page_info": {
        "total_records": "3",
        "record_per_page": "50",
        "total_page": "1",
        "current_page": "1"
    },
    "records": [
        {
            "fax": "",
            "location_id": "",
            "state": "",
            "location_name": "",
            "post_code": "",
            "office_phone": "",
            "contact": "",
            "city": "",
            "email": "",
            "address": "",
            "mobile": "",
            "collection": "0.0",
            "product_full": "0.0",
            "product_empty": "0",
            "product_low": "0",
            "product_normal": "0"
        }
    ]
}

Get a location

Description:

Retrieve a location by location ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/locations/{location_id}

Method:

GET

Path Parameters:

Name	Format	Required	Description
location_id	int	Mandatory	Location id.

Response:

{
    "status": "1",
    "info": "success",
    "record":[
    {
       "fax": "",
       "location_id": "",
       "state": "",
       "location_name": "",
       "post_code": "",
       "office_phone": "",
       "contact": "",
       "city": "",
       "email": "",
       "address": "",
       "mobile": "",
       "collection": "0.0",
       "product_full": "0.0",
       "product_empty": "0",
       "product_low": "0",
       "product_normal": "0"
      }
    ]
}

Insert location

Description:

Create a new location.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/locations

Method:

POST

Header Parameters:

Content-Type: application/json

Body Parameters:

Name	Format	Required	Description
location_name	String	Mandatory	Unique Location name in your company.
contact	String	Optional	Contact
address	String	Optional	Location address.
city	String	Optional	location city.
post_code	String	Optional	Location postcode.
state	String	Optional	Location state.
country	String	Optional	Location country.
office_phone	String	Optional	Office phone number of contact.
home_phone	String	Optional	Home phone number of contact.
mobile	String	Optional	Mobile number of contact.
fax	String	Optional	Fax of contact.
email	String	Optional	Email of contact.
notes	String	Optional	Notes

Response:

{
    "status": "1",
    "info": "success",
    "id": "1234",
    "fax": "",
    "location_id": "",
    "state": "",
    "location_name": "",
    "post_code": "",
    "office_phone": "",
    "contact": "",
    "city": "",
    "email": "",
    "address": "",
    "mobile": ""
}

Update location

Description:

Update a location by location ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/locations/{location_id}

Method:

POST

Header Parameters :

Content-Type: application/json

Path Parameters:

Name	Format	Required	Description
location_id	int	Mandatory	Location id.

Body Parameters:

Name	Format	Required	Description
location_name	String	Mandatory	Unique Location name in your company.
contact	String	Optional	Contact
address	String	Optional	Location address.
city	String	Optional	location city.
post_code	String	Optional	Location postcode.
state	String	Optional	Location state.
country	String	Optional	Location country.
office_phone	String	Optional	Office phone number of contact.
home_phone	String	Optional	Home phone number of contact.
mobile	String	Optional	Mobile number of contact.
fax	String	Optional	Fax of contact.
email	String	Optional	Email of contact.
notes	String	Optional	Notes

Response:

{
    "status": "1",
    "info": "success",
    "fax": "",
    "location_id": "",
    "state": "",
    "location_name": "",
    "post_code": "",
    "office_phone": "",
    "contact": "",
    "city": "",
    "email": "",
    "address": "",
    "mobile": ""
}

Delete location

Description:

Delete a location by location ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/locations/{location_id}

Method:

DELETE

Path Parameters

Name	Format	Required	Description
location_id	int	Mandatory	Location id.

Response:

{
    "status": "1",
    "info": "success"
}

Get a list of routes

Description:

Retrieve all routes for your company.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/routes

Method:

GET

Query Parameters:

Name

Format

Required

Description

Response:

{
    "status": "1",
    "info": "success",
    "page_info": {
        "total_records": "1",
        "record_per_page": "30",
        "total_page": "1",
        "current_page": "1"
    },
    "records": [
        {
            "route_id": "3",
            "driver": "driver",
            "description": "description",
            "route_name": "test route name"
        }
    ]
}

Get a route

Description:

Retrieve a route by route ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/routes/{route_id}

Method:

GET

Path Parameters:

Name	Format	Required	Description
route_id	int	Mandatory	Route ID.

Response:

{
    "status": "1",
    "info": "success",
    "record": [
        {
            "route_id": "",
            "driver": "",
            "description": "",
            "route_name": ""
        }
    ]
}

Insert route

Description:

Create a new route.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/routes

Method:

POST

Header Parameters :

Content-Type: application/json

Body Parameters:

Name	Format	Required	Description
route_name	String	Mandatory	Unique route name in your company.
driver	String	Optional	Route driver.
description	String	Optional	Route description.

Response:

{
    "status": "success",
    "route_id": "",
    "route_name": "",
    "driver": "",
    "description": ""
}

Update route

Description:

Update a route by route ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/routes/{route_id}

Method:

POST

Header Parameters:

Content-Type: application/json

Path Parameters:

Name	Format	Required	Description
route_id	int	Mandatory	Route ID.

Body Parameters:

Name	Format	Required	Description
route_name	String	Mandatory	Unique route name in your company.
driver	String	Optional	Route driver.
description	String	Optional	Route description.

Response:

{
    "status": "1",
    "info": "success",
    "id": "",
    "driver": "",
    "description": "",
    "route_name": ""
}

Delete route

Description:

Delete a route by route ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/routes/{route_id}

Method:

DELETE

Path Parameters

Name	Format	Required	Description
route_id	int	Mandatory	Route ID.

Response:

{
    "status": "0",
    "info": "fail"
}

Get a list of machines

Description:

Retrieve all machines for your company.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/machines

Method:

GET

Allowed Query Parameters:

Name	Format	Required	Description
machine_status	int	Optional	Filter by machine status. By default, all machines are returned. Accepted values: "0": offline, "1": online, "2": lost contact.
location_name	String	Optional	Location name of machine.
route_name	String	Optional	Route name of machine.
machine_model	String	Optional	Machine type name.
search_condition	String	Optional	Search by machine ID, serial number, or IMEI.

Response:

{
    "status": "1",
    "info": "success",
    "page_info": {
        "total_records": "50",
        "record_per_page": "30",
        "total_page": "2",
        "current_page": "1"
    },
    "records": [
        {
          "machine_model_id": "109",
          "purchase_date": "07/08/2018 00:00:00",
          "location_name": "test080608",
          "yearly_value": "0.0",
          "route_name": "testroute",
          "serial_no": "machinetest",
          "restock_value": "0.0",
          "yesterday_value": "0.0",
          "route_id": "2616",
          "machine_id": "11243",
          "last_restock": "",
          "install_date": "07/08/2018 00:00:00",
          "location_id": "14447",
          "today_value": "0.0",
          "monthly_value": "0.0",
          "imei": "01234567890",
          "machine_status": "0",
          "weekly_value": "0.0",
          "signal": "31",
          "machine_model": "Bianchi BVM 671",
          "last_report": "",
          "temperature": "36.0",
          "roi": "0.0",
          "purchase_price": "6000.0",
          "dep_rate": "0.0",
          "current_value": "128.0",
          "weight": "66.0",
          "place": ""
        }
    ]
}

Get a machine

Description:

Retrieve a machine by machine ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/machines/{machine_id}

Method:

GET

Path Parameters:

Name	Format	Required	Description
machine_id	int	Mandatory	Machine ID.

Response:

{
    "status": "1",
    "info": "success",
    "record": [
        {
            "machine_model_id": "109",
            "purchase_date": "07/08/2018 00:00:00",
            "location_name": "test080608",
            "yearly_value": "0.0",
            "route_name": "testroute",
            "serial_no": "machinetest",
            "restock_value": "0.0",
            "yesterday_value": "0.0",
            "route_id": "2616",
            "machine_id": "11243",
            "last_restock": "",
            "install_date": "07/08/2018 00:00:00",
            "location_id": "14447",
            "today_value": "0.0",
            "monthly_value": "0.0",
            "imei": "01234567890",
            "machine_status": "0",
            "weekly_value": "0.0",
            "signal": "31",
            "machine_model": "Bianchi BVM 671",
            "last_report": "",
          "temperature": "36.0",
          "roi": "0.0",
          "purchase_price": "6000.0",
          "dep_rate": "0.0",
          "current_value": "128.0",
          "weight": "66.0",
          "place": ""
        }
    ]
}

Insert machine

Description:

Create a new machine.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/machines

Method:

POST

Header Parameters:

Content-Type: application/json

Body Parameters:

Name	Format	Required	Description
serial_no	String	Mandatory	Unique serial number in your company.
machine_model_id	String	Mandatory	Machine model id.
location_id	String	Mandatory	ID of an existing location in your company.
route_id	String	Mandatory	ID of an existing route in your company.
imei	String	Optional	Unlinked imei number.

Response:

{
    "status": "1",
    "info": "success",
    "id": "12345",
    "machine_model_id": "6",
    "route_id": "123",
    "location_id": "123",
    "serial_no": "testMachineserial_no"
}

Update machine

Description:

Update a machine by machine ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/machines/{machine_id}

Method:

POST

Header Parameters:

Content-Type: application/json

Path Parameters:

Name	Format	Required	Description
machine_id	int	Mandatory	Machine ID.

Body Parameters:

Name	Format	Required	Description
serial_no	String	Optional	Unique serial number in your company.
machine_model_id	String	Optional	Machine model id.
location_id	String	Optional	ID of an existing location in your company.
route_id	String	Optional	ID of an existing route in your company.
imei	String	Optional	Unlinked imei number.

Response:

{
    "status": "1",
    "info": "success",
    "id": "",
    "machine_model_id": "",
    "route_id": "",
    "location_id": "",
    "imei": ""
}

Delete machine

Description:

Delete a machine by machine ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/machines/{machine_id}

Method:

DELETE

Path Parameters

Name	Format	Required	Description
machine_id	int	Mandatory	Machine ID.

Response:

{
    "status": "1",
    "info": "success"
}

Get a list of coils

Description:

Retrieve all coils for a machine. A machine ID is required.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/coils

Method:

GET

Query Parameters:

Name	Format	Required	Description
machine_id	int	Mandatory	You must set machine_id to receive coils.

Response:

{
    "status": "1",
    "info": "success",
    "page_info": {
        "total_records": "1",
        "record_per_page": "30",
        "total_page": "1",
        "current_page": "1"
    },
    "records": [
        {
            "current_level": "3",
            "machine_id": "12345",
            "par_level": "3",
            "product_id": "123",
            "price": "10.0",
            "coil_id": "123456",
            "alarm_level": "1",
            "last_life_vends": "0",
            "last_ife_value": "0.0",
            "last_vend_time": "",
            "coil_no": "1",
            "product_name": "test product"
        }
    ]
}

Get a coil

Description:

Retrieve a coil by coil ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/coils/{coil_id}

Method:

GET

Path Parameters:

Name	Format	Required	Description
coil_id	int	Mandatory	Coil ID.

Response:

{
    "status": "1",
    "info": "success",
    "record": [
        {
            "current_level": "",
            "machine_id": "",
            "par_level": "",
            "product_id": "",
            "price": "",
            "coilId": "",
            "alarm_level": "",
            "last_life_vends": "",
            "last_ife_value": "",
            "last_vend_time": "",
            "coil_no": "",
            "product_name": ""
        }
    ]
}

Insert coil

Description:

Create a new coil.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/coils

Method:

POST

Header Parameters:

Content-Type: application/json

Body Parameters:

Name	Format	Required	Description
machine_id	String	Mandatory	Valid machine ID for your company.
product_id	String	Mandatory	Valid product ID for your company.
price	String	Mandatory	Product price.
coil_no	String	Mandatory	Unnique coil no in machine.
current_level	String	Mandatory	Current stock level. Must be less than or equal to the PAR level.
alarm_level	String	Mandatory	Alarm level. Must be greater than 0 and less than the PAR level.
par_level	String	Mandatory	Par level.

Response:

{
    "status": "1",
    "info": "success",
    "id": "",
    "current_level": "",
    "machine_id": "",
    "product_id": "",
    "par_level": "",
    "price": "",
    "alarm_level": "",
    "coil_no": ""
}

Update coil

Description:

Update a coil by coil ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/coils/{coil_id}

Method:

POST

Header Parameters :

Content-Type: application/json

Path Parameters:

Name	Format	Required	Description
coil_id	int	Mandatory	Coil ID.

Body Parameters:

Name	Format	Required	Description
product_id	String	Optional	Valid product ID for your company.
price	String	Optional	Product price.
coil_no	String	Optional	Unnique coil no in machine.
current_level	String	Optional	Current stock level. Must be less than or equal to the PAR level.
alarm_level	String	Optional	Alarm level. Must be greater than 0 and less than the PAR level.
par_level	String	Optional	Par level.

Response:

{
    "status": "1",
    "info": "success",
    "id": "",
    "current_level": "",
    "product_id": "",
    "par_level": "",
    "price": "",
    "alarm_level": "",
    "coil_no": ""
}

Delete coil

Description:

Delete a coil.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/coils/{coil_id}

Method:

DELETE

Produces:

application/json

Path Parameters

Name	Format	Required	Description
coil_id	int	Mandatory	Coil ID.

Response:

{
    "status": "success"    
}

Get coil alarms

Description:

Retrieve all coil alarms.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/coils?coil_alarm=1

Method:

GET

Query Parameters:

Name	Format	Required	Description
location_id	int	Mandatory	Filter coil with location.
route_id	int	Mandatory	Filter coil with route.
show_empty_coils	int	Mandatory	Whether to include empty coils. Default: 0. Accepted values: 0, 1.
show_low_coils	int	Mandatory	Whether to include low-stock coils. Default: 0. Accepted values: 0, 1.

Response:

{
    "status": "1",
    "info": "success",
    "page_info": {
        "total_records": "1",
        "record_per_page": "30",
        "total_page": "1",
        "current_page": "1"
    },
    "records": [
        {
            "current_level": "3",
            "machine_id": "12345",
            "par_level": "3",
            "product_id": "123",
            "price": "10.0",
            "coil_id": "123456",
            "alarm_level": "1",
            "last_life_vends": "0",
            "last_ife_value": "0.0",
            "last_vend_time": "",
            "coil_no": "1",
            "product_name": "test product",
            "machine_place": "machine place",
            "location_name": "Test location",
            "product_upc_no": "000000"
        }
    ]
}

Get a list of machine models

Description:

Retrieve all machine models.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/machine_models

Method:

GET

Query Parameters:

Name

Format

Required

Description

Produces:

application/json

Response:

{
    "status": "1",
    "info": "success",
    "page_info": {
        "total_records": "190",
        "record_per_page": "30",
        "total_page": "7",
        "current_page": "1"
    },
    "records": [
        {
            "machine_model": "",
            "machine_model_id": ""
        }
    ]
}

Get a machine model

Description:

Retrieve a machine model.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/machine_models/{machine_model_id}

Method:

GET

Path Parameters:

Name	Format	Required	Description
machine_model_id	int	Mandatory	Machine model id

Response:

{
    "status": "1",
    "info": "success",
    "record": [
        {
            "machine_model_id": "",
            "machine_model": "Bay Wash 100"
        }
    ]
}

Get a list of users

Description:

Retrieve all users for your company.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/user

Method:

GET

Allowed Query Parameters:

Name	Format	Required	Description
search_condition	String	Optional	Search by username, first name, or last name.

Response:

{
    "status": "1",
    "info": "success",
    "page_info": {
        "total_records": "20",
        "record_per_page": "30",
        "total_page": "1",
        "current_page": "1"
    },
    "records": [
        {
            "email": "",
            "country": "",
            "postcode": "",
            "state": "",
            "address": "",
            "fax_no": "",
            "mobile": "",
            "home_phone": "",
            "office_phone": "",
            "last_name": "",
            "first_name": "",
            "user_name": "",
            "user_id": ""
        }
    ]
}

Get a user

Description:

Retrieve a user by user ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/user/{user_id}

Method:

GET

Path Parameters:

Name	Format	Required	Description
user_id	int	Mandatory	User ID.

Response:

{
        
    "status": "1",
        
    "info": "success",
        
    "record": [
        
       {
        
            "email": "",
        
            "country": "",
        
            "postcode": "",
        
            "state": "",
        
            "address": "",
        
            "fax_no": "",
        
            "mobile": "",
        
            "home_phone": "",
        
            "office_phone": "",
        
            "last_name": "",
        
            "first_name": "",
        
            "user_name": "",
        
            "user_id": ""
        
        }
        
    ]
        
}

Insert user

Description:

Create a new user.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/user

Method:

POST

Header Parameters:

Content-Type: application/json

Body Parameters:

Name	Format	Required	Description
account_name	String	Mandatory	Username. Must be unique within the system.
password	String	Mandatory	Password.
first_name	String	Mandatory	First name of user.
last_name	String	Mandatory	Last name of user.
user_role	String	Optional	User role. Accepted values: "1": administrator, "2": cashless administrator, "3": guest (default), "4": service technician.
office_phone	String	Optional	Office phone of user.
home_phone	String	Optional	Home phone of user.
mobile	String	Optional	Mobile number of user.
fax	String	Optional	Fax number of user.
address	String	Optional	Address.
state	String	Optional	State.
country	String	Optional	Country.
postcode	String	Optional	Postcode.
email	String	Optional	Email address of user.

Response:

{
        
    "status": "1",
        
    "info": "success",
        
    "id": "1234",
        
    "country": "country",
        
    "home_phone": "home_phone",
        
    "address": "address",
        
    "user_name": "",
        
    "postcode": "postcode",
        
    "mobile": "mobile",
        
    "last_name": "last_name",
        
    "office_phone": "office_phone",
        
    "user_role": "1",
        
    "password": "password",
        
    "account_name": "accoune_name",
        
    "state": "state",
        
    "fax": "fax_no",
        
    "first_name": "first_name",
        
    "email": "email@test.com"
        
}

Update user

Description:

Update a user by user ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/user/{user_id}

Method:

POST

Header Parameters:

Content-Type: application/json

Path Parameters:

Name	Format	Required	Description
user_id	int	Mandatory	User ID.

Body Parameters:

Name	Format	Required	Description
first_name	String	Optional	First name of user.
last_name	String	Optional	Last name of user.
user_role	String	Optional	User role. Accepted values: "1": administrator, "2": cashless administrator, "3": guest (default), "4": service technician.
office_phone	String	Optional	Office phone of user.
home_phone	String	Optional	Home phone of user.
mobile	String	Optional	Mobile number of user.
fax	String	Optional	Fax number of user.
address	String	Optional	Address.
state	String	Optional	State.
country	String	Optional	Country.
postcode	String	Optional	Postcode.
email	String	Optional	Email address of user.

Can not update account name.

Response:

{
        
    "status": "1",
        
    "info": "success",
        
    "id": "1234",
        
    "country": "new country",
        
    "home_phone": "new1 home_phone",
        
    "address": "new address",
        
    "user_name": "",
        
    "postcode": "new postcode",
        
    "mobile": "new mobile",
        
    "last_name": "new last_name",
        
    "office_phone": "new office_phone",
        
    "user_role": "2",
        
    "state": "new state",
        
    "fax": "new fax_no",
        
    "first_name": "new first_name",
        
    "email": "email@test.com"
        
}

Delete user

Description:

Delete a user by user ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/user/{user_id}

Method:

DELETE

Path Parameters

Name	Format	Required	Description
user_id	int	Mandatory	User ID.

Response:

{
        
    "status": "1",
        
    "info": "success"
        
}

Description:

Authenticate with a username and password to obtain an API key.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/user/login

Method:

POST

Header Parameters:

Content-Type: application/json

Body Parameters:

Name	Format	Required	Description
user_name	String	Mandatory	Username.
password	String	Mandatory	Password.

This endpoint does not require the key HTTP header.

Response:

{
    "status": "1",
    "info": "success",
    "api_key": "API key"
}

Get my company details

Description:

Retrieve your company details.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/company

Method:

GET

Response:

{
        
    "status": "1",
        
    "info": "success",
        
    "record": [
        
        {
        
            "country": "AUS",
        
            "office_phone": "office phone",
        
            "state": "VIC",
        
            "post_code": "3194",
        
            "city": "Mentone",
        
            "address": "Suite 1.02, 3 Joseph Avenue",
        
            "contact": "Contact name",
        
            "company_name": "Circumtec",
        
            "company_id": "2",
        
            "moblie": "mobile",
        
            "fax": "new fax",
        
            "email": "test@mail.com",
        
            "notes": "this is the notes",
        
            "abn": "new abn",
        
            "homePhone": "new home phone"
        
        }
        
    ]
        
}

Update my company details

Description:

Update your company details.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/company

Method:

POST

Header Parameters:

Content-Type: application/json

Body Parameters:

Name	Format	Required	Description
company_name	String	Optional	Company name.
abn	String	Optional	ABN.
contact	String	Optional	Contact of company.
office_phone	String	Optional	Office phone of company.
home_phone	String	Optional	Home phone of company.
mobile	String	Optional	Mobile number of company.
fax	String	Optional	Fax number of company.
address	String	Optional	Address of company.
city	String	Optional	State.
state	String	Optional	State.
country	String	Optional	Country.
postcode	String	Optional	Postcode.
email	String	Optional	Email address of user.
notes	String	Optional	Notes.

Response:

{
        
    "status": "1",
        
    "info": "success",
        
    "id": "",
        
    "home_phone": "new home phone",
        
    "country": "new country",
        
    "notes": "this is the notes",
        
    "address": "new address",
        
    "city": "new city",
        
    "user_name": "DEMO",
        
    "mobile": "new mobile",
        
    "postcode": "new postcode",
        
    "abn": "new abn",
        
    "office_phone": "new office phone",
        
    "company_name": "new company name",
        
    "contact": "new contact",
        
    "state": "new state",
        
    "fax": "new fax",
        
    "email": "test@mail.com"
        
}

Get a list of categories

Description:

Retrieve all categories for your company.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/category

Method:

GET

Query Parameters:

Name

Format

Required

Description

Response:

{
    "status": "1",
    "info": "success",
    "page_info": {
        "total_records": "15",
        "record_per_page": "30",
        "total_page": "1",
        "current_page": "1"
    },
    "records": [
        {
            "category_id": "107226",
            "category_name": "Soft Drink Cans",
            "note": "",
            "category_image": "/img/10400/producttype/producttype_47361.jpeg",
            "is_system": ""

        }
    ]
}

Get a category

Description:

Retrieve a category by category ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/category/{category_id}

Method:

GET

Path Parameters:

Name	Format	Required	Description
category_id	int	Mandatory	Category ID.

Response:

{
    "status": "1",
    "info": "success",
    "record":[
    {
       "category_id": "107226",
       "category_name": "Soft Drink Cans",
       "note": "",
       "category_image": "/img/10400/producttype/producttype_47361.jpeg",
       "is_system": ""
      }
    ]
}

Insert category

Description:

Create a new category.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/category

Method:

POST

Header Parameters:

Content-Type: application/json

Body Parameters:

Name	Format	Required	Description
category_name	String	Mandatory	Unique category name in your company.
note	String	Optional	Note
category_image	String	Optional	Image url.

Response:

{
            
    "status": "1",
            
    "info": "success",
            
    "record":[
            
    {
            
       "category_id": "123456",
            
       "category_name": "New category name",
            
       "note": "note...",
            
       "category_image": "/img/10400/producttype/producttype_47361.jpeg",
            
       "is_system": ""
            
      }
            
    ]
            
}

Update category

Description:

Update a category by category ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/category/{category_id}

Method:

POST

Header Parameters :

Content-Type: application/json

Path Parameters:

Name	Format	Required	Description
category_id	int	Mandatory	Category ID.

Body Parameters:

Name	Format	Required	Description
Name	Format	Required	Description
category_name	String	Optional	Unique category name in your company.
note	String	Optional	Note
category_image	String	Optional	Image url.

Response:

{
            
    "status": "1",
            
    "info": "success",
            
    "record":[
            
    {
            
       "category_id": "123456",
            
       "category_name": "New category name",
            
       "note": "note...",
            
       "category_image": "/img/10400/producttype/producttype_47361.jpeg",
            
       "is_system": ""
            
      }
            
    ]
            
}

Delete category

Description:

Delete a category by category ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/category/{category_id}

Method:

DELETE

Path Parameters

Name	Format	Required	Description
category_id	int	Mandatory	Category ID.

Response:

{
    "status": "1",
    "info": "success"
}

Get a list of brands

Description:

Retrieve all brands for your company.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/brands

Method:

GET

Query Parameters:

Name

Format

Required

Description

Response:

{
    "status": "1",
    "info": "success",
    "page_info": {
        "total_records": "15",
        "record_per_page": "30",
        "total_page": "1",
        "current_page": "1"
    },
    "records": [
        {
            "brand_id": "197005",
            "brand_name": "Brand Name",
            "note": "",
            "brand_image": "/images/nopic.gif",
            "is_system": ""

        }
    ]
}

Get a brand

Description:

Retrieve a brand by brand ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/brands/{brand_id}

Method:

GET

Path Parameters:

Name	Format	Required	Description
brand_id	int	Mandatory	Brand ID.

Response:

{
    "status": "1",
    "info": "success",
    "record":[
    {
            "brand_id": "197005",
            "brand_name": "Brand Name",
            "note": "",
            "brand_image": "/images/nopic.gif",
            "is_system": ""
      }
    ]
}

Insert brand

Description:

Create a new brand.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/brands

Method:

POST

Header Parameters:

Content-Type: application/json

Body Parameters:

Name	Format	Required	Description
brand_name	String	Mandatory	Unique brand name in your company.
note	String	Optional	Note
brand_image	String	Optional	Image url.

Response:

{
            
    "status": "1",
            
    "info": "success",
            
    "record":[
            
    {
            
       "brand_id": "123456",
            
       "brand_name": "New brand name",
            
       "note": "note...",
            
       "brand_image": "/img/nopic.jpeg",
            
       "is_system": ""
            
      }
            
    ]
            
}

Update brand

Description:

Update a brand by brand ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/brands/{brand_id}

Method:

POST

Header Parameters :

Content-Type: application/json

Path Parameters:

Name	Format	Required	Description
brand_id	int	Mandatory	Brand ID.

Body Parameters:

Name	Format	Required	Description
brand_name	String	Optional	Unique brand name in your company.
note	String	Optional	Note
brand_image	String	Optional	Image url.

Response:

{
            
    "status": "1",
            
    "info": "success",
            
    "record":[
            
    {
            
       "brand_id": "123456",
            
       "brand_name": "New category name",
            
       "note": "note...",
            
       "brand_image": "/img/10400/producttype/producttype_47361.jpeg",
            
       "is_system": ""
            
      }
            
    ]
            
}

Delete brand

Description:

Delete a brand by brand ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/brands/{brand_id}

Method:

DELETE

Path Parameters

Name	Format	Required	Description
brand_id	int	Mandatory	Brand ID.

Response:

{
    "status": "1",
    "info": "success"
}

Get a list of products

Description:

Retrieve all products for your company.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/products

Method:

GET

Query Parameters:

Name	Format	Required	Description
virtual_product	int	Optional	If virtual_product=1, return all virtual products(Membership card). Default value is 0;

Response:

{
            
   "status": "1",
            
   "info": "success",
            
   "page_info": {
            
        "record_per_page": "1",
            
        "total_records": "1",
            
        "current_page": "1",
            
        "total_page": "1" 
            
    },
            
    "records": [
            
        {
            
            "product_id": "473474",
            
            "brand_id": "177357",
            
            "brand_name": "brand name",
            
            "product_type_id": "107228",
            
            "product_type_name": "Chips",
            
            "upc_no": "",
            
            "product_name": "Product name",
            
            "supplier_id": "0",
            
            "price": "1.0",
            
            "size": "",
            
            "in_stock": "60",
            
            "reorder": "0",
            
            "min_order": "0",
            
            "bulk_qty": "0",
            
            "shelf_life": "20",
            
            "alarm_level": "0",
            
            "supplier_name": "supplier name",
            
            "large_image": "/images/nopic.gif",
            
            "daily_avg": "0.0",
            
            "brand_image": "/images/nopic.gif",
            
            "category_image": "/images/nopic.gif",
            
            "description": "description"
            
        }
            
    ]
            
}

Get a product

Description:

Retrieve a product by product ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/products/{product_id}

Method:

GET

Path Parameters:

Name	Format	Required	Description
product_id	int	Mandatory	Product ID.

Response:

{
            
   "status": "1",
            
   "info": "success",
            
   "page_info": {
            
        "record_per_page": "1",
            
        "total_records": "1",
            
        "current_page": "1",
            
        "total_page": "1" 
            
    },
            
    "records": [
            
        {
            
            "product_id": "473474",
            
            "brand_id": "177357",
            
            "brand_name": "brand name",
            
            "product_type_id": "107228",
            
            "product_type_name": "Chips",
            
            "upc_no": "",
            
            "product_name": "Product name",
            
            "supplier_id": "0",
            
            "price": "1.0",
            
            "size": "",
            
            "in_stock": "60",
            
            "reorder": "0",
            
            "min_order": "0",
            
            "bulk_qty": "0",
            
            "shelf_life": "20",
            
            "alarm_level": "0",
            
            "supplier_name": "supplier name",
            
            "large_image": "/images/nopic.gif",
            
            "daily_avg": "0.0",
            
            "brand_image": "/images/nopic.gif",
            
            "category_image": "/images/nopic.gif",
            
            "description": "description"
            
        }
            
    ]
            
}

Insert product

Description:

Create a product.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/products

Method:

POST

Header Parameters:

Content-Type: application/json

Body Parameters:

Name	Format	Required	Description
product_name	String	Mandatory	Unique product name in your company.
brand_id	String	Mandatory	Brand ID from "brands" API.
product_type_id	String	Mandatory	Category ID from "category" API.
alarm_level	String	Mandatory	Alarm level, must be greater than 0 and less than the PAR level.
bulk_qty	String	Mandatory	The bulk quantity.
reorder	String	Mandatory	The reorder quantity.
min_order	String	Mandatory	The minimum order quantity.
cost	String	Mandatory	The product cost.
upc_no	String	Mandatory	UPC number.
in_stock	String	Mandatory	The quantity currently in stock.
shelf_life	String	Mandatory	Shelf life.
size	String	Optional	The product size.

Response:

{
    "status": "1",
    "info": "success",
    "page_info": {
        "record_per_page": "1",
        "total_records": "1",
        "current_page": "1",
        "total_page": "1"
    },
    "records": [
        {
            "product_id": "473474",
            "brand_id": "177357",
            "brand_name": "brand name",
            "product_type_id": "107228",
            "product_type_name": "Chips",
            "upc_no": "",
            "product_name": "Product name",
            "supplier_id": "0",
            "price": "1.0",
            "size": "",
            "in_stock": "60",
            "reorder": "0",
            "min_order": "0",
            "bulk_qty": "0",
            "shelf_life": "20",
            "alarm_level": "0",
            "supplier_name": "supplier name",
            "large_image": "/images/nopic.gif",
            "daily_avg": "0.0",
            "brand_image": "/images/nopic.gif",
            "category_image": "/images/nopic.gif",
            "description": "description"
        }
    ]
}

Update product

Description:

Update a product by product ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/products/{product_id}

Method:

POST

Header Parameters:

Content-Type: application/json

Path Parameters:

Name	Format	Required	Description
category_id	int	Mandatory	Category ID.

Body Parameters:

Name	Format	Required	Description
product_name	String	Optional	Unique product name in your company.
brand_id	String	Optional	Brand ID from "brands" API.
product_type_id	String	Optional	Category ID from "category" API.
alarm_level	String	Optional	Alarm level, must be greater than 0 and less than the PAR level.
bulk_qty	String	Optional	The bulk quantity.
reorder	String	Optional	The reorder quantity.
min_order	String	Optional	The minimum order quantity.
cost	String	Optional	The product cost.
upc_no	String	Optional	UPC number.
in_stock	String	Optional	The quantity currently in stock.
shelf_life	String	Optional	Shelf life.
size	String	Optional	The product size.

Response:

{
    "status": "1",
    "info": "success",
    "page_info": {
        "record_per_page": "1",
        "total_records": "1",
        "current_page": "1",
        "total_page": "1"
    },
    "records": [
        {
            "product_id": "473474",
            "brand_id": "177357",
            "brand_name": "brand name",
            "product_type_id": "107228",
            "product_type_name": "Chips",
            "upc_no": "",
            "product_name": "Product name",
            "supplier_id": "0",
            "price": "1.0",
            "size": "",
            "in_stock": "60",
            "reorder": "0",
            "min_order": "0",
            "bulk_qty": "0",
            "shelf_life": "20",
            "alarm_level": "0",
            "supplier_name": "supplier name",
            "large_image": "/images/nopic.gif",
            "daily_avg": "0.0",
            "brand_image": "/images/nopic.gif",
            "category_image": "/images/nopic.gif",
            "description": "description"
        }
    ]
}

Delete product

Description:

Delete a product by product ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/products/{product_id}

Method:

DELETE

Path Parameters

Name	Format	Required	Description
product_id	int	Mandatory	Product ID.

Response:

{
    "status": "1",
    "info": "success"
}

Get a list of transactions

Description:

Retrieve all transactions for your company.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/transactions

Method:

GET

Query Parameters:

Name	Format	Required	Description
start_date	string(dd/MM/yyyy)	Optional	Default: current date.
end_date	string(dd/MM/yyyy)	Optional	Default: current date.
card_no	string	Optional	Query with card number.
card_account_id	int	Optional	Query with card account id.

Response:

{
            
   "status": "1",
            
   "info": "success",
            
   "page_info": {
            
        "record_per_page": "30",
            
        "total_records": "7",
            
        "current_page": "1",
            
        "total_page": "1" 
            
    },
            
    "records": [
            
        {
            
            "transaction_id": "666819",
            
            "card_id": "8660105",
            
            "card_no": "test122501",
            
            "card_type": "Normal",
            
            "description": "description",
            
            "card_account_id": "17600354",
            
            "credit_time": "19/01/2021 11:48:40",
            
            "status": "0",
            
            "balance": "60.00",
            
            "credit": "0.0",
            
        },
            
        ... ...
            
    ]
            
}
            
}

Get a list of DTUs

Description:

Retrieve all DTUs.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/dtus

Method:

GET

Query Parameters:

Name	Format	Required	Description
no_machine	string	Optional	Accepted values: "0", "1". When `no_machine` is 0, return all DTUs that are not linked to a machine.
is_linked	string	Optional	Accepted values: "0", "1".
dtu_model	string	Optional	DTU model.
update_flag	string	Optional	Update flag field.
firmware_ver	string	Optional	DTU firmware version.

Response:

{
            
   "status": "1",
            
   "info": "success",
            
   "page_info": {
            
        "record_per_page": "30",
            
        "total_records": "7",
            
        "current_page": "1",
            
        "total_page": "1" 
            
    },
            
    "records": [
            
        {
            
            "dtu_id": "26666",
            
            "machine_id": "18420",
            
            "imei": "867377026312235",
            
            "ip_address": "10.99.236.238",
            
            "dtu_state": "1",
            
            "report_interval": "2",
            
            "serial_no": "",
            
            "model_no": "cv408",
            
            "build_standard": "0",
            
            "location": "",
            
            "asset_no": "",
            
            "decimal_point": "0.0",
            
            "currency_code_no": "0",
            
            "currency_code_name": "",
            
            "vmc_serial": "",
            
            "vmc_model": "",
            
            "vms_build_std": "",
            
            "heartbeat_interval": "1440",
            
            "apn": "",
            
            "firmware_ver": "1.0.21",
            
            "signal": "10",
            
            "last_report": "",
            
            "imsi": "",
            
            "ccid": "",
            
            "company_id": "",
            
            "mode": "0"
            
        },
            
        ... ...
            
    ]
            
}
            
}

Get a DTU

Description:

Retrieve a DTU by DTU ID.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/dtus/{dtu_id}

Method:

GET

Path Parameters:

Name	Format	Required	Description
dtu_id	int	Mandatory	DTU ID.

Response:

{
            
   "status": "1",
            
   "info": "success",
            
   "page_info": {
            
        "record_per_page": "1",
            
        "total_records": "1",
            
        "current_page": "1",
            
        "total_page": "1" 
            
    },
            
    "records": [
            
        {
            
            "dtu_id": "26666",
            
            "machine_id": "18420",
            
            "imei": "867377026312235",
            
            "ip_address": "10.99.236.238",
            
            "dtu_state": "1",
            
            "report_interval": "2",
            
            "serial_no": "",
            
            "model_no": "cv408",
            
            "build_standard": "0",
            
            "location": "",
            
            "asset_no": "",
            
            "decimal_point": "0.0",
            
            "currency_code_no": "0",
            
            "currency_code_name": "",
            
            "vmc_serial": "",
            
            "vmc_model": "",
            
            "vms_build_std": "",
            
            "heartbeat_interval": "1440",
            
            "apn": "",
            
            "firmware_ver": "1.0.21",
            
            "signal": "10",
            
            "last_report": "",
            
            "imsi": "",
            
            "ccid": "",
            
            "company_id": "",
            
            "mode": "0"
            
        },
            
        ... ...
            
    ]
            
}
            
}

Send a command to a DTU

Description:

Send a real-time command to a DTU.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/dtus?imei={imei}&action={action}

Method:

GET

Path Parameters:

Name	Format	Required	Description
imei	String	Mandatory	DTU IMEI.
action	String	Mandatory	Command action.

Supported actions:

Name	Format	Description	Sample
dex	String	Request a DEX report.	https://api.circumvend.com.au/api/v1/vmms/dtus?imei=123456&action=dex
restock_only	String	Restock the machine by resetting the current level of every coil to its PAR level.	https://api.circumvend.com.au/api/v1/vmms/dtus?imei=123456&action=restock_only
restock	String	Perform the `restock_only` action and create a collection report.	https://api.circumvend.com.au/api/v1/vmms/dtus?imei=123456&action=restock
remote_credit	String	Send credit to a DTU. The card number can be any valid card listed under Cashless > Card List in your account. The API returns `{ "status": "1", "info": "success", "job_no": "IMEI1234567890_1754447919416_5111" }` on success or `{ "status": "0", "info": "fail" }` on failure. A successful response includes a `job_no`.	https://api.circumvend.com.au/api/v1/vmms/dtus?imei=123456&action=remote_credit&card_no=FREE_CREDIT&credit=1400
check_status	String	Check whether the DTU is `idle` or `busy`. The API returns `{ "status": "1", "info": "idle" }` or `{ "status": "0", "info": "busy" }`. A `busy` response means the device is not responding. The check may take up to 20 seconds.	https://api.circumvend.com.au/api/v1/vmms/dtus?imei=123456&action=check_status

Response:

{
            
   "status": "1",
            
   "info": "success"
            
}

Get a DTU job by job number

Description:

Retrieve DTU job details using the job_no returned by remote_credit.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/dtujob

Method:

POST

Header Parameters

Content-Type: application/json

Request Body (application/json):

{
    "action": "get_job",
    "params": {
        "job_no": "job_no_123456789"
    }
}

Note: The response includes a job_state field, which indicates the job status. Possible values are created, running, completed, and failed.

Response:

{
    "status": "1",
    "info": "success",
    "records": [
        {
            "job_no": "123456789_1754450191384_1372",
            "imei": "123456789",
            "job_state": "completed",
            "company_id": "123",
            "machine_id": "12345",
            "create_at": "2025-08-06 13:16:31",
            "create_ts": "1754450191523",
            "last_update": "2025-08-06 13:16:31",
            "update_ts": "1754450191523",
            "note": "Job has been completed"
        }
    ]
}

Machine daily sales

Description:

Retrieve daily sales for all machines.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/reports

Method:

GET

Query Parameters:

Name	Format	Required	Description
report_type	string	Mandatory	report_type = machine_daily
start_date	String(dd/MM/yyyy)	Optional	For example, 10/09/2022. Default: current date.
end_date	String(dd/MM/yyyy)	Optional	For example, 16/09/2022. Default: current date.
machine_id	string	Optional	Filter reports by machine ID.

Response:

{
            
   "status": "1",
            
   "info": "success",
            
   "page_info": {
            
        "record_per_page": "0",
            
        "total_records": "0",
            
        "current_page": "0",
            
        "total_page": "0" 
            
    },
            
    "records": [
            
        {
            
            "log_day": "2022-09-10",
            
            "total_value": "10.00",
            
            "card_value": "6.00",
            
            "cash_value": "4.00",
            
            "machine_id": "",
            
        },
            
        ... ...
            
    ]
            
}
            
}

Machine hourly sales

Description:

Get sales data for each hour of the day.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/reports

Method:

GET

Path Parameters:

Name	Format	Required	Description
report_type	string	Mandatory	report_type = machine_hourly
log_day	String(dd/MM/yyyy)	Optional	Sales date. For example, 16/09/2022. Default: current date.
machine_id	string	Optional	Filter sales with machine.

Response:

{
            
   "status": "1",
            
   "info": "success",
            
   "page_info": {
            
        "record_per_page": "0",
            
        "total_records": "0",
            
        "current_page": "0",
            
        "total_page": "0" 
            
    },
            
    "records": [
            
        {
            
            "totalValue": "0.00",
            
            "hourlySales": { 
            
               "0": "0.00",
            
               "1": "0.00",
            
               "2": "0.00",
            
               "3": "0.00",
            
               "4": "0.00",
            
               "5": "0.00",
            
               "6": "0.00",
            
               "7": "0.00",
            
               "8": "0.00",
            
               "9": "0.0",
            
               "10": "0.00",
            
               "11": "0.00",
            
               "12": "0.00",
            
               "13": "0.00",
            
               "14": "0.00",
            
               "15": "0.00",
            
               "16": "0.00",
            
               "17": "0.00",
            
               "18": "0.00",
            
               "19": "0.00",
            
               "20": "0.00",
            
               "21": "0.00",
            
               "22": "0.00",
            
               "23": "0.00",
            
               "24": "0.00",
            
               }
            
        },
            
        ... ...
            
    ]
            
}
            
}

Get a list of alarms

Description:

Retrieve all alarms.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/alarms

Method:

GET

Query Parameters:

Name

Format

Required

Description

Response:

{
            
   "status": "1",
            
   "info": "success",
            
   "page_info": {
            
        "record_per_page": "30",
            
        "total_records": "7",
            
        "current_page": "1",
            
        "total_page": "1" 
            
    },
            
    "records": [
            
        {
            
            "alarm_id": "26666",
            
            "location_name": "location",
            
            "machine_id": "12345",
            
            "subject": "Machine 12345 in [location] offline, IMEI:1234567890abcd, normally caused by power off or signal issue. \r\n",
            
            "first_occur_time": "16/07/2022 01:06:09",
            
            "status": "New",
            
            "alarm_type": "Offline",
            
        },
            
        ... ...
            
    ]
            
}
            
}

Get location coordinates

Description:

Retrieve geographic coordinates for all locations.

Request URL:

https://api.circumvend.com.au/api/v1/vmms/maps?category=all_locations

Method:

GET

Query Parameters:

Name

Format

Required

Description

Response:

{
            
   "status": "1",
            
   "info": "success",
            
   "page_info": {
            
        "record_per_page": "30",
            
        "total_records": "7",
            
        "current_page": "1",
            
        "total_page": "1" 
            
    },
            
    "records": [
            
        {
            
            "latitude": "-37.96199",
            
            "longitude": "145.03839",
            
            "product_empty": "0",
            
            "product_low": "0",
            
            "locationName": "Circumtec Office",
            
            "locationId": "12345",
            
            "product_normal": "5",
            
            "productFull": "100",
            
            "machineCount": "1",
            
            "address": "328 Reserve Rd",
            
            "city": "Cheltenham",
            
            "state": "VIC",
            
        },
            
        ... ...
            
    ]
            
}
            
}

General Error Response

If a request fails, the API returns an error description in the info field.

Error response:

{
    "status":"0",
    "info": "fail"
}

Example Request

cURL

GET:

Get a list of machines.

curl --request GET \
  --url 'https://api.circumvend.com.au/api/v1/vmms/machines?record_per_page=20' \
  --header 'key: api key'

Get a machine.

curl --request GET \
  --url 'https://api.circumvend.com.au/api/v1/vmms/machines/12345' \
  --header 'key: api key'

POST:

Insert machine.

curl --request POST \
  --url 'https://api.circumvend.com.au/api/v1/vmms/machines' \
  --header 'Content-Type: application/json' \
  --header 'key: api key' \
  --data '{
    "serial_no": "testMachine",
    "machine_model_id": "1",
    "location_id": "2",
    "route_id": "3"
  }'

Update machine.

curl --request POST \
  --url 'https://api.circumvend.com.au/api/v1/vmms/machines/11239' \
  --header 'Content-Type: application/json' \
  --header 'key: api key' \
  --data '{
    "machine_model_id": "",
    "location_id": "",
    "imei": "",
    "route_id": ""
  }'

DELETE:

Delete machine.

curl --request DELETE \
  --url 'https://api.circumvend.com.au/api/v1/vmms/machines/11239' \
  --header 'key: api key'

PHP

GET:

Get a list of machines.


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.circumvend.com.au/api/v1/vmms/machines?record_per_page=20",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "key: api key"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Get machine


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.circumvend.com.au/api/v1/vmms/machines/123",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "key: api key"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

POST:

Insert machine.


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.circumvend.com.au/api/v1/vmms/machines",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \"serial_no\":\"testMachine\",\n  \"machine_model_id\":\"1\",\n \n  \"location_id\":\"2\",\n  \"route_id\":\"3\"\n}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "key: api key"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Update machine.



$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.circumvend.com.au/api/v1/vmms/machines/11239",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \n  \"machine_model_id\":\"103\",\n  \"location_id\":\"14453\",\n  \"imei\":\"861075024559726\",\n  \"route_id\":\"2\"\n}",
  CURLOPT_HTTPHEADER => array(
    "Content-Type: application/json",
    "key: api key"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

DELETE:

Delete machine.

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.circumvend.com.au/api/v1/vmms/machines/123",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => array(
    "key: api key"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Python

GET:

Get a list of machines.

import requests

url = "https://api.circumvend.com.au/api/v1/vmms/machines"

querystring = {"record_per_page":"20"}

headers = {'key': 'api key'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)

Get machine.

import requests

url = "https://api.circumvend.com.au/api/v1/vmms/machines/11244"

headers = {'key': 'api key'}

response = requests.request("GET", url, headers=headers)

print(response.text)

POST:

Insert machine.

import requests

url = "https://api.circumvend.com.au/api/v1/vmms/machines"

payload = "{\n  \"serial_no\":\"testMachine\",\n  \"machine_model_id\":\"1\",\n \n  \"location_id\":\"2\",\n  \"route_id\":\"3\"\n}"
headers = {
    'key': "api key",
    'Content-Type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Update machine.

import requests

url = "https://api.circumvend.com.au/api/v1/vmms/machines/123"

payload = "{\n  \n  \"machine_model_id\":\"1\",\n  \"location_id\":\"2\",\n  \"imei\":\"testImeiNumber\",\n  \"route_id\":\"3\"\n}"
headers = {
    'key': "api key",
    'Content-Type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

DELETE:

Delete machine.

import requests

url = "https://api.circumvend.com.au/api/v1/vmms/machines/123"

headers = {'key': 'api key'}

response = requests.request("DELETE", url, headers=headers)

print(response.text)

jQuery

GET:

Get a list of machines.

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.circumvend.com.au/api/v1/vmms/machines?record_per_page=20",
  "method": "GET",
  "headers": {
    "key": "api key"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Get machine.

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.circumvend.com.au/api/v1/vmms/machines/123",
  "method": "GET",
  "headers": {
    "key": "api key"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

POST:

Insert machine.

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.circumvend.com.au/api/v1/vmms/machines",
  "method": "POST",
  "headers": {
    "key": "api key",
    "Content-Type": "application/json"
  },
  "processData": false,
  "data": "{\n  \"serial_no\":\"testMachine\",\n  \"machine_model_id\":\"1\",\n \n  \"location_id\":\"2\",\n  \"route_id\":\"3\"\n}"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Update machine.

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.circumvend.com.au/api/v1/vmms/machines/123",
  "method": "POST",
  "headers": {
    "key": "api key",
    "Content-Type": "application/json"
  },
  "processData": false,
  "data": "{\n  \n  \"machine_model_id\":\"1\",\n  \"location_id\":\"2\",\n  \"imei\":\"testImeinumber\",\n  \"route_id\":\"3\"\n}"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

DELETE:

Delete machine.

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.circumvend.com.au/api/v1/vmms/machines/123",
  "method": "DELETE",
  "headers": {
    "key": "api key"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

Overview

How to get an API key

API limits

Header parameters

Common query parameters for HTTP GET

1. Paged results.

2. Ordering of results.

3. Retrieving a filtered set of results using the "where" parameter.

Get a list of cards

Get a card

Insert card

Header parameters

Update card

Delete card

Card top-up

Create a PIN code

Get a list of card accounts

Get a card account

Insert card account

Update card account

Get a list of card vends

Refund a vend

Get a list of locations

Get a location

Insert location

Update location

Delete location

Get a list of routes

Get a route

Insert route

Update route

Delete route

Get a list of machines

Get a machine

Insert machine

Update machine

Delete machine

Get a list of coils

Get a coil

Insert coil

Update coil

Delete coil

Get coil alarms

Get a list of machine models

Get a machine model

Get a list of users

Get a user

Insert user

Update user

Delete user

User login

Get my company details

Update my company details

Get a list of categories

Get a category

Insert category

Update category

Delete category

Get a list of brands

Get a brand

Insert brand

Update brand

Delete brand

Get a list of products

Get a product

Insert product

Update product

Delete product

Get a list of transactions

Get a list of DTUs

Get a DTU

Send a command to a DTU

Get a DTU job by job number

Header Parameters

Machine daily sales

Machine hourly sales

Get a list of alarms

Get location coordinates

General Error Response

Example Request