Beaconstac REST API documentation

Introduction

The Beaconstac API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

The Beaconstac API uses API key to authenticate requests.

Your API key carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

You can find your developer token by using the following steps.

Login to the Beaconstac dashboard.
Go to your 'Account' section using the drop-down on the top-right.
In the 'Account Details' section, copy the 'Developer Token' value.
Add a header field with key Authorization and value as Token <YOUR_TOKEN>

Reading the Documentation

Filter fields

The API supports filters on fields specified in each object collections' List request. To use the filter add the filter name along with the operator and then the value in the request params.

Filter fields supported:

exact: default. Based on exact match
icontains: Case insensitive contains
lt: less than match
gt: greater than match
lte: less than equal to match
gte: greater than equal to match

Example: If a object states that the filter arguments:

name: exact, icontains
place__name: exact, icontains

Some of the ways you can use filtering

?name='test_beacon' by default if no filter is specified for a param it defaults to exact
?name__icontains='test' case insensitive filter
?name='test_beacon'&place__name__icontains='office' Does a filter for all objects with name 'test_beacon' and who have been attached to places whose name inturn contains (case insensitive) 'office' in it

organization exact filter is supported across all objects. To get objects from all your organizations(including child organizations) use 'all' as the filter value

Searching

The API supports search filters on fields specified in each object collections' List request. To use the search filter specify the value in the request params and the response will be objects that match value with any of the search fields mentioned in the objects' List request documentation. The Searches will use case-insensitive partial matches.

Example: If a object states that the search fields supported are:

name
place__name

Some of the ways you can use filtering

?search='office' Will search both the name of the object and attached places' name objects for the text 'office' and return the results

Ordering

The API supports ordering on fields specified in each object collections' List request. To use the ordering feature specify the parameter to order by in the request params. Ordering is done in an ascending order by default.

Example: If a object states that the ordering fields supported are:

name

Some of the ways you can use filtering

?ordering='name' Will order by name by ascending order
?ordering='-name' Will order by name in decending order

Core Resources

Beacon

Beacon objects allow you to perform actions on your beacons. You can retrieve individual beacons as well as a list of all your beacons or update a beacon.

Beacon object

Attributes

Field	Type	Required	Read only	Description
`id`	`integer`	`false`	`true`	Unique identifier for the object
`name`	`string`	`true`	`false`	The name of the beacon
`UUID`	`string`	`true`	`true`	iBeacon UUID
`major`	`integer`	`true`	`true`	iBeacon major value
`minor`	`integer`	`true`	`true`	iBeacon minor value
`organization`	`integer`	`true`	`true`	Organization id
`place`	`integer`	`true`	`false`	Place id
`serial_number`	`string`	`false`	`true`	serial number
`eddystone_nid`	`string`	`false`	`true`	Eddystone namespace instance
`eddystone_bid`	`string`	`false`	`true`	Eddystone byte instance
`eddystone_url`	`string`	`false`	`true`	Eddystone URL(Deprecated)
`url`	`string`	`false`	`true`	Eddystone URL
`state`	`string`	`false`	`true`	State of the beacon (`A` Active, `S` Sleeping)
`place_data`	`list[object]`	`false`	`true`	Place data associated with place id. Only available in `List`
`tags`	`list[integer]`	`false`	`false`	List of tag ids associated
`tag_data`	`list[object]`	`false`	`true`	Tag data
`rules`	`list[integer]`	`false`	`false`	List of rule ids associated
`rule_data`	`list[object]`	`false`	`true`	Rule data
`mode`	`string`	`false`	`true`	Mode of the beacon
`tx_power`	`integer`	`false`	`false`	Transmission power
`advertising_interval`	`integer`	`false`	`false`	Advertising interval
`battery`	`integer`	`false`	`false`	Battery
`temperature`	`integer`	`false`	`false`	Temperature
`latitude`	`float`	`false`	`false`	Latitude
`longitude`	`float`	`false`	`false`	Longitude
`closeby_id`	`integer`	`false`	`true`	Closeby ID of the beacon(Deprecated)
`nearby_id`	`string`	`false`	`true`	Proximity ID of the beacon
`temperature`	`integer`	`false`	`false`	Temperature
`proximity_status`	`string`	`false`	`true`	Proximity status (Deprecated)
`meta`	`object`	`false`	`false`	Metadata associated with the beacon
`deployment_meta`	`object`	`false`	`false`	Deployment meta
`kit_type`	`object`	`false`	`true`	Beacon kit type (Deprecated)
`created`	`timestamp`	`false`	`true`	Created timestamp
`updated`	`timestamp`	`false`	`true`	Last updated timestamp
`heartbeat`	`timestamp`	`false`	`true`	Timestamp when the beacon was last detected
`campaign`	`Campaign`	`false`	`false`	`Campaign` object
`notifications`	`list[CampaignNotification]`	`false`	`false`	`CampaignNotification` object

Campaign object

Attributes

Field	Type	Required	Read only	Description
`id`	`integer`	`false`	`true`	Unique identifier for the object
`content_type`	`integer`	`true`	`false`	Campaign Type (0 for 'No campaign')
`custom_url`	`URL`	`true` if `content_type` is 1	`false`	Custom URL
`markdown_card`	`integer`	`true` if `content_type` is 2	`false`	Markdown card
`form`	`integer`	`true` if `content_type` is 3	`false`	Form
`schedule`	`integer`	`true` if `content_type` is 4	`false`	Schedule
`campaign_active`	`boolean`	`false`	`true`	Current campaign status
`organization`	`integer`	`false`	`true`	Organization
`created`	`timestamp`	`false`	`true`	Created timestamp
`updated`	`timestamp`	`false`	`true`	Last updated timestamp

Campaign Notification object

Attributes

Field	Type	Required	Read only	Description
`id`	`integer`	`false`	`true`	Unique identifier for the object
`language_code`	`string`	`true`	`false`	ISO 639-1 language code. Each beacon can have only 1 language notification.
`is_default`	`boolean`	`true`	`false`	Is default notification. Each beacon can have only one notification set as default.
`title`	`string`	`false`	`false`	Title of the notification (max 49 characters)
`description`	`string`	`false`	`false`	Description on the notification (max 2048 characters)
`icon_url`	`URL`	`false`	`false`	Icon URL
`app_intent`	`string`	`false`	`false`	App intent
`banner_type`	`integer`	`false`	`false`	Banner type for NearBee
`banner_image_url`	`string`	`false`	`false`	Banner Image URL for NearBee
`meta`	`object`	`false`	`false`	Metadata
`slug`	`string`	`false`	`true`	Slug for the notification
`created`	`timestamp`	`false`	`true`	Created timestamp
`updated`	`timestamp`	`false`	`true`	Last updated timestamp

List beacons

Returns a list of your beacons. The beacons are returned sorted by beacon heartbeat, with the most recent detected beacons appearing first.

GET https://api.beaconstac.com/api/2.0/beacons/

Filter arguments:

name: exact, icontains
serial_number: exact, icontains
place__name: exact, icontains
tags__name: exact, icontains
url: exact
heartbeat: lt, lte, gt, gte
campaign__content_type: exact
state: exact

Search Fields:

name
serial_number
place__name
tags__name
url
campaign__content_type

Ordering fields:

name
serial_number
battery
heartbeat: default
place__name
created
updated
campaign__content_type
state

Retrieve a beacon

Retrieves the details of an existing beacon. You need only supply the unique beacon identifier that was returned upon beacon listing.

GET https://api.beaconstac.com/api/2.0/beacons/{beacon_id}

Update beacon

Updates the specified beacon by setting the values of the parameters passed. Any parameters not provided will be left unchanged. However, the request should contain the required fields. Please refer to the Beacon object.

PUT https://api.beaconstac.com/api/2.0/beacons/{beacon_id}

Example: Changing campaign to a Markdown Card

{
    "id": 1189,
    "campaign": {
        "id": 223,
        "custom_url": "https://beaconstac.com",
        "content_type": 2,
        "campaign_active": true,
        "organization": 1284,
        "markdown_card": 434,
        "form": 7099,
        "schedule": null
    },
    "name": "Corner_",
    "url": "https://eddy.pro/f78WrG",
    "UUID": "F94DBB23-2266-7822-3782-57BEAC0952AC",
    "major": 16,
    "minor": 10,
    "serial_number": "0117C53F26D6",
    "eddystone_nid": "5DC33487F02E477D4058",
    "eddystone_bid": "0117C53F26D6",
    "place": 1929
}

NFC Tag

NFCTag objects allow you to perform actions on your NFC Tags. You can retrieve individual nfc tags as well as a list of all your tags or update a tag.

NFC Tag object

Attributes

Field	Type	Required	Read only	Description
`id`	`integer`	`false`	`true`	Unique identifier for the object
`name`	`string`	`true`	`false`	The name of the NFC Tag
`uid`	`string`	`true`	`true`	NFC Tag UID
`counter`	`integer`	`false`	`true`	NFC Tag counter. Counts the number of times the tag has been read
`organization`	`integer`	`true`	`true`	Organization id
`place`	`integer`	`true`	`false`	Place id
`url`	`string`	`false`	`true`	NFC Tag URL
`state`	`string`	`false`	`true`	State of the NFC Tag (`A` Active, `S` Sleeping)
`place_data`	`list[object]`	`false`	`true`	Place data associated with place id. Only available in `List`
`tags`	`list[integer]`	`false`	`false`	List of tag ids associated
`tag_data`	`list[object]`	`false`	`true`	Tag data
`meta`	`object`	`false`	`false`	Metadata associated with the NFC Tag
`created`	`timestamp`	`false`	`true`	Created timestamp
`updated`	`timestamp`	`false`	`true`	Last updated timestamp
`heartbeat`	`timestamp`	`false`	`true`	Timestamp when the NFC Tag was last detected
`campaign`	`Campaign`	`false`	`false`	`Campaign` object

List NFC Tags

Returns a list of your NFC Tags. The tags are returned sorted by updated, with the most recently updated tags appearing first.

GET https://api.beaconstac.com/api/2.0/nfctags/

Filter arguments:

name: exact, icontains
place__name: exact, icontains
tags__name: exact, icontains
url: exact
campaign__content_type: exact
state: exact

Search Fields:

name
place__name
tags__name
url
campaign__content_type

Ordering fields:

name
place__name
created
updated - default
campaign__content_type
state

Retrieve an NFC Tag

Retrieves the details of an existing NFC Tag. You need only supply the unique NFC Tag identifier that was returned upon tags listing.

GET https://api.beaconstac.com/api/2.0/nfctags/{nfctag_id}

Update an NFC Tag

Updates the specified NFC Tag by setting the values of the parameters passed. Any parameters not provided will be left unchanged. However, the request should contain the required fields. Please refer to the NFCTag object.

PUT https://api.beaconstac.com/api/2.0/nfctags/{nfctag_id}

Example: Changing campaign to a Markdown Card

{
    "id": 1189,
    "campaign": {
        "id": 223,
        "custom_url": "https://beaconstac.com",
        "content_type": 2,
        "campaign_active": true,
        "organization": 1284,
        "markdown_card": 434,
        "form": 7099,
        "schedule": null
    },
    "name": "Corner",
    "url": "https://nfc.tapnscan.me/f78WrG",
    "uid": "abc",
    "place": 1929
}

QR Code

QRCode objects allow you to perform actions on your QR Codes. You can retrieve individual QR Codes as well as a list of all your qr codes or update a QR Code.

QR Code object

Attributes

Field	Type	Required	Read only	Description
`id`	`integer`	`false`	`true`	Unique identifier for the object
`name`	`string`	`true`	`false`	The name of the qr code
`fields_data`	`object`	`true`	`false`	Fields data for the QR Code
`attributes`	`object`	`true`	`false`	Attributes data for the QR Code
`qr_type`	`integer`	`false`	`false`	QR type (`1` Static, `2` Dynamic)
`organization`	`integer`	`true`	`true`	Organization id
`place`	`integer`	`true`	`false`	Place id
`url`	`string`	`false`	`true`	QR code URL
`state`	`string`	`false`	`true`	State of the QR Code (`A` Active, `S` Sleeping)
`place_data`	`list[object]`	`false`	`true`	Place data associated with place id. Only available in `List`
`tags`	`list[integer]`	`false`	`false`	List of tag ids associated
`tag_data`	`list[object]`	`false`	`true`	Tag data
`meta`	`object`	`false`	`false`	Metadata associated with the QR Code
`created`	`timestamp`	`false`	`true`	Created timestamp
`updated`	`timestamp`	`false`	`true`	Last updated timestamp
`heartbeat`	`timestamp`	`false`	`true`	Timestamp when the qr code was last detected
`campaign`	`Campaign`	`false`	`false`	`Campaign` object

List QR Codes

Returns a list of your QR Codes. The tags are returned sorted by updated, with the most recently updated qr codes appearing first.

GET https://api.beaconstac.com/api/2.0/qrcodes/

Filter arguments:

name: exact, icontains
place__name: exact, icontains
tags__name: exact, icontains
url: exact
campaign__content_type: exact
state: exact

Search Fields:

name
place__name
tags__name
url
campaign__content_type

Ordering fields:

name
place__name
created
updated - default
campaign__content_type
state

Retrieve a QR Code

Retrieves the details of an existing qr code. You need only supply the unique qr code identifier that was returned upon qr codes listing.

GET https://api.beaconstac.com/api/2.0/qrcodes/{qrcode_id}

Update a QR Code

Updates the specified qr code by setting the values of the parameters passed. Any parameters not provided will be left unchanged. However, the request should contain the required fields. Please refer to the QRCode object.

PUT https://api.beaconstac.com/api/2.0/qrcodes/{qrcode_id}

Example: Changing campaign to a Markdown Card

{
    "id": 1189,
    "campaign": {
        "id": 223,
        "custom_url": "https://beaconstac.com",
        "content_type": 2,
        "campaign_active": true,
        "organization": 1284,
        "markdown_card": 434,
        "form": 7099,
        "schedule": null
    },
    "name": "Corner",
    "url": "https://qr.tapnscan.me/f78WrG",
    "organization": 1284
}

Create a QR Code

Creates a new QR Code. However, the request should contain the required fields. Please refer to the QRCode object.

POST https://api.beaconstac.com/api/2.0/qrcodes/

Example for creating QRCode with campaign set to a Markdown Card:

{
    "attributes": {
        "color": "#000000",
        "margin": "",
        "backgroundImage": "",
        "logoImage": "https://static.beaconstac.com/assets/img/qr-code-logos/calender.svg"
    },
    "name": "test 3",
    "qr_type": 2,
    "organization": 1284,
    "place": 23,
    "campaign": {
        "content_type": 2,
        "markdown_card": 34918
    }
}

Example for creating QRCode with campaign set to a Form:

{
    "attributes": {
        "color": "#000000",
        "margin": "",
        "backgroundImage": "",
        "logoImage": "https://static.beaconstac.com/assets/img/qr-code-logos/calender.svg"
    },
    "name": "test 3",
    "qr_type": 2,
    "organization": 1284,
    "place": 23,
    "campaign": {
        "content_type": 3,
        "form": 36092
    }
}

Example for creating dynamic QRCode of type vCard:

Create editable Dynamic vCard QR Codes for employees

{
    "name": "Dynamic vCard QR Code",
    "qr_type": 2,
    "organization": 1284,
    "attributes": {
        "color": "#fb6e6e",
        "margin": 25,
        "logoImage": "https://d1bqobzsowu5wu.cloudfront.net/15406/36caec11f02d460aad0604fa26799c50"
    },
    "campaign": {
        "content_type": 7,
        "vcard_plus": {
            "first_name": "John",
            "last_name": "Doe",
            "user_image_url": "https://d3nvy39jvu7woe.cloudfront.net/static/images/default_vcard_image.png",
            "designation": "Android Developer",
            "company": "Mobstac Inc.",
            "summary": "Hello there!!!!",
            "phone": {
                "mobile": "9876543210",
                "work": "9012345678"
            },
            "email": "john_doe@example.com",
            "address_line1": "#316 Mobstac",
            "address_line2": "Indiranagar",
            "city": "Bengaluru",
            "zip": "560038",
            "country": "India",
            "address_url": "https://www.google.com/maps/search/?api=1&query=12.9764566,77.6020364&query_place_id=ChIJt-8HuakWrjsRUNukdoGH8Es",
            "website": "https://www.example.com",
            "logo_url": "https://d1bqobzsowu5wu.cloudfront.net/15406/36caec11f02d460aad0604fa26799c50",
            "customizations": {
                "background_color": "#2594FF",
                "user_info_color": "#FFFFFF"
            }
        }
    }
}

Example for creating dynamic QRCodes pointed to PDF files:

Point your QR Code to PDF files so that users can easily access the contents from their phone.

a) Download PDF to user's device

{
    "name": "my PDF QR Code",
    "qr_type": 1,
    "organization": 1284,
    "attributes": {
        "color": "#000000",
        "margin": 25,
        "logoImage": "https://d1bqobzsowu5wu.cloudfront.net/15406/36caec11f02d460aad0604fa26799c50"
    },
    "campaign": {
        "content_type": 13,
        "pdf": {
            "files": [
                {
                    "url": "https://drive.google.com/file/d/1f0WF96qlqYhMvYg1qCDUBi-5Jg-NX9E6/view?usp=sharing",
                    "name": "Enterprise QR Code solution"
                }
            ],
            "uploaded": false
        }
    }
}

b) View PDF directly on the browser

{
    "name": "my PDF QR Code",
    "qr_type": 1,
    "organization": 1284,
    "attributes": {
        "color": "#000000",
        "margin": 25,
        "logoImage": "https://d1bqobzsowu5wu.cloudfront.net/15406/36caec11f02d460aad0604fa26799c50"
    },
    "campaign": {
        "content_type": 13,
        "pdf": {
            "files": [
                {
                    "url": "https://d1bqobzsowu5wu.cloudfront.net/15406/877ea8ec987e4587be463f23a1e39092",
                    "name": "Enterprise QR Code Solution"
                }
            ],
            "uploaded": true
        }
    }
}

** Note: For best results on PDF QR Codes that can be directly viewed on the viewer's browser(type (b)), use PDF files uploadedto Beaconstac.

Example for creating dynamic QRCode for coupons:

Make Coupon QR Codes to offer discounts and deals to your consumers to improve conversions and generate leads. Place these in-store or on print or digital material to maximize your ROI.

{
    "name": "Coupon QR Code",
    "qr_type": 1,
    "organization": 1284,
    "attributes": {
        "color": "#000000",
        "margin": 25,
        "logoImage": "https://d1bqobzsowu5wu.cloudfront.net/15406/36caec11f02d460aad0604fa26799c50"
    },
    "campaign": {
        "content_type": 10,
        "coupon": {
            "coupon_code": "ABCD1234",
            "header": "Flat 25% off",
            "expires_at": "2020-10-24T00:00:00+05:30",
            "timezone": "America/New_York",
            "message": "Big sale at Beaconstac stores",
            "company_name": "Mobstac Inc.",
            "terms_and_conditions": "read T&C carefully",
            "description_header": "Big Holiday sale",
            "description_body": "Enjoy the biggest holiday sale",
            "location": "https://www.google.com/maps/search/?api=1&query=12.9764566,77.6020364&query_place_id=ChIJt-8HuakWrjsRUNukdoGH8Es",
            "website": "https://www.example.com",
            "logo_url": "https://d1bqobzsowu5wu.cloudfront.net/15406/36caec11f02d460aad0604fa26799c50",
            "customizations": {
                "background_color": "#199087",
                "coupon_color": "#FFFFFF",
                "coupon_color": "#FFFFFF",
                "header_color": "#59C65D"
            }
        }
    }
}

Download a QR code

Download a QR code in a particular size and image format. Image types supported are PNG, JPEG, SVG and PDF. If no canvas type is sent in the parameters, the QRCode would be generated in all image types supported.

GET https://api.beaconstac.com/api/2.0/qrcodes/{qrcode_id}/download/?size={size}&canvas_type={canvas_type}

Example: Download the QRCode of size 1024x1024 pixels in SVG format. GET https://api.beaconstac.com/api/2.0/qrcodes/100/download/?size=1024&canvas_type=svg

{
    "svg": "url.svg"
}

( For detailed QR Code API documentation please refer: https://www.beaconstac.com/qr-code-generator-api )

Bulk QR Codes

BulkQRCode objects allow you to create a collection of multiple QR Codes from a CSV file in a single request. You can list, retreive, create or download a Bulk QR Code collection.

Obtain your AuthorizationToken from the Beaconstac dashboard

Bulk QR Code object

Attributes

Field	Type	Required	Read only	Description
`id`	`integer`	`false`	`true`	Unique identifier for the object
`name`	`string`	`true`	`false`	The name of the Bulk QR code collection
`media`	`integet`	`false`	`true`	Media ID
`media_data`	`object`	`false`	`false`	Media data associated with media ID
`attributes`	`object`	`true`	`false`	Attributes/Design data for the QR Codes being created
`qr_type`	`integer`	`false`	`true`	QR type (`1`)
`qr_data_type`	`integer`	`true`	`false`	QR data type (`1` Website, `2` SMS, `3` Phone, `4` email, `5` vCard, `6` text)
`organization`	`integer`	`true`	`true`	Organization ID
`storage_url`	`string`	`false`	`true`	QR code URL
`created`	`timestamp`	`false`	`true`	Created timestamp
`updated`	`timestamp`	`false`	`true`	Last updated timestamp

List Bulk QR Code collections

Returns a list of your QR Codes. The tags are returned sorted by updated, with the most recently updated qr codes appearing first.

Example:

Use the below cURL command to list all Bulk QR Code collections in your account:

curl --location --request GET 'https://api.beaconstac.com/api/2.0/bulkqrcodes/' \
--header 'Authorization: Token <AuthorizationToken>'

Filter arguments:

name: exact, icontains
qr_data_type: exact

Search Fields:

name

Ordering fields:

name
created
updated - default

Retrieve a Bulk QR Code collection

Retrieves the details of an existing Bulk QR Code collection. You need only supply the unique Bulk QR Code identifier that was returned upon listing.

Example:

Use the below cURL command to retreive a single Bulk QR Code collection by id.

curl --location --request GET 'https://api.beaconstac.com/api/2.0/bulkqrcodes/101/' \
--header 'Authorization: Token <AuthorizationToken>'

CSV file data format

The examples for the CSV files can be viewed from the Beaconstac dashboard or from the CSV Files in the links below:

QR Data type	Example CSV File
`1` (Website)	https://admin.beaconstac.com/assets/files/static-website-csv.csv
`2` (Phone)	https://dashboard.beaconstac.com/assets/files/static-phone-csv.csv
`3` (SMS)	https://dashboard.beaconstac.com/assets/files/static-sms-csv.csv
`4` (Email)	https://dashboard.beaconstac.com/assets/files/static-email-csv.csv
`5` (vCard)	https://dashboard.beaconstac.com/assets/files/static-vcard-csv.csv
`6` (Text)	https://dashboard.beaconstac.com/assets/files/static-text-csv.csv

Create a Bulk QR Code collection

Creates a new Bulk QR Code collection using data from CSV file. However, the request should contain the required fields.

Example:

Create a Bulk QR Code collection by using the cURL request:

curl --location --request POST 'https://api.beaconstac.com/api/2.0/bulkqrcodes/' \
--header 'Authorization: Token e62435a78e67ec98bba3b879ba00448650032557' \
--header 'Content-Type: multipart/form-data' \
--form 'file=@/Users/hariprasad/Desktop/bulk-qr-sample-csv/static-vcard-csv.csv' \
--form 'name=myvCard-QRCodes' \
--form 'qr_type=1' \
--form 'size=512' \
--form 'error_correction_level=0' \
--form 'qr_data_type=5' \
--form 'attributes={"color":"#ab578f",
"gradientType":"radial",
 "margin": 50,
"dataPattern":"left-diamond",
"eyeBallShape":"left-diamond",
"eyeFrameShape":"left-leaf",
"eyeBallColor":"#ea8745",
"eyeFrameColor":"#ea4587",
"logoImage": "https://static.beaconstac.com/assets/img/qr-code-logos/instagram.svg",
"frameStyle":"banner-top"
}' \
--form 'organization=720'

Response

{
    "id": 220,
    "attributes": {
        "color": "#ab578f",
        "gradientType": "radial",
        "margin": 50,
        "dataPattern": "left-diamond",
        "eyeBallShape": "left-diamond",
        "eyeFrameShape": "left-leaf",
        "eyeBallColor": "#ea8745",
        "eyeFrameColor": "#ea4587",
        "logoImage": "https://static.beaconstac.com/assets/img/qr-code-logos/instagram.svg",
        "frameStyle": "banner-top"
    },
    "media_data": {
        "id": 68976,
        "name": "myvCard-QRCodes",
        "url": "https://d1bqobzsowu5wu.cloudfront.net/720/6d69b10e8e794beb920c7a899cf6d044"
    },
    "name": "myvCard-QRCodes",
    "storage_url": "https://d1bqobzsowu5wu.cloudfront.net/720/bulkqr/MjIwLTIwMjAtMDUtMTNUMTQ6MTY6NDAuNDY1ODI2KzAwOjAw.zip",
    "qr_type": 1,
    "qr_data_type": 5,
    "created": "2020-05-13T19:46:40.465826+05:30",
    "updated": "2020-05-13T19:46:50.948362+05:30",
    "organization": 720,
    "media": 68976
}

The QR Code designs can be customized by varying the attributes of the Bulk QR Code object. More details can be accessed here

Download Bulk QR code collection

The Bulk QR Code collection can be downloaded using the link from the storage_url ( Ex. https://d1bqobzsowu5wu.cloudfront.net/720/bulkqr/MjE5LTIwMjAtMDUtMTNUMTQ6MDA6MDkuODgwMTYzKzAwOjAw.zip ) field.

The URL downloads a zipped collection of the images in 4 formats: png, jpeg, pdf, svg.

Update an existing Bulk QR Code collection

You can update an existing Bulk QR Code collection with different design data using the unique ID field of the Bulk QR Code object. (Note: The csv file attached with a collection cannot be updated)

Example:

Update a Bulk QR Code collection by using the cURL request:

Request:

curl --location --request PUT 'https://api.beaconstac.com/api/2.0/bulkqrcodes/220/' \
--header 'Authorization: Token e62435a78e67ec98bba3b879ba00448650032557' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "id": 220,
    "attributes": {
        "color": "#2595ff",
        "gradientType": "radial",
        "margin": 50,
        "dataPattern": "left-diamond",
        "eyeBallShape": "left-diamond",
        "eyeFrameShape": "left-leaf",
        "eyeBallColor": "#2595ff",
        "eyeFrameColor": "#95ff25",
        "logoImage": "https://static.beaconstac.com/assets/img/qr-code-logos/instagram.svg",
        "frameStyle": "banner-bottom"
    },
    "media_data": {
        "id": 68976,
        "name": "myvCard-QRCodes",
        "url": "https://d1bqobzsowu5wu.cloudfront.net/720/6d69b10e8e794beb920c7a899cf6d044"
    },
    "name": "myvCard-QRCodes",
    "storage_url": "https://d1bqobzsowu5wu.cloudfront.net/720/bulkqr/MjIwLTIwMjAtMDUtMTNUMTQ6MTY6NDAuNDY1ODI2KzAwOjAw.zip",
    "qr_type": 1,
    "qr_data_type": 5,
    "created": "2020-05-13T19:46:40.465826+05:30",
    "updated": "2020-05-13T19:46:50.948362+05:30",
    "organization": 720,
    "media": 68976
}'

Response

{
    "id": 220,
    "attributes": {
        "color": "#2595ff",
        "gradientType": "radial",
        "margin": 50,
        "dataPattern": "left-diamond",
        "eyeBallShape": "left-diamond",
        "eyeFrameShape": "left-leaf",
        "eyeBallColor": "#2595ff",
        "eyeFrameColor": "#95ff25",
        "logoImage": "https://static.beaconstac.com/assets/img/qr-code-logos/instagram.svg",
        "frameStyle": "banner-bottom"
    },
    "media_data": {
        "id": 68977,
        "name": "myvCard-QRCodes",
        "url": "https://d1bqobzsowu5wu.cloudfront.net/720/45b9ef3414d541e88c6cae514aea454e"
    },
    "name": "myvCard-QRCodes",
    "storage_url": "https://d1bqobzsowu5wu.cloudfront.net/720/bulkqr/MjIwLTIwMjAtMDUtMTNUMTQ6MTY6NDAuNDY1ODI2KzAwOjAw.zip",
    "qr_type": 1,
    "qr_data_type": 5,
    "created": "2020-05-13T19:46:40.465826+05:30",
    "updated": "2020-05-13T19:49:44.578320+05:30",
    "organization": 720,
    "media": 68977
}

Geofence

Geofence objects allow you to perform actions on your geofences. You can retrieve individual geofences as well as a list of all your geofences or update a geofence.

Geofence object

Attributes

Field	Type	Required	Read only	Description
`id`	`integer`	`false`	`true`	Unique identifier for the object
`name`	`string`	`true`	`false`	The name of the geofence
`latitude`	`float`	`true`	`false`	Latitude
`longitude`	`float`	`true`	`false`	Longigtude
`radius`	`integer`	`true`	`false`	Radius of the geofence
`organization`	`integer`	`true`	`true`	Organization id
`place`	`integer`	`true`	`false`	Place id
`url`	`string`	`false`	`true`	Geofence URL
`state`	`string`	`false`	`true`	State of the geofence (`A` Active, `S` Sleeping)
`place_data`	`list[object]`	`false`	`true`	Place data associated with place id. Only available in `List`
`tags`	`list[integer]`	`false`	`false`	List of tag ids associated
`tag_data`	`list[object]`	`false`	`true`	Tag data
`meta`	`object`	`false`	`false`	Metadata associated with the geofence
`created`	`timestamp`	`false`	`true`	Created timestamp
`updated`	`timestamp`	`false`	`true`	Last updated timestamp
`heartbeat`	`timestamp`	`false`	`true`	Timestamp when the geofence was last detected
`campaign`	`Campaign`	`false`	`false`	`Campaign` object
`notifications`	`list[CampaignNotification]`	`false`	`false`	`CampaignNotification` object

List Geofences

Returns a list of your Geofences. The Geofences are returned sorted by updated, with the most recently updated Geofence appearing first.

GET https://api.beaconstac.com/api/2.0/geofences/

Filter arguments:

name: exact, icontains
place__name: exact, icontains
url: exact
campaign__content_type: exact
state: exact

Search Fields:

name
place__name
url
campaign__content_type

Ordering fields:

name
place__name
created
updated - default
campaign__content_type
state

Retrieve a Geofence

Retrieves the details of an existing Geofence. You need only supply the unique Geofence identifier that was returned upon Geofence listing.

GET https://api.beaconstac.com/api/2.0/geofences/{geofence_id}

Update Geofence

Updates the specified Geofence by setting the values of the parameters passed. Any parameters not provided will be left unchanged. However, the request should contain the required fields. Please refer to the Geofence object.

PUT https://api.beaconstac.com/api/2.0/geofences/{geofence_id}

Example: Changing campaign to a Markdown Card

{
    "id": 1189,
    "campaign": {
        "id": 223,
        "custom_url": "https://beaconstac.com",
        "content_type": 2,
        "campaign_active": true,
        "organization": 1284,
        "markdown_card": 434,
        "form": 7099,
        "schedule": null
    },
    "name": "Corner",
    "url": "https://geo.tapnscan.me/f78WrG",
    "place": 1929,
    "latitude": 12.21343,
    "longitude": 12.213132,
    "radius": 100
}

Create Geofence

Creates a new geofence by setting the values of the parameters passed. The request should contain the required fields. Please refer to the Geofence object.

POST https://api.beaconstac.com/api/2.0/geofences/

Example: Create Geofence with campaign to a Markdown Card

{
    "campaign": {
        "id": 223,
        "custom_url": "https://beaconstac.com",
        "content_type": 2,
        "campaign_active": true,
        "organization": 1284,
        "markdown_card": 434,
        "form": 7099,
        "schedule": null
    },
    "name": "Corner",
    "place": 1929,
    "latitude": 12.21343,
    "longitude": 12.213132,
    "radius": 100,
    "organization": 1234
}

Place

Place objects allow you to view all places in your account and view beacons attached to them.

Place object

Attributes

Field	Type	Required	Read only	Description
`id`	`integer`	`false`	`true`	Unique identifier for the object
`name`	`string`	`true`	`false`	The name of the place
`organization`	`integer`	`true`	`true`	Organization id
`latitude`	`float`	`false`	`false`	Latitude
`longitude`	`float`	`false`	`false`	Longitude
`place_id`	`string`	`false`	`false`	Google Place ID
`address`	`string`	`false`	`false`	Address of the place
`beacons`	`list[object]`	`false`	`true`	Beacon data associated with place id. Only available in `List`
`beacon_count`	`integer`	`false`	`true`	Beacon count
`default_place`	`boolean`	`false`	`true`	Indicated whether the place is a default place
`business_icon_url`	`string`	`false`	`false`	Business Icon URL (Used in NearBee)
`business_cover_url`	`string`	`false`	`false`	Business Cover URL(Used in NearBee)
`business_color`	`string`	`false`	`false`	Business Color(Used in NearBee)
`created`	`timestamp`	`false`	`true`	Created timestamp
`updated`	`timestamp`	`false`	`true`	Last updated timestamp

List Places

Returns a list of your beacons. The beacons are returned sorted by beacon heartbeat, with the most recent detected beacons appearing first.

GET https://api.beaconstac.com/api/2.0/places/

Filter arguments:

name: exact, icontains

Search Fields:

name

Ordering fields:

name
created
updated - default
address

Retrieve a Place

Retrieves the details of an existing Place. You need only supply the unique Place identifier that was returned upon Place listing.

GET https://api.beaconstac.com/api/2.0/places/{place_id}

Update Place

Updates the specified Place by setting the values of the parameters passed. Any parameters not provided will be left unchanged. However, the request should contain the required fields. Please refer to the Place object.

PUT https://api.beaconstac.com/api/2.0/places/{place_id}

Example: Update an existing place based on ID of the place

{
	"organization": 1234,
	"name": "Mobstac, New York",
	"address": "450 Lexington Avenue, 4th Floor New York, NY 10017",
	"latitude": "40.73",
	"longitude": "-73.94"
}

Create Place

Creates a new place in your account by setting the values of the parameters passed. The request should contain the required fields. Please refer to the Place object.

POST https://api.beaconstac.com/api/2.0/places/

Example: Create a new Place

{
    "organization": 1234,
    "name": "Mobstac, Bangalore",
    "address": "MobStac,2nd floor, Mayfair Building, Karnataka, 316, 100 Feet Rd, Binnamangala, Stage 1, Indiranagar, Bengaluru, Karnataka 560038, India",
    "latitude": 12.9818683,
    "longitude": 77.6404921999999
}

User

User objects allow you to perform actions on the users in your account. You can list of all your users, retrieve individual users, create a user or update a user.

(Note: Creation of Users is supported only on Reseller plan and above)

User object

Attributes

Field	Type	Required	Read only	Description
`id`	`integer`	`false`	`true`	Unique identifier for the object
`username`	`string`	`true`	`false`	The username used to login
`organization`	`integer`	`true`	`true`	Organization id
`first_name`	`string`	`false`	`false`	First name of the user
`last_name`	`string`	`false`	`false`	Last name of the user
`email`	`string`	`false`	`false`	email of the user
`customer_plan`	`string`	`false`	`false`	Customer Plan the User is subscribed to (`ST` Starter, `LT` Lite, `BA` Basic, `PR` Premium, `RE` Reseller, `WL` Whitelabel, `EN` Enterprise)
`subscription_state`	`string`	`false`	`false`	Subscription state of the user (`A` Active, `E` Expired, `R` Removed)
`user_group`	`string`	`false`	`false`	User group the user belongs to (`OW` Owner, `AD` Admin, `RO` Read-Only)
`profile_picture`	`string`	`false`	`false`	URL to the User's profile picture
`billing_email`	`string`	`false`	`false`	User email used for billing
`firebase_token`	`string`	`false`	`false`	User firebase token used to send Notifications
`is_active`	`boolean`	`false`	`true`	User active status
`is_superuser`	`boolean`	`false`	`true`	Superuser status
`stripe_id`	`string`	`false`	`false`	Stripe ID of the user
`shopify_id`	`integer`	`false`	`false`	Shopify ID for the user
`date_joined`	`timestamp`	`false`	`true`	Date joined timestamp
`created`	`timestamp`	`false`	`true`	Created timestamp
`updated`	`timestamp`	`false`	`true`	Last updated timestamp

(Note: Stripe ID and Shopify ID will be null for all users with user groups AD and RO)

List Users

Returns a list of all Users. The users are returned sorted by date joined, with the most recently joined users appearing first.

GET https://api.beaconstac.com/api/2.0/users/

Filter arguments:

first_name: exact, icontains
last_name: exact, icontains
username: exact, icontains
email: exact, icontains
organization id: exact
date_joined: lt, lte, gt, gte
customer_plan: exact
subscription_state: exact

Search Fields:

username
email
user_group
first_name
last_name

Ordering fields:

username
email
date_joined - default
user_group
first_name
last_name

Retrieve a User

Retrieves the details of an existing user. You need to supply the unique user identifier that was returned upon listing.

GET https://api.beaconstac.com/api/2.0/users/{user_id}

Create a new User

Creates a new user. However, the request should contain the required fields. New users can be created only by users having customer

POST https://api.beaconstac.com/api/2.0/users/

Example: Create a new user User in an organization.

{
      "username": "sample_user",
      "customer_plan": "PR",
      "first_name": "Sample",
      "last_name": "User",
      "email": "sample_user@beaconstac.com",
      "billing_email": "billing@beaconstac.com",
      "organization": 1284,
      "profile_picture": "https://d1bqobzsowu5wu.cloudfront.net/720/93f7199471e64ddb9ad4e8bb888bb1ce",
      "password": "testPassword123"
}

(Note: User password is set to default password if no password is passed)

Update an existing User

Creates a new user. However, the request should contain the required fields. New users can be created only by users having customer

POST https://api.beaconstac.com/api/2.0/users/{user_id}

Example: Create a new user User in an organization.

{
    "first_name": "John",
    "last_name": "Doe",
    "profile_picture": "https://d1bqobzsowu5wu.cloudfront.net/2934/cf50e4abe1724089a7dd8bc60dbe8977",
    "organization": 1284
}

Partner API endpoints

Creating user accounts in the Beaconstac store

Beaconstac Analytics

Product

Product types:

beacon
nfc
qr
geofence

from, to parameters should be in EPOCH milliseconds.

Product overview

Get analytics overview for the product type over the time interval.

POST https://api.beaconstac.com/reporting/2.0/?organization={organization_id}&method=Products.getOverview

Example: Get performance for all beacons in organization ID 23 POST https://api.beaconstac.com/reporting/2.0/?organization=23&method=Products.getOverview

Request body:

{
    "product_type": "beacon",
    "from": 1559273172,
    "to": 1559283172
}

Product performance

Get analytics performace for the product.

POST https://api.beaconstac.com/reporting/2.0/?organization={organization_id}&method=Products.getPerformance

Example: Get performance for nfc tag POST https://api.beaconstac.com/reporting/2.0/?organization=23&method=Products.getPerformance

Request body:

{
    "product_type": "nfc",
    "product_id": 12,
    "from": 1559273172,
    "to": 1559283172,
    "interval": "1d",
    "timezone": "UTC"
}

Product impressions

Get impressions generated by the product. If no place is provided data will be returned for all products of the product type specified in the organization.

POST https://api.beaconstac.com/reporting/2.0/?organization={organization_id}&method=Products.getImpressions

Example: Get impression for all qr codes in place id 12 POST https://api.beaconstac.com/reporting/2.0/?organization=23&method=Products.getImpressions

Request body:

{
    "product_type": "qr",
    "place": 12,
    "from": 1559273172,
    "to": 1559283172,
    "interval": "1d",
    "timezone": "UTC"
}

Product impression detail

Get impressions details generated by the product. If no place is provided data will be returned for all products of the product type specified in the organization.

POST https://api.beaconstac.com/reporting/2.0/?organization={organization_id}&method=Products.getImpressionDetail

Example: Get impression details for all qr codes in place id 12 POST https://api.beaconstac.com/reporting/2.0/?organization=23&method=Products.getImpressionDetail

Request body:

{
    "product_type": "qr",
    "place": 12,
    "from": 1559273172,
    "to": 1559283172
}

Product impression distribution

Get impression distribution generated by the product. If no place is provided data will be returned for all products of the product type specified in the organization.

POST https://api.beaconstac.com/reporting/2.0/?organization={organization_id}&method=Products.getImpressionDistribution

Example: Get impression distribution for all qr codes in place id 12 POST https://api.beaconstac.com/reporting/2.0/?organization=23&method=Products.getImpressionDistribution

Request body:

{
    "product_type": "qr",
    "place": 12,
    "from": 1559273172,
    "to": 1559283172
}

Generate product CSV data

Generate a detailed CSV report for products in the specified organizations. The report will be emailed to the user email mentioned in the POST body. If not email is specified it would be emailed to the user making the request.

POST https://api.beaconstac.com/reporting/2.0/?organization={organization_id}&method=Products.getImpressionDistribution

Example: Generate CS impression distribution for qr codes 23 and 43 in organizations 1 and 2. POST https://api.beaconstac.com/reporting/2.0/?method=Csv.getProductData

Request body:

{
    "product_type": "qr",
    "organization_ids": [1, 2],
    "product_ids": [23, 43],
    "from": 1559273172,
    "to": 1559283172,
    "timezone": "UTC"
}

Get analytics overview for a given period

Get analytics overview (product count, notification count, impression count, conversion percentage) of your product based on product type being passed. The total number of unique visitors is also given in the response.

POST https://api.beaconstac.com/reporting/2.0/?organization={organization_id}&method=Overview.getPeriodOverview

Example: Generate analytics overview of all products over a period of time.

POST https://api.beaconstac.com/reporting/2.0/?organization={organization_id}&method=Overview.getPeriodOverview

Request body:

{
	"from": "1567535400000",
	"to": "1582482600000",
	"product_type": "geofence",
	"organization": 1234
}

Name		Name	Last commit message	Last commit date
Latest commit History 72 Commits
lib		lib
older		older
source		source
.editorconfig		.editorconfig
.gitignore		.gitignore
.travis.yml		.travis.yml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE		LICENSE
README.md		README.md
Vagrantfile		Vagrantfile
config.rb		config.rb
deploy.sh		deploy.sh
font-selection.json		font-selection.json

License

Beaconstac/api

Folders and files

Latest commit

History

Repository files navigation

Beaconstac REST API documentation

Introduction

Authentication

Table of Contents

Reading the Documentation

Filter fields

Searching

Ordering

Core Resources

Beacon

Beacon object

Campaign object

Campaign Notification object

List beacons

Retrieve a beacon

Update beacon

NFC Tag

NFC Tag object

List NFC Tags

Retrieve an NFC Tag

Update an NFC Tag

QR Code

QR Code object

List QR Codes

Retrieve a QR Code

Update a QR Code

Create a QR Code

Download a QR code

Bulk QR Codes

Bulk QR Code object

List Bulk QR Code collections

Retrieve a Bulk QR Code collection

CSV file data format

Create a Bulk QR Code collection

Download Bulk QR code collection

Update an existing Bulk QR Code collection

Geofence

Geofence object

List Geofences

Retrieve a Geofence

Update Geofence

Create Geofence

Place

Place object

List Places

Retrieve a Place

Update Place

Create Place

User

User object

List Users

Retrieve a User

Create a new User

Update an existing User

Partner API endpoints

Beaconstac Analytics

Product

Product overview

Product performance

Product impressions

Product impression detail

Product impression distribution

Generate product CSV data

Get analytics overview for a given period

About

Resources

License

Code of conduct

Stars

Watchers

Forks

Languages