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:
- Your API Access Key.
- Your account credentials.
- The API method to call.
- 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 | Description |
1 | sites | Returns a list of all sites. |
2 | siteDetail | Returns information about a particular site. |
3 | setSiteDetail | Updates an existing site or creates a new one. |
4 | companies | Returns a list of all companies. |
5 | companyDetail | Returns information about a particular company. |
6 | setCompanyDetail | Updates an existing company or creates a new one. |
7 | people | Returns a list of all people. |
8 | personDetail | Returns information about a particular person. |
9 | setPersonDetail | Updates an existing person or creates a new one. |
10 | inOutTimes | Returns a list of times that people signed in and out at a given site over a given time period. |
11 | timeSheet | Returns the number of minutes people were at a given site over a given time period, including any activities that have been assigned. |
12 | activities | Returns activities, allocated hours, budgets and estimated progress. |
13 | signInOut | Signs a person in or out at a given site. |
Method #1: sites
This method returns a list of sites.
Parameter | Description |
accessKey | An alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key. |
userLogin | An 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. |
userPassword | The password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected. |
method | Set 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 |
accessKey | An alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key. |
userLogin | An 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. |
userPassword | The password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected. |
method | Set the value to "siteDetail" to invoke this method. |
site | The 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 |
accessKey | An alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key. |
userLogin | An 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. |
userPassword | The password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected. |
method | Set the value to "setSiteDetail" to invoke this method. |
site | The identifier of an existing site, or "new" to indicate that a new site should be created. |
name | Optional for existing sites. Required for new sites. Specifies the name of a site. |
classification | Optional. Sets a site's classification, which can be used to determine a subset of announcements to show in the app. |
address | Optional. The address of the site. |
phone | Optional. The site's phone number. |
manager | Optional. The identifier of a person from the "people" method to specify who the site manager is. |
status | Optional. Either "active" or "inactive". Determines whether the site is available for selection in the app. |
type | Optional. Either "site" or "event". Events are locations where people are signed out automatically after a specified duration. |
eventDuration | Optional. Only relevant for events. Specifies the duration after which people are automatically signed out. For example, "1 hour", "2 hours", etc. |
whoCanSignIn | Optional. Can be "Everyone", "Staff" or "Visitors". |
takePhotosOfStaff | Optional. "Yes" or "No". Determines whether the app takes photos of staff when they sign in and out. |
takePhotosOfVisitors | Optional. "Yes" or "No". Determines whether the app takes photos of visitors when they sign in and out. |
showAttendees | Optional. "Yes" or "No". Determines whether the app publicly displays the list of people on site. |
showAnnouncements | Optional. "Yes" or "No". Determines whether the app shows announcements at the site. |
animateSignInButton | Optional. "Yes" or "No". Determines whether the Sign In button in the app is emphasised with animation. |
showRollCallButton | Optional. "Yes" or "No". Determines whether roll calls are available in the app. |
askForPhoneNumber | Optional. "Yes" or "No". When yes, visitors are asked to provide their phone number when signing in for the first time. |
askForEmail | Optional. "Yes" or "No". When yes, visitors are asked to provide their email address when signing in for the first time. |
simplifySignOut | Optional. "Yes" or "No". Determines whether people sign out from a single list, or by mirroring the sign in process. |
askStaffForActivities | Optional. "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:
- 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.
Parameter | Description |
accessKey | An alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key. |
userLogin | An 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. |
userPassword | The password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected. |
method | Set 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 |
accessKey | An alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key. |
userLogin | An 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. |
userPassword | The password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected. |
method | Set the value to "companyDetail" to invoke this method. |
company | The 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 |
accessKey | An alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key. |
userLogin | An 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. |
userPassword | The password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected. |
method | Set the value to "setCompanyDetail" to invoke this method. |
company | The identifier of an existing company, or "new" to indicate that a new company should be created. |
name | Optional for existing companies. Required for new companies. Specifies the name of a company. |
phone | Optional. The company's phone number. |
Optional. The company's email address. | |
website | Optional. The company's website. |
address | Optional. The company's address. |
status | Optional. Either "Current" or "Expired". Determines whether the company is available for selection in the app. |
mode | Optional. Either "Staff" or "Visitor". This affects the behaviour in the Attendance app when selecting a company. |
quickSignIn | Optional. Either "Yes" or "No". Determines whether people can choose their name from a list or have to type it in each time. |
priority | Optional. Either "Normal" or "Top". Companies with top priority appear at the top of the list in the Attendance app. |
includeInTimeSheets | Optional. "Yes" or "No". When yes the company's employees are included in time sheets. |
notes | Optional. 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:
- 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.
Parameter | Description |
accessKey | An alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key. |
userLogin | An 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. |
userPassword | The password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected. |
method | Set 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 |
accessKey | An alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key. |
userLogin | An 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. |
userPassword | The password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected. |
method | Set the value to "personDetail" to invoke this method. |
person | The 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 |
accessKey | An alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key. |
userLogin | An 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. |
userPassword | The password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected. |
method | Set the value to "setPersonDetail" to invoke this method. |
person | The identifier of an existing person, or "new" to indicate that a new person should be created. |
name | Optional for existing people. Required for new people. Specifies the name of a person. |
department | Optional. The person's department. |
receivesVisitorArrivalAlerts | Optional. Either "Yes" or "No". Determines whether a person is listed as a visitor host in the Attendance app. |
phone | Optional. The person's phone number. |
Optional. The person's email address. | |
otherContact | Optional. Other contact means for the person. |
company | Optional. The identifier or name of the person's company (a GUID if specifying an ID or a string if specifying a name). |
staffId | Optional. An identifier for linking the person to their corresponding record in a payroll system. |
jobTitle | Optional. The person's role. |
usualStartTime | Optional. Specifies when an employee usually starts work. For example, "8:00am". |
resignedOn | Optional. The date that a person stopped being an employee for a company. The format is DMY, for example "23 Sep 2023". |
notes | Optional. 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:
- 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.
Parameter | Description |
accessKey | An alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key. |
userLogin | An 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. |
userPassword | The password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected. |
method | Set the value to "inOutTimes" to invoke this method. |
site | The identifier of a valid site. |
from | A date in the form yyyy-mm-dd representing the earliest data to fetch. |
to | A 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 |
accessKey | An alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key. |
userLogin | An 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. |
userPassword | The password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected. |
method | Set the value to "timeSheet" to invoke this method. |
site | The identifier of a valid site. |
from | A date in the form yyyy-mm-dd representing the earliest data to fetch. |
to | A 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 |
accessKey | An alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key. |
userLogin | An 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. |
userPassword | The password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected. |
method | Set the value to "activities" to invoke this method. |
site | The 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 |
accessKey | An alpha-numeric token that enables access to the API. Please send us an email and we will provide you with an access key. |
userLogin | An 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. |
userPassword | The password of the specified user. NB: the API requires HTTPS. Attempts to call it via HTTP are rejected. |
method | Set the value to "signInOut" to invoke this method. |
person | The identifier of an existing person. |
site | The identifier of a valid site. |
signOut | Specify 0 to sign in, or 1 to sign out. |
timeZone | The 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: