The Ticatag Platform connects your website, apps or backend with Ticatag’s products.

Introduction

This is the documentation for the Ticatag v2 API.
The Ticatag API offers access over all your Ticatag data (account, devices, events, hooks, geofences, …​).

Security and authentication

The api is an SSL-only API.
Ticatag API uses the OAuth 2.0 protcol for authentication and authorization.
Your client application must request an access token from the Ticatag Authorization Server and sends the token to the Ticatag API that you want to access.

Authentication

First, you need to get your client credentials to be able to obtain an access token. To request your client credentials, please drop an email to dev@ticatag.com

Once, you get your credentials you can get an access token and use the api.

OAuth 2 provides several grant types for different use cases. The grant types defined are:
  • Authorization Code for apps running on a web server

  • Implicit for browser-based or mobile apps

  • Password for signing in with a username and password

  • Client credentials for application access

Access token using client credentials
Example request
$ curl -X POST "https://account.ticatag.com/uaa/oauth/token?client_id=johndoe-corp&client_secret=secret&grant_type=client_credentials"
Example response
HTTP/1.1 200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiZGV2aWNlcyIsImV2ZW50cyJdLCJzY29wZSI6WyJ1c2VyX2RldmljZXMiLCJ1c2VyX3Byb2ZpbGUiXSwiZXhwIjoxNDc3OTY0NjM2LCJhdXRob3JpdGllcyI6WyJST0xFX1RSVVNURURfQ0xJRU5UIl0sImp0aSI6IjAyMjk3MjA2LTU4YWEtNGM3Zi1hYTdhLTBjNzIwMTdhMjFiNSIsImNsaWVudF9pZCI6InRpYmUtaW9zIn0.T1MXUoMi1qIbjLPcjG0I3Q1vH3v_Kk6JSlOXnaOUm4NpdOr3MrAEIjVf8LRW_nmZoIV5K4SVx9ku9jQ6vARdm9S56DldgnrdAB2mzzn2GS8B6yyqQtEAZEBjaf2xSaao8uS3q60GLagcWgUoN3bkSBX38DACUJV_tC-tEXVUSjl0oUl8_7hXqevWqOjkf9Xb-aq5tg4IIww1pjSMsyHDR0H_qqvGmUiCkYI-NEnoMuU70oT6ttUSHIyMkK0CYyM5Tb_oRBLIPJ3BI3dpkXtqKbbDnghyM9Pp68dG_lJ3h2HVc6O6V0zWloOtVwQnkCIox-ptEMswRt4sNv8royU69w",
  "token_type": "bearer",
  "expires_in": 43199,
  "scope": "user_devices user_profile",
  "jti": "02297206-58aa-4c7f-aa7a-0c72017a21b5"
}

HTTP verbs

Ticatag API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to update an existing resource, full updates only

PATCH

Used to update an existing resource, including partial updates

DELETE

Used to delete an existing resource

HTTP status codes

Ticatag API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code

Usage

200 OK

Standard response for successful HTTP requests.

201 Created

The request has been fulfilled and resulted in a new resource being created.

204 No Content

The server successfully processed the request, but is not returning any content.

400 Bad Request

The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

404 Not Found

The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

500 Internal Server error

The server cannot process the request due to an internal error.

Pagination

Ticatag API returns a maximum of 25 resources by default. You can change the number resources returned on a per-request basis by passing a size parameter in the request URL parameters.
When the response exceeds the size, you can paginate through the resources by incrementing the page parameter. To ease navigation, the result includes the following URLs in the response body : first, prev, self, next, last.

Example request
$ curl "https://api.ticatag.com/v2/resources?page=2&size=100"
Request parameters
Parameter Description

page

Page of results

size

Size of results

Example response
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8

{
  "_embedded": {
    "resources": [
    	...
  	]
  },
  "_links": {
    "first": {
      "href": "https://api.ticatag.com/v2/resources?page=0&size=100"
    },
    "prev": {
      "href": "https://api.ticatag.com/v2/resources?page=1&size=100"
    },
    "self": {
      "href": "https://api.ticatag.com/v2/resources?page=2&size=100"
    },
    "next": {
      "href": "https://api.ticatag.com/v2/resources?page=3&size=100"
    },
    "last": {
      "href": "https://api.ticatag.com/v2/resources?page=4&size=100"
    }
  },
  "page": {
    "size": 100,
    "total_elements": 499,
    "total_pages": 5,
    "number": 2
  }
}
Response fields
Path Type Description

_embedded.resources

Array

An array of resources

_links.self

String

This resource list

_links.first

String

The first page in the resource list

_links.next

String

The next page in the resource list

_links.prev

String

The previous page in the resource list

_links.last

String

The last page in the resource list

page.size

Number

The number of resources in this page

page.total_elements

Number

The total number of resources

page.total_pages

Number

The total number of pages

page.number

Number

The page number

Resources

Devices

Devices are the Ticatag’s products (TiBe, TiFiz, …​).

List Devices

A GET request lists all devices owned by an organization or an user.

Example request
$ curl 'https://api.ticatag.com/v2/devices' -i
Example response
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8

{
  "_embedded" : {
    "devices" : [ {
      "name" : "tiBe1",
      "_links" : {
        "self" : {
          "href" : "https://api.ticatag.com/v2/devices/b4c91680-f989-4b74-8471-93ff7c99e939"
        }
      }
    }, {
      "name" : "tiBe2",
      "_links" : {
        "self" : {
          "href" : "https://api.ticatag.com/v2/devices/9d14185d-6b59-408a-a8fc-19630a37acfb"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.ticatag.com/v2/devices"
    }
  },
  "page" : {
    "size" : 25,
    "total_elements" : 2,
    "total_pages" : 1,
    "number" : 0
  }
}
Path Type Description

_embedded.devices

Array

An array of Device resources

A GET request search all of the user or organization devices.

Available Parameters
Parameter Description

type

Search for devices by type: ibeacon, unb

status

Search for devices by type: active, inactive, lost, found

mac_address

Search for devices by mac address

major

Search for devices by major

minor

Search for devices by minor

q

Search for devices with name or serial number matching your query

includes

Fields to include in response: mac_address, ibeacon_identifiers, images, status, software_version, type, product, last location

Example request
$ curl 'https://api.ticatag.com/v2/devices?includes=mac_address,ibeacon_identifiers,images,status,software_version,type,product,last_location&type=ibeacon&status=active&mac_address=ABCDEFGH&major=1234&minor=5678&q=tiBe1' -i
Example response
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8

{
  "_embedded" : {
    "devices" : [ {
      "name" : "tiBe1",
      "type" : "ibeacon",
      "status" : "active",
      "image_url" : "https://ticatag.com/my-tibe1-picture.png",
      "thumbnail_url" : "https://ticatag.com/my-tibe1-thumb.png",
      "mac_address" : "ABCDEFGH",
      "proximity_uuid" : "801DDF60-A557-43B5-BBA1-D4ABEFC13045",
      "major" : 1234,
      "minor" : 5678,
      "product" : {
        "name" : "tibe-connect",
        "image_url" : "https://ticatag.s3.amazonaws.com/788cbf8a-47ea-4766-ab2a-fe1a4e6cff6b",
        "variants" : {
          "version" : "3.0"
        }
      },
      "last_location" : {
        "timestamp" : "2016-11-03T12:53:18Z",
        "latitude" : 48.75897166666667,
        "longitude" : -3.4674300000000002
      },
      "_links" : {
        "self" : {
          "href" : "https://api.ticatag.com/v2/devices/38db426e-8443-4606-8e94-ab977cecaf4c"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.ticatag.com/v2/devices"
    }
  },
  "page" : {
    "size" : 25,
    "total_elements" : 1,
    "total_pages" : 1,
    "number" : 0
  }
}

Retrieve a device

A GET request will retrieve the details of a device

Example request
$ curl 'https://api.ticatag.com/v2/devices/4171412a-9324-4a3c-8357-219f023dee0b?includes=mac_address,ibeacon_identifiers,images,status,software_version,type,product,last_location' -i
Example response
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8

{
  "name" : "tiFiz1",
  "type" : "unb",
  "status" : "active",
  "image_url" : "https://ticatag.com/my-tifiz-picture.png",
  "thumbnail_url" : "https://ticatag.com/my-tifiz-thumb.png",
  "serial_number" : "75A02",
  "product" : {
    "name" : "tifiz",
    "image_url" : "https://ticatag.s3.amazonaws.com/cb8135b2-444c-45d7-aebb-40f16fd54f0b",
    "variants" : {
      "version" : "1.0"
    }
  },
  "last_location" : {
    "timestamp" : "2016-11-03T12:53:19Z",
    "latitude" : 48.75897166666667,
    "longitude" : -3.4674300000000002
  },
  "_links" : {
    "self" : {
      "href" : "https://api.ticatag.com/v2/devices/4171412a-9324-4a3c-8357-219f023dee0b"
    }
  }
}
Response structure
Path Type Description

name

String

The name of the device

type

String

The type of the device: ibeacon, unb

status

String

The status of the device: active, inactive, lost, found

image_url

String

The image url of the device

thumbnail_url

String

The thumbnail url of the device

mac_address

String

The mac address of the beacon

proximity_uuid

String

The proximity UUID of the beacon

major

Number

The major of the beacon

minor

Number

The minor of the beacon

serial_number

String

The serial number of the unb device

product

Object

Product info like name, image url, version

last_location

Object

The last known location of the device

last_location.timestamp

String

The timestamp of the location

last_location.latitude

Number

The latitude of the location

last_location.longitude

Number

The longitude of the location

Events

Events are the data produced by Ticatag’s products : location, temperature, battery level, button pressed, …​

List events

A GET request lists all of events owned by an organization or an user.

Example request
$ curl 'https://api.ticatag.com/v2/events' -i
Example response
HTTP/1.1 200 OK

{
  "_embedded" : {
    "events" : [ {
      "name" : "temperature",
      "timestamp" : "2016-12-20T15:07:33.763Z",
      "device_id" : "24b5d5a5-401a-48f2-b603-1539cd1f7f83",
      "value" : 15.5,
      "unit" : "celsius"
    }, {
      "name" : "temperature",
      "timestamp" : "2016-12-20T15:07:33.763Z",
      "device_id" : "24b5d5a5-401a-48f2-b603-1539cd1f7f83",
      "value" : 60.0,
      "unit" : "fahrenheit"
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.ticatag.com/v2/events"
    }
  },
  "page" : {
    "size" : 25,
    "total_elements" : 2,
    "total_pages" : 1,
    "number" : 0
  }
}
Path Type Description

_embedded.events

Array

An array of Event resources

A GET request search all of the user or organization events.

Available Parameters
Parameter Description

names

List of events names to search for: location, battery, button, temperature, level

device_ids

List of device identifiers to search for

start_date

Search for events with timestamp after start_date

end_date

Search for events with timestamp before end_date

Syntax examples
Parameters Returns

size=100&names=location&device_ids=123456

The 100 latest locations of the device having id 123456

size=100&names=button&device_ids=987654&start_date=2016-01-01T00:00:00.000Z

The button pressed of the device having id 987654 since 1st january 2016

Example request
$ curl 'https://api.ticatag.com/v2/events?names=location,battery&device_ids=24b5d5a5-401a-48f2-b603-1539cd1f7f83&start_date=2016-12-18T15%3A07%3A33.172Z&end_date=2016-12-21T15%3A07%3A33.172Z' -i
Example response
HTTP/1.1 200 OK

{
  "_embedded" : {
    "events" : [ {
      "name" : "location",
      "timestamp" : "2016-12-20T15:07:32.91Z",
      "device_id" : "24b5d5a5-401a-48f2-b603-1539cd1f7f83",
      "latitude" : 43.6315928,
      "longitude" : 4.8154062
    }, {
      "name" : "location",
      "timestamp" : "2016-12-20T15:07:32.91Z",
      "device_id" : "24b5d5a5-401a-48f2-b603-1539cd1f7f83",
      "latitude" : 48.88232460614006,
      "longitude" : 2.60536553525333
    }, {
      "name" : "battery",
      "timestamp" : "2016-12-20T15:07:32.796Z",
      "device_id" : "24b5d5a5-401a-48f2-b603-1539cd1f7f83",
      "value" : 95,
      "unit" : "percent"
    }, {
      "name" : "battery",
      "timestamp" : "2016-12-20T15:07:32.796Z",
      "device_id" : "24b5d5a5-401a-48f2-b603-1539cd1f7f83",
      "value" : 3025,
      "unit" : "millivolt"
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api.ticatag.com/v2/events?names=location,battery"
    }
  },
  "page" : {
    "size" : 25,
    "total_elements" : 4,
    "total_pages" : 1,
    "number" : 0
  }
}

Event objects

Depending of the event name, the structure differs slightly among the events.

Location event
Path Type Description

name

String

Event name; location here

device_id

String

The device identifier

timestamp

String

The timestamp of the location

latitude

Number

The latitude of the location

longitude

Number

The longitude of the location

Battery event
Path Type Description

name

String

Event name; battery here

device_id

String

The device identifier

timestamp

String

The timestamp of the measure

unit

String

The unit of the measure : millivolt, percent

value

Number

The value of the measure

Temperature event
Path Type Description

name

String

Event name; temperature here

device_id

String

The device identifier

timestamp

String

The timestamp of the measure

unit

String

The unit of the measure : fahrenheit, celsius

value

Number

The value of the measure

Button event
Path Type Description

name

String

Event name; button here

device_id

String

The device identifier

timestamp

String

The timestamp of the event

click_type

String

The type of click : click, double_click, hold

Geofence monitoring event
Path Type Description

name

String

Event name; button here

device_id

String

The device identifier

timestamp

String

The timestamp of the event

boundary_crossing

String

The type of boundary crossing : entry, exit

latitude

Number

The latitude of the region

longitude

Number

The longitude of the region

Hooks

Hooks are notifications that Ticatag Platform sends to client apps to which they subscribed for. Ticatag platform sends POST request to the URI set in the hook. The request body is a JSON object.

Configuring your hooks settings

Hooks are configured from the portal in the device settings section.
Clicking + reveals a form to add new URL and select the events to subscribe for for receiving hooks.

Push Notifcation

Example request
POST <your_notification_callback_uri>
Content-Type: application/json

{
  "event": "LOCATION_CHANGED",
  "beacon": {
    "name": "My TiFiz",
    "serialNumber": "E555",
    "location": {
      "latitude": 43.83883,
      "longitude": 3.641531,
      "timestamp": 1478187361745
    }
  }
}