Shift Scheduling

Get Shifts

curl "https://example.ziik.io/api/shifts"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
{
    "hits": [{
        "id": 1231,
        "content_type": "schedule",
        "permissions": {
            "edit": true,
            "delete": true
        },
        "unit": {
            "id": 10,
            "name": "Example unit",
            "url": "api/units/10"
        },
        "created_by": {
            "See User Service ..."
        },
        "applicants": [],
        "date": {
            "start": 1500821600,
            "end": 1500825200
        },
        "type": "taken",
        "trade": false,
        "assigned": {
            "See User Service ..."
        },
        "url": "api/shifts/1231"
    }, {
        "id": 1230,
        "content_type": "schedule",
        "permissions": {
            "edit": true,
            "delete": true
        },
        "unit": {
            "id": 10,
            "name": "Example unit",
            "url": "api/units/10"
        },
        "created_by": {
            "See User Service ..."
        },
        "applicants": [],
        "date": {
            "start": 1500821600,
            "end": 1500825200
        },
        "type": "trade",
        "trade": true,
        "assigned": {
            "See User Service ..."
        },
        "url": "api/shifts/1230"
    }]
}

This endpoint retrieves a list of shifts.

HTTP Request

GET https://example.ziik.io/api/shifts

Query Parameters

ParameterTypeDefaultDescription
unitIntegerUser's unitUnit to fetch shifts for
userIntegerNULLUser to fetch shifts for. Overrides any unit parameter set
startIntegerNULLUnix timestamp of earliest start time of a shift
endIntegerNULLUnix timestamp of latest start time of a shift

Get Single Shift

curl "https://example.ziik.io/api/shift/123"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

  {
      "id": 1230,
      "content_type": "schedule",
      "permissions": {
          "edit": true,
          "delete": true
      },
      "unit": {
          "id": 10,
          "name": "Example unit",
          "url": "api/units/10"
      },
      "created_by": {
          "See User Service ...
      "},
      "applicants": [],
      "date": {
          "start": 1500821600,
          "end": 1500825200
      },
      "type": "trade",
      "trade": true,
      "assigned": {
          "See User Service ..."
      },
      "url": "api/shifts/1230"
  }

This endpoint returns a single shift

HTTP Request

GET https://example.ziik.io/api/shifts/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the shift

Permissions Required

  • Authenticated user

Create Shift

curl -i -X POST "https://example.ziik.io/api/shifts"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 201 Created with a location header for where to find the newly created shift

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/shifts/1234
{
    "message": "Shift created"
}

This endpoint creates a shift.

HTTP Request

POST https://example.ziik.io/api/shifts

Request Parameters

ParameterTypeRequiredDescription
unitIntegerNoUnit to create shift in. Defaults to user's own unit
startIntegerYesUnix timestamp of when the shift begins
endIntegerYesUnix timestamp of when the shift ends
assignedIntegerNoUser ID of shift assignee
tradeBooleanNoWhether the shift should be available for trade

Permissions Required

  • Schedule permission to units and shift's unit equal to user's unit or below

Edit Shift

curl -i -X PATCH "https://example.ziik.io/api/shifts/123"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on successful update.

HTTP/1.0 204 No Content

This endpoint updates an existing shift.

HTTP Request

PATCH https://example.ziik.io/api/shifts/ID

Request Parameters

ParameterTypeRequiredDescription
unitIntegerNoUnit to create shift in. Defaults to user's own unit
startIntegerNoUnix timestamp of when the shift begins
endIntegerNoUnix timestamp of when the shift ends
assignedIntegerNoUser ID of shift assignee
tradeBooleanNoWhether the shift should be available for trade

Permissions Required

  • Schedule permission to units and shift's unit equal to user's unit or below

Delete Shift

curl -i -X DELETE "https://example.ziik.io/api/shifts/123"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns a 204 No Content header on success:

HTTP/1.0 204 No Content

This endpoint deletes a shift.

HTTP Request

DELETE https://example.ziik.io/api/shifts/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the shift to delete

Permissions Required

  • Schedule permission to units and shift's unit equal to user's unit or below

Apply for Shift Trade

curl -i -X POST "https://example.ziik.io/api/shifts/123/apply"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint adds the requesting user to the applicants list for this shift.

HTTP Request

POST https://example.ziik.io/api/shifts/ID/apply

Request Parameters

None

Permissions Required

  • Request & Apply permission
  • Shift is open for trade
  • Shift is NOT assigned to the requesting user

Request Shift Trade

curl -i -X POST "https://example.ziik.io/api/shifts/123/request"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint opens a shift for trade.

HTTP Request

POST https://example.ziik.io/api/shifts/ID/request

Request Parameters

None

Permissions Required

  • Request & Apply permission
  • Shift is NOT open for trade
  • Shift is assigned to the requesting user

Take Trade Shift

curl -i -X POST "https://example.ziik.io/api/shifts/123/take"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint takes a shift - i.e. assigns it to the current user.

HTTP Request

POST https://example.ziik.io/api/shifts/ID/take

Request Parameters

None

Permissions Required

  • Take without approval permission
  • Shift is open for trade
  • Shift is NOT assigned to the requesting user

Approve Shift Trade

curl -i -X POST "https://example.ziik.io/api/shifts/123/approve/234"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on success

HTTP/1.0 204 No Content

This endpoint assigns a shift to another user.

HTTP Request

POST https://example.ziik.io/api/shifts/ID/approve/<UID>

Request Parameters

None

Permissions Required

  • Approve shift trade permission
  • Shift is open for trade
  • Shift is NOT assigned to the user in the URL

Get Vacations

curl "https://example.ziik.io/api/shifts"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
{
    "hits": [{
        "id": 1231,
        "content_type": "schedule",
        "permissions": {
            "edit": true,
            "delete": true
        },
        "unit": {
            "id": 10,
            "name": "Example unit",
            "url": "api/units/10"
        },
        "created_by": {
            "See User Service ...
        "},
        "applicants": [],
        "date": {
            "start": 1500821600,
            "end": 1500825200
        },
        "type": "vacation",
        "trade": false,
        "assigned": {
            "See User Service ..."
        },
        "url": "api/shifts/vacations/1231"
    }, {
        "id": 1230,
        "content_type": "schedule",
        "permissions": {
            "edit": true,
            "delete": true
        },
        "unit": {
            "id": 10,
            "name": "Example unit",
            "url": "api/units/10"
        },
        "created_by": {
            "See User Service ...
        "},
        "applicants": [],
        "date": {
            "start": 1500821600,
            "end": 1500825200
        },
        "type": "vacation",
        "trade": true,
        "assigned": {
            "See User Service ..."
        },
        "url": "api/shifts/vacations/1230"
    }],
    "meta": {
        "pagination": {
            "total": 315,
            "count": 50,
            "per_page": 50,
            "current_page": 2,
            "total_pages": 7,
            "links": []
        }
    }
}

This endpoint retrieves a list of vacations.

A vacation is just like a shift with the type "vacation" instead of "taken", "trade" or "empty"

HTTP Request

GET https://example.ziik.io/api/shifts/vacations

Query Parameters

ParameterTypeDefaultDescription
unitIntegerUser's unitUnit to fetch vacations for
pageInteger1Page number for pagination.
limitInteger50Number of records to return per page.
startIntegerNULLUnix timestamp of earliest start time of a vacation
endIntegerNULLUnix timestamp of latest start time of a vacation

Get Single Vacation

curl "https://example.ziik.io/api/shifts/vacations/123"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"

The above command returns JSON structured like this:

  {
      "id": 1230,
      "content_type": "schedule",
      "permissions": {
          "edit": true,
          "delete": true
      },
      "unit": {
          "id": 10,
          "name": "Example unit",
          "url": "api/units/10"
      },
      "created_by": {
          "See User Service ..."
      },
      "applicants": [],
      "date": {
          "start": 1500821600,
          "end": 1500825200
      },
      "type": "vacation",
      "trade": false,
      "assigned": {
          "See User Service ..."
      },
      "url": "api/shifts/vacations/1230"
  }

This endpoint returns a single vacation

HTTP Request

GET https://example.ziik.io/api/shifts/vacations/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the vacation

Permissions Required

  • Authenticated user

Create Vacation

curl -i -X POST "https://example.ziik.io/api/shifts/vacations"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 201 Created with a location header for where to find the newly created shift

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/shifts/vacations/1234
{
    "message": "Vacation created"
}

This endpoint creates a vacation.

HTTP Request

POST https://example.ziik.io/api/shifts/vacations

Request Parameters

ParameterTypeRequiredDescription
startIntegerYesUnix timestamp of when the vacation begins
endIntegerYesUnix timestamp of when the vacation ends
assignedIntegerNoUser ID of vacating user. Defaults to requesting user

Permissions Required

  • Either Set own vacation permission and assigned equal to the requesting user
  • OR Set vacation for unit members and assigned user's unit equal to requesting user's unit

Edit Vacation

curl -i -X PATCH "https://example.ziik.io/api/shifts/vacations/123"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on successful update.

HTTP/1.0 204 No Content

This endpoint updates an existing vacation.

HTTP Request

PATCH https://example.ziik.io/api/shifts/vacations/ID

Request Parameters

ParameterTypeRequiredDescription
startIntegerNoUnix timestamp of when the vacation begins
endIntegerNoUnix timestamp of when the vacation ends
assignedIntegerNoUser ID of vacating user. Defaults to requesting user

Permissions Required

  • Either Set own vacation permission and assigned equal to the requesting user
  • OR Set vacation for unit members and assigned user's unit equal to requesting user's unit

Delete Vacation

curl -i -X DELETE "https://example.ziik.io/api/shifts/vacations/123"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns a 204 No Content header on success:

HTTP/1.0 204 No Content

This endpoint deletes a vacation.

HTTP Request

DELETE https://example.ziik.io/api/shifts/vacations/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the vacation to delete

Permissions Required

  • Either Set own vacation permission and assigned equal to the requesting user
  • OR Set vacation for unit members and assigned user's unit equal to requesting user's unit

Shift Templates

Get Templates

curl "https://example.ziik.io/api/shifts/templates"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
{
    "hits": [{
        "id": "1",
        "name": "Standard week",
        "unit": "10"
      },
      {
        "id": "2",
        "name": "Holiday week",
        "unit": "10"
    }],
    "meta": {
        "pagination": {
            "total": 315,
            "count": 50,
            "per_page": 50,
            "current_page": 2,
            "total_pages": 7,
            "links": []
        }
    }
}

This endpoint retrieves a list of templates.

HTTP Request

GET https://example.ziik.io/api/shifts/templates

Query Parameters

ParameterTypeDefaultDescription
unitIntegerNULLUnit to fetch templates for. Defaults to requesting user's unit.
pageInteger1Page number for pagination.
limitInteger50Number of records to return per page.

Get Single Template

curl "https://example.ziik.io/api/shifts/templates/1"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
{
    "id": "1",
    "name": "Standard week",
    "unit": "10",
    "template": [{
        "start_date": 288000,
        "end_date": 316800,
        "shift_type": "1",
        "worker": "23"
    }, {
        "start_date": 288000,
        "end_date": 316800,
        "shift_type": "3",
        "worker": 0
    }, {
        "start_date": 288000,
        "end_date": 316800,
        "shift_type": "3",
        "worker": 0
    }, {
        "start_date": 201600,
        "end_date": 230400,
        "shift_type": "1",
        "worker": "23"
    }]
}

This endpoint retrieves details about a single template.

HTTP Request

GET https://example.ziik.io/api/shifts/templates/ID

URL Parameters

ParameterTypeDescription
idIntegerTemplate ID.

Apply Template to Week

curl -i -X POST "https://example.ziik.io/api/shifts/templates/1/apply"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 201 Created on success. No Location header is given in this case.

HTTP/1.0 201 Created
{
    "message": "Template applied"
}

This endpoint replaces all shifts in a given week with the shifts defined in the chosen template.

Templates operate on individual units and cannot be used across other units. Therefore, only the template's unit is affected by this operation.

HTTP Request

POST https://example.ziik.io/api/shifts/templates/ID/apply

Request Parameters

ParameterTypeRequiredDescription
weekIntegerYesISO week number to apply the template to
yearIntegerNoDefaults to current year

Permissions Required

  • Schedule permissions for the template's unit

Create Template

curl -i -X POST "https://example.ziik.io/api/shifts/templates"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 201 Created with a location header for where to find the newly created shift

HTTP/1.0 201 Created
Location: https://example.ziik.io/api/shifts/vacations/1234
{
    "message": "Template created"
}

This endpoint creates a template from a given week, that can later be applied to weeks in the same unit as the template is created.

HTTP Request

POST https://example.ziik.io/api/shifts/templates

Request Parameters

ParameterTypeRequiredDescription
nameStringYesName to identify the template
unitIntegerYesUnit to connect the template to
weekIntegerYesISO week number to fetch shifts from to save as template
yearIntegerNoDefaults to current year

Permissions Required

  • Schedule permissions for the template's unit

Edit Template

curl -i -X PATCH "https://example.ziik.io/api/shifts/templates/123"
  -H "Authorization: Bearer aaaaaaaaa.bbbbbbbbb.cccccccccc"
  -d "{ [...] }"

The above command returns 204 No Content on successful update.

HTTP/1.0 204 No Content

This endpoint updates an existing template, fetching shifts from a new week and overwrites the existing template with these shifts.

HTTP Request

PATCH https://example.ziik.io/api/shifts/templates/ID

Request Parameters

ParameterTypeRequiredDescription
weekIntegerYesISO week number to fetch shifts from to save as template
yearIntegerNoIf not given, defaults to current year

Permissions Required

  • Schedule permissions for the template's unit

Delete Template

curl -i -X DELETE "https://example.ziik.io/api/shifts/templates/123"
  -H "Authorization: Bearer aaaaaa.bbbbbbb.ccccccc"

The above command returns a 204 No Content header on success:

HTTP/1.0 204 No Content

This endpoint deletes a template.

HTTP Request

DELETE https://example.ziik.io/api/shifts/templates/ID

URL Parameters

ParameterTypeDescription
IDIntegerThe ID of the template to delete

Permissions Required

  • Schedule permissions for the template's unit

Export Shift Data

curl -i -X GET "https://example.ziik.io/api/shifts/export"
  -H "Authorization: Bearer aaaaaa.bbbbbb.cccccc"

The above command returns an XLSX document with shift data for the filtering parameters

This endpoints returns an XLSX document with shift data for the filtering parameters

HTTP Request

GET https://example.ziik.io/api/shifts/export

Query Parameters

ParameterTypeRequiredDescription
unitIntegerIf no user specifiedID of unit
userIntegerIf no unit specifiedID of user
startIntegerYesUNIX Timestamp of earliest starting timestamp for shift
endIntegerYesUNIX Timestamp of latest starting timestamp for shift
typesArrayNoArray of shift types (1,2 and/or 3) - defaults to any type