API Reference Guide

Getting Started

To get started with the API we suggest you an IDE for testing API's. Bruno or Postman are great tools for testing out API requests and getting your workflow right, before you start programming.

Getting started with Bruno

To get started you will need to download and install Bruno. Bruno is a great open source tool for testing out API requests and getting your workflow right, before you start programming.

Import our Bruno Collection by downloading this file to add all our endpoints and parameters.
Import collection into Bruno
Authentication is done via API key by adding the request header "apiKey".
How to add API key into Bruno
The API key can generated in Portal Settings API

Getting started with Postman

To get started you will need to download and install Postman. Postman is a great tool for testing out API requests and getting your workflow right, before you start programming.

Import our Postman Collection by copying this link to add all our endpoints and parameters.
Import collection into Postman
Authentication is done via API key by adding the request header "apiKey".
How to add API key into Postman
The API key can generated in Portal Settings API

Reference

Groups Get

Returns information about the group objects. Will return all the groups.

Example Query

GET https://timeclock.kiwi/api/groups

Example response

1 
[
2 
    {
3 
        "id": "d2358de1-3631-428a-a314-f1bdb8ab53a2",
4 
        "name": "Auckland",
5 
        "deleted": false,
6 
        "last_updated": "2024-06-06T21:19:17.622Z",
7 
        "created": "2024-06-06T21:19:17.622Z"
8 
    },
9 
    {
10 
        "id": "369b6e85-b90f-4262-9fab-08da623fe3bd",
11 
        "name": "Christchurch",
12 
        "deleted": false,
13 
        "last_updated": "2024-08-12T20:00:36.701Z",
14 
        "created": "2024-08-12T20:00:36.701Z"
15 
    }
16 
]

Jobs Get

Returns information about the job objects. By default will return all the jobs.

Parameters

PropertyDescriptionTypeRequirementDefault
idProviding an ID will return the specific job. Not providing this value will return all jobs.UUIDOptional
completedReturn only jobs completed field matches the value.BooleanOptionalfalse
deletedReturn only jobs deleted field matches the value.BooleanOptionalfalse

Example Query

GET https://timeclock.kiwi/api/jobs?id=01d2aa95-1866-4718-8d86-08aa5182f20d&completed=true&deleted=true

Example response

1 
[
2 
    {
3 
        "id": "055fdff9-c264-4c5d-a98e-e98bab581d1a",
4 
        "name": "63 Handover Rd",
5 
        "description": "",
6 
        "cost_code": null,
7 
        "due_date": null,
8 
        "completed": false,
9 
        "permanent": false,
10 
        "deleted": false,
11 
        "last_updated": "2024-11-01T02:22:56.973Z",
12 
        "created": "2024-11-01T02:22:56.973Z",
13 
        "groups": [
14 
            {
15 
                "id": "f8a97df7-85b9-4331-a284-9463c68810b8",
16 
                "name": "Mosgiel"
17 
            }
18 
        ],
19 
        "kiosks": null,
20 
        "people": null
21 
    },
22 
]

Jobs Add

Adds a job object.

Body

PropertyDescriptionTypeRequirementDefault
nameThe name of the job.StringRequired
descriptionThe description of the job.StringOptional
permanentIs this a job that can be marked as completed?BooleanOptionalfalse
due_dateThe date the job is due to be completed.StringRequired if permanent == false
cost_codeThe cost code for the job.StringOptional
completedHas this job been completed?BooleanOptionalfalse
deletedHas this job been deleted?BooleanOptionalfalse

Example Query

POST https://timeclock.kiwi/api/jobs
1 
{
2 
    "name": "99 Bamford St",
3 
    "description": "Renovating kitchen in 6 apartments",
4 
    "permanent": false,
5 
    "due_date": "2024-11-30 09:00",
6 
    "cost_code": "123456",
7 
    "completed": false,
8 
    "deleted": false
9 
}

Example response

1 
{
2 
    "name": "99 Bamford St",
3 
    "description": "Renovating kitchen in 6 apartments",
4 
    "permanent": false,
5 
    "due_date": "2024-11-30 09:00",
6 
    "cost_code": "123456",
7 
    "completed": false,
8 
    "deleted": false,
9 
    "id": "b6dac400-5097-4763-8021-137222cb1ad4"
10 
}

Jobs Delete

Deletes listed job objects.

Body

PropertyDescriptionTypeRequirementDefault
UUIDA list of UUIDs for all jobs to be deleted.UUIDRequired

Example Query

DELETE https://timeclock.kiwi/api/jobs
1 
["01d2aa95-1866-4718-8d86-08aa5182f20d", "13074d81-2483-46ea-8bce-b8d761c2580e"]

Example response

1 
{
2 
    "status": 200
3 
}

Jobs Update

Updates a job object.

Body

PropertyDescriptionTypeRequirementDefault
idThe UUID of the job that you want to modify.UUIDRequired
nameThe name of the job.StringRequired
descriptionThe description of the job.StringOptional
permanentIs this a job that can be marked as completed?BooleanOptionalfalse
due_dateThe date the job is due to be completed.StringRequired if permanent == false
cost_codeThe cost code for the job.StringOptional
completedHas this job been completed?BooleanOptionalfalse
deletedHas this job been deleted?BooleanOptionalfalse
groupsThe UUIDs of all the groups this job is a part of.UUIDOptional
kiosksThe UUIDs of all the kiosks this job is a part of.UUIDOptional
peopleThe UUIDs of all the people this job will be visible to.UUIDOptional
materialsA list of all the materials that have been used on this job. Materials have to have been used by a person.UUIDOptional
notesAdds a new note to the job.UUIDOptional

Example Query

PUT https://timeclock.kiwi/api/jobs
1 
{
2 
    "id": "dfb37a1e-692e-44d5-bedf-309b44b9e136",
3 
    "name": "99 Bamford St",
4 
    "description": "Renovating kitchen in 6 apartments",
5 
    "permanent": true,
6 
    "due_date": "2024-11-30 09:00",
7 
    "cost_code": "123456",
8 
    "completed": true,
9 
    "deleted": true,
10 
    "groups": ["d2358de1-3631-428a-a314-f1bdb8ab53a2","d2358de1-3631-428a-a314-f1bdb8ab53a3"],
11 
    "kiosks": ["d2358de1-3631-428a-a314-f1bdb8ab53a2","d2358de1-3631-428a-a314-f1bdb8ab53a3"],
12 
    "people": ["d2358de1-3631-428a-a314-f1bdb8ab53a2","d2358de1-3631-428a-a314-f1bdb8ab53a3"],
13 
    "materials": [{ "id": "03b133a9-4546-4e73-89c8-119fb5042fdb", "person_id": "017a1008-de92-4df2-a533-4e17b643123e", "quantity": 5}],
14 
    "notes": [{ "person_id": "017a1008-de92-4df2-a533-4e17b643123e", "note": "Concrete has cat paw prints on it."}]
15 
}

Example response

1 
{
2 
    "status": 200
3 
}

Kiosks Get

Returns information about the kiosk objects. Will return all the kiosks.

Example Query

GET https://timeclock.kiwi/api/kiosks

Example response

1 
[
2 
    {
3 
        "id": "353e1f09-9851-42c8-9b2c-e536ce2cd3bb",
4 
        "name": "Back Stairs",
5 
        "deleted": false,
6 
        "status": "Offline",
7 
        "last_updated": "2024-06-10T00:09:43.169Z",
8 
        "created": "2024-06-10T00:09:43.169Z"
9 
    },
10 
    {
11 
        "id": "7276d2e1-0fe2-4b64-8d89-1e9b65f4a969",
12 
        "name": "Factory Front",
13 
        "deleted": false,
14 
        "status": "Offline",
15 
        "last_updated": "2024-06-10T02:22:51.027Z",
16 
        "created": "2024-06-10T02:22:51.027Z"
17 
    }
18 
]

Materials Get

Returns information about the material objects. Will return all the materials.

Example Query

GET https://timeclock.kiwi/api/materials

Example response

1 
[
2 
    {
3 
        "id": "03b133a9-4546-4e73-89c8-119fb5042fdb",
4 
        "name": "M2 Screw",
5 
        "cost_code": "0001",
6 
        "unit": "none",
7 
        "description": "2mm thick screw",
8 
        "last_updated": "2024-08-19T21:42:33.021Z",
9 
        "created": "2024-08-19T21:42:33.021Z"
10 
    },
11 
    {
12 
        "id": "c127106f-0570-485c-9466-dcf543d9ffbd",
13 
        "name": "MDF18",
14 
        "cost_code": "ABC123",
15 
        "unit": "m²",
16 
        "description": "18mm MDF",
17 
        "last_updated": "2024-08-05T03:08:12.870Z",
18 
        "created": "2024-08-05T03:08:12.870Z"
19 
    }
20 
]

People Get

Returns information about the people objects. Will return all the people.

Example Query

GET https://timeclock.kiwi/api/people

Example response

1 
[
2 
    {
3 
        "id": "b6cc9e4b-cccb-4206-92a0-a387ff121c69",
4 
        "first_name": "Aspen",
5 
        "last_name": "Brewster",
6 
        "email": "[email protected]",
7 
        "pin_enabled": false,
8 
        "pin": null,
9 
        "permission": 3,
10 
        "last_updated": "2024-09-09T02:44:06.604Z",
11 
        "created": "2024-09-09T02:44:06.604Z"
12 
    },
13 
    {
14 
        "id": "2d68300b-f34e-45f9-a1a5-fdf0daa59729",
15 
        "first_name": "Bryne",
16 
        "last_name": "Lynton",
17 
        "email": null,
18 
        "pin_enabled": false,
19 
        "pin": null,
20 
        "permission": 3,
21 
        "last_updated": "2024-09-09T02:44:06.604Z",
22 
        "created": "2024-09-09T02:44:06.604Z"
23 
    }
24 
]

Shifts Get

Returns information about the shift objects.

Parameters

PropertyDescriptionTypeRequirementDefault
start-dateFirst day of shifts to return (inclusive).ISO 8601 date (YYYY-MM-DD)Required
end-dateLast day of shifts to return (inclusive).ISO 8601 date (YYYY-MM-DD)Required
group-idReturn only shifts for people belonging to this group.UUIDOptional
person-idReturn only shifts for this person.UUIDOptional

Example Query

GET https://timeclock.kiwi/api/shifts?start-date=2026-02-20&end-date=2026-02-27&group-id=752d68b5-5d57-4727-8c1c-85383b76fecf&person-id=a8b3e429-d307-4cd1-bde4-1c2510b6b8ef

Example response

1 
[
2 
  {
3 
    "person_id": "a8b3e429-d307-4cg1-bde4-1c2510b8b8ef",
4 
    "first_name": "Ada",
5 
    "last_name": "Nicodemou",
6 
    "days": [
7 
      {
8 
        "date": "2026-02-20",
9 
        "total_hours": 6.82,
10 
        "hours_worked": 6.57,
11 
        "break_hours": 0.25
12 
      },
13 
      {
14 
        "date": "2026-02-21",
15 
        "total_hours": 6.98,
16 
        "hours_worked": 6.73,
17 
        "break_hours": 0.25
18 
      },
19 
      {
20 
        "date": "2026-02-22",
21 
        "total_hours": 7.02,
22 
        "hours_worked": 6.77,
23 
        "break_hours": 0.25
24 
      }
25 
    ]
26 
  },
27 
  {
28 
    "person_id": "b1d8859f-84cc-49c0-ba94-175c8a1e16c4",
29 
    "first_name": "Fred",
30 
    "last_name": "Flinstone",
31 
    "days": [
32 
      {
33 
        "date": "2026-02-20",
34 
        "total_hours": 8.12,
35 
        "hours_worked": 7.95,
36 
        "break_hours": 0.17
37 
      },
38 
      {
39 
        "date": "2026-02-21",
40 
        "total_hours": 8.13,
41 
        "hours_worked": 7.88,
42 
        "break_hours": 0.25
43 
      },
44 
      {
45 
        "date": "2026-02-22",
46 
        "total_hours": 1.97,
47 
        "hours_worked": 1.72,
48 
        "break_hours": 0.25
49 
      }
50 
    ]
51 
  }
52 
]

We are always happy to help.
Reach out to us and we will do our best to make our employee attendance system work for you.