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.

• Add, amend and delete sites, people and companies.
• Extract sites, people and companies.
• 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 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:

• 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.

API Methods

The following methods are available in the Attendance API.

Method #1: sites

This method returns a list of sites.

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.

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.

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 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.

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.

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.

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:

• accessKey=[your_access_key]
• userLogin=[your_attendance_login]
• userPassword=[your_attendance_password]
• method=setCompanyDetail
• company=new
• name=Name of new company
• mode=Staff

Updating an Existing Company

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

• accessKey=[your_access_key]
• userLogin=[your_attendance_login]
• userPassword=[your_attendance_password]
• method=setCompanyDetail
• company=[company_id]
• name=Updated name
• priority=Top
• includeInTimeSheets=

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:

• accessKey=[your_access_key]
• userLogin=[your_attendance_login]
• userPassword=[your_attendance_password]
• method=setCompanyDetail
• company=[company_id]
• status=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.

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.

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.

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:

• accessKey=[your_access_key]
• userLogin=[your_attendance_login]
• userPassword=[your_attendance_password]
• method=setPersonDetail
• person=new
• name=Name of new person
• company=Identifier of an existing company
• jobTitle=Person's role

Updating an Existing Person

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

• accessKey=[your_access_key]
• userLogin=[your_attendance_login]
• userPassword=[your_attendance_password]
• method=setPersonDetail
• person=[person_id]
• name=Updated name
• staffId=Updated staff identifier
• phone=

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:

• accessKey=[your_access_key]
• userLogin=[your_attendance_login]
• userPassword=[your_attendance_password]
• method=setPersonDetail
• person=[person_id]
• resignedOn=23 Sep 2023

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.

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.

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.

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