Introduction

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

Api endpoint

https://api.ticatag.com/v2

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.

Authorization endpoint

https://account.ticatag.com/uaa/oauth/token

Authentication

https://account.ticatag.com/uaa/oauth/token

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

Example - Access token using client credentials

Request

curl -X POST "https://account.ticatag.com/uaa/oauth/token?client_id=johndoe-corp&client_secret=secret&grant_type=client_credentials"

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(s)
POST	Used to create a new resource
PUT	Used to update an existing resource, full updates only
PATCH	Used to update an existing resource, full updates only
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	Description
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.

Request

$ curl "https://api.ticatag.com/v2/resources?page=2&size=100"

Request parameters

Parameter	Description
page	Page number
size	Page size

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