Introduction

The When I Work API is thorough, flexible, and restful. It’s methods are logically grouped, and follow standard conventions. Make a selection from the left to jump to the method group you would like to know more about.

Feel free to contact us if something seems out of place.

Libraries

We currently offer the following API wrappers:

PHP: wheniwork-api-php

Authentication

Server authentication is based on a token model. The developer with authenticate using a private developer key, along with the user’s credentials. Your developer key can be used like the following in the headers.

W-Key: iworksoharditsnotfunny

Authenticating in will return back a token that can be use for all further requests. The token may be included in the headers, as a cookie or in the query string using the key W-Token, like the following.

W-Token: ilovemyboss

Example Request

curl https://api.wheniwork.com/2/login \
  --data '{"username":"user@example.com","password":"*******"}' \
  -H "W-Key: iworksoharditsnotfunny"

<?php
$result = Wheniwork::login(
              "iworksoharditsnotfunny",
              "user@example.com",
              "*******"
          );
?>

Example Response

{
  "users": [
    {
      "id": 4364,
      "first_name": "Goldie",
      "last_name": "Wilson",
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "phone_number": "555-555-5555",
      "token": "ilovemyboss"
    }
  ],
  "accounts": [

  ]
}

Be sure to replace iworksoharditsnotfunny with your requested Developer Key.

The first thing to do after you receive your Developer Key is to login and replace that with a token. This token will be used for all future authenticated requests.

Parameters

Key	Description
username	email The email of the user logging in.
password	string Password of the user logging in.
key	string Developer key. Can be used instead of `W-Key` in the headers. Do not need both.

Once you have the token, you must include it in all authenticated requests. The W-Key does not need to be included.

W-Token: ilovemyboss

Web App SSO

Example Request

curl -X POST https://api.wheniwork.com/2/users/autologin \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->post("users/autologin");
?>

Example Response

{
  "user": {
    "id": 4364,
    "first_name": "Goldie",
    "last_name": "Wilson",
    "email": "goldiewilson@hillvalleycalifornia.gov",
    "phone_number": "555-555-5555",
    "token": "ilovemyboss"
  },
  "hash": "the_auto_login_hash"
}

If you find any need to send an authenticated user into the web app without requiring them to login, you can use the autologin hash query parameter to accomplish this: al.

An example would be sending the user to the following URL.

http://app.wheniwork.com/scheduler?al=the_auto_login_hash

Shifts

Example Object

{
  "id": 10000,
  "user_id": 101,
  "location_id": 1045,
  "position_id": 19483,
  "site_id": 4351,
  "start_time": "Fri, 07 Mar 2014 08:30:00 -0600",
  "end_time": "Fri, 07 Mar 2014 14:30:00 -0600",
  "break_time": 0.5,
  "color": "cc0000",
  "notes": "We need more cow bell.",
  "published": true,
  "published_date": "Thu, 06 Mar 2014 22:17:14 -0600",
  "notified_at": null,
  "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
  "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
}

Shifts provide the basis for scheduling. Many other objects, including Locations, Positions, Sites and Users all link through Shifts.

Shift Object

Parameter	Description
id	integer Unique identifier for the shift
user_id	integer Link identifier for the User attached to this shift. 0 means OpenShift.
location_id	integer Link identifier for the Location to which this shift is attached.
position_id	integer Link identifier for the Position attached to this shift.
site_id	integer Link identifier for the Site attached to this shift.
start_time	datetime Start time of the shift.
end_time	datetime End time of the shift.
break_time	float Hours of unpaid break.
color	hex Hex color used to identify the shift in the UI.
notes	string Notes about the shift. Max length 350.
published	boolean Published shifts show to employees.
published_date	datetime Date the shift was most recently published.
notified_at	datetime Date the shift was most recently notified.
created_at	datetime Date at which the shift was created.
updated_at	datetime Date the shift was most recently updated.

Listing Shifts

Example Request

curl https://api.wheniwork.com/2/shifts/?location_id=1&start_time=2014-03-05 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("shifts", array(
                                "location_id" => 1, 
                                "start_time"  => "2014-03-05"
                              ));
?>

Example Response

{
  "start": "Wed, 05 Mar 2014 00:00:00 -0600",
  "end": "Sat, 08 Mar 2014 23:59:59 -0600",
  "shifts": [
    {
      "id": 10000,
      "start_time": "Fri, 07 Mar 2014 08:30:00 -0600",
      "end_time": "Fri, 07 Mar 2014 14:30:00 -0600"
    },
    {
      "id": 27384,
      "start_time": "Fri, 07 Mar 2014 08:30:00 -0600",
      "end_time": "Fri, 07 Mar 2014 14:30:00 -0600"
    }
  ]
}

This method allows you to search for shifts. See the parameters below for all the options.

HTTP Request

GET https://api.wheniwork.com/2/shifts

Parameters

Key	Description
start_time	datetime Start time for a search window
end_time	datetime End time for a search window
user_id	integer, string array Only show shifts for a user, or multiple (e.g. 1,5,3)
location_id	integer, string array Only show shifts for a location, or multiple.
site_id	integer, string array Only show shifts for a site, or multiple.
position_id	integer, string array Only show shifts for a position, or multiple.

Get Existing Shift

Example Request

curl https://api.wheniwork.com/2/shifts/1 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("shifts/1337");
?>

Example Response

{
  "shift": {
    "id": 1337,
    "start_time": "Fri, 07 Mar 2014 08:30:00 -0600",
    "end_time": "Fri, 07 Mar 2014 14:30:00 -0600",
    "notes": "Come in early today."
  }
}

HTTP Request

GET https://api.wheniwork.com/2/shifts/{id}

Parameters

Key	Description
id	ID of the shift requested.

Create/Update Shift

Example Request

<?php
$wiw = new Wheniwork("ilovemyboss");

// Create a shift
$result = $wiw->create("shifts", array(...));

// Update a shift
$result = $wiw->update("shifts/10000", array(...));
?>

Example Response

{
  "shift": {
    "id": 10000,
    "start_time": "Fri, 07 Mar 2014 08:30:00 -0600",
    "end_time": "Fri, 07 Mar 2014 14:30:00 -0600",
    "notes": "Come in early today."
  }
}

Create HTTP Request

POST https://api.wheniwork.com/2/shifts/

Update HTTP Requests

PUT https://api.wheniwork.com/2/shifts/{id}

Post/Put Body

The POST and/or PUT body can include fields from the Shift Object.

Publish/Unpublish Shifts

Example Request

curl -X POST https://api.wheniwork.com/2/shifts/publish/ \
 --data '{"ids":[1534,3543,65554,33444]}' \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->post("shifts/publish/", array("ids"=>array(34542,45434)));
?>

Example Response

{
  "success": true
}

These methods allow you to publish or unpublish a group of shifts.

HTTP Request

POST https://api.wheniwork.com/2/shifts/publish/

HTTP Request

POST https://api.wheniwork.com/2/shifts/unpublish/

Parameters

Key	Description
ids	Post body parameter that can be used to publish multiple shifts. `[4543,23453]`

Notify Shifts

Example Request

curl -X POST https://api.wheniwork.com/2/shifts/notify/ \
 --data '{"start":"2014-05-16 00:00:00", "end":"2014-05-19 23:59:59"}' \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->post("shifts/notify/", array("start"=>"2014-05-16 00:00:00", "end"=>"2014-05-19 23:59:59"));
?>

Example Response

{
  "success": true,
  "email": 12,
  "sms": 4
}

This method allows you to notify users about new or updated shifts.

HTTP Request

POST https://api.wheniwork.com/2/shifts/notify/

Parameters

Key	Description
start	datetime Start time for a notify window
end	datetime End time for a notify window
user_id	integer, array Only notify shifts for a user, or multiple (e.g. `[1,5,3]`)
location_id	integer, array Only notify shifts for a location, or multiple.
position_id	integer, array Only notify shifts for a position, or multiple.
site_id	integer, array Only notify shifts for a site, or multiple.

Example Request

curl -X POST https://api.wheniwork.com/2/shifts/notify/47433 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->post("shifts/notify/47433");
?>

Example Response

{
  "success": true,
  "email": 1,
  "sms": 0
}

You can also send a notification about just one shift using the following

HTTP Request

POST https://api.wheniwork.com/2/shifts/notify/{id}

Parameters

Key	Description
id	integer ID of the shift you want to notify.

Delete Shift

Example Request

curl -X DELETE https://api.wheniwork.com/2/shifts/1 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->delete("shifts/1337");
?>

Example Response

{
  "success": true
}

HTTP Request

DELETE https://api.wheniwork.com/2/shifts/{id}

Parameters

Key	Description
id	ID of the shift requested.
ids	Optional query parameter that can be used to delete multiple shifts. `?ids=5,2,34`

Users

Example Object

{
  "id": 4364,
  "first_name": "Goldie",
  "last_name": "Wilson",
  "email": "goldiewilson@hillvalleycalifornia.gov",
  "phone_number": "555-555-5555",
  "hours_preferred": 40,
  "hours_max": 40,
  "hourly_rate": 15.5,
  "role": 2,
  "positions": [
    12284,
    9554
  ],
  "locations": [
    34,
    58934
  ],
  "notes": "",
  "activated": 1,
  "password": "Th3m@y0R"
}

Users are the employees, supervisors, and managers that have access to your WhenIWork

User Object

Parameter	Description
id	integer Unique identifier for the user.
first_name	string First name of this user.
last_name	string Last name of this user.
email	string The email address of this user.
phone_number	string The phone number of this user.
hours_preferred	float The preferred number of hours for the user.
hours_max	float Max hours this user can work.
hourly_rate	float The hourly rate for this user.
role	integer The user’s role. 2 = Manager 5 = Supervisor 3 = Employee (default)
positions	array (of IDs) An array of positions to be assigned to the user.
locations	array (of IDs) An array of locations to be applied to the user.
notes	string Notes about the user
activated	boolean Whether the manager has activated this user.
password	string Set a password, but only on user creation, not update. (write only)

Listing Users

Example Request

curl https://api.wheniwork.com/2/users/?location_id=1 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("users");
?>

Example Response

{
  "users": [
    {
      "id": 4364,
      "first_name": "Goldie",
      "last_name": "Wilson",
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "phone_number": "555-555-5555"
    },
    {
      "id": 27384,
      "first_name": "Jennifer",
      "last_name": "Parker",
      "email": "jen.parker@example.com",
      "phone_number": "555-555-5555"
    }
  ]
}

This method allows you to search for users. See the parameters below for all the options.

HTTP Request

GET https://api.wheniwork.com/2/users

Parameters

Key	Description
location_id	integer, string Only show shifts for a location, or multiple (e.g. 1,5,3).

Get Existing User

Example Request

curl https://api.wheniwork.com/2/users/1 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("users/1");
?>

Example Response

{
  "user": {
    "id": 4364,
    "first_name": "Goldie",
    "last_name": "Wilson",
    "email": "goldiewilson@hillvalleycalifornia.gov",
    "phone_number": "555-555-5555",
    "notes": "This user excels at awesome."
  }
}

HTTP Request

GET https://api.wheniwork.com/2/users/{id}

Parameters

Key	Description
id	ID of the user requested.

Create/Update User

Create HTTP Request

POST https://api.wheniwork.com/2/users/

Update HTTP Requests

PUT https://api.wheniwork.com/2/users/{id}

Parameters

The POST and/or PUT body can include fields from the User Object.

Additional Params

Key	Description
reactivate	boolean Pass this to reactivate a previously deleted user.

Invite Users

Example Request

curl -X POST https://api.wheniwork.com/2/users/invite/ \
 --data '{"ids":[14,15,67]}' \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->post("users/invite/", array("ids"=>array(14,15,67)));
?>

Example Response

{
  "count": 3,
  "email": 3,
  "sms": 1,
  "success": true
}

Users can be invited by managers, or by supervisors. This will send them an email or text message inviting them to register. Users must already be created to be invited.

HTTP Request

POST https://api.wheniwork.com/2/users/invite/

Parameters

Key	Description
ids	array List of IDs of users to invite.
send_all	boolean Invite all users without a login. `ids` parameter is ignored.
message	string An optional message to include in the email invite.

You can also invite a single user with the following.

HTTP Request

POST https://api.wheniwork.com/2/users/invite/{id}

Parameters

Key	Description
id	integer The ID of the user to invite.
message	string An optional message to include in the email invite.

Delete User

Example Request

curl -X DELETE https://api.wheniwork.com/2/users/4364 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->delete("users/4364");
?>

Example Response

{
  "success": true
}

Users can be deleted by managers, or by supervisors. If a supervisor, the user must be able to manage all locations the user is attached to.

HTTP Request

DELETE https://api.wheniwork.com/2/users/{id}

Parameters

Key	Description
id	ID of the shift requested.

Positions

Example Object

{
  "id": 32,
  "account_id": 3,
  "name": "Stocker",
  "color": "1174a6",
  "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
  "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
}

Positions are the different titles that employees can be grouped into.

Position Object

Parameter	Description
id	integer The unique ID of the position.
account_id	integer The ID of the account that the position belongs to.
name	string The name of the position.
color	hexadecimal The position’s color in the schedule.
created_at	datetime Date at which the position was created.
updated_at	datetime Date the position was most recently updated.

Listing Positions

Example Request

curl https://api.wheniwork.com/2/positions \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("positions");
?>

Example Response

{
  "positions": [
    {
      "id": 32,
      "name": "Stocker",
      "color": "1174a6"
    },
    {
      "id": 5,
      "name": "Bagger",
      "color": "FF6666"
    }
    {
      "id": 6,
      "name": "Cashier",
      "color": "0066FF"
    }
  ]
}

HTTP Request

GET https://api.wheniwork.com/2/positions

Get Existing Position

Example Request

curl https://api.wheniwork.com/2/positions/32 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("positions/32");
?>

Example Response

{
  "position": {
    "id": 32,
    "name": "Stocker",
    "color": "1174a6"
  }
}

HTTP Request

GET https://api.wheniwork.com/2/positions/{position_id}

Parameters

Key	Description
position id	ID of the position requested.

Create/Update Position

Create HTTP Request

POST https://api.wheniwork.com/2/positions/

Update HTTP Requests

PUT https://api.wheniwork.com/2/positions/{position id}

Parameters

The POST and/or PUT body can include fields from the Position Object.

Delete Existing Position

Example Request

curl -X DELETE https://api.wheniwork.com/2/positions/9 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->delete("positions/9");
?>

Example Response

{
  "success": true
}

HTTP Request

DELETE https://api.wheniwork.com/2/positions/{position_id}

Parameters

Key	Description
position id	ID of the position to be deleted.

Locations

Example Object

{
  "id": 136,
  "name": "Downtown",
  "address": "9303 Lyon Drive, Hill Valley, CA 12345",
  "coordinates": [
    "34.2390664",
    "-118.4332328"
  ],
  "created_at": "Sat, 26 Oct 1985 01:20:00 -0500",
  "updated_at": "Wed, Oct 21 2015 16:29:00 -0500"
}

Locations are the main physical locations where your business operates and where employees, managers, and supervisors are assigned.

Location Object

Parameter	Description
id	integer The unique id of the location.
name	string The name of the location.
address	string The location’s address.
coordinates	string The coordinates of the location.
created_at	date The date the location was created.
updated_at	date The last time the location was updated.

Listing Locations

Example Request

curl https://api.wheniwork.com/2/locations \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("locations");
?>

Example Response

{
  "locations": [
    {
      "id": 136,
      "name": "Downtown",
      "address": "9303 Lyon Drive, Hill Valley, CA 12345",
      "coordinates": [
        "34.2390664",
        "-118.4332328"
      ]
    },
    {
      "id": 137,
      "name": "Uptown",
      "address": "100 Courthouse Square, Hill Valley, CA 12345",
      "coordinates": [
        "34.141362",
        "-118.349732"
      ]
    }
  ]
}

HTTP Request

GET https://api.wheniwork.com/2/locations

Get Existing Location

Example Request

curl https://api.wheniwork.com/2/locations/136 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("locations/136");
?>

Example Response

{
  "location": {
    "id": 136,
    "name": "Downtown",
    "address": "9303 Lyon Drive, Hill Valley, CA 12345",
    "coordinates": [
      "34.2390664",
      "-118.4332328"
    ]
  }
}

HTTP Request

GET https://api.wheniwork.com/2/locations/{id}

Parameters

Key	Description
id	ID of the location requested.

Create/Update Location

Create HTTP Request

POST https://api.wheniwork.com/2/locations/

Update HTTP Requests

PUT https://api.wheniwork.com/2/locations/{id}

Parameters

The POST and/or PUT body can include fields from the Location Object.

Delete Existing Location

Example Request

curl -X DELETE https://api.wheniwork.com/2/locations/136 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->delete("locations/136");
?>

Example Response

{
  "success": true
}

Locations can be deleted by managers.

HTTP Request

DELETE https://api.wheniwork.com/2/locations/{id}

Parameters

Key	Description
id	ID of the location to be deleted.

Sites

Example Object

{
  "id": 9,
  "name": "Twin Pines",
  "locationid": 136,
  "address": "1600 S Azusa Ave, City of Industry, CA 91748",
  "coordinates": [
    "33.9935161",
    "-117.9264044"
  ]
}

Sites are off-site locations where users of a location can be assigned and scheduled.

Site Object

Parameter	Description
id	integer The unique ID of the site.
name	string The name of the site.
locationid	integer The ID of the location that the site belongs to.
address	string The address of the site.
coordinates	array The new coordinates for the site, as an array of comma separated values.

Listing Sites

Example Request

curl https://api.wheniwork.com/2/sites \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("sites");
?>

Example Response

{
  "sites": [
    {
      "id": 9,
      "name": "Twin Pines",
      "locationid": 136
    },
    {
      "id": 4,
      "name": "Lone Pine",
      "locationid": 136
    }
  ]
}

HTTP Request

GET https://api.wheniwork.com/2/sites

Get Existing Site

Example Request

curl https://api.wheniwork.com/2/sites/9 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("sites/9");
?>

Example Response

{
  "site": {
    "id": 9,
    "name": "Twin Pines",
    "locationid": 136
  }
}

HTTP Request

GET https://api.wheniwork.com/2/sites/{id}

Parameters

Key	Description
id	ID of the site requested.

Create/Update Site

Create HTTP Request

POST https://api.wheniwork.com/2/sites/

Update HTTP Requests

PUT https://api.wheniwork.com/2/sites/{id}

Parameters

The POST and/or PUT body can include fields from the Site Object.

Delete Existing Site

Example Request

curl -X DELETE https://api.wheniwork.com/2/sites/9 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->delete("sites/9");
?>

Example Response

{
  "success": true
}

HTTP Request

DELETE https://api.wheniwork.com/2/sites/{site_id}

Parameters

Key	Description
site id	ID of the site to be deleted.

Blocks

Example Object

{
  "id": 233,
  "account_id": 0,
  "location_id": 14,
  "position_id": 7,
  "start_time": "16:00:00",
  "end_time": "21:30:00",
  "color": "b38dd9",
  "break_time": 0.5,
  "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
  "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
}

Blocks

Block Object

Parameter	Description
id	integer The unique ID of the shift block.
account_id	integer The ID of the account the shift block is attached to.
location_id	integer The ID of the location the shift block is for.
position_id	integer The ID of the position that the shift is designated for.
start_time	date time The start time for the shift block.
end_time	date time The end time for the shift block.
color	hexadecimal The hexadecimal value of the color for the shift block.
break_time	float The unpaid break time (in hours) for the shift block
created_at	datetime Date at which the shift block was created.
updated_at	datetime Date the shift block was most recently updated.

Listing Shift Blocks

Example Request

curl https://api.wheniwork.com/2/blocks \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("blocks");
?>

Example Response

{
  "blocks": [
    {
      "id": 233,
      "start_time": "16:00:00",
      "end_time": "21:30:00"
    },
    {
      "id": 183,
      "start_time": "06:00:00",
      "end_time": "14:30:00"
    }
    {
      "id": 204,
      "start_time": "08:45:00",
      "end_time": "16:30:00"
    }

  ]
}

HTTP Request

GET https://api.wheniwork.com/2/blocks

Get Existing Shift Block

Example Request

curl https://api.wheniwork.com/2/block/233 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("block/233");
?>

Example Response

{
  "block": {
    "id": 233,
    "start_time": "16:00:00",
    "end_time": "21:30:00"
  }
}

HTTP Request

GET https://api.wheniwork.com/2/blocks/{block_id}

Parameters

Key	Description
block id	ID of the shift block being requested.

Create/Update Shift Block

Create HTTP Request

POST https://api.wheniwork.com/2/blocks/

Update HTTP Requests

PUT https://api.wheniwork.com/2/blocks/{block id}

Parameters

The POST and/or PUT body can include fields from the Block Object.

Delete Existing Shift Block

Example Request

curl -X DELETE https://api.wheniwork.com/2/blocks/233 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->delete("blocks/233");
?>

Example Response

{
  "success": true
}

HTTP Request

DELETE https://api.wheniwork.com/2/blocks/{block_id}

Parameters

Key	Description
block id	ID of the shift block to be deleted.

Requests

Example Object

{
  "id": 54,
  "account_id": 0,
  "user_id": 135,
  "creator_id": 135,
  "status": 0,
  "type": 0,
  "start_time": "Fri, 14 Mar 2014 00:00:00 -0500",
  "end_time": "Fri, 21 Mar 2014 00:00:00 -0500",
  "created_at": "Wed, 19 Feb 2014 10:51:33 -0600",
  "updated_at": "Wed, 19 Feb 2014 10:51:33 -0600"
}

Requests

Request Object

Parameter	Description
id	integer The unique ID of the request.
account_id	integer The ID of the account this request belongs to.
user_id	integer The ID of the user.
creator_id	integer The ID of the user creating the request.
status	integer Status of the request
type	integer Type of request.
start_time	datetime Start time of request.
end_time	datetime End time of request.
created_at	datetime The date and time the request was created.
updated_at	datetime The date and time the request was last updated.

Listing Requests

Example Request

curl https://api.wheniwork.com/2/requests?start=2012-03-01&end=2012-04-30&max_id=42 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("requests", array(
                                "start" => "2012-03-01",
                                "end"  => "2012-04-3",
                                "max_id" => 42
                              ));
?>

Example Response

{
  "requests": [
    {
      "id": 54,
      "user_id": 135,
      "creator_id": 135,
      "status": 0,
      "type": 0,
      "start_time": "Fri, 14 Mar 2014 00:00:00 -0500",
      "end_time": "Fri, 21 Mar 2014 00:00:00 -0500"
    },
    {
      "id": "55",
      "user_id": 135,
      "creator_id": 135,
      "status": 0,
      "type": 0,
      "start_time": "Mon, 24 Mar 2014 08:00:00 -0600",
      "end_time": "Fri, 28 Mar 2014 08:00:00 -0600"
    },
  ],
  "messages": [
    {
      "id": 61,
      "user_id": 135,
      "request_id": "54",
      "title": "This is a message title.",
      "content": "This request has been canceled."
    },
    {
      "id": "66",
      "user_id": 135,
      "request_id": "54",
      "title": "Request Approved",
      "content": "This request has been canceled.",
      "message": "This Request has been approved"
    },
    {
      "id": "68",
      "user_id": 135,
      "request_id": "55",
      "title": "Request Approved",
      "content": "This request has been canceled.",
      "message": "This Request has been approved"
    },
  ],
  "users": [
   {
      "id": 135,
      "first_name": "Goldie",
      "last_name": "Wilson",
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "phone_number": "555-555-5555"
    },
   {
      "id": 27384,
      "first_name": "Emmett",
      "last_name": "Brown",
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "phone_number": "555-555-5555"
    }
  ]
}

List requests for given parameters

HTTP Request

GET https://api.wheniwork.com/2/requests?start=2012-03-01&end=2012-04-30&max_id=58

Parameters

Key	Description
start	The start date for the request time-frame.
end	End time for the request time-frame.
since_id	Return all requests created since the request with given ID.
max_id	Return all requests created before the request with the given ID.

Get Existing Request

Example Request

curl https://api.wheniwork.com/2/requests/65 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("requests/65");
?>

Example Response

{
  "request": {
    "id": 54,
    "user_id": 135,
    "creator_id": 135,
    "status": 0,
    "type": 0,
    "start_time": "Fri, 14 Mar 2014 00:00:00 -0500",
    "end_time": "Fri, 21 Mar 2014 00:00:00 -0500"
  },
  "messages": [
   {
      "id": 61,
      "user_id": 135,
      "request_id": "54",
      "title": "This is a message title.",
      "content": "This request has been canceled."
    },
   {
      "id": "66",
      "user_id": 135,
      "request_id": "54",
      "title": "Request Approved",
      "content": "This request has been canceled.",
      "message": "This Request has been approved"
    },
  ],
  "users": [
   {
      "id": 135,
      "first_name": "Goldie",
      "last_name": "Wilson",
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "phone_number": "555-555-5555"
    },
   {
      "id": 27384,
      "first_name": "Emmett",
      "last_name": "Brown",
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "phone_number": "555-555-5555"
    }
  ]
}

HTTP Request

GET https://api.wheniwork.com/2/requests/{request_id}

Parameters

Key	Description
request id	ID of the request.

Create/Update Request

Example POST Data

{
   "user_id": "135",
   "type": "1",
   "start_time":"2012-02-25 8:00",
   "end_time":"2012-05-25 17:00",
   "status":0

}

Example Request

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->create("requests", array(
                                 "user_id" => "135",
                                 "type" => "1",
                                 "start_time" => "2012-02-25 8:00",
                                 "end_time" => "2012-05-25 17:00",
                                 "status" => 0
                              ));
?>

Example Response

{
    "request": {
    "id": 56,
    "account_id": 3,
    "user_id": 135,
    "creator_id": 135,
    "status": 0,
    "type": 0,
    "start_time": "Sat, 25 Feb 2012 08:00:00 -0600",
    "end_time": "Fri, 25 May 2012 17:00:00 -0500",
    "created_at": "Fri, 27 Apr 2012 11:33:53 -0500",
    "updated_at": "Fri, 27 Apr 2012 11:33:53 -0500"
    }
}

Create HTTP Request

`POST https://api.wheniwork.com/2/requests/‘

Parameters

Key	Description
user_id	The ID of the user for whom the request is to be created.
type	The type of request
start_time	The start date and time for the request.
end_time	The end date and time for the request.
since_id	Return all requests created since the request with given ID.
status	The status for the request to be created.

Update HTTP Requests

PUT https://api.wheniwork.com/2/requests/{request id}

Parameters

The PUT body can include fields from the Request Object.

Delete Existing Request

Example Request

curl -X DELETE https://api.wheniwork.com/2/requests/54 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->delete("requests/54");
?>

Example Response

{
  "success": true
}

HTTP Request

DELETE https://api.wheniwork.com/2/requests/{request_id}

Parameters

Key	Description
request id	ID of the request to be deleted.

Swaps

Example Object

{
  "id": "2238",
  "account_id": 0,
  "user_id": 145,
  "type": 1,
  "status": 0,
  "accepted_id": 0,
  "statuses": [
    {"user_id":23,"status":0,"shift_id":0},
    {"user_id":24,"status":0,"shift_id":0}
  ]
}

Swaps

Swap Object

Parameter	Description
id	integer The unique ID of the swap.
account_id	integer The ID of the account associated with the swap.
user_id	integer The ID of the user who initiated the swap.
type	integer The type of swap. (1 = swap, 2 = drop, 3 = alert)
status	integer The status of the swap. (0 = Pending, 1 = Approved, 2 = Declined, 3 = Completed, 4 = Canceled, 5 = Expired)
accepted_id	integer The ID of the user who took the shift
statuses	array An array of user shift acceptance statuses.

Listing Swaps

Example Request

curl https://api.wheniwork.com/2/swaps/ \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("swaps");
?>

Example Response

{
  "swaps": [
  {
      "id": "2238",
      "user_id": 145,
      "type": 1,
      "status": 0,
      "accepted_id": 0
    }
  ],
  "messages" : [
  {
      "id": 61,
      "user_id": 135,
      "request_id": 123,
      "swap_id": "2238",
      "title": "This is a message title.",
      "content": "This request has been canceled."
    }
  ],
  "shifts" : [
  {
      "id": 10000,
      "start_time": "Fri, 07 Mar 2014 08:30:00 -0600",
      "end_time": "Fri, 07 Mar 2014 14:30:00 -0600"
    }
  ],
  "users" : [
  {
      "id": 4364,
      "first_name": "Goldie",
      "last_name": "Wilson",
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "phone_number": "555-555-5555"
    },
  {
      "id": 27384,
      "first_name": "Emmett",
      "last_name": "Wilson",
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "phone_number": "555-555-5555"
    }
  ]
}

HTTP Request

GET https://api.wheniwork.com/2/swaps

Get Existing Swap

Example Request

curl https://api.wheniwork.com/2/swaps/22 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("swaps/22");
?>

Example Response

{
  "swaps": [
    {
      "id": "2238",
      "user_id": 145,
      "type": 1,
      "status": 0,
      "accepted_id": 0
    }
    ],
    "messages" : [
    {
      "id": 61,
      "user_id": 135,
      "request_id": 123,
      "swap_id": "2238",
      "title": "This is a message title.",
      "content": "This request has been canceled."
    }
    ],
    "shifts" : [
    {
      "id": 10000,
      "start_time": "Fri, 07 Mar 2014 08:30:00 -0600",
      "end_time": "Fri, 07 Mar 2014 14:30:00 -0600"
    }
    ],
    "users" : [
    {
      "id": 4364,
      "first_name": "Goldie",
      "last_name": "Wilson",
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "phone_number": "555-555-5555"
    },
    {
      "id": 27384,
      "first_name": "Emmett",
      "last_name": "Wilson",
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "phone_number": "555-555-5555"
    }
    ]
}

HTTP Request

GET https://api.wheniwork.com/2/swaps/{swap_id}

Parameters

Key	Description
swap id	ID of the swap being requested.

Create/Update Swap

Example Post Data

{
    "shift_id":1046,
    "type": 3,
    "shifts":[1047],
    "users":[134,132,110]
}

Example Request

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->create("swaps", array(
                                 "shift_id" => 1046,
                                 "type" => 3,
                                 "shifts" => "1047",
                                 "users" => array(134,132,110)
                              ));
?>

Example Response Object

{
    "swaps": [
    {
      "id": "2238",
      "user_id": 145,
      "type": 1,
      "status": 0,
      "accepted_id": 0
    }
    ],
    "messages" : [
    {
      "id": 61,
      "user_id": 135,
      "request_id": 123,
      "swap_id": "2238",
      "title": "This is a message title.",
      "content": "This request has been canceled."
    }
    ],
    "shifts" : [
    {
      "id": "1047",
      "start_time": "Fri, 07 Mar 2014 08:30:00 -0600",
      "end_time": "Fri, 07 Mar 2014 14:30:00 -0600"
    },
    {
      "id": "1046",
      "start_time": "Fri, 07 Mar 2014 08:30:00 -0600",
      "end_time": "Fri, 07 Mar 2014 14:30:00 -0600"
    }
    ],
    "users" : [
    {
      "id": 134,
      "first_name": "Emmett",
      "last_name": "Brown",
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "phone_number": "555-555-5555"
    },
    {
      "id": 132,
      "first_name": "Lorraine",
      "last_name": "Tannen",
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "phone_number": "555-555-5555"
    },
    {
      "id": 110,
      "first_name": "Goldie",
      "last_name": "Wilson",
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "phone_number": "555-555-5555"
    }
    ]

}

Create HTTP Request

POST https://api.wheniwork.com/2/swaps/

Key	Description
shift id	ID of the shift being swapped.
type	The type of swap to be created.
shifts	The IDs of the shifts requested to be swapped for.
users	The IDs of users available to take shifts.

Update HTTP Requests

PUT https://api.wheniwork.com/2/swaps/{swap id}

Parameters

The PUT body can include fields from the Swap Object.

Delete Existing Swap

Example Request

curl -X DELETE https://api.wheniwork.com/2/swap/233 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->delete("swap/233");
?>

Example Response

{
  "success": true
}

HTTP Request

DELETE https://api.wheniwork.com/2/swap/{swap_id}

Parameters

Key	Description
swap id	ID of the swap to be deleted.

Availabilities

Example Object

{
  "id": 10,
  "account_id": 77,
  "user_id": 371,
  "name": "Emmett's availability preferences.",
  "description": "Emmett B.'s summer availability",
  "start_date": "Tue, 1 Jun 2014",
  "end_date": "Fri, 13 Apr 2012",
  "ongoing": false,
  "repeat": 1,
  "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
  "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
}

Availabilities are objects that define a user’s availability to be assigned shifts during a certain period of time.

Availability Object

Parameter	Description
id	integer The unique ID of the availability.
account_id	integer The ID of the account that this user’s availability is tied to.
user_id	integer The ID of the user tied to the availability.
name	string The name of the availability.
description	string The description for the availability
start_date	date The starting date of the time period the availability is designated for.
end_date	date The ending date of the time period the availability is designated for.
ongoing	boolean Is the availability the user’s ongoing availability.
repeat	integer The repeat value for availability.
created_at	datetime Date at which the availability was created.
updated_at	datetime Date the availability was most recently updated.

Listing Availabilities

Example Request

curl https://api.wheniwork.com/2/availabilities \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("availabilities");
?>

Example Response

{
  "availabilities": [
    {
      "id": 10,
      "user_id": 371,
      "name": "Emmett's availability preferences.",
      "description": "Emmett B.'s summer availability"
    },
    {
      "id": 11,
      "user_id": 453,
      "name": "George's availability",
      "description": "George M.'s School Year Availability"
    }
    {
      "id": 12,
      "user_id": 456,
      "name": "Lorraine's availability",
      "description": "Lorraine B.'s Winter Availability"
    }

  ]
}

HTTP Request

GET https://api.wheniwork.com/2/availabilities?user_id=371,453,456

Get Existing Availability

Example Request

curl https://api.wheniwork.com/2/availabilities/10 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("availabilities/10");
?>

Example Response

{
  "availability": {
    "id": 10,
    "user_id": 371,
    "name": "Emmett's availability preferences.",
    "description": "Emmett B.'s summer availability"
  },
  "availabilityitems": [
    {
      "id": 85,
      "availability_id": 10,
      "day": 0,
      "start_time": "07:15:00",
      "end_time": "16:00:00"
    },
    {
      "id": 12,
      "availability_id": 10,
      "day": 1,
      "start_time": "08:00:00",
      "end_time": "18:30:00"
    },
    {
      "id": 13,
      "availability_id": 10,
      "day": 3,
      "start_time": "05:00:00",
      "end_time": "14:00:00"
    },
    {
      "id": 14,
      "availability_id": 10,
      "day": 5,
      "start_time": "011:00:00",
      "end_time": "23:15:00"
    }
  ]

}

HTTP Request

GET https://api.wheniwork.com/2/availabilities/{availability_id}

Parameters

Key	Description
availability id	ID of the availability object being requested.

Get Availability Items

Get all availabilities for a specified group of users for a specified time-frame.

Example Request

curl https://api.wheniwork.com/2/availabilities/items?user_id=371&start=2014-01-01 8:00am&end=2014-09-01 10:00pm \
 -H "W-Token: ilovemyboss"

Example Response

{
  "availability": {
    "id": 10,
    "user_id": 371,
    "name": "Emmett's availability preferences.",
    "description": "Emmett B.'s summer availability"
  },
  "availabilityitems": [
    {
      "id": 85,
      "availability_id": 10,
      "day": 0,
      "start_time": "07:15:00",
      "end_time": "16:00:00"
    },
    {
      "id": 12,
      "availability_id": 10,
      "day": 1,
      "start_time": "08:00:00",
      "end_time": "18:30:00"
    },
    {
      "id": 13,
      "availability_id": 10,
      "day": 3,
      "start_time": "05:00:00",
      "end_time": "14:00:00"
    },
    {
      "id": 14,
      "availability_id": 10,
      "day": 5,
      "start_time": "011:00:00",
      "end_time": "23:15:00"
    }
  ]

}

HTTP Request

GET https://api.wheniwork.com/2/availabilities/items?{user_ids_array}&{start_datetime}&{end_datetime}

Parameters

Key	Description
user ids array	An array of user IDs to search.
start datetime	The start date and time you are searching in.
end datetime	The end date and time you are searching in.

Create/Update Availability

Create HTTP Request

POST https://api.wheniwork.com/2/availabilities/

Update HTTP Requests

PUT https://api.wheniwork.com/2/availabilities/{availability id}

Parameters

The POST and/or PUT body can include fields from the Availability Object.

Delete Existing Availability

Example Request

curl -X DELETE https://api.wheniwork.com/2/availabilities/10 \
 -H "W-Token: ilovemyboss"

<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->delete("availabilities/10");
?>

Example Response

{
  "success": true
}

HTTP Request

DELETE https://api.wheniwork.com/2/availabilities/{availability_id}

Parameters

Key	Description
availability id	ID of the availability to be deleted.

Payrolls

Example Object

{
  "id": 24,
  "account_id": 0,
  "creator_id": 0,
  "start_date": "Wed, 26 Feb 2014 00:00:00 -0600",
  "end_date": "Tue, 11 Mar 2014 23:59:59 -0500",
  "notes": "",
  "is_closed": true,
  "is_finalized": true,
  "finalized_at": "Tue, 29 Nov -001 18:00:00 -0600",
  "created_at": "Wed, 19 Feb 2014 10:51:33 -0600",
  "updated_at": "Wed, 19 Feb 2014 10:51:33 -0600"
}

User Object

Parameter	Description
id	integer The unique ID for this payroll item.
account_id	integer The account ID that this payroll item belongs to.
creator_id	integer The user ID of the person who created the payroll item.
start_date	datetime The start date of the payroll period,
end_date	datetime The start date of the payroll period,
notes	string Notes for the payroll period.
is_closed	boolean True if the payroll period is closed
is_finalized	boolean True if the payroll period has been finalized.
finalized_at	datetime The date and time that the payroll period was finalized.
created_at	datetime The date and time the payroll period was created.
updated_at	datetime The date and time the payroll period was last updated.

Listing Payrolls

Example Request

curl https://api.wheniwork.com/2/payrolls \
 -H "W-Token: ilovemyboss"

Example Response

{
  "payrolls": [
   {
      "id": 24,
      "start_date": "Wed, 26 Feb 2014 00:00:00 -0600",
      "end_date": "Tue, 11 Mar 2014 23:59:59 -0500",
      "notes": "",
      "finalized_at": "Tue, 29 Nov -001 18:00:00 -0600"
    },
    {
      "id": 25,
      "start_date": "Wed, 12 Feb 2014 00:00:00 -0600",
      "end_date": "Tue, 25 Feb 2014 00:00:00 -0600",
      "notes": "",
      "finalized_at": "Tue, 29 Nov -001 18:00:00 -0600"
    },
    {
      "id": 26,
      "start_date": "Wed, 29 Jan 2014 00:00:00 -0600",
      "end_date": "Tue, 11 Feb 2014 00:00:00 -0600",
      "notes": "",
      "finalized_at": "Tue, 29 Nov -001 18:00:00 -0600"
    },
  ]
}

This method allows you to list payroll periods or find ones within a specified date range

HTTP Request

`GET https://api.wheniwork.com/2/payrolls/?start={start_date}&end={end_date}

Parameters

Key	Description
start date	Start date of search range (YYYY-MM-DD)
end date	End date of search range (YYYY-MM-DD)

Get Existing Payroll Period

Example Request

curl https://api.wheniwork.com/2/payrolls/24 \
 -H "W-Token: ilovemyboss"

Example Response

{
  "payroll": {
      "id": 24,
      "start_date": "Wed, 26 Feb 2014 00:00:00 -0600",
      "end_date": "Tue, 11 Mar 2014 23:59:59 -0500",
      "notes": "",
      "finalized_at": "Tue, 29 Nov -001 18:00:00 -0600"
    },
  "payrollhours": [
    {
      "id": 100,
      "payroll_id": 24,
      "type": 1,
      "user_id": 4634,
      "position_id": 1,
      "hours": 20.25,
      "rate": 15.75
    },
    {
      "id": 101,
      "payroll_id": 24,
      "type": 1,
      "user_id": 4634,
      "position_id": 1,
      "hours": 10,
      "rate": 10,
      "total": 100
    },
    {
      "id": 102,
      "payroll_id": 24,
      "type": 1,
      "user_id": 4634,
      "position_id": 1,
      "hours": 5,
      "rate": 11,
      "total": 55
    }
  ]
}

HTTP Request

GET https://api.wheniwork.com/2/payrolls/{id}

Parameters

Key	Description
id	ID of the pay period requested.

Create / Update Payroll

Update HTTP Requests

PUT https://api.wheniwork.com/2/payrolls/{id}

Parameters

The PUT body can include fields from the Payroll Object.

Delete Existing Payroll

Times

Example Object

{
  "id": 11,
  "account_id": 0,
  "user_id": 4634,
  "creator_id": 4634,
  "position_id": 1,
  "location_id": 136,
  "site_id": 9,
  "shift_id": 1000,
  "start_time": "Fri, 07 Mar 2014 08:30:00 -0600",
  "end_time": "Fri, 07 Mar 2014 14:30:00 -0600",
  "length": 6,
  "hourly_rate": 20,
  "is_alerted": true,
  "alert_type": 8,
  "is_approved": true,
  "modified_by": 202,
  "updated_at": "Wed, 19 Feb 2014 10:51:33 -0600",
  "created_at": "Wed, 19 Feb 2014 10:51:33 -0600"
}

User Object

Parameter	Description
id	integer The unique ID for this time entry.
account_id	integer The ID of the account this entry is associated with.
user_id	integer The ID of the user that this time entry is for.
creator_id	integer The ID of the user who created this time entry.
position_id	integer The ID of the position that is associated with this entry.
location_id	integer The ID of the location that is associated with this entry.
site_id	integer The ID of the site that is associated with this time entry.
shift_id	integer The ID of the shift that correlates to this time entry.
start_time	date time The start date and time of the time entry.
end_time	datetime End time of the time entry.
length	float The length of the time entry. (readonly)
hourly_rate	float Hourly rate for this time entry.
is_alerted	boolean True if an alert needs to be created for this shift.
alert_type	integer The type of alert created.
is_approved	boolean True if the time entry has been approved.
modified_by	integer The ID of the user who modified the time entry.
updated_at	datetime The date and time the time entry was last updated.
created_at	datetime The date and time the time entry was created.

Listing Times

Example Request

curl https://api.wheniwork.com/2/times \
 -H "W-Token: ilovemyboss"

Example Response

{
  "times": [
    {
      "id": 11,
      "user_id": 4634,
      "creator_id": 4634,
      "position_id": 1,
      "location_id": 136,
      "site_id": 9,
      "shift_id": 1000,
      "start_time": "Fri, 07 Mar 2014 08:30:00 -0600",
      "end_time": "Fri, 07 Mar 2014 14:30:00 -0600",
      "length": 6,
      "hourly_rate": 20
    },

   ],
  "punches": [
    {
      "id": 150134,
      "time_id": 11,
      "user_id": 4634,
      "location_id": 136,
      "site_id": 0,
      "type": 1
    },
    {
      "id": 150135,
      "time_id": 11,
      "user_id": 4634,
      "location_id": 136,
      "site_id": 0,
      "type": 2
    }
  ],
  "shifts": [
   {
      "id": 10000,
      "start_time": "Fri, 07 Mar 2014 08:30:00 -0600",
      "end_time": "Fri, 07 Mar 2014 14:30:00 -0600"
    }
  ],
  "users": [
    {
      "id": 4364,
      "first_name": "Goldie",
      "last_name": "Wilson",
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "phone_number": "555-555-5555"
    }
  ]
}

This method allows you to list times or find ones within a specified date range

HTTP Request

`GET https://api.wheniwork.com/2/times/?start={start_date}&end={end_date}

Parameters

Key	Description
start date	Start date of search range (YYYY-MM-DD)
end date	End date of search range (YYYY-MM-DD)

Get Existing Time

Example Request

curl https://api.wheniwork.com/2/times/11 \
 -H "W-Token: ilovemyboss"

Example Response

{
  "times": [
      {
      "id": 11,
      "user_id": 4634,
      "creator_id": 4634,
      "position_id": 1,
      "location_id": 136,
      "site_id": 9,
      "shift_id": 1000,
      "start_time": "Fri, 07 Mar 2014 08:30:00 -0600",
      "end_time": "Fri, 07 Mar 2014 14:30:00 -0600",
      "length": 6,
      "hourly_rate": 20
    },

  ]
}

HTTP Request

GET https://api.wheniwork.com/2/times/{id}

Parameters

Key	Description
id	ID of the time requested.

Get User Times

Example Request

curl https://api.wheniwork.com/2/times/user/4634 \
 -H "W-Token: ilovemyboss"

Example Response

{
    "user": {
        "id": 4634,
        "email": "goldiewilson@hillvalleycalifornia.gov",
        "first_name": "Goldie",
        "last_name": "Wilson",
        "positions": [
            32,
            5
        ],
        "locations": [
            136
        ],
        "punch_state": {
            "timestamp": "Wed, 02 Apr 2014 16:21:36 -0500",
            "can_punch_in": false,
            "can_punch_out": true,
            "open_time_id": 158049,
            "near_location_id": null,
            "near_site_id": null,
            "punch_in_shift_id": 1000
        }
    },
    "times": [
      {
      "id": 11,
      "user_id": 4634,
      "creator_id": 4634,
      "position_id": 1,
      "location_id": 136,
      "site_id": 9,
      "shift_id": 1000,
      "start_time": "Fri, 07 Mar 2014 08:30:00 -0600",
      "end_time": "Fri, 07 Mar 2014 14:30:00 -0600",
      "length": 6,
      "hourly_rate": 20
    }
    ],
    "shifts": [
      {
      "id": 10000,
      "start_time": "Fri, 07 Mar 2014 08:30:00 -0600",
      "end_time": "Fri, 07 Mar 2014 14:30:00 -0600"
    }
    ],
    "locations": [
      {
      "id": 136,
      "name": "Downtown",
      "address": "9303 Lyon Drive, Hill Valley, CA 12345",
      "coordinates": [
        "34.2390664",
        "-118.4332328"
      ]
    }
    ],
    "positions": [
      {
      "id": 32,
      "name": "Stocker",
      "color": "1174a6"
    }
    ]

}

This method allows you to get times for a specific user. This request also gives you the user’s punch state.

HTTP Request

`GET https://api.wheniwork.com/2/times/?start={start_date}&end={end_date}

Create / Update Times

Update HTTP Requests

PUT https://api.wheniwork.com/2/times/{id}

Parameters

The PUT body can include fields from the Times Object.

Delete Existing Payroll

Example Request

curl -X DELETE https://api.wheniwork.com/2/times/123 \
 -H "W-Token: ilovemyboss"

Example Response

{
  "success": true
}

HTTP Request

DELETE https://api.wheniwork.com/2/times/{id}

Parameters

Key	Description
id	ID of the time object to be deleted.

Batch

Example Post Data

[{
    "method":"get",
    "url":"/rest/shifts",
    "params":{
        "start":"Sun, 15 Apr 2012 00:00:00",
        "end":"Sat, 21 Apr 2012 23:59:59",
        "unpublished":true,
        "include_allopen":true
    }
},
{
    "method":"get",
    "url":"/rest/requests",
    "params":{
        "start":"Sun, 15 Apr 2012 00:00:00",
        "end":"Sat, 21 Apr 2012 23:59:59",
        "include_pending":true,
        "status":"0,2"
    }
},
{
    "method":"get",
    "url":"/rest/availabilities/items",
    "params":{
        "start":"Sun, 15 Apr 2012 00:00:00",
        "end":"Sat, 21 Apr 2012 23:59:59"
    }
}]

Example Request

curl https://api.wheniwork.com/2/batch \
 -H "W-Token: ilovemyboss"

Batch allows you to execute multiple requests at the same time.

HTTP Request

POST https://api.wheniwork.com/2/batch

Parameters

Key	Description
method	POST, GET, PUT or DELETE
url	The method you are requesting
params	The parameters of your request as defined in the individual methods.

Messages

Example Object

{
  "id": 61,
  "account_id": 0,
  "user_id": 135,
  "request_id": 123,
  "swap_id": 0,
  "conversation_id": 0,
  "title": "This is a message title.",
  "content": "This request has been canceled.",
  "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
  "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
}

Messages

Message Object

Parameter	Description
id	integer The unique ID of the message.
account_id	integer The account ID that the message is associated with.
user_id	integer The ID of the user.
request_id	integer The ID of the request the message is for.
swap_id	integer The ID of the swap the message is for.
conversation_id	integer The ID of the conversation the message is a part of.
title	string The title of the message.
content	string The content of the message.
created_at	datetime Date at which the message was created.
updated_at	datetime Date the message was most recently updated.

Listing Messages

List messages for given parameters

Example Request

curl https://api.wheniwork.com/2/messages?request_id=123 \
 -H "W-Token: ilovemyboss"

Example Response

{
  "messages": [
    {
      "id": 61,
      "user_id": 135,
      "request_id": 123,
      "title": "This is a message title.",
      "content": "This request has been canceled."
    },
    {
      "id": 456,
      "user_id": 14,
      "request_id": 123,
      "title": "Approved",
      "content": "This request has been approved"
    }
    {
      "id": 789,
      "user_id": 14,
      "request_id": 123,
      "title": "Canceled",
      "content": "This request has been canceled again."
    }

  ]
}

HTTP Request

GET https://api.wheniwork.com/2/messages?swap_id={swap_id}&request_id={request_id}&conversation_id={conversation_id}

Parameters

Key	Description
swap	ID of the shift block being requested.

Only one of the parameters is required, but they can also be combined.

Get Existing Message

Example Request

curl https://api.wheniwork.com/2/messages/61 \
 -H "W-Token: ilovemyboss"

Example Response

{
  "message": {
    "id": 61,
    "user_id": 135,
    "request_id": 123,
    "title": "This is a message title.",
    "content": "This request has been canceled."
  }
}

HTTP Request

GET https://api.wheniwork.com/2/messages/{message_id}

Parameters

Key	Description
message id	ID of the shift block being requested.

Create/Update Message

Create HTTP Request

POST https://api.wheniwork.com/2/messages/

Update HTTP Requests

PUT https://api.wheniwork.com/2/messages/{message id}

Parameters

The POST and/or PUT body can include fields from the Message Object.

Delete Existing Message

Example Request

curl -X DELETE https://api.wheniwork.com/2/messages/61 \
 -H "W-Token: ilovemyboss"

Example Response

{
  "success": true
}

HTTP Request

DELETE https://api.wheniwork.com/2/messages/{message_id}

Parameters

Key	Description
message id	ID of the message to be deleted.

Send

Example Post Data

{
  "ids": [
    145,
    245
  ],
  "subject": "Open shift up for grabs!",
  "message": "We have an open shift available on Tuesday from 1:00 PM to 10:00 PM"
}

Send and email to a group of users.

Send Object

Parameter	Description
ids	array An array of user IDs to send the email to.
subject	string The subject of the email notification.
message	string The email notification message content.

Example Request

curl https://api.wheniwork.com/2/send \
 -H "W-Token: ilovemyboss"

HTTP Request

POST https://api.wheniwork.com/2/send

Response

An empty array is returned upon success.

Templates

Example Object

{
  "id": 12,
  "account_id": 1946,
  "location_id": 0,
  "user_id": 1,
  "start_date": "Mon, 17 Feb 2014",
  "end_date": "Sun, 23 Feb 2014",
  "name": "Winter Schedule",
  "description": "Our weekly schedule for December - March.",
  "created_at": "Wed, 19 Feb 2014 10:51:33 -0600",
  "updated_at": "Wed, 19 Feb 2014 10:51:33 -0600"
}

Templates allow you to create a group of shifts that can be used to make scheduling easier.

Template Object

Parameter	Description
id	integer The unique ID of the template.
account_id	integer The ID of the account the template belongs to.
location_id	integer The location ID for the shift template.
user_id	integer The ID of the user who created the template.
start_date	date time The start date for the template.
end_date	date time The start date for the template.
name	string A name for the template.
description	string A description for the template
created_at	datetime The date and time the template was created.
updated_at	datetime The date and time the template was last updated.

Listing Templates

Example Request

curl https://api.wheniwork.com/2/templates/ \
 -H "W-Token: ilovemyboss"

Example Response

{
  "templates": [
    {
      "id": 12,
      "location_id": 0,
      "user_id": 1,
      "start_date": "Mon, 17 Feb 2014",
      "end_date": "Sun, 23 Feb 2014",
      "name": "Winter Schedule",
      "description": "Our weekly schedule for December - March."
    }
  ],
  "templateshifts" : [
     {
      "id": "38383",
      "template_id": 12,
      "user_id": 44,
      "location_id": 15,
      "position_id": 2,
      "site_id": 0,
      "start_time": "Tue, 18 Feb 2014 08:00:00 -0500",
      "end_time": "Tue, 18 Feb 2014 15:00:00 -0500"
    }
  ]
}

HTTP Request

GET https://api.wheniwork.com/2/templates

Get Existing template

Example Request

curl https://api.wheniwork.com/2/templates/12 \
 -H "W-Token: ilovemyboss"

Example Response

{
  "templates": [
    {
      "id": 12,
      "location_id": 0,
      "user_id": 1,
      "start_date": "Mon, 17 Feb 2014",
      "end_date": "Sun, 23 Feb 2014",
      "name": "Winter Schedule",
      "description": "Our weekly schedule for December - March."
    }
  ],
  "templateshifts" : [
   {
      "id": "38383",
      "template_id": 12,
      "user_id": 44,
      "location_id": 15,
      "position_id": 2,
      "site_id": 0,
      "start_time": "Tue, 18 Feb 2014 08:00:00 -0500",
      "end_time": "Tue, 18 Feb 2014 15:00:00 -0500"
    },
    {
      "id": "144",
      "template_id": 12,
      "user_id": 44,
      "location_id": 15,
      "position_id": 2,
      "site_id": 0,
      "start_time": "Tue, 18 Feb 2014 08:00:00 -0600",
      "end_time": "Tue, 18 Feb 2014 17:00:00 -0600"
    },
    {
      "id": "148",
      "template_id": 12,
      "user_id": 44,
      "location_id": 15,
      "position_id": 2,
      "site_id": 0,
      "start_time": "Wed, 19 Feb 2014 08:30:00 -0600",
      "end_time": "Wed, 19 Feb 2014 16:00:00 -0600"
    },
  ]

}

HTTP Request

GET https://api.wheniwork.com/2/templates/{template_id}

Parameters

Key	Description
template id	ID of the template being requested.

Create/Update template

Example Request Object

{
      "name":"Cafe 80's October template",
      "start":"2015-10-01",
      "end":"2015-10-31",
      "ids":[{"user_id":135,"location_id":137,"position_id":172}]

}

Example Response Object

{

  "templates": [
    {
      "id": 12,
      "location_id": 137,
      "user_id": "135",
      "start_date": "Mon, 17 Feb 2014",
      "end_date": "Sun, 23 Feb 2014",
      "name": "Cafe 80's February Shift Template",
      "description": "Our weekly schedule for December - March.",
      "start": "2014-02-01",
      "end": "2014-02-28",
      "position_id": "172"
    }
  ],
  "templateshifts" : [
   {
      "id": "38383",
      "template_id": 12,
      "user_id": "135",
      "location_id": 137,
      "position_id": "172",
      "site_id": 0,
      "start_time": "Tue, 18 Feb 2014 08:00:00 -0500",
      "end_time": "Tue, 18 Feb 2014 15:00:00 -0500"
    },
   ]

}

Create HTTP Request

POST https://api.wheniwork.com/2/templates/

Key	Description
name	The name of the new template.
start	Start date for the new template.
end	End of the time frame for the template.
description	Description of the new template.
ids	IDs of elements to be included in the template.

Update HTTP Requests

PUT https://api.wheniwork.com/2/templates/{template id}

Parameters

The PUT body can include fields from the Template Object.

Delete Existing Template

Example Request

curl -X DELETE https://api.wheniwork.com/2/template/12 \
 -H "W-Token: ilovemyboss"

Example Response

{
  "success": true
}

HTTP Request

DELETE https://api.wheniwork.com/2/template/{template_id}

Parameters

Key	Description
template id	ID of the template to be deleted.

Plans

Example Object

{
  "id": 1,
  "name": "Free",
  "price": 0,
  "price_annual": 0,
  "wb_price": 0,
  "wb_annual": 0,
  "employees": "5",
  "texting": false,
  "texting_price": 0,
  "is_legacy": false,
  "sort": 0
}

Get all plans.

Plan Object

Parameter	Description
id	integer The unique ID of the plan.
name	string The name of the plan.
price	float The price of the plan
price_annual	float The annual cost of the plan.
wb_price	float The WageBase plan cost.
wb_annual	float The WageBase annual plan cost.
employees	integer The number of employees allowed on the plan.
texting	boolean Is texting allowed on this account
texting_price	float The texting cost.
is_legacy	boolean Is this a legacy plan?
sort	integer The sort order of the plan.

Listing Plans

Example Request

curl https://api.wheniwork.com/2/plans \
 -H "W-Token: ilovemyboss"

HTTP Request

POST https://api.wheniwork.com/2/plans

Errors

When I Work uses the following error codes:

Error Code	Meaning
400	Bad Request – Your request sucks
401	Unauthorized – Your API key is wrong or you’re in the wrong place
403	Forbidden – The request is above your permission level
404	Not Found – The specified request could not be found
405	Method Not Allowed – You tried to access a kitten with an invalid method
406	Not Acceptable – You requested a format that isn’t json
410	Gone – The kitten requested has been removed from our servers
418	I’m a teapot
429	Too Many Requests – You’re requesting too many kittens! Slown down!
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Introduction

Libraries

Authentication

Login

Parameters

Web App SSO

Shifts

Shift Object

Listing Shifts

HTTP Request

Parameters

Get Existing Shift

HTTP Request

Parameters

Create/Update Shift

Create HTTP Request

Update HTTP Requests

Post/Put Body

Publish/Unpublish Shifts

HTTP Request

HTTP Request

Parameters

Notify Shifts

HTTP Request

Parameters

HTTP Request

Parameters

Delete Shift

HTTP Request

Parameters

Users

User Object

Listing Users

HTTP Request

Parameters

Get Existing User

HTTP Request

Parameters

Create/Update User

Create HTTP Request

Update HTTP Requests

Parameters

Additional Params

Invite Users

HTTP Request

Parameters

HTTP Request

Parameters

Delete User

HTTP Request

Parameters

Positions

Position Object

Listing Positions

HTTP Request

Get Existing Position

HTTP Request

Parameters

Create/Update Position

Create HTTP Request

Update HTTP Requests

Parameters

Delete Existing Position

HTTP Request

Parameters

Locations

Location Object

Listing Locations

HTTP Request

Get Existing Location

HTTP Request

Parameters

Create/Update Location

Create HTTP Request

Update HTTP Requests

Parameters

Delete Existing Location

HTTP Request

Parameters

Sites