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.
siteDetailReturns information about a particular site.
setSiteDetailUpdates an existing site or creates a new one.
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.
activitiesReturns activities, allocated hours, budgets and estimated progress.

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: siteDetail

This method returns detailed information about a single site.

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 "siteDetail" to invoke this method.
siteThe id of a valid site.

Results

The resulting JSON is an array containing a single site.

{
  "siteDetail": [
    {
      "id": "{E3D86AC5-69C3-4C00-9AD9-A6DF3797B9F1}",
      "name": "Christchurch Office",
      "classification": "Default",
      "address": "1 Avenue Way",
      "phone": "+64 (0)22 123 456",
      "manager": "{8C841FAE-8271-423B-A51D-4E9720BD416A}",
      "status": "active",
      "type": "Site",
      "whoCanSignIn": "Everyone",
      "takePhotosOfStaff": "Yes",
      "takePhotosOfVisitors": "No",
      "showAttendees": "Yes",
      "showAnnouncements": "Yes",
      "animateSignInButton": "Yes",
      "showRollCallButton": "Yes",
      "simplifySignOut": "Yes",
      "askForPhoneNumber": "No",
      "askForEmail": "No"
    }
  ]
}

Method #3: setSiteDetail

This method updates an existing site or creates a new one.

The "Manage all sites" security role is required for the user login. This can be specified in the Dashboard. Without the security role, an access denied error is returned when attempting to update or edit a site.

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 "setSiteDetail" to invoke this method.
siteThe id of an existing site, or "new" to indicate that a new site should be created.
nameOptional for existing sites. Required for new sites. Specifies the name of a site.
classificationOptional. Sets a site's classification, which can be used to determine a subset of announcements to show in the app.
addressOptional. The address of the site.
phoneOptional. The site's phone number.
managerOptional. The id of a person from the "people" method to specify who the site manager is.
statusOptional. Either "active" or "inactive". Determines whether the site is available for selection in the app.
typeOptional. Either "site" or "event". Events are locations where people are signed out automatically after a specified duration.
eventDurationOptional. Only relevant for events. Specifies the duration after which people are automatically signed out. For example, "1 hour", "2 hours", etc.
whoCanSignInOptional. Can be "Everyone", "Staff" or "Visitors".
takePhotosOfStaffOptional. "Yes" or "No". Determines whether the app takes photos of staff when they sign in and out.
takePhotosOfVisitorsOptional. "Yes" or "No". Determines whether the app takes photos of visitors when they sign in and out.
showAttendeesOptional. "Yes" or "No". Determines whether the app publicly displays the list of people on site.
showAnnouncementsOptional. "Yes" or "No". Determines whether the app shows announcements at the site.
animateSignInButtonOptional. "Yes" or "No". Determines whether the Sign In button in the app is emphasised with animation.
showRollCallButtonOptional. "Yes" or "No". Determines whether roll calls are available in the app.
simplifySignOutOptional. "Yes" or "No". Determines whether people sign out from a single list, or by mirroring the sign in process.
askForPhoneNumberOptional. "Yes" or "No". When yes, visitors are asked to provide their phone number when signing in for the first time.
askForEmailOptional. "Yes" or "No". When yes, visitors are asked to provide their email address when signing in for the first time.

Creating a new site

To create a new site, specify "new" in the request body, specify a name, and optionally provide any other details. For example:

  • accessKey=[your_access_key]
  • userLogin=[your_attendance_login]
  • userPassword=[your_attendance_password]
  • method=setSiteDetail
  • site=new
  • name=Name of new site
  • whoCanSignIn=Staff

Updating an existing site

To change the name of a site, or any other property specify parameters as follows:

  • accessKey=[your_access_key]
  • userLogin=[your_attendance_login]
  • userPassword=[your_attendance_password]
  • method=setSiteDetail
  • site=[site_id]
  • name=Updated name
  • showRollCallButton=No
  • showAnnouncements=

Blank parameters are ignored. For example, showAnnouncements does not have a value in the request above and will therefore be ignored. The site's existing value for showAnnouncements will be left unchanged.

Deleting a site

To prevent a site from being presented in the app, change its status to inactive:

  • accessKey=[your_access_key]
  • userLogin=[your_attendance_login]
  • userPassword=[your_attendance_password]
  • method=setSiteDetail
  • site=[site_id]
  • status=inactive

Results

The resulting JSON is an acknowledgement that the update was made. The site id is returned.

{
  "status": "ok",
  "site": "{E3D86AC5-69C3-4C00-9AD9-A6DF3797B9F1}"
}

To verify the changes, issue a call to siteDetail to retrieve information about the site, or view the site in the Dashboard.

Method #4: 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 #5: 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 #6: 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 #7: 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"
        }
      ]
    }
  ]
}

Method #8: activities

This method returns a list of all activities for a given site, including their budgets, allocated time, and estimated progress.

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 "activities" to invoke this method.
siteThe id of a valid site.

Results

Activities are also known as job costs, cost codes, or department codes. They are used to identify the tasks that staff work on.

The total time allocated is returned, as are budgets and estimated progress where available.

{
  "activities": [
    {
      "group": "Groundworks",
      "estimatedProgress": "50",
      "items": [
        {
          "id": "{F63660C8-193E-4313-B51C-CF56C8824601}",
          "name": "Drainage",
          "code": "DRA",
          "paid": "true",
          "status": "active",
          "minutesBudgeted": "2400",
          "minutesAllocated": "1680"
        },
        {
          "id": "{6546F533-3AAD-46B1-AA6E-99E074E1FABF}",
          "name": "Excavation",
          "code": "EXC",
          "paid": "true",
          "status": "active",
          "minutesBudgeted": "6000",
          "minutesAllocated": "5040"
        },
        {
          "id": "{96753ABC-7ADD-42D9-8142-1F89FBF3324C}",
          "name": "Foundations",
          "code": "FND",
          "paid": "true",
          "status": "active",
          "minutesBudgeted": "12000",
          "minutesAllocated": "5700"
        }
      ]
    }
  ]
}

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 >