Application Programming Interface (API)

The Attendance System has an interface that can be used to integrate it with other systems.

By using the interface, other systems can:

  • Extract sites, companies and people,
  • Extract attendance history,
  • Extract time sheet data.

The Attendance System API is available under the Business Edition.

What is the API?

The Attendance API is a service that is available over the Internet.

It is used by other systems, such as a Payroll system, to extract time-sheet data from the Attendance system.

It can also be used to extract low-level data for custom reporting, such as sign-in/sign-out times.

How to use the API

The Attendance API is usually integrated by software developers.

It is a RESTful interface that accepts POST requests over HTTPS with form-encoded parameters, and returns results in JSON.

Send requests to your account's endpoint (eg. api_s1.attendance.co.nz, api_s2.attendance.co.nz, ...) along with:

  • an Access Key,
  • your account credentials,
  • the method to call, and
  • any parameters that the method requires.

Access Keys are available for free. To get one, simply send us an email and we'll send one to you.

Identify your account's end-point by logging into the Dashboard and inspecting the address bar. Your end-point is the domain prefixed with "api_".

Example usage

A list of sites can be retrieved by sending an HTTPS POST request to your end-point.

The required parameters are:

  • accessKey=[your_access_key]
  • userLogin=[your_attendance_login]
  • userPassword=[your_attendance_password]
  • method=sites

Parameters are form-encoded and passed as the request body. Key-value pairs are separated by ampersands (&) and values are percent-encoded.

The Content-Type header must be set to "application/x-www-form-urlencoded".

The "method" parameter specifies the type of data being requested, which in this example is the list of sites.

The result of the request looks like:

{
  "sites": [
    {
      "id": "{5BEC7C29-FF95-4ECC-9314-064B52618EEE}",
      "name": "Christchurch Office",
      "status": "active"
    },
    {
      "id": "{F2998A52-1890-49F4-AE98-F9BFB09ECBCB}",
      "name": "Dunedin Operations",
      "status": "active"
    },
    {
      "id": "{00906812-FB96-4069-B758-AA21F78122F6}",
      "name": "Head Office",
      "status": "active"
    },
    {
      "id": "{5F071045-7532-4B62-99D8-ABBF369E013E}",
      "name": "Wellington Call Centre",
      "status": "inactive"
    }
  ]
}

A lightweight javascript implementation is available to demonstrate the usage of the API.

Postman can also be used to test the interface and review the results.

Methods

The following methods are available in the Attendance API.

Method

Description

sitesReturns a list of all sites.
companiesReturns a list of all companies.
peopleReturns a list of all people.
inOutTimesReturns a list of times that people signed in and out at a given site over a given time period.
timeSheetReturns the number of minutes people were at a given site over a given time period, including any activities that have been assigned.

Method #1: sites

This method returns a list of sites.

Parameter

Description

accessKeyAn alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key.
userLoginAn active user login listed in the Admin/Users page of the dashboard. You may wish to create a user specifically for use with the API.
userPasswordThe password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected.
methodSet the value to "sites" to invoke this method.

Results

The resulting JSON contains an array of sites, each comprising an id, name and status.

{
  "sites": [
    {
      "id": "{5BEC7C29-FF95-4ECC-9314-064B52618EEE}",
      "name": "Christchurch Office",
      "status": "active"
    }
  ]
}

Method #2: companies

This method returns a list of companies.

Parameter

Description

accessKeyAn alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key.
userLoginAn active user login listed in the Admin/Users page of the dashboard. You may wish to create a user specifically for use with the API.
userPasswordThe password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected.
methodSet the value to "companies" to invoke this method.

Results

The resulting JSON contains an array of companies, each comprising an id, name and classification.

{
  "companies": [
    {
      "id": "{B03CF7B3-0BE9-44B4-8E55-47782FDD87C0}",
      "name": "Acme Company Ltd",
      "classification": "Service provider"
    }
  ]
}

Method #3: people

This method returns a list of people.

Parameter

Description

accessKeyAn alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key.
userLoginAn active user login listed in the Admin/Users page of the dashboard. You may wish to create a user specifically for use with the API.
userPasswordThe password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected.
methodSet the value to "people" to invoke this method.

Results

The resulting JSON contains an array of people, each comprising an id, name, job title and company.

{
  "people": [
    {
      "id": "{E2A5FDE1-33F8-43CA-A01D-5DD4A3A5E23A}",
      "name": "James Smith",
      "jobTitle": "Accounts Administrator",
      "companyId": "{B03CF7B3-0BE9-44B4-8E55-47782FDD87C0}",
      "companyName": "Acme Company Ltd"
    }
  ]
}

Method #4: inOutTimes

This method returns a list of times that people signed in and out at a given site. A date range is required.

Parameter

Description

accessKeyAn alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key.
userLoginAn active user login listed in the Admin/Users page of the dashboard. You may wish to create a user specifically for use with the API.
userPasswordThe password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected.
methodSet the value to "inOutTimes" to invoke this method.
siteThe id of a valid site.
fromA date in the form yyyy-mm-dd representing the earliest data to fetch.
toA date in the form yyyy-mm-dd representing the most recent data to fetch.

Results

The resulting JSON contains dates, people, and the times they signed in and out.

The time of day is specified as minutes past midnight. For example, 525 is 8:45am and 879 is 2:39pm.

{
  "site": "{5BEC7C29-FF95-4ECC-9314-064B52618EEE}",
  "from": "2017-01-16",
  "to": "2017-01-22",
  "inOutTimes": [
    {
      "date": "2017-01-16",
      "person": "{E2A5FDE1-33F8-43CA-A01D-5DD4A3A5E23A}",
      "io": "in",
      "at": 525
    },
    {
      "date": "2017-01-16",
      "person": "{E2A5FDE1-33F8-43CA-A01D-5DD4A3A5E23A}",
      "io": "out",
      "at": 879
    }
  ]
}

Method #5: timeSheet

This method returns the total minutes of attendance per day for each person, as well as any activities that were assigned to them. Activities are assigned in the dashboard when editing a time sheet. A date range is required.

Parameter

Description

accessKeyAn alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key.
userLoginAn active user login listed in the Admin/Users page of the dashboard. You may wish to create a user specifically for use with the API.
userPasswordThe password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected.
methodSet the value to "timeSheet" to invoke this method.
siteThe id of a valid site.
fromA date in the form yyyy-mm-dd representing the earliest data to fetch.
toA date in the form yyyy-mm-dd representing the most recent data to fetch.

Results

The resulting JSON contains dates, people, minutes per day, and their activities.

Minutes is interpreted as a duration. For example, 510 is 8 hours and 30 minutes.

{
  "site": "{5BEC7C29-FF95-4ECC-9314-064B52618EEE}",
  "from": "2017-01-16",
  "to": "2017-01-22",
  "timeSheet": [
    {
      "date": "2017-01-16",
      "person": "{E2A5FDE1-33F8-43CA-A01D-5DD4A3A5E23A}",
      "personName": "James Smith",
      "company": "{B03CF7B3-0BE9-44B4-8E55-47782FDD87C0}",
      "companyName": "Acme Company Ltd",
      "minutes": "510",
      "activities": [
        {
          "name": "Training",
          "code": "TR",
          "minutes": "240"
        },
        {
          "name": "Administration",
          "code": "AD",
          "minutes": "150"
        },
        {
          "name": "Payroll",
          "code": "PR",
          "minutes": "60"
        },
        {
          "name": "Meal break",
          "code": "",
          "minutes": "60"
        }
      ]
    }
  ]
}

Error Handling

Any errors encountered by the service are returned in JSON format.

If an error is encountered, then the resulting JSON will have an error property. Despite any error, the HTTP status code is always 200 (Success).

For example, the following JSON is returned if a method is called with an invalid access key.

{
  "error": "Invalid access key"
}

Up next: Get Started >