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:

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

Login

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

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.

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.

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

Delete Existing 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("users4364");
?>

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",
  "break_hours": 0.5,
  "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.
break_hours float
Hours of unpaid break.
length float
The length of the time entry.
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 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.