API Reference

Summary

The Fareclock API enables you to integrate our service with your own software applications. It is designed using RESTful principles based on HTTP. Our API endpoint is:

https://www.fareclock.com/api/ .

This API is currently available on the Pro plan only.

 

API Version

The current version of the API is 0.1. If unspecified, the default version of the API will always be the latest version.

The version may specified in the HTTP header, as follows:

X-Api-Version: 0.1

If we make changes to the API in the future which are incompatible with the current version, then we will fork a new additional version.

 

Authentication

The Fareclock API uses HTTP access authentication to authenticate each request. Multiple API keys can be created per account to support application isolation. The API keys are set up and managed in the Fareclock Admin Console application.

The API key establishes authentication using an HTTP header, as follows:

Authorization: Token 1UfK4tEqvWxN2EYTqRLUuSkqaUCmcTvx

 

Throttling

The API currently limits the rate of requests per account to the following:

        Burst rate: 5 / minute

        Sustained rate: 1000 / day

Once you reach one of these thresholds, you will receive an HTTP 429 response. You should not continue to try to query the API when you exceed this threshold, as it may delay the end of the limit period.

We may increase these rates in the future. If you are exceeding these rates and need an increase, please contact us.

 

Content Format

The API currently supports JSON and XML formats. Format defaults to JSON, but can be specified by either HTTP accept header, or by specifying the format in the url using format file-type media extension indicator.

 

Examples of specifying format using accept header:

Accept: application/json

 or

Accept: application/xml

 

Examples specifying format using url:

   /api/punches.json

or

   /api/punches.xml

 

Request Parameters

The API currently has only a GET method, and all parameters are sent via the url query string.

 

HTTP Response Codes

200 OK: Success

400 Bad Request: Likely invalid format or parameters

401 Unauthorized: Authentication failed

403 Forbidden: Permission refused

404 Not Found: Invalid url

429 Too Many Requests: Throttle threshold exceeded

500 Internal Server Error

 

API Errors

Errors may occur within the API semantics. These errors will be transmitted in the HTTP response based on the content format:

JSON:                {"detail": "Invalid token"}

XML:                <root><detail>Invalid token</detail></root>

 

API Methods

 

1) Punches

 

Endpoint:        GET https://www.fareclock.com/api/punches

 

Description: Returns list of punches, based on input parameters. All datetimes should be considered UTC, unless a timezone offset is specified in the string.

 

Parameters:

  • from
  • Start date of period
  • Format: YYYY-MM-DD
  • to
  • End date of period
  • Format: YYYY-MM-DD
  • orgUnit
  • ID of employee organization unit
  • clockOrgUnit
  • ID of clock organization unit
  • employee
  • ID of employee
  • department
  • ID of department
  • status
  • one of: { all, approved, rejected, flagged, notapproved, notrejected }
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Article is closed for comments.