API for Developers

API (Application Programming Interface) for Developers

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

Use the API to extract data for custom reporting, extract data for payroll systems, or synchronise employee data from a domain server.

The Attendance System API is available under the Business Edition.

What is the API?

The Attendance API is an internet-accessible service available for use by various software systems to retrieve and manage data from the Attendance System.

It offers the capability to extract detailed data for customised reporting, including sign-in and sign-out times, timesheets and job costing information.

Using the API

The Attendance API 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:

  1. Your API Access Key.
  2. Your account credentials.
  3. The API method to call.
  4. Any parameters that the method requires.

API Access Keys are available as part of the Business Edition. To get one, simply send us an email at hello@attendance.co.nz and we'll send it 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_".

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"
}

Example Usage

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

The required parameters are:

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.

API Methods

The following methods are available in the Attendance API.

#

Method

Description

1sitesReturns a list of all sites.
2siteDetailReturns information about a particular site.
3setSiteDetailUpdates an existing site or creates a new one.
4companiesReturns a list of all companies.
5companyDetailReturns information about a particular company.
6setCompanyDetailUpdates an existing company or creates a new one.
7peopleReturns a list of all people.
8personDetailReturns information about a particular person.
9setPersonDetailUpdates an existing person or creates a new one.
10inOutTimesReturns a list of times that people signed in and out at a given site over a given time period.
11timeSheetReturns the number of minutes people were at a given site over a given time period, including any activities that have been assigned.
12activitiesReturns activities, allocated hours, budgets and estimated progress.
13signInOutSigns a person in or out at a given site.

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 identifier 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",
      "description": "Southern Logistics Port",
      "classification": "Default",
      "address": "1 Avenue Way",
      "phone": "+64 (0)22 123 456",
      "manager": "{8C841FAE-8271-423B-A51D-4E9720BD416A}",
      "status": "active",
      "type": "Site",
      "whoCanSignIn": "Everyone",
      "signInStaffFrom": "",
      "signInVisitorsFrom": "",
      "enableTouchlessSignIn": "Yes",
      "printableQrCodes": "Yes",
      "takePhotosOfStaff": "Yes",
      "takePhotosOfVisitors": "No",
      "showAttendees": "Yes",
      "showAnnouncements": "Yes",
      "animateSignInButton": "Yes",
      "showRollCallButton": "Yes",
      "askVisitorsWhoTheyAreSeeing": "Yes",
      "printVisitorLabels": "No",
      "knownCompaniesOnly": "No",
      "knownPeopleOnly": "No",
      "askForPhoneNumber": "No",
      "askForEmail": "No"
      "simplifySignOut": "Yes",
      "askStaffForActivities": "Yes"
    }
  ]
}

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 identifier 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 identifier 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.
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.
simplifySignOutOptional. "Yes" or "No". Determines whether people sign out from a single list, or by mirroring the sign in process.
askStaffForActivitiesOptional. "Yes" or "No". Determines whether staff can specify the activities or job costs they worked on when signing out.

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:

Updating an Existing Site

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

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:

Results

The resulting JSON is an acknowledgement that the update was made. The site identifier 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 identifier and name.

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

Method #5: companyDetail

This method returns detailed information about a single company.

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 "companyDetail" to invoke this method.
companyThe identifier of a valid company.

Results

The resulting JSON is an array containing a single company.

{
  "companyDetail": [
    {
      "id": "{8CBCDE67-22C2-4116-8D56-2317DCDA49FB}",
      "name": "ABC Contractors Ltd",
      "phone": "+64 (0)22 123 456",
      "email": "",
      "website": "",
      "address": "1 Avenue Way",
      "status": "Current",
      "mode": "Visitor",
      "quickSignIn": "Yes",
      "priority": "Normal",
      "includeInTimeSheets": "No",
      "notes": "",
    }
  ]
}

Method #6: setCompanyDetail

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

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 "setCompanyDetail" to invoke this method.
companyThe identifier of an existing company, or "new" to indicate that a new company should be created.
nameOptional for existing companies. Required for new companies. Specifies the name of a company.
phoneOptional. The company's phone number.
emailOptional. The company's email address.
websiteOptional. The company's website.
addressOptional. The company's address.
statusOptional. Either "Current" or "Expired". Determines whether the company is available for selection in the app.
modeOptional. Either "Staff" or "Visitor". This affects the behaviour in the Attendance app when selecting a company.
quickSignInOptional. Either "Yes" or "No". Determines whether people can choose their name from a list or have to type it in each time.
priorityOptional. Either "Normal" or "Top". Companies with top priority appear at the top of the list in the Attendance app.
includeInTimeSheetsOptional. "Yes" or "No". When yes the company's employees are included in time sheets.
notesOptional. Free-form text associated with the company.

Creating a New Company

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

Updating an Existing Company

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

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

Deleting a Company

To prevent a company from being presented in the app, change its status to expired:

Results

The resulting JSON is an acknowledgement that the update was made. The company identifier is returned.

{
  "status": "ok",
  "company": "{8CBCDE67-22C2-4116-8D56-2317DCDA49FB}"
}

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

Method #7: 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",
      "staffId": "JS1",
      "jobTitle": "Accounts Administrator",
      "companyId": "{8CBCDE67-22C2-4116-8D56-2317DCDA49FB}",
      "companyName": "ABC Contractors Ltd"
    }
  ]
}

Method #8: personDetail

This method returns detailed information about an individual.

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 "personDetail" to invoke this method.
personThe identifier of a valid person.

Results

The resulting JSON is an array containing a single person.

{
  "personDetail": [
    {
      "id": "{E2A5FDE1-33F8-43CA-A01D-5DD4A3A5E23A}",
      "name": "James Smith",
      "department": "",
      "receivesVisitorArrivalAlerts": "No",
      "phone": "+64 (0)22 123 456",
      "email": "",
      "otherContact": "",
      "companyId": "{8CBCDE67-22C2-4116-8D56-2317DCDA49FB}",
      "companyName": "ABC Contractors Ltd",
      "staffId": "JS1",
      "jobTitle": "Accounts Administrator",
      "usualStartTime": "8:00am",
      "resignedOn": "",
      "notes": "",
    }
  ]
}

Method #9: setPersonDetail

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

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 "setPersonDetail" to invoke this method.
personThe identifier of an existing person, or "new" to indicate that a new person should be created.
nameOptional for existing people. Required for new people. Specifies the name of a person.
departmentOptional. The person's department.
receivesVisitorArrivalAlertsOptional. Either "Yes" or "No". Determines whether a person is listed as a visitor host in the Attendance app.
phoneOptional. The person's phone number.
emailOptional. The person's email address.
otherContactOptional. Other contact means for the person.
companyOptional. The identifier or name of the person's company (a GUID if specifying an ID or a string if specifying a name).
staffIdOptional. An identifier for linking the person to their corresponding record in a payroll system.
jobTitleOptional. The person's role.
usualStartTimeOptional. Specifies when an employee usually starts work. For example, "8:00am".
resignedOnOptional. The date that a person stopped being an employee for a company. The format is DMY, for example "23 Sep 2023".
notesOptional. Free-form text associated with the person.

Creating a New Person

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

Updating an Existing Person

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

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

Deleting a Person

To prevent a person from being listed in the app, specify a date for the resignedOn property:

Results

The resulting JSON is an acknowledgement that the update was made. The identifier for the person is returned.

{
  "status": "ok",
  "person": "{246C04D5-D322-45C6-A7BB-D6A0D50BAB92}"
}

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

Method #10: 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 identifier 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 #11: 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 identifier 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",
      "personStaffId": "JS1",
      "company": "{B03CF7B3-0BE9-44B4-8E55-47782FDD87C0}",
      "companyName": "Acme Company Ltd",
      "minutes": "510",
      "activities": [
        {
          "name": "Training",
          "code": "TR",
          "isPaid": true,
          "minutes": "240"
        },
        {
          "name": "Administration",
          "code": "AD",
          "isPaid": true,
          "minutes": "150"
        },
        {
          "name": "Payroll",
          "code": "PR",
          "isPaid": true,
          "minutes": "60"
        },
        {
          "name": "Meal break",
          "code": "",
          "isPaid": false,
          "minutes": "60"
        }
      ]
    }
  ]
}

Method #12: 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 identifier 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"
        }
      ]
    }
  ]
}

Method #13: signInOut

This method signs a person in or out and logs their entry/exit time in the Dashboard.

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 "signInOut" to invoke this method.
personThe identifier of an existing person.
siteThe identifier of a valid site.
signOutSpecify 0 to sign in, or 1 to sign out.
timeZoneThe number of minutes that the person's time zone is ahead of UTC/GMT.

Results

The resulting JSON is an acknowledgement that the sign in or out was recorded. The sign in or out and the time of day are shown in the Dashboard.

{
  "status": "ok"
}

Ready to Get Started?

I would like to:

Schedule a Demo   Sign Up Now