Aladtec API Documentation

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

New OpenAPI Version

We're excited to announce a brand new version of the Aladtec API which brings full support for the widely adopted OpenAPI industry standard. OpenAPI empowers developers to rapidly develop new integrations with a low-code approach.

Our new API version comes with other improvements:

Overview

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

The 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


Date/Time Formats

Date/Time (RFC 3339 format)

YYYY-MM-DDTHH:MM:SS±HH:MM

Date

YYYY-MM-DD

Time

HH:MM


The following table describes each of the date/time format specifiers that we use in the API.

Format Description Example
"YYYY" year 2019
"MM" month 01
"DD" date 22
"T" separator character N/A
"HH" hours expressed in 24 hour notation 23
"MM" minutes 42
"SS" seconds 59
"±HH:MM" UTC offset (hours and minutes from UTC time) -06:00

System Timezone

Every Aladtec system is configured to one timezone.

The IANA, aka Olson, timezone (e.g. "America/Chicago") can be queried from the /configuration resource.

Responses

HTTP Status Codes

The Aladtec API will attempt to return an appropriate HTTP status code for every request.

Code Text Description
200 Ok Request was successful
201 Created Resource was created successfully
204 No Content Request was successful and no response content was returned
400 Bad Request Request was invalid, most likely due to missing or incorrect parameters
401 Unauthorized Authorization credentials were invalid or missing
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.

Response Shapes

Each API response will contain a JSON object that matches one of two standard schemas.

Success Example

Returned for responses sent with a 200 level HTTP Status Code.

{
  "data": [ ... ],
  "meta": { ... }
}

Error Example

Returned for responses sent with a 400 or 500 level HTTP Status Code.

{
  "errors": [
    {
      "error": "Time Off is not enabled in this system.",
      "detail": ""
    }
  ]
}

OpenAPI Description

The Aladtec API supports the widely adopted OpenAPI standard and allows customers to rapidly develop integrations without having to fully understand the implementation of our API.

Our OpenAPI description will allow customers to:

Aladtec has implemented version 3 of the OpenAPI specification in YML format for all operations.

File URL

Directly link the OpenAPI YML into compatible software to automatically get all future updates to this API version.

https://developer.aladtec.com/downloads/json_api_v3_openapi_spec.yml

File Download

Download the OpenAPI YML to use with compatible SDK code generators and with software that requires the specification to be imported by file upload.

Download OpenAPI

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.

API Profiles

Aladtec can create multiple API profiles for your organization, each with access to different data. Not all data is available by default.

If you would like to configure API profiles, 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 by contacting Aladtec Support. The client secret must remain confidential as it allows unrestricted access to an Aladtec system's data. All access tokens will expire one hour 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.

Resources

/members

get

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

post

Creates a new member in the Member Database.

post

Creates multiple new members in the Member Database.

patch

Updates a subset of existing members given a list of IDs and new attribute values.

patch

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

get

Returns all employee types. These can be customized per Aladtec system. Examples: part...

get

Returns all customer created Member Database attribute definitions.

/availability

get

Returns Member Availability for the requested date/time range.

/time-off

get

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

get

Returns all active Time Off Types.

post

Creates new Time Off Types given a list of names.

patch

Updates a subset of existing Time Off Types given a list of IDs and corresponding new...

delete

Deletes a subset of Time Off Types given a list of IDs.

/schedules

get

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

get

Returns a list of unique position qualifications.

post

Creates new position qualifications given a list of names.

patch

Updates a subset of existing position qualifications given a list of IDs and corresponding...

delete

Deletes a subset of position qualifications given a list of IDs.

/scheduled-time

get

Returns scheduled time ranges for a specified period of time

get

Returns time ranges where no member is scheduled. Typically used for finding shifts...

get

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

get

Returns Schedule Notes grouped by calendar date. Up to one year can be retrieved in a...

get

Returns scheduled time ranges that end within a specified period of time. Adjacent blocks...

/extra-hours

get

Returns extra hours ranges for a specified period of time in the past.

/time-clock

get

Returns a list of unique, active Paycodes which can be applied to time clock time.

get

Returns a list of unique, active Kiosks used to clock in and out.

/time-clock-time

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.

post

Clocks a member in given a valid member ID.

post

Clocks a member out given a valid member ID.

/events

get

Events for requested date/time range.

/shift-labels

get

Shift Labels for requested date range.

/work-groups

get

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

/time-types

get

Returns a list of unique Time Types which can be applied to scheduled time.

/accrual-banks

get

Returns a list of all accrual banks.

get

Returns the number of hours in each specified accrual bank for a list of provided members.

put

Sets accrual bank balances given a list of hours for members' accrual banks.

post

Updates accrual bank balances given a list of adjustment hours for members' accrual banks.

/configuration

get

Returns a list of configuration settings.

/reports

get

Runs the Payroll Report export. Pagination is required to export all...