Aladtec API Documentation

Base URL: https://secure#.aladtec.com/example/api

New Version has Arrived

A new and improved version of the Aladtec API has launched which includes powerful updates to the /members routes and additional quality of life improvements. Version 1.0 will only receive security and maintenance updates going forward. Applications built prior to the release of the new version will continue to work with no changes required. Developers are encouraged to check out the new version and update their applications to take advantage of the latest features.

Preface

The Aladtec API can be used to retrieve information from the Aladtec system, specifically:

The Aladtec API is implemented as a JSON web service that accepts authenticated HTTP requests, then returns a response with an HTTP status code and a JSON payload. No separate installation is required to use the Aladtec API.

General Information

  1. Date/Time is expressed in the time zone defined by the Aladtec system being accessed
  2. Date/Time format is YYYY-MM-DDTHH:MM, where YYYY = year, MM = month, DD = day, T = separator character, HH = hours (expressed in 24 hour notation), MM = minutes, e.g. 2018-05-01T17:30
  3. Date format is YYYY-MM-DD, where YYYY = year, MM = month, DD = day, e.g. 2018-05-01
  4. Time format is HH:MM, where HH = hours (expressed in 24 hour notation), MM = minutes, e.g. 14:30.
  5. Aladtec API will attempt to return an appropriate HTTP status code for every request
  6. Parameter keys and values are case sensitive
  7. Only data contained within the requested date range will be included in the response; however, a response may include additional information to indicate if the data extends outside of the requested date range
  8. Aladtec URLs are subject to change at the discretion of Aladtec

API Rate Limits

An Aladtec subscription provides 50 requests per minute and 2500 requests per rolling 24 hour period. Once the rate limit has been reached, a status code of 429 (Too Many Requests), will be returned until the rate limit automatically resets.

If a higher rate limit is required, please contact Aladtec Support at 888.749.5550.

Authentication

Aladtec follows OAuth 2.0 standards for authentication. All API endpoints require authentication using a valid, non-expired access token. To get API tokens for an Aladtec system you must have received a client ID and a client secret for that system. The client secret must remain confidential as it allows unrestricted access to an Aladtec system's data. All access tokens will expire seven days after they are created.

Getting an Access Token

Aladtec has implemented Client Credentials authentication for obtaining access tokens. Tokens obtained using Client Credentials will give unrestricted access to a system's data.

/oauth

post

Generates new API access tokens given valid credentials

post https://secure#.aladtec.com/example/api/oauth/token

Description

Generates new API access tokens given valid credentials

Request Body

{} application/json

grant_type string required Possible values: 'client_credentials'
client_id string required Client ID used to identify your software interacting with Aladtec
client_secret string required Confidential secret to authenticate your software

Example: 

{
  "grant_type": "client_credentials",
  "client_id": "sys-234F3SFSE",
  "client_secret": "ERIOBNSLWVNUIEW3843H3B3B3B3N2MN2"
}

HTTP status code 200

Response Body

{} application/json

token string

The new API token

expires integer

UNIX timestamp value of when the API token expires

Example: 

{
  "token": "GdreEkwMnZUcU1tcmQ3aHJ1cXM1LmZDR05neUc4WklTcE44SHlyNHNwe",
  "expires": 1553634604
}

<?php

/* Set your system URL, client ID, and client secret here. */
$base_url = 'https://secure#.aladtec.com/example/api';
$client_id = 'sys-234F3SFSE';
$client_secret = 'ERIOBNSLWVNUIEW3843H3B3B3B3N2MN2';

$url = $base_url . '/oauth/token';
$ch = curl_init( $url );

curl_setopt( $ch, CURLOPT_CUSTOMREQUEST, 'POST' );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array(
	'Content-Type: application/json'
) );
curl_setopt( $ch, CURLOPT_POSTFIELDS, json_encode( array(
	'grant_type' => 'client_credentials',
	'client_id' => $client_id,
	'client_secret' => $client_secret
) ) );

$response_body = curl_exec( $ch );

$error = curl_error( $ch );
if ( $error ) {
	echo 'Error: ' . $error;
}

print( $response_body );

curl_close( $ch );
/* Set your system URL, client ID, and client secret here. */
var base_url = 'https://secure#.aladtec.com/example/api';
var client_id = 'sys-234F3SFSE';
var client_secret = 'ERIOBNSLWVNUIEW3843H3B3B3B3N2MN2';

var xhr = new XMLHttpRequest();

var url = base_url + '/oauth/token';
xhr.open( 'POST', url );

xhr.send( JSON.stringify( {
	grant_type: 'client_credentials',
	client_id: client_id,
	client_secret: client_secret
} ) );

xhr.addEventListener( 'load', function () {
	console.log( xhr.responseText );
});

Response Codes

Code Text Description
200 Ok Request was successful
400 Bad Request Request was invalid, may be due to missing or incorrect parameters
401 Unauthorized Authentication credentials were invalid or missing, may be due to expired token
403 Forbidden The API credentials used do not have access to the resource requested
404 Not Found The URL path was not found
405 Method Not Allowed An invalid HTTP method was specified for the resource. For example, a GET request was made to /oauth/token which only supports POST requests.
429 Too Many Requests The rate limit for the Aladtec system was reached and the request cannot be completed
500 Internal Server Error A problem has occurred on Aladtec servers, if the error continues - contact Aladtec Support for additional assistance

The Aladtec API will include additional details in the response which can be used for troubleshooting, for example:

  [{
        "error": "Invalid credentials.",
        "detail": "An API token was either not provided or invalid.  A valid API token must be set in the Authorization Bearer header."
  }]

Resources

/members

Routes for retrieving member information

get

Returns members and the member's associated Member Database attributes.

get

Returns all accessible Member Database attributes defined by the Member Database...

/availability

Routes for retrieving Member Availability ranges

get

Returns Member Availability for the requested date/time range.

/time-off

Routes for retrieving member Time Off information

get

Approved and pending Time Off ranges for the requested date/time range. Note: By default,...

/schedules

Routes for retrieving Schedule information

get

Schedule information defined in an Aladtec system. Data is sorted by the order defined on...

/scheduled-time

Routes for retrieving scheduled time information

get

Returns scheduled time ranges for a specified period of time

get

Schedule and position for each member scheduled at the time of the request

/time-clock-time

Routes for retrieving Time Clock information

get

Time Clock records for the requested date/time range. If a member is clocked in at the...

get

Members clocked in at the time of the request.

/events

Routes for retrieving Event ranges

get

Events for requested date/time range.

/shift-labels

Routes for retrieving Shift Label information

get

Shift labels for requested date range.