Aladtec API Documentation

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

Welcome to Version 2.0

This new version introduces powerful opportunities for automating updates to the Member Database. The /members routes have been reimagined, providing the ability to create, update, and inactivate members.

Additional quality of life improvements:

  • Standard Aladtec attribute fields are specified by a JSON name for ease of use
  • A member’s primary email address is stored separately from secondary emails
  • Paginate large /members responses with limit and offset query parameters
  • Required attributes identify themselves as such in /members/custom-attributes
  • Uniquely identify attribute options for Single and Multi Options

Preface

The Aladtec API can be used to retrieve, create, or update information contained in an Aladtec system, specifically:

  • Members - member information such as names, member IDs, certifications, and emergency contacts
  • Availability - availability of all members during requested date/time range
  • Time Off - all approved time off, including the type of time off, during requested date/time range
  • Scheduling - information relating to the schedules such as positions, time types, and members currently working during requested date/time range
  • Time Clock - information relating to time clock records, including clock in/out, paycodes, and members currently clocked in during requested date/time range
  • Events - event details, such as title, description, and location, for requested date/time range
  • Shift Labels - label assigned to a schedule day, such as A/B/C or Red/Gold/Black, for the requested date range
  • Work Groups - category for member, containing specific set of rules for requests allowed, work limits, and overtime rules

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

Response Codes

CodeTextDescription
200OkRequest was successful
201CreatedResource was created successfully
204No ContentRequest was successful and no response content was returned
400Bad RequestRequest was invalid, may be due to missing or incorrect parameters
401UnauthorizedAuthentication credentials were invalid or missing, may be due to expired token
403ForbiddenThe API credentials used do not have access to the resource requested
404Not FoundThe URL path was not found
405Method Not AllowedAn invalid HTTP method was specified for the resource. For example, a GET request was made to /oauth/token which only supports POST requests.
429Too Many RequestsThe rate limit for the Aladtec system was reached and the request cannot be completed
500Internal Server ErrorA 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 and updating Member Database information.

get

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

post

Creates a new member in the Member Database.

patch

Updates an existing Member using a subset of attributes or the entire Member.

get

Returns all Employee Types. Employee Types can be customized per Aladtec system. Examples:...

get

Returns all customer created Member Database Attribute definitions

/availability

Collection of availability ranges for members

get

Returns member availability for the requested date/time range.

/time-off

Collection of member time off information

get

Approved time off and paid time off for the requested date/time range

/schedules

Collection of schedules

get

Schedule information defined in an Aladtec system

/scheduled-time

Collection of scheduled time ranges

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

Collection of 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

Collection of events

get

Events for requested date/time range.

/shift-labels

Collection of shift labels

get

Shift labels for requested date range.

/work-groups

Collection of work groups

get

Returns all Work Groups. Work Groups are used for putting members into groups if they...