Suggest Edits

Authentication

 

Methods

POST /register

This method this used to create an account. It returns the account information as well as a session token "X-Csrf-Token" that is required in the request header for all requests to this API.

POST /login

This method this used to login into an existing account. It returns the account information as well as the session token.

POST /password

This method this used to change the account's password.

DELETE /logout

This method is used to logout of an account, by invalidating a session token.

Suggest Edits

Authentication: Register

 

Request

HTTP Request

POST "https://api.beaconinside.com/manager/v1/auth/register"

Request body

{
  "name":  "Joe Doe",
  "email": "joe.doe@company.de",
  "password": "125bfskda35fsd",
}

Response

This method returns an Account resource:

{
   "id": "5152211763986432",
   "status": 1,
   "status_formatted": "active",
   "name": "Joe Doe",
   "email": "joe.doe@company.de",
   "created_at": "2014-10-02T06:54:55.365703Z",
   "updated_at": "2014-10-02T06:54:55.365703Z",
   "session": "Mbyb-XxtJ6s4bhjiftNtXk-OoV5UGpiAPghkW0Iy1JM="
}
Suggest Edits

Authentication: Login

 

Request

HTTP Request

POST "https://api.beaconinside.com/manager/v1/auth/login"

Request body

{
  "email": "joe.doe@company.de",
  "password": "125bfskda35fsd",
}

Response

This method returns an Account resource:

{
   "id": "5152211763986432",
   "status": 1,
   "status_formatted": "active",
   "name": "Joe Doe",
   "email": "joe.doe@company.de",
   "created_at": "2014-10-02T06:54:55.365703Z",
   "updated_at": "2014-10-02T06:54:55.365703Z",
   "session": "Mbyb-XxtJ6s4bhjiftNtXk-OoV5UGpiAPghkW0Iy1JM="
}
Suggest Edits

Authentication: Password

 

Request

HTTP Request

POST "https://api.beaconinside.com/manager/v1/auth/password"

Request body

{
  "password": "my_old_password",
  "new_password": "my_new_password",
}

Response

204

Suggest Edits

Authentication: Logout

 

This request is used to logout of the session, by invalidating the session token.

Request

HTTP Request

DELETE "https://api.beaconinside.com/manager/v1/auth/logout"

Request body

{
  "password": "my_old_password",
  "new_password": "my_new_password",
}

Response

204

Suggest Edits

Overview

Overview of the Manage API.

 

The Beaconinside MANAGE API allows you to programmatically access all your Accounts, Applications, Beacons and Groups in the Beaconinside CMS.

This API is organized by resource type which has a data representation and one or more methods.

The key resource types are:

To access the above resources one must log in using the Authentication resource and obtain a session token. This token must be sent as header parameter in all further requests.

Authentication

Method
Request
Description

POST
"/manager/v1/auth/login"

Endpoint to log into an already registered account.

DELETE
"/manager/v1/auth/logout"

Endpoint for invalidating a session token.

Accounts

For the Accounts resource we have the following endpoints:

Method
Request
Desription

GET
"/manager/v1/accounts/:accountId"

Get's the account's metadata by Id.

PUT
"/manager/v1/accounts/:accountId"

Patches the account entity with values from body.

DELETE
"/manager/v1/accounts/:accountId"

Deletes the account identified by it's ID.

GET
"/manager/v1/accounts/:accountId/applications"

Gets the list of applications for the account.

GET
"/manager/v1/accounts/:accountId/beacons"

Gets a list of beacons for the account.

GET
"/manager/v1/accounts/:accountId/groups"

Gets a list of groups for the account.

Beacons

For the Beacons resource we have the following endpoints:

Method
Request
Description

POST
"/manager/v1/beacons"

Creates a new beacon entity.

GET
"/manager/v1/beacons/:beaconId"

Gets a beacon entity by Id.

PUT
"/manager/v1/beacons/:beaconId"

Updates a beacon entity with values from the request's body.

PATCH
"/manager/v1/beacons/:beaconId?fields=name"

Patches a beacon entity with values from the request's body.

DELETE
"/manager/v1/beacons/:beaconId"

Deletes a beacon by Id.

GET
"/manager/v1/beacons/:beaconId/groups"

Get's a list of groups this beacon belongs to, by Id.

GROUPS

For the Groups resource we have the following endpoints:

Method
Request
Description

POST
"/manager/v1/groups"

Creates a new group entity.

GET
"/manager/v1/groups/:groupId"

Get's group entity by Id.

PATCH
"/manager/v1/groups/:groupId?fields"

Patches group entity with values from body.

DELETE
"/manager/v1/groups/:groupId"

Deletes a group by Id.

GET
"/manager/v1/groups/:groupId/beacons"

Get's the list of beacons belonging to this group, by Id.

 

For a list of methods for this resource, see the end of this page.

Resource Representation

The metadata for an account.

ProprietyName
Value
Description

id

string

Id of the account.

status

int

Status of the account:
-1 if deleted , 0 if status is unknown, 1 if status is active.

status_formatted

string

Formatted status of the account: "deleted","active" or "unknown".

created_at

datetime

Creation time of this account.

updated_at

datetime

Last update time for this account.

name

string

Name of the account.

email

string

Email of the account.

password

string

Password of the account.

session

string

Session token for the account.

lastlogin

datetime

Last login time for this account.

Methods

GET

Get's an account metadata by ID.

Accounts: PUT

Updates an account's metadata.

DELETE

Deletes an account by Id.

GET - Applications

Returns list of applications belonging to this account.

GET - Beacons

Returns list of beacons belonging to this account.

GET - Groups
Returns list of groups belonging to this account.

Suggest Edits

Accounts: GET

Get's an account metadata by ID.

 

Request

HTTP Request

GET "https://api.beaconinside.com/manager/v1/accounts/:accountId"

Path parameters

Parameter Name
Value
Description

accountId

String

The Id of the account in question.

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

Do not supply a request body with this method.

Response

This method returns an Account resource

Examples

Response

{
  "id": "5277655813324800", 
  "status": 1, 
  "status_formatted": "active", 
  "created_at": "2016-01-08T15:04:18.078853Z", 
  "updated_at": "2016-01-08T15:38:10.553579Z",

  "email": "joe.doe@company.de", 
  "lastlogin": "2016-01-08T15:37:59.454889Z", 
  "name": "Joe Doe", 
  "password": "my_password", 
  "session": "vy2dfI1xWE79Y6TZEVxHvd5n7n"
}
Suggest Edits

Accounts: PUT

Update an account's metadata

 

Request

HTTP Request

PUT "https://api.beaconinside.com/manager/v1/accounts/:accountId

Path parameters

Parameter Name
Value
Description

accountId

String

The Id of the account in question.

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

{
  "email": string, 
  "name": string, 
}

Response

This method returns an Account resource

Examples

Request

{
  "email": "joe.doe@company.de", 
  "name": "Joe Doe", 
}

Response

{
  "id": "5277655813324800", 
  "status": 1, 
  "status_formatted": "active", 
  "created_at": "2016-01-08T15:04:18.078853Z", 
  "updated_at": "2016-01-08T15:38:10.553579Z",

  "email": "joe.doe@company.de", 
  "lastlogin": "2016-01-08T15:37:59.454889Z", 
  "name": "Joe Doe", 
  "password": "my_password", 
  "session": "vy2dfI1xWE79Y6TZEVxHvd5n7n"
}
Suggest Edits

Accounts: GET - Applications

Returns a list of the account's beacons.

 

Request

HTTP Request

GET "https://api.beaconinside.com/manager/v1/accounts/:accountId/applications"

Path parameters

Parameter Name
Value
Description

accountId

String

The Id of the account in question.

Query parameters

There are no query parameters for this request.

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

Do not supply a request body with this method.

Response

If successful this method returns a list of applications resources.

Examples

Response

[
  {
    "id":"5629349534213120",
    "status": 1,
    "status_formatted": "active",
    "created_at": "2015-07-13T14:03:57.060175Z",
    "updated_at": "2015-07-13T14:03:57.060175Z",
    
    "name": "Default Application",
    "token": "D2t6nyxxGDEXgaj6wems"
  },
  ...
]
Suggest Edits

Accounts: GET - Beacons

Returns a list of the account's beacons.

 

Request

HTTP Request

GET "https://api.beaconinside.com/manager/v1/accounts/:accountId/beacons"

Path parameters

Parameter Name
Value
Description

accountId

String

Id of the account in question.

Query parameters

There are no query parameters for this request.

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

Do not supply a request body with this method.

Response

If successful this method returns a list of beacons resources.

Examples

Response

[
  {
    "id": "5685263489584384",
    "status": 1,
    "status_formatted": "active",
    "created_at": "2015-07-22T12: 03: 09.111021Z",
    "updated_at": "2015-10-16T12: 08: 46.713684Z",

    // device information
    "name": "#beacon1",
    "description": "white beacon by the entrance#1",
    "lat": 37.80253063457482,
    "lon": -122.405822,
    "beacon_identifier": "B-tGt5Nz",
    "vendor": "Beaconinside",
    "model": "2nd Gen",
    "serial_number": "",
    "production_date": "0001-01-01T00: 00: 00Z",
    "firmware_version": "",
    "mac": "",
    "tx_power": -54,
    "measured_power": -64,
    "calibration_value": -65,
    "advertising_name": "",
    "advertising_interval": 86400,
    "sleep_mode": false,
    "advertising_format": 2,

    // iBeacon data
    "uuid": "F0018B9B-7509-4C31-A905-1A27D39C003C",
    "minor": 0,
    "major": 0,
    "range": 0,

    // Eddystone data
    "instance_id": "",
    "namespace_id": "",
    "url": "",
    "flag": "",

    // Security data
    "secure_uuid": "BBBB2880-16E4-4688-A338-546DD4432ED1",
    "lock_code": "",
    "hashchain_value_reported": "2015-12-24T12:43:12Z",

    "meta_data": ""
  },
  ...
]
Suggest Edits

Accounts: GET - Groups

Returns a list of the account's groups.

 

Request

HTTP Request

GET "https://api.beaconinside.com/manager/v1/accounts/:accountId/groups"

Path parameters

Parameter Name
Value
Description

accountId

String

The Id of the account in question.

Query parameters

There are no query parameters for this request.

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

Do not supply a request body with this method.

Response

If successful this method returns a list of groups.

Examples

Response

[
  {
    "id": "5703402298738688",
    "status": 2,
    "status_formatted": "default",
    "created_at": "2015-07-13T14:03:57.189528Z",
    "updated_at": "2015-10-19T07:22:09.57411Z",

    "name": "My Group",
    "description": "This is my description",
    "beacon_ids": [...],
    "type": 1
  },
  ...
]
Suggest Edits

Applications

 

For a list of methods for this resource, see the end of this page.

Resource Representation

The metadata for an application.

ProprietyName
Value
Description

id

string

Id of the application.

status

int

Status of the application: -1 if "deleted", 0 if "unknown", 1 if "active", 2 if "default".

status_formatted

string

Formatted status of the application: "deleted", "unknown", "active" or "default".

created_at

datetime

Creation time for this application.

updated_at

datetime

Last update time for this application.

name

string

Name of the application.

token

string

Api token for this application.

Methods

GET

Get's an application metadata by ID.

Suggest Edits

Applications: GET

Get's an application metadata by ID.

 

Request

HTTP Request

GET "https://api.beaconinside.com//manager/v1/applications/:applicationId"

Path parameters

Parameter Name
Value
Description

applicationId

String

Id of the application in question.

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

Do not supply a request body with this method.

Response

This method returns an Applications resource.

Examples

Response

{
  "id": "5629349534213120",
  "status": 2,
  "status_formatted": "default",
  "created_at": "2015-07-13T14: 03: 57.060175Z",
  "updated_at": "2015-07-13T14: 03: 57.060175Z",
  
  "name": "Default Application",
  "token": "D2t6nyxxGDEXgaj6wems"
}
Suggest Edits

Applications: POST

Creates an application.

 

Request

HTTP Request

POST "https://api.beaconinside.com//manager/v1/applications/"

Path parameters

This request has no path parameters

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

This request contains the application fields in the body.

Response

This method returns an Applications resource:

{"id":"5629349534213120",
  "status":2,
  "status_formatted":"default",
  "created_at":"2015-07-13T14:03:57.060175Z",
  "updated_at":"2015-07-13T14:03:57.060175Z",
  "name":"Default Application",
  "token":"D2t6nyxxGDEXgaj6wems"}

Examples

Suggest Edits

Beacons

Beacons resource representation

 

For a list of methods for this resource, see the end of this page.

Resource Representation

The metadata for a beacon.

ProprietyName
Value
Description

id

string

Id of the beacon.

status

int

Status of the beacon: -1 id "deleted", 0 if "unknown", 1 if "active" and 2 if "inactive" (checkout sleep mode).

status_formatted

string

formatted status of the beacon: "deleted", "unknown", "active" or "inactive".

created_at

datetime

Creation time for this beacon.

updated_at

datetime

Last update time for this beacon.

name

string

Name of the beacon.

descritpion

string

Description of the beacon.

group_ids

list of strings

List of groups ids that the beacon belongs to.

lat

float

Latitude of the position of the beacon.

lon

float

Longitude of the position of the beacon.

dirty

boolean

This flag is set to true when the data on the cms is different from the data on the beacon.

beacon_identifier

string

Unique identifier of the beacon.

vendor

string

Name of the beacon vendor.

model

string

Name of the beacon model.

serial_number

string

Serial number of the beacon.

production_date

datetime

Time of the production of the beacon.

firmware_version

string

Firmware version installed on the beacon.

mac

string

MAC adress of the beacon

tx_power

int

Transmission power of the beacon.

measured_power

int

Measured power of the beacon.

calibration_value

int

Calibration value of the beacon.

advertising_name

string

Advertising name of the beacon.

advertising_interval

int

Advertising interval of the beacon.

sleep_mode

boolean

This flag indicates if the beacon is set to sleep mode or not.

advertising_format

int

This value indicates the different profiles this beacon is advertising.

uuid

string

Ibeacon uuid, if the ibeacon profile is set.

minor

int

Minor value, if the ibeacon profile is set.

major

int

Major value, if the ibeacon profile is set.

range

int

instance_id

string

Instance id, if the eddystone uid profile is set.

namespace_id

string

Namespace id, if the eddystone uid profile is set.

url

string

Advertised url, if the eddystone url profile is set.

flag

string

secure_uuid

string

Advertised secure uuid, the secure beacon profile is set.

lock_code

string

hashchain_value_reported

datetime

Time the hashchain value is reported.

meta_data

json string

Json of key/value items for user defined attributes

Methods

POST

Creates a beacon.

GET

Get's a beacon's metadata by ID.

PATCH

Updates a beacon's metadata.

DELETE

Deletes a beacon by ID

GET - Groups

Returns list of groups that this beacon belongs to.

Suggest Edits

Beacons: POST

Creates a beacon.

 

Request

HTTP Request

POST "https://api.beaconinside.com/manager/v1/beacons/"

Path parameters

This request has no path parameters

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

This request contains the beacon fields in the body.

Response

This method returns a beacon resource:

{
  "id":"5685263489584384",
  "status":1,
  "status_formatted":"active",
  "created_at":"2015-07-22T12:03:09.111021Z",
  "updated_at":"2015-10-16T12:08:46.713684Z",
  "name":"#beacon1",
  "description":"white beacon by the entrance#1",
  "group_ids":["5703402298738688"],
  "lat":37.80253063457482,
  "lon":-122.405822,
  "dirty":false,
  "beacon_identifier":"B-tGt5Nz",
  "vendor":"Beaconinside",
  "model":"2nd Gen",
  "serial_number":"",
  "production_date":"0001-01-01T00:00:00Z",
  "firmware_version":"",
  "mac":"",
  "tx_power":2147483647,
  "measured_power":2147483647,
  "calibration_value":2147483647,
  "advertising_name":"",
  "advertising_interval":2147483647,
  "sleep_mode":false,
  "advertising_format":2,
  "uuid":"",
  "minor":0,
  "major":0,
  "range":0,
  "instance_id":"",
  "namespace_id":"",
  "url":"",
  "flag":"",
  "secure_uuid":"BBBB2880-16E4-4688-A338-546DD4432ED1",
  "lock_code":"",
  "hashchain_value_reported":"0001-01-01T00:00:00Z",
  "meta_data":""
}

Examples

Suggest Edits

Beacons: GET

Get's a beacon metadata by ID.

 

Request

HTTP Request

GET "https://api.beaconinside.com//manager/v1/beacons/:beaconId"

Path parameters

Parameter Name
Value
Description

beaconId

String

The Id of the beacon in question.

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

Do not supply a request body with this method.

Response

This method returns a beacon resource:

{
  "id":"5685263489584384",
  "status":1,
  "status_formatted":"active",
  "created_at":"2015-07-22T12:03:09.111021Z",
  "updated_at":"2015-10-16T12:08:46.713684Z",
  "name":"#beacon1",
  "description":"white beacon by the entrance#1",
  "group_ids":["5703402298738688"],
  "lat":37.80253063457482,
  "lon":-122.405822,
  "dirty":false,
  "beacon_identifier":"B-tGt5Nz",
  "vendor":"Beaconinside",
  "model":"2nd Gen",
  "serial_number":"",
  "production_date":"0001-01-01T00:00:00Z",
  "firmware_version":"",
  "mac":"",
  "tx_power":2147483647,
  "measured_power":2147483647,
  "calibration_value":2147483647,
  "advertising_name":"",
  "advertising_interval":2147483647,
  "sleep_mode":false,
  "advertising_format":2,
  "uuid":"",
  "minor":0,
  "major":0,
  "range":0,
  "instance_id":"",
  "namespace_id":"",
  "url":"",
  "flag":"",
  "secure_uuid":"BBBB2880-16E4-4688-A338-546DD4432ED1",
  "lock_code":"",
  "hashchain_value_reported":"0001-01-01T00:00:00Z",
  "meta_data":""
}

Examples

Suggest Edits

Beacons: PATCH

Updates a beacon's metadata by ID.

 

Request

HTTP Request

PATCH "https://api.beaconinside.com/manager/v1/beacons/beaconId?fields=name"

Path parameters

Parameter Name
Value
Description

beaconId

String

The Id of the beacon in question.

Query parameters

Parameter Name
Value
Description

fields

String

list of the fields that will be updated

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

The body of this request contains the values to be updated.

Response

This method returns a beacon resource:

{
  "id":"5685263489584384",
  "status":1,
  "status_formatted":"active",
  "created_at":"2015-07-22T12:03:09.111021Z",
  "updated_at":"2015-10-16T12:08:46.713684Z",
  "name":"#beacon1",
  "description":"white beacon by the entrance#1",
  "group_ids":["5703402298738688"],
  "lat":37.80253063457482,
  "lon":-122.405822,
  "dirty":false,
  "beacon_identifier":"B-tGt5Nz",
  "vendor":"Beaconinside",
  "model":"2nd Gen",
  "serial_number":"",
  "production_date":"0001-01-01T00:00:00Z",
  "firmware_version":"",
  "mac":"",
  "tx_power":2147483647,
  "measured_power":2147483647,
  "calibration_value":2147483647,
  "advertising_name":"",
  "advertising_interval":2147483647,
  "sleep_mode":false,
  "advertising_format":2,
  "uuid":"",
  "minor":0,
  "major":0,
  "range":0,
  "instance_id":"",
  "namespace_id":"",
  "url":"",
  "flag":"",
  "secure_uuid":"BBBB2880-16E4-4688-A338-546DD4432ED1",
  "lock_code":"",
  "hashchain_value_reported":"0001-01-01T00:00:00Z",
  "meta_data":""
}

Examples

Suggest Edits

Beacons: DELETE

Deletes a beacon by Id.

 

Request

HTTP Request

DELETE "https://api.beaconinside.com/manager/v1/beacons/:beaconId"

Path parameters

Parameter Name
Value
Description

beaconId

String

The Id of the beacon in question.

Query parameters

There are no query parameters for this request.

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

Do not supply a request body with this method.

Response

If successful this method returns an empty request body.

Examples

Suggest Edits

Beacons: GET - Groups

Returns a list of the beacon's groups.

 

Request

HTTP Request

GET "https://api.beaconinside.com/manager/v1/beacons/:beaconId/groups"

Path parameters

Parameter Name
Value
Description

beaconId

String

The Id of the beacon in question.

Query parameters

There are no query parameters for this request.

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

Do not supply a request body with this method.

Response

If successful this method returns a list of groups.

[{"id":"5703402298738688",
  "status":2,
  "status_formatted":"default",
  "created_at":"2015-07-13T14:03:57.189528Z",
  "updated_at":"2015-10-19T07:22:09.57411Z",
  "name":"All Beacons",
  "description":"",
  "beacon_ids":["5685165389584384","5643240998055936","5747973207073280","5728117278296576","5697962787747840","5764640656181760","5631943370404544","5704837555552256"],
  "type":1}]

Examples

Suggest Edits

Groups

Group resource representation

 

For a list of methods for this resource, see the end of this page.

Resource Representation

The metadata for an application.

ProprietyName
Value
Description

id

string

Id of the group.

status

int

Status of the group: -1 if "deleted", 0 if "unknown", 1 if "active", 2 if "default"

status_formatted

string

Formatted status of the group, possible values are: "deleted", "unknown", "active" or "default".

created_at

datetime

Creation time for this group.

updated_at

datetime

Last update time for this group.

name

string

Name of the group.

description

string

Description of the group.

beacon_ids

list of strings

List of beacon ids belonging to this group.

type

int

Type of the group : 1 for beacon groups, 2 for geofence groups.

Methods

POST

Creates a group.

GET

Get's a group's metadata by ID.

PATCH

Updates a group's metadata.

DELETE

Deletes a group by ID

GET - Beacons

returns list of beacons belonging to this group.

GET - Geofences

returns list of geofences belonging to this group.

Suggest Edits

Groups: POST

Creates a beacon.

 

Request

HTTP Request

POST "https://api.beaconinside.com/manager/v1/groups/"

Path parameters

This request has no path parameters

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

This request contains the group fields in the body.

Response

This method returns a beacon resource:

{"id":"5703402298738688",
  "status":2,
  "status_formatted":"default",
  "created_at":"2015-07-13T14:03:57.189528Z",
  "updated_at":"2015-10-19T07:22:09.57411Z",
  "name":"All Beacons",
  "description":"",
  "beacon_ids":["5685165389584384",
                "5643240998055936",
                "5747973207073280",
                "5728117278296576",
                "5697962787747840",
                "5764640656181760",
                "5631943370404544",
                "5704837555552256"],
  "type":1}

Examples

Suggest Edits

Groups: GET

Get's a group metadata by ID.

 

Request

HTTP Request

GET "https://api.beaconinside.com//manager/v1/groups/:groupId"

Path parameters

Parameter Name
Value
Description

groupId

String

The Id of the group in question.

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

Do not supply a request body with this method.

Response

This method returns a group resource:

{"id":"5703402298738688",
  "status":2,
  "status_formatted":"default",
  "created_at":"2015-07-13T14:03:57.189528Z",
  "updated_at":"2015-10-19T07:22:09.57411Z",
  "name":"All Beacons",
  "description":"",
  "beacon_ids":["5685165389584384",
                "5643240998055936",
                "5747973207073280",
                "5728117278296576",
                "5697962787747840",
                "5764640656181760",
                "5631943370404544",
                "5704837555552256"],
  "type":1}

Examples

Suggest Edits

Groups: PATCH

Updates a group's metadata by ID.

 

Request

HTTP Request

PATCH "https://api.beaconinside.com/manager/v1/groups/groupId?fields=name"

Path parameters

Parameter Name
Value
Description

groupId

String

The Id of the group in question.

Query parameters

Parameter Name
Value
Description

fields

String

list of the fields that will be updated

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

The body of this request contains the values to be updated.

Response

This method returns a group resource:

{"id":"5703402298738688",
  "status":2,
  "status_formatted":"default",
  "created_at":"2015-07-13T14:03:57.189528Z",
  "updated_at":"2015-10-19T07:22:09.57411Z",
  "name":"All Beacons",
  "description":"",
  "beacon_ids":["5685165389584384",
                "5643240998055936",
                "5747973207073280",
                "5728117278296576",
                "5697962787747840",
                "5764640656181760",
                "5631943370404544",
                "5704837555552256"],
  "type":1}

Examples

Suggest Edits

Groups: DELETE

Deletes a group by Id.

 

Request

HTTP Request

DELETE "https://api.beaconinside.com/manager/v1/groups/:groupId"

Path parameters

Parameter Name
Value
Description

group

String

The Id of the group in question.

Query parameters

There are no query parameters for this request.

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

Do not supply a request body with this method.

Response

If successful this method returns an empty request body.

Examples

Suggest Edits

Groups: GET - Beacons

Returns a list of the group's beacons.

 

Request

HTTP Request

GET "https://api.beaconinside.com/manager/v1/groups/:groupId/beacons"

Path parameters

Parameter Name
Value
Description

groupId

String

The Id of the group in question.

Query parameters

There are no query parameters for this request.

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Request body

Do not supply a request body with this method.

Response

If successful this method returns a list of beacons.

[{"id":"5685263489584384",
  "status":1,
  "status_formatted":"active",
  "created_at":"2015-07-22T12:03:09.111021Z",
  "updated_at":"2015-10-16T12:08:46.713684Z",
  "name":"#beacon1",
  "description":"white beacon by the entrance#1",
  "group_ids":["5703402298738688"],
  "x":37.80253063457482,
  "y":-122.405822,
  "dirty":false,
  "beacon_identifier":"B-tGt5Nz",
  "vendor":"Beaconinside",
  "model":"2nd Gen",
  "serial_number":"",
  "production_date":"0001-01-01T00:00:00Z",
  "firmware_version":"",
  "mac":"",
  "tx_power":2147483647,
  "measured_power":2147483647,
  "calibration_value":2147483647,
  "advertising_name":"",
  "advertising_interval":2147483647,
  "sleep_mode":false,
  "advertising_format":2,
  "uuid":"",
  "minor":0,
  "major":0,
  "range":0,
  "instance_id":"",
  "namespace_id":"",
  "url":"",
  "flag":"",
  "secure_uuid":"BBBB2880-16E4-4688-A338-546DD4432ED1",
  "lock_code":"",
  "hashchain_value_reported":"0001-01-01T00:00:00Z",
  "meta_data":""}]

Examples

Suggest Edits

Applications: GET - Overview

Returns an overview of the applications characteristics

 

Request

HTTP Request

GET "https://api.beaconinside.com/analytics/v1/applications"

Path parameters

There is no path parameters for this request.

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Reponse

This method returns a list of dictionaries containing the applications significant characteristics.

Response parameters

Parameter Name
Value
Description

start

String

Start date of the application with format yyyy-mm-dd

notifications

Integer

Number of notifications sent to users

conversions

Integer

Number of conversions made

Ratio

Float

Ratio of the conversions by the notifications

Visitors

Integer

Number of visitors for this application

dwell_avg

Integer

Average dwell time

dwell_sum

Integer

Total dwell time

Example

[
  {
   	"start": "2016-01-04",
   	"notifications": 324,
   	"conversions": 223,	
   	"ratio": 0.69,
   	"visitors": 429,
   	"dwell_avg": 194,
   	"dwell_sum": 19832,
  },
  ...
]
Suggest Edits

Applications: GET - Activity

Returns the application's notifications and conversions

 

Request

HTTP Request

GET "https://api.beaconinside.com/analytics/v1/applications/:applicationId/activity"

Path parameters

Parameter Name
Value
Description

applicationId

Integer

ID of the application requested

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

Parameter Name
Value
Description

start

String

Starting date for collecting data. Date format : yyyy-mm-dd

end

String

Ending date for collecting data. Date format : yyyy-mm-dd

interval

String

Time step to be used: : "daily", "weekly", "monthly" or "all"

groupby

String

Group by a characteristic: "platform"

Response

This methods returns a list of dictionaries containing the applications' total number of notifications and conversions, aggregated or not by platform and time step

Response parameters

Parameter Name
Value
Description

date

String

Beginning date of the time interval

os

String

Operating system

notifications

Integer

Number of notifications sent during the specified interval

conversions

Integer

Number of conversion made

Example

// Without parameter
[
  {
    'conversions': 1146, 
    'notifications': 5021
  }
]
// With interval="monthly" & groupby="platform"
[
  {
    'conversions': 95, 
    'notifications': 162, 
    'date': '2015-10-01', 
    'os': 'Android'
  }, 
  {
    'conversions': 25, 
    'notifications': 142, 
    'date': '2015-10-01', 
    'os': 'iOS'
  }, 
  {
    'conversions': 47, 
    'notifications': 388, 
    'date': '2015-11-01', 
    'os': 'Android'
  }, 
  {
    'conversions': 51, 
    'notifications': 278, 
    'date': '2015-11-01', 
    'os': 'iOS'
  }, 
  ...
]
Suggest Edits

Applications: GET - Devices

Returns an overview of the devices connectivity

 

Request

HTTP Request

GET "https://api.beaconinside.com/analytics/v1/applications/:applicationId/devices"

Path parameters

Parameter Name
Value
Description

applicationId

Integer

ID of the application requested

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

Parameter Name
Value
Description

start

String

Starting date for collecting data. Date format : yyyy-mm-dd

end

String

Ending date for collecting data. Date format : yyyy-mm-dd

Response

This method returns a dictionary containing an overview of the BLE and location connectivity of the devices

Response parameters

Parameter Name
Value
Description

always activated

Integer

Number of devices with BLE/Location always activated

never activated

Integer

Number of devices with BLE/Location never activated

alternating

Integer

Number of devices with an alternating BLE/Location status

unavailable

Integer

Number of devices for which the BLE/Location status is not available

Example

{
	'ble': {
    'alternating': 0,
    'never activated': 744,
    'always activated': 369,
    'unavailable': 13
  },
	'location': {
 		'alternating': 0,
    'never activated': 724,
    'always activated': 325,
    'not authorized': 77
 	}
}
Suggest Edits

Applications: GET - App Launches

Returns the number of the application's launches

 

Request

HTTP Request

GET "https://api.beaconinside.com/analytics/v1/applications/:applicationId/appstarts"

Path parameters

Parameter Name
Value
Description

applicationId

String

ID of the application requested

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

Parameter Name
Value
Description

start

String

Starting date for collecting data. Date format : yyyy-mm-dd

end

String

Ending date for collecting data. Date format : yyyy-mm-dd

groupby

String

Group by a characteristic: "platform"

Response

This method returns a list of dictionaries containing the number of application launches, aggregated or not.

Response parameters

Parameter Name
Value
Description

os

String

Operating system

number_of_app_launches

Integer

Number of times the application has been started

Example

// without parameter
[
	{
    'number_of_app_launches': 3973
  }
]
// with groupby='platform'
[
  { 
    os: 'iOS', 
    number_of_app_launches: 1982
  },
  { 
    os: 'Android', 
    number_of_app_launches: 1991
  }
]
Suggest Edits

Applications: GET - App Downloads

Returns the number of application's downloads

 

Request

HTTP Request

GET "https://api.beaconinside.com/analytics/v1/applications/:applicationId/appdownloads"

Path parameters

Parameter Name
Value
Description

applicationId

String

ID of the application requested

Query parameters

There are no query parameters for this request.

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

Parameter Name
Value
Description

start

String

Starting date for collecting data. Date format : yyyy-mm-dd

end

String

Ending date for collecting data. Date format : yyyy-mm-dd

groupby

String

Group by a characteristic: "platform"

Response

This method returns a list of dictionaries with the number of application downloads, aggregated or not.

Response parameters

Parameter Name
Value
Description

os

String

Operating System

app_downloads

Integer

Number of times an application has been downloaded

Example

// without parameter
[
  {
    'app_downloads': 3973
  }
]

// with groupby='platform'
[
  { 
    os: 'iOS', 
    app_downloads: 1982
  },
  { 
    os: 'Android', 
    app_downloads: 1991
  }
]
Suggest Edits

Campaigns: GET - Overview

Returns an overview of the campaigns characteristics

 

Request

HTTP Request

GET "https://api.beaconinside.com/analytics/v1/applications/:applicationId/campaigns

Path parameters

Parameter Name
Value
Description

applicationId

Integer

ID of the application requested

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

There are no optional parameters for this request.

Reponse

This request returns a dictionary containing the campaigns significant characteristics.

Response parameters

Parameter Name
Value
Description

id

Integer

Campaign identifier

name

String

Campaign name

start

String

Campaign start date with format yyyy-mm-dd

end

String

Campaign end date with format yyyy-mm-dd

notifications

Integer

Number of notifications sent for the campaign concerned

conversions

Integer

Number of conversions made by users for the campaign concerned

ratio

Float

Ratio of conversions by notifications

visitors_notification

Integer

Number of visitors that received a notification

visitors_conversion

Integer

Number of visitors that converted a notification

Example

[
  {
    id: 1234567891011121,
    name: 'My Cool Campaign',
    start: '2015-01-01',
    end: '2015-10-07',
    notifications: 534,
    conversions: 345,
    ratio: 0.65,
    visitors_notification: 654,
    visitors_conversion: 265,
  },
  ...
]
Suggest Edits

Visitors: GET

Returns the application's visitors

 

Request

HTTP Request

GET "https://api.beaconinside.com/analytics/v1/applications/:applicationId/visitors"

Path parameters

Parameter Name
Value
Description

applicationId

Integer

ID of the application requested

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

Parameter Name
Value
Description

start

String

Starting date for collecting data. Date format : yyyy-mm-dd

end

String

Ending date for collecting data. Date format : yyyy-mm-dd

interval

String

Time step to be used: "daily", "weekly", "monthly" or "all"

groupby

String

Group by a characteristic: "platform"

Response

This method returns a list of dictionaries containing the application visitors, aggregated or not.

Response parameters

Parameter Name
Value
Description

date

String

Beginning date of the interval considered

os

String

Operating system

visitors

Integer

Number of visitors during this time interval

new_visitors

Integer

Number of new visitors during this time interval

Example

// Without parameter
[
	{
    'visitors': 1158, 
    'new_visitors': 757
  },
]
// With interval="monthly" & groupby="platform"
[
	{
    'date': '2015-10-01', 
    'visitors': 1158, 
    'new_visitors': 757, 
    'os': 'iOS'
  },
	{
    'date': '2015-10-01', 
    'visitors': 341, 
    'new_visitors': 231, 
    'os': 'Android'
  },
	{
    'date': '2015-11-01', 
    'visitors': 301, 
    'new_visitors': 622, 
    'os': 'iOS'
  },
	{
    'date': '2015-11-01', 
    'visitors': 1305, 
    'new_visitors': 562, 
    'os': 'Android'
  },
  ...
]
Suggest Edits

Visitors: GET - Activity

Returns the activity of an application's visitors

 

Request

HTTP Request

GET "https://api.beaconinside.com/analytics/v1/applications/:applicationId/visitors/activity"

Path parameters

Parameter Name
Value
Description

applicationId

Integer

ID of the application requested

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

Parameter Name
Value
Description

start

String

Starting date for collecting data. Date format : yyyy-mm-dd

end

String

Ending date for collecting data. Date format : yyyy-mm-dd

interval

String

Time step to be used: : "daily", "weekly", "monthly" or "all"

groupby

String

Group by a characteristic: "platform"

Response

This method returns a list with the application visitors activity per specified interval and/or platform

Response parameters

Parameter Name
Value
Description

date

String

Beginning date of the interval considered

os

String

Operating system

notified_visitors

Integer

Number of visitors who received a notification during this period

converted_visitors

Integer

Number of visitors who converted a notification during this period

Example

// Without parameter
[
  {
    'notified_visitors': 1275,
    'converted_visitors': 510
  }
]
// With interval=monthly & groupby=platform
[
  {
    date: "2016-10-01", 
    notified_visitors: 430, 
    converted_visitors: 411, 
    os: 'iOS'
  },
  {
    date: "2016-10-01", 
    notified_visitors: 253, 
    converted_visitors: 132, 
    os: 'Android'
  },
  {
    date: "2016-11-01", 
    notified_visitors: 342, 
    converted_visitors: 211, 
    os: 'iOS'
  },
  {
    date: "2016-11-01", 
    notified_visitors: 536, 
    converted_visitors: 246, 
    os: 'Android'
  },
    ...
]
Suggest Edits

Visitors: GET - Frequency

Returns the visitors frequency distribution

 

Request

HTTP Request

GET "https://api.beaconinside.com/analytics/v1/applications/:applicationId/visitors/frequency"

Path parameters

Parameter Name
Value
Description

applicationId

Integer

ID of the application requested

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

Parameter Name
Value
Description

start

String

Starting date for collecting data. Date format : yyyy-mm-dd

end

String

Ending date for collecting data. Date format : yyyy-mm-dd

Response

This method returns a list of dictionaries containing the distribution of the number of visits, and the part of all the visitors that it represents in each case

Response parameters

Parameter Name
Value
Description

interval

Integer

Number of times a visitor came

number_of_visitors

Integer

Number of visitors that came the corresponding number of times

percentage

Float

Ratio of the visitors that came the corresponding number of times

Example

[   
	{
    'percentage': 00, 
    'interval': 0, 
    'number_of_visitors': 0
  }, 
	{
    'percentage': 64, 
    'interval': 1, 
    'number_of_visitors': 37
  }, // 64% of the visitors came 1 time
	{
    'percentage': 12, 
    'interval': 2, 
    'number_of_visitors': 7
  },  // 7 visitors came 2 times
  ...
]
Suggest Edits

Visitors: GET - Recency

Returns the application's visitors recency

 

Request

HTTP Request

GET "https://api.beaconinside.com/analytics/v1/applications/:applicationId/visitors/recency"

Path parameters

Parameter Name
Value
Description

applicationId

Integer

ID of the application requested

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

Parameter Name
Value
Description

start

String

Starting date for collecting data. Date format : yyyy-mm-dd

end

String

Ending date for collecting data. Date format : yyyy-mm-dd

Response

This method returns a dictionary containing the number of visitors per last visit day

Response parameters

Parameter Name
Value
Description

last_n_days

Integer

Number of visitors that came the last n days for the last time

Example

{   
  last_1_days: 132, // 132 visitors came yesterday last time
  last_2_days: 245,
  last_3_days: 1043,
 	...
}
Suggest Edits

Visitors: GET - Visits

Returns the number of visitors per number of visit days

 

Request

HTTP Request

GET "https://api.beaconinside.com/analytics/v1/applications/:applicationId/visitors/visits"

Path parameters

Parameter Name
Value
Description

applicationId

Integer

ID of the application requested

Header parameters

This request requires authentication token (X-Csrf-Token) in headers.

Optional parameters

This request takes no optional parameters.

Response

This method returns a dictionary of the number of venues and the corresponding amount of unique visitors

Response parameters

Parameter Name
Value
Description

n

Integer

Number of visitors that came exactly n times

Example

{   
  1: 430, // 430 visitors came only once
  2: 142,
  3: 102,
 	...
}
 

The Beaconinside Analytics API gives you access to the information your beacons transmitted to our databases.
Those information are computed in order to offer you what we consider as interesting and useful metrics, and let you have a deep understanding of your beacons network.

Authentication & Authorization

To access your resources, you need to authenticate as described in the Authentication API.

Resources

The 3 key resource types are:

  • Applications
  • Campaigns
  • Visitors

Definitions

Visitor

A visitor is a user that downloaded your application, and entered one of your beacon zone. Each visitor is unique: for the rest of the documentation, when we talk about number of visitors, we mean the number of unique visitors.

Visit

A user entering one of your beacon zones is visiting it. If the time between two visits is less than 15 minutes, they are counted as one.
To sum up, if a unique visitors enters two times a beacon zone in a period exceeding 15 minutes, he creates two visits.