Introduction
The When I Work API is thorough, flexible, and restful. Its 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
Authentication with When I Work is based on a token model. You first authenticate using a private developer key and the username and password of a When I Work user. Your developer key can be used like the following in the headers. See the Login endpoint for more details.
W-Key: iworksoharditsnotfunny
Authenticating will return back a login object containing a token that is used to authenticate all future requests. The token may be included in the headers, as a cookie, or in the query string, using the key W-Token. For example, you might include the following as a header for your request:
W-Token: ilovemyboss
Authenticating will also return back a list of User objects, each of which is associated with a When I Work account. In order to specify which Account you are making requests to, API requests must provide a When I Work user id through the W-UserId header. For example, to make requests on behalf of the When I Work user with id 5, you would include the following header in your request:
W-UserId: 5
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
{
"login": {
"id": 5,
"first_name": "Goldie",
"last_name": "Wilson",
"email": "goldiewilson@hillvalleygov.org",
"token": "ilovemyboss"
},
"users": [
{
"id": 4364,
"login_id": 5,
"account_id": 10000,
"first_name": "Goldie",
"last_name": "Wilson",
},
{
"id": 5475,
"login_id": 5,
"account_id": 12345,
"first_name": "Goldie",
"last_name": "Wilson",
}
],
"accounts": [
{
"id": 10000,
"company": "ABC Company",
},
{
"id": 12345,
"company": "123 Company",
}
]
}
Show hidden fieldsHide extra fieldsBe sure to replace
iworksoharditsnotfunnywith your requested Developer Key.
The first thing to do after you receive your Developer Key is to login to get your token. After receiving your token, you will make all future requests using your token in the header of the request.
Once you have the token, you must include it in all authenticated requests.
In addition to the login object, this endpoint returns all User objects associated with the login, and all Account objects associated with those users.
HTTP Request
POST https://api.wheniwork.com/2/login
You must include your Developer Key in the W-Key header, like so:
W-Key: iworksoharditsnotfunny
Parameters
| Key | Description |
|---|---|
| username | string (email address) The email of the user logging in. |
| password | string The password of the user logging in. |
| key | string Your developer key. This can be used instead of W-Key in the headers. You do not need both. |
Register
Example Request
curl --request POST \
--url https://api.wheniwork.com/2/login/register \
--header 'W-Token: ilovemyboss' \
--data '{"first_name": "Goldie", "last_name": "Wilson", "email": "goldiewilson@hillvalleygov.org", "password": "*******", "password_confirm": "*******", "phone_number": "555-555-5555", "subdomain": "abc-company"}'
<?php
$wiw = new Wheniwork('ilovemyboss');
$result = $wiw->post('login/register', [
'first_name' => 'Goldie',
'last_name' => 'Wilson',
'email' => 'goldiewilson@hillvalleycalifornia.gov',
'password' => 'examplepassword',
'password_confirm' => 'examplepassword',
'phone_number' => '555-555-5555',
'subdomain' => 'abc-company'
]);
?>
Example Response
{
"login": {
"id": 5,
"first_name": "Goldie",
"last_name": "Wilson",
"email": "goldiewilson@hillvalleygov.org",
"token": "ilovemyboss"
},
"user": {
"id": 4364,
"login_id": 5,
"first_name": "Goldie",
"last_name": "Wilson",
}
}
Show hidden fieldsHide extra fieldsBe sure to replace
iworksoharditsnotfunnywith your requested Developer Key.
This endpoint allows you to create new users and associate them with an account.
HTTP Request
POST https://api.wheniwork.com/2/login/register
Parameters
| Key | Description |
|---|---|
| first_name | string The first name of this user. |
| last_name | string The last name of this user. |
| phone_number | string The phone number of this user. |
| string The email address of this user. |
|
| password | string The password of this user. |
| password_confirm | string The password of this user. |
| subdomain | string The subdomain of this user. |
| account_id | string(optional) The account id of this user. |
Please note that all passwords must be:
- at least 10 characters long
- may not contain the email address
- must have reasonable variation (eg.
aaaaaaaaaais not allowed) - must not be a dictionary word
Find Account
Example Request
curl https://api.wheniwork.com/2/login/find?q=when \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("login/find?q=when");
?>
Example Response
{
"accounts": [
{
"id": 11,
"company": "When I Work",
"subdomain": "wheniwork",
"type": 3,
"logo": "https://s3.amazonaws.com/files.wheniwork.com/logos/16434.gif",
"account_holder": "Randy Olson",
"registered": false,
"place": {
"business_name": "When I Work",
"address": "60 Plato Blvd, St Paul, MN 55107, United States",
"place_id": "ChIJYfRBzjfVslIRQLB018IGX3o",
"place_type": "point_of_interest,establishment",
"latitude": "44.93739849",
"longitude": "-93.0843011"
}
},
{
"id": 17,
"company": "When Bagels Met Donuts",
"subdomain": "bagelsdonuts",
"type": 3,
"logo": "https://s3.amazonaws.com/files.wheniwork.com/logos/16434.gif",
"account_holder": "Jimmy Baker",
"registered": true,
"place": null
}
]
}
In order to find accounts that a user has joined or may want to join, you can use the login/find endpoint.
The results returned may include expired accounts.
A maximum of 100 results will be returned and there is no pagination support.
HTTP Request
GET https://api.wheniwork.com/2/login/find
Parameters
| Key | Description |
|---|---|
| q | string A search term to match against the company name or address. |
| places | boolean Also search for matching Google Places. |
| place_id | string array Look for specific Google Places that match accounts or locations in accounts. |
Either place_id or q is required. If places is enabled, the search term q will also be matched against place names and addresses.
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,
"login_id": 2112,
"first_name": "Goldie",
"last_name": "Wilson",
"token": "ilovemyboss"
},
"hash": "the_auto_login_hash"
}
Show hidden fieldsHide extra fieldsIf you find any need to send an authenticated user into the web app without requiring them to log in, you can generate a unique hash that will log them into the app automatically.
You can then use the al (autologin) query parameter to accomplish this. An example would be sending the user to the following URL:
http://app.wheniwork.com/scheduler?al={the_auto_login_hash}
HTTP Request
POST https://api.wheniwork.com/2/users/autologin
Related Objects
Examples
curl https://api.wheniwork.com/2/shifts?include_objects=true
curl https://api.wheniwork.com/2/shifts?include_objects=false
curl https://api.wheniwork.com/2/shifts?include_objects=users
curl https://api.wheniwork.com/2/shifts?include_objects=positions,locations
curl https://api.wheniwork.com/2/shifts?include_objects[]=positions&include_objects[]=locations
By default, all responses from the API will include related objects. For example, when calling the shifts endpoint, the response will also include a users array with all the employees for those shifts.
Including related objects is controlled by the include_objects parameter, which can either be boolean, a comma-separated list, or an array. Boolean values are recognized as true, yes, on, and 1 and the inverse of each. To completely disable the inclusion of related objects, use false.
Shifts
Example Object
{
"id": 10000,
"account_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 cowbell.",
"instances": 1,
"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",
"acknowledged": 0,
"acknowledged_at": "",
"creator_id": 101,
"is_open": null
}
Shifts provide the basis for scheduling. Many other objects, including Locations, Positions, Sites, and Users, all link through Shifts.
For more information about how to use Shifts, visit the Help Center.
Shift Object
| Parameter | Description |
|---|---|
| id | integer Unique identifier for the shift. |
| account_id | integer Link identifier for the Account to which this shift is attached. |
| user_id | integer Link identifier for the User attached to this shift. 0 means the shift is an OpenShift. |
| location_id | integer Link identifier for the Location to which this shift is attached. |
| position_id | integer Link identifier for the Position assigned to this shift. |
| site_id | integer Link identifier for the Site assigned 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 during the shift. |
| color | hex Hex color used to identify the shift in the UI. |
| notes | string Notes about the shift. The maximum length is 350 characters. |
| instances | integer For OpenShifts, how many instances of that shift are available to assign to employees. In the UI, this is indicated by the red badge on the OpenShift. For normal shifts, this will be 1. |
| published | boolean Whether the shift has been published. Published shifts are visible to all employees. |
| published_date | datetime Date the shift was most recently published. (Will be null if the shift is not published.) |
| notified_at | datetime Date when notifications about the shift were most recently sent. |
| created_at | datetime Date the shift was created. |
| updated_at | datetime Date the shift was most recently updated. |
| acknowledged | integer Whether the shift has been acknowledged by the employee. ( 0 for false, 1 for true.) |
| acknowledged_at | datetime The time, if any, when the shift was acknowledged by the employee. |
| creator_id | integer The id of the user who created the shift. |
| is_open | boolean Whether the shift is an OpenShift. |
Listing Shifts
Example Request
curl https://api.wheniwork.com/2/shifts/?location_id=1&start=2014-03-05 00:00:00&end=2014-03-08 23:59:59 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("shifts", array(
"location_id" => 1,
"start" => "2014-03-05 00:00:00",
"end" => "2014-03-08 23:59:59"
));
?>
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": "Sat, 08 Mar 2014 09:00:00 -0600",
"end_time": "Sat, 08 Mar 2014 17:00:00 -0600",
}
]
}
Show hidden fieldsHide extra fieldsThis 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 | datetime Start time for the search window. The default is the current date and time. |
| end | datetime End time for the search window. The default is exactly three days from the start time. |
| user_id | integer, string array The ID of the user to get shifts for. For multiple users, enter a list of user IDs separated by commas (e.g. 1,5,3). |
| location_id | integer, string array The ID of the location to get shifts for. For multiple locations, enter a list of location IDs separated by commas. |
| include_open | boolean Whether to include OpenShifts in the results. |
| include_allopen | boolean Whether to include OpenShifts in the results, including shifts that might be conflicts. |
| include_onlyopen | boolean Whether only OpenShifts should be included in the results. |
| unpublished | boolean Whether unpublished shifts should be included in the results. |
| deleted | boolean Whether to include a list of deleted shift IDs in the results. |
Get Existing Shift
Example Request
curl https://api.wheniwork.com/2/shifts/1337 \
-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.",
}
}
Show hidden fieldsHide extra fieldsGets the details of an existing shift.
HTTP Request
GET https://api.wheniwork.com/2/shifts/{id}
Parameters
| Key | Description |
|---|---|
| id | integer The ID of the shift requested. |
Create/Update Shift
Example Request
# Create a shift
curl -X POST https://api.wheniwork.com/2/shifts/ \
--data '{"notes": "Come in early today."}' \
-H "W-Token: ilovemyboss"
# Update a shift
curl -X PUT https://api.wheniwork.com/2/shifts/10000 \
--data '{"notes": "Come in early today."}' \
-H "W-Token: ilovemyboss"
<?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.",
}
}
Show hidden fieldsHide extra fieldsCreates a new shift or updates an existing one.
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 or PUT body can include fields from the Shift Object.
Acknowledge Shifts
Example Request
curl -X POST https://api.wheniwork.com/2/shifts/acknowledge/ \
--data '{"ids":[34542,45434], "before":"Sun, 6 Dec 2015 00:00:00 -0600"}' \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->post("shifts/acknowledge/", array(
"ids" => array(
34542,
45434
),
"before" => "Sun, 6 Dec 2015 00:00:00 -0600"
));
?>
Example Response
{
"success": true,
"acknowledged": 2
}
This method allows you to acknowledge a group of shifts.
HTTP Request
POST https://api.wheniwork.com/2/shifts/acknowledge/
Parameters
| Key | Description |
|---|---|
| ids | integer array The IDs of the shifts to acknowledge. This parameter must be in the POST body. |
| before | string The timestamp that represents when the shift data was last fetched from the server. This is optional, and is useful to protect against inadvertently acknowledging shifts that were updated since data was fetched. |
Get Shift History
Example Request
curl https://api.wheniwork.com/2/shifts/1337/history \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("shifts/1337/history");
?>
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.",
},
"history": [
{
"type": "created",
},
{
"type": "time_changed",
},
{
"type": "time_changed",
}
]
}
Show hidden fieldsHide extra fieldsGets the history of an existing shift. Shift history events are created when one or more of the following elements are changed:
- start_time
- end_time
- user_id
- position_id
- location_id
- site_id
- published
- break_time
- acknowledged_at
History events contain actor and at fields, and can also contain one or more
of the following optional fields depending on event type:
- start
- end
- user
- break
There is one special event called "current" that includes the current state of the shift.
HTTP Request
GET https://api.wheniwork.com/2/shifts/{id}/history
Parameters
| Key | Description |
|---|---|
| id | integer The ID of the shift for which to fetch history. |
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(
1534,
3543,
65554,
33444
)
));
?>
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 | integer array The IDs of the shifts to publish or unpublish. This parameter must be in the POST body. |
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 within a specific window.
HTTP Request
POST https://api.wheniwork.com/2/shifts/notify/
Parameters
| Key | Description |
|---|---|
| start | datetime Start time for the notification window. |
| end | datetime End time for the notification window. |
| user_id | integer, integer array The ID of the user to notify. For multiple users, enter an array of user IDs (e.g. [1,5,3]). |
| location_id | integer, integer array The ID of the location to send notifications for. For multiple locations, enter an array of location IDs. |
| site_id | integer, integer array The ID of the site to send notifications for. For multiple sites, enter an array of site IDs. |
| position_id | integer, integer array The ID of the position to send notifications for. For multiple position, enter an array of position IDs. |
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 send notifications about. |
Copy Shifts
Example Request
curl -X POST https://api.wheniwork.com/2/shifts/copy/ \
--data '{
"target_start":"Sun, 27 Dec 2015 00:00:00 -0600",
"target_end":"Sat, 02 Jan 2016 23:59:59 -0600",
"location_id":4267,
"mode":"previous_week",
"conflicts":"avoid"
}' \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->post("shifts/copy/", array(
"target_start" => "Sun, 27 Dec 2015 00:00:00 -0600",
"target_end" => "Sat, 02 Jan 2016 23:59:59 -0600",
"location_id" => 4267,
"mode" => "previous_week",
"conflicts":"avoid"
));
?>
Example Response
{
"confirmation": "3 shifts were copied.",
"warning": "",
"shifts": [
{
"id": 27384,
"user_id": 528479,
"start_time": "Mon, 28 Dec 2015 08:00:00 -0600",
"end_time": "Mon, 28 Dec 2015 16:00:00 -0600",
},
{
"id": 27385,
"user_id": 845179,
"start_time": "Tue, 29 Dec 2015 08:00:00 -0600",
"end_time": "Tue, 29 Dec 2015 16:00:00 -0600",
},
{
"id": 27386,
"user_id": 528479,
"start_time": "Wed, 30 Dec 2015 08:00:00 -0600",
"end_time": "Wed, 30 Dec 2015 16:00:00 -0600",
}
]
}
Show hidden fieldsHide extra fieldsThis method allows you to copy shifts from one timeframe into another. There are two modes of operation, one that will copy the previous day's shifts, and another that will copy the previous week's shifts.
There are 3 strategies to address shift conflicts that might arise from the copy operation. The "conflicts" parameter accepts values of "overwrite", "allow", and "avoid". "Overwrite" will delete any previously existing shift that would have created a conflict with the newly copied shift. "Allow" will keep any conflicting shifts that result from the copy. "Avoid" will create newly copied shifts as OpenShifts that otherwise would have created a conflict with previously existing shifts.
The newly created shifts resulting from the copy are included in the response.
HTTP Request
POST https://api.wheniwork.com/2/shifts/copy/
Parameters
| Key | Description |
|---|---|
| target_start | datetime Start time for time range into which shifts will be copied. Required. |
| target_end | datetime End time for time range into which shifts will be copied. Required. |
| mode | string "previous_week" or "previous_day" Indicates whether the source timerange is the week or day previous to the destination range. Required |
| location_id | integer, integer array The ID(s) of the Location(s) for which shifts will be copied. Required. |
| user_id | integer, integer array The ID(s) of the User(s) for which shifts will be copied. Optional. |
| site_id | integer, integer array The ID(s) of the Site(s) for which shifts will be copied. Optional, defaults to all sites. |
| position_id | integer, integer array The ID(s) of the Position(s) for which shifts will be copied. Optional, defaults to all positions. |
| conflicts | string The strategy for addressing shift conflicts resulting from the copy. Accepts: "overwrite", "allow", or "avoid". Documented above. |
Delete Shift
Example Request
curl -X DELETE https://api.wheniwork.com/2/shifts/1337 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->delete("shifts/1337");
?>
Example Response
{
"success": true
}
Deletes an existing shift.
HTTP Request
DELETE https://api.wheniwork.com/2/shifts/{id}
Parameters
| Key | Description |
|---|---|
| id | integer ID of the shift to delete. |
| ids | integer array Array of IDs of the shifts to delete. |
Get Labor
Example Request
curl https://api.wheniwork.com/2/shifts/labor?start=2016-07-04&end=2016-07-08 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("shifts/labor", array(
"start" => "2016-07-04",
"end" => "2016-07-08",
));
?>
Example Response
{
"count": 8,
"data": {
"2016-07-04": {
"hours": 12.5,
"labor": 190,
"coverage": [
0,
0,
0,
0,
0,
0,
0,
0,
0.5,
1,
1,
1,
1,
2,
2,
2,
2,
1,
0,
0,
0,
0,
0,
0
]
},
"2016-07-05": {
"hours": 12.5,
"labor": 190,
},
"2016-07-06": {
"hours": 12.5,
"labor": 190,
},
"2016-07-07": {
"hours": 12.5,
"labor": 190,
}
}
}
Show hidden fieldsHide extra fieldsGets labor information from the schedule, such as total hours worked per day, labor cost, and coverage.
Parameters
| Key | Description |
|---|---|
| start | datetime The start time of the range to calculate labor stats for. |
| end | datetime The end time of the range to calculate labor stats for. |
Response Data
| Key | Description |
|---|---|
| count | integer The total number of shifts contributing to the result. |
| data | object A JSON object containing labor data objects, indexed by date. Dates are formatted as YYYY-MM-DD (ISO 8601). |
Labor data Object
| Parameter | Description |
|---|---|
| hours | number The total number of hours scheduled for this day. |
| labor | number The total labor cost for this day. |
| coverage | number array An array of 24 elements, each corresponding to an hour of the day. Each element contains the total number of hours of labor scheduled for that hour of the day. |
Counting Shifts
Example Request
curl https://api.wheniwork.com/2/shifts/count?location_id=1&start=2014-03-05 00:00:00&end=2014-03-08 23:59:59 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("shifts/count", array(
"location_id" => 1,
"start" => "2014-03-05 00:00:00",
"end" => "2014-03-08 23:59:59"
));
?>
Example Response
{
"shifts": 17,
"locations": 1,
"users": 8,
"positions": 3,
"sites": 0
}
This method allows you to count shifts as well as their associated locations, users, positions, and sites. The accepted parameters are identical to the list shifts endpoint. See the parameters below for all the options.
HTTP Request
GET https://api.wheniwork.com/2/shifts/count
Parameters
| Key | Description |
|---|---|
| start | datetime Start time for the search window. The default is the current date and time. |
| end | datetime End time for the search window. The default is exactly three days from the start time. |
| user_id | integer, string array The ID of the user to get shifts for. For multiple users, enter a list of user IDs separated by commas (e.g. 1,5,3). |
| location_id | integer, string array The ID of the location to get shifts for. For multiple locations, enter a list of location IDs separated by commas. |
| include_open | boolean Whether to include OpenShifts in the results. |
| include_allopen | boolean Whether to include OpenShifts in the results, including shifts that might be conflicts. |
| include_onlyopen | boolean Whether only OpenShifts should be included in the results. |
| unpublished | boolean Whether unpublished shifts should be included in the results. |
Schedule
Listing Images
Example Request
curl https://api.wheniwork.com/2/schedule/images \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("schedule/images");
?>
Example Response
{
"images": [
{
"id": 32,
"account_id": 3,
"user_id": 3,
"fullsize": "https://s3.amazonaws.com/uploads.wheniwork.com/s/32/2014-04-06/f/5757277e91b7e.png",
"thumbnail": "https://s3.amazonaws.com/uploads.wheniwork.com/s/32/2014-04-06/t/5757277e91b7e.png"
}
],
"next": null,
"total": 1
}
Show hidden fieldsHide extra fieldsThis method allows you to fetch images of paper schedules that have been posted for employees.
If there are more images to fetch, the next value will be a page number.
HTTP Request
GET https://api.wheniwork.com/2/schedule/images?page={page}
Parameters
| Key | Description |
|---|---|
| page | integer Which page of images to return, default 1. |
Get Existing Image
Example Request
curl https://api.wheniwork.com/2/schedule/images/32 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("schedule/images/32");
?>
Example Response
{
"image": {
"id": 32,
"account_id": 3,
"user_id": 3,
"fullsize": "https://s3.amazonaws.com/uploads.wheniwork.com/s/32/2014-04-06/f/5757277e91b7e.png",
"thumbnail": "https://s3.amazonaws.com/uploads.wheniwork.com/s/32/2014-04-06/t/5757277e91b7e.png"
}
}
Show hidden fieldsHide extra fieldsGets the details of an existing image.
HTTP Request
GET https://api.wheniwork.com/2/schedule/images/{id}
Parameters
| Key | Description |
|---|---|
| id | integer ID of the image to get. |
Create Image
Example Request
curl -X POST https://api.wheniwork.com/2/schedule/images/ \
--data '@/path/to/file.jpg' \
-H "W-Token: ilovemyboss"
Example Response
{
"image": {
"id": 33,
"account_id": 3,
"user_id": 3,
"fullsize": "https://s3.amazonaws.com/uploads.wheniwork.com/s/32/2014-04-06/f/5757277e91b7e.png",
"thumbnail": "https://s3.amazonaws.com/uploads.wheniwork.com/s/32/2014-04-06/t/5757277e91b7e.png"
}
}
Show hidden fieldsHide extra fieldsCreates a new schedule image.
HTTP Request
POST https://api.wheniwork.com/2/schedule/images
POST Body
The body of the request must be binary image data.
Delete Image
Example Request
curl -X DELETE https://api.wheniwork.com/2/schedule/images/33 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->delete("schedule/images/33");
?>
Example Response
{
"success": true
}
Deletes an existing image.
HTTP Request
DELETE https://api.wheniwork.com/2/schedule/images/{id}
Parameters
| Key | Description |
|---|---|
| id | integer ID of the image to delete. |
Accounts
Example Object
{
"id": 10000,
"master_id": 0,
"type": 3,
"logo": "https://s3.amazonaws.com/files.wheniwork.com/logos/16434.gif",
"company": "ABC Company",
"subdomain": "abc-company",
"enabled": true,
"bad_credit_card": false,
"plan_expires": "Sun, 14 Feb 2016 00:00:00 -0600",
"features": "[\"all\",\"locations\",\"sites\", ...]",
"timezone_id": "11",
"timezone_name": "America/Chicago",
"settings": "...",
"place": {
"business_name": "When I Work",
"address": "60 Plato Blvd, St Paul, MN 55107, United States",
"place_id": "ChIJYfRBzjfVslIRQLB018IGX3o",
"place_type": "point_of_interest,establishment",
"latitude": "44.93739849",
"longitude": "-93.0843011"
}
}
Accounts are objects that define a business account with When I Work. Every user must be associated with an account in order to be able to access Shifts and other data.
Account Object
| Parameter | Description |
|---|---|
| id | integer Unique identifier for the account |
| master_id | integer The id of the parent account (if this is a subaccount) |
| type | integer Account type. Must be one of: 1 = SCHEDULING 2 = ATTENDANCE 3 = BOTH |
| logo | string Path to the image file for the company's logo |
| company | string Name of the company for which this account is in use |
| subdomain | string Subdomain of wheniwork.com to access company-specific When I Work web application |
| enabled | boolean Whether this account object is enabled |
| bad_credit_card | boolean Whether this account has an invalid credit card in use |
| plan_expires | datetime Date and time when this account's plan expires |
| features | array List of all the enabled features on the account |
| timezone_id | integer Identifier for time zone, as specified by the Timezones endpoint. |
| timezone_name | string Name for the timezone specified in the timezone_id |
| settings | json A list of settings for this account |
| place | Place Object Object Containing place information |
Place Object
| Parameter | Description |
|---|---|
| business_name | string (Optional) Business Name |
| address | string Place Address |
| place_id | string Place id returned by google |
| place_type | string, array Types returned by google |
| latitude | string, decimal Latitude of place location |
| longitude | string, decimal Longitude of place location |
Features
The features that are enabled on accounts will vary. The following features are considered defaults and should be considered enabled when all is present:
| Parameter | Description |
|---|---|
| locations | Locations |
| sites | Sites |
| acknowledgement | Shift Acknowledgement |
| month-view | Month View in Scheduling |
| annotations | Schedule Annotations |
| account-rep | Has Account Representative |
| mobile-alerts | Mobile Alerts |
| employee-control | Has Global Privacy Setting |
| workchat | WorkChat |
There are a few other features that may be explicitly enabled on some accounts:
| Parameter | Description |
|---|---|
| all | Default features enabled |
| scheduling | Scheduling |
| attendance | Attendance |
| unclaimed | Unclaimed Workplace |
| square-plan | Account Billed through Square |
| workchat-conversations | Individual and group conversations in WorkChat |
NOTE: Account features are derived from the plan and cannot be modified using the API!
Get Existing Account
Example Request
curl https://api.wheniwork.com/2/account \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("account");
?>
Example Response
{
"account": {
"id": 11,
"master_id": 11,
"type": 3,
"logo": "https://s3.amazonaws.com/files.wheniwork.com/logos/16434.gif",
"company": "123 Company",
"subdomain": "123-company",
"enabled": true,
"bad_credit_card": false,
"plan_expires": "Sun, 14 Feb 2016 00:00:00 -0600",
"features": "[\"all\",\"locations\",\"sites\", ...]",
"timezone_id": "11",
"timezone_name": "America/Chicago",
"settings": "...",
"place": {
"business_name": "When I Work",
"address": "60 Plato Blvd, St Paul, MN 55107, United States",
"place_id": "ChIJYfRBzjfVslIRQLB018IGX3o",
"place_type": "point_of_interest,establishment",
"latitude": "44.93739849",
"longitude": "-93.0843011"
}
}
}
HTTP Request
GET https://api.wheniwork.com/2/account
Parameters
This endpoint has no parameters.
Create/Update Account
Create HTTP Request
POST https://api.wheniwork.com/2/account/
Update HTTP Requests
PUT https://api.wheniwork.com/2/account/{account id}
Parameters
The POST and/or PUT body can include fields from the Account Object.
Additional Parameters
| Key | Description |
|---|---|
| referral_reason | (Optional) referral reason, which will persist as the referral_code. |
Update Account Settings
Example Request
curl -X POST https://api.wheniwork.com/2/account/settings \
-H "W-Token: ilovemyboss" \
-data '{"company":"123 Company","ref_employees":7,"subdomain":"123-company","industry_id":14}'
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->post("account/settings", array(
"company" => "123 Company",
"ref_employees" => 7,
"subdomain" => "123-company",
"industry_id" => 14,
));
?>
Example Response
{
"id": 10000,
"master_id": 0,
"type": 3,
"logo": "https://s3.amazonaws.com/files.wheniwork.com/logos/16434.gif",
"company": "123 Company",
"subdomain": "123-company",
"enabled": true,
"bad_credit_card": false,
"plan_expires": "Sun, 14 Feb 2016 00:00:00 -0600",
"features": "[\"all\",\"locations\",\"sites\", ...]",
"timezone_id": "11",
"timezone_name": "America/Chicago",
"settings": "...",
"place": null
}
Account managers/owners can update certain account settings using this endpoint.
HTTP Request
POST https://api.wheniwork.com/2/account/settings
Parameters
| Key | Description |
|---|---|
| company | Company name. |
| timezone_id | Updated timezone ID. |
| industry_id | ID of the industry relevant to this account. |
| ref_employees | Number of employees for this account. |
| subdomain | Account subdomain (subdomain.wheniwork.com). |
| country_id | ID of account country (only editable for trials). |
| type | Account type (trials only). |
Invite to Account
Managers can be invited to unclaimed accounts by using this endpoint.
HTTP Request
POST https://api.wheniwork.com/2/account/{account_id}/invite
Example Request
curl -X POST https://api.wheniwork.com/2/account/35/invite \
-H "W-Token: ilovemyboss" \
-data '{"email":"sally@example.com","manager_name":"Sally Smith","message":"This scheduling app is really slick!"}'
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->post("account/11/invite", array(
"email" => "sally@example.com",
"manager_name" => "Sally Smith",
"message" => "This scheduling app is really slick!",
));
?>
Example Response
{
"success": true
}
Parameters
Either email or phone_number must be provided. If both are provided, an SMS and an email will be sent.
| Key | Description |
|---|---|
| account_id | ID of the account object. |
| Email address of the manager. | |
| phone_number | Phone number of the manager. |
| region | Two letter country code of the phone number. This can be omitted if the phone number is in E164 format. |
| manager_name | Managers name. |
| message | A custom message that will be added to the invite. |
Claim Account
Example Request
curl -X POST https://api.wheniwork.com/2/account/11/claim \
--data '{"industry_id":9,"ref_employees":3}' \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->post("account/11/claim", array(
"industry_id" => 9,
"ref_employees" => 3
));
?>
Example Response
{
"account": {
"id": 11,
"master_id": 11,
"type": 3,
"logo": "https://s3.amazonaws.com/files.wheniwork.com/logos/16434.gif",
"company": "123 Company",
"subdomain": "123-company",
"enabled": true,
"bad_credit_card": false,
"plan_expires": "Sun, 14 Feb 2016 00:00:00 -0600",
"features": "[\"all\",\"locations\",\"sites\", ...]",
"timezone_id": "11",
"timezone_name": "America/Chicago",
"settings": "...",
"place": null
},
"user": {
"id": 4364,
"login_id": 2112,
"account_id": 11,
"role": 1,
"email": "goldiewilson@hillvalleycalifornia.gov",
"first_name": "Goldie",
"last_name": "Wilson",
"phone_number": "555-555-5555",
"employee_code": "1020",
"activated": true,
"notes": "",
"hours_preferred": 40,
"hours_max": 40,
"hourly_rate": 15.5,
"type": 1,
"last_login": "Mon, 05 Oct 2015 18:26:44 -0500",
"positions": [
12284,
9554
],
"locations": [
34,
58934
],
"is_deleted": false,
"is_hidden": false,
"is_payroll": false,
"is_private": false,
"is_trusted": false
}
}
HTTP Request
POST https://api.wheniwork.com/2/account/{account id}/claim
Parameters
| Key | Description |
|---|---|
| account_id | ID of the account object to be claimed. |
| industry_id | ID of the industry relevant to this account. |
| ref_employees | Number of employees for this account. |
Login
Create/Update Login Avatar
Example Request
curl -X POST https://api.wheniwork.com/2/login/avatar \
-H "W-Token: ilovemyboss"
-H "Content-Type: image/jpeg"
<?php
$ch = curl_init(https://api.wheniwork.com/2/login/avatar);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: ' . $type]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $image);
$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
?>
Example Response
{
"avatar": {
"hash": "{hash}",
"type": "jpg",
"sizes": {
"small": {
"href": "{loginhash}/small",
"path": "2/fb/{loginhash}.small.jpg",
"url": "//s3.amazonaws.com/2/fb/{loginhash}.small.jpg"
}
},
"medium": {
"href": "/{loginhash}/medium",
"path": "4/e1/{loginhash}.medium.jpg",
"url": "//s3.amazonaws.com/4/fb/{loginhash}.medium.jpg"
},
"created_at": "2016-01-13T22:05:22+00:00",
"updated_at": "2016-01-13T22:05:22+00:00",
"best": "medium"
},
"error": false
}
Creates or updates login avatar.
User can only update their own avatar.
HTTP Request
POST https://api.wheniwork.com/2/login/avatar
Users
Example Object
{
"id": 4364,
"login_id": 2112,
"account_id": 10000,
"role": 2,
"email": "goldiewilson@hillvalleycalifornia.gov",
"first_name": "Goldie",
"last_name": "Wilson",
"phone_number": "555-555-5555",
"employee_code": "1020",
"activated": true,
"notes": "",
"hours_preferred": 40,
"hours_max": 40,
"hourly_rate": 15.5,
"type": 1,
"last_login": "Mon, 05 Oct 2015 18:26:44 -0500",
"positions": [
12284,
9554
],
"locations": [
34,
58934
],
"is_deleted": false,
"is_hidden": false,
"is_payroll": false,
"is_private": false,
"is_trusted": false
}
Users are the employees, supervisors, and managers that have access to your business on When I Work.
User Object
| Parameter | Description |
|---|---|
| id | integer Unique identifier for the user. |
| login_id | integer Unique identifier for the login belonging to the user. |
| account_id | integer ID of the primary account for this user. |
| role | integer The user's role. 1 = Admin2 = Manager3 = Employee (Default)4 = Lead (Unused)5 = Supervisor |
| string The email address of this user. |
|
| first_name | string The first name of this user. |
| last_name | string The last name of this user. |
| phone_number | string The phone number of this user. |
| employee_code | string The user's employee code. This code can be used to clock in instead of the user's email address, or it can be used to help map users in When I Work to other services. |
| activated | boolean Whether the manager has activated this user. |
| notes | string Notes about this user. |
| hours_preferred | float The preferred number of hours for this user to work. |
| hours_max | float The max hours that this user can work. |
| hourly_rate | float The hourly rate for this user. |
| type | integer A bitwise flag representing additional wage options: 1 = hourly employee, 2 = salaried employee, 4 = exempt from overtime. |
| last_login | datetime The date and time when this user last logged in. |
| positions | array (of IDs) An array of positions to be assigned to this user. |
| locations | array (of IDs) An array of locations to be applied to this user. |
| is_deleted | boolean Whether the user has been deleted. |
| is_hidden | boolean Whether the user has been hidden from the scheduler. |
| is_payroll | boolean Whether the user has access to payroll. (Only available for managers and supervisors.) |
| is_private | boolean Whether the user has privacy enabled, which will hide their contact details from other employees. |
| is_trusted | boolean Whether the user can edit their own timesheet. |
Listing Users
Example Request
curl https://api.wheniwork.com/2/users \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("users");
?>
Example Response
{
"users": [
{
"id": 4364,
"login_id": 2112,
"first_name": "Goldie",
"last_name": "Wilson",
},
{
"id": 27384,
"login_id": 2112,
"email": "jen.parker@example.com",
"first_name": "Jennifer",
"last_name": "Parker",
}
]
}
Show hidden fieldsHide extra fieldsGet a list of users, optionally filtered by ID or location. See the parameters below for all the options.
HTTP Request
GET https://api.wheniwork.com/2/users
Parameters
| Key | Description |
|---|---|
| ids | integer array The IDs of the users to retrieve, as a comma-separated list (e.g. 9,17,42). |
| location_id | integer, integer array The ID of the location to get users for. For multiple locations, enter a list of location IDs separated by commas. |
| show_deleted | boolean Whether to include deleted users in the results. Defaults to false. |
Get Existing User
Example Request
curl https://api.wheniwork.com/2/users/4364 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("users/4364");
?>
Example Response
{
"user": {
"id": 4364,
"login_id": 2112,
"account_id": 10000,
"role": 2,
"email": "goldiewilson@hillvalleycalifornia.gov",
"first_name": "Goldie",
"last_name": "Wilson",
"phone_number": "555-555-5555",
"employee_code": "1020",
"activated": true,
"notes": "This user excels at awesome.",
"hours_preferred": 40,
"hours_max": 40,
"hourly_rate": 15.5,
"type": 1,
"last_login": "Mon, 05 Oct 2015 18:26:44 -0500",
"positions": [
12284,
9554
],
"locations": [
34,
58934
],
"is_deleted": false,
"is_hidden": false,
"is_payroll": false,
"is_private": false,
"is_trusted": false
}
}
Get a specific user by their ID.
HTTP Request
GET https://api.wheniwork.com/2/users/{id}
Parameters
| Key | Description |
|---|---|
| id | ID of the user to retrieve. |
Create New User
Example Request
curl https://api.wheniwork.com/2/users --data '{"first_name":"Goldie", "last_name": "Wilson", "email": "goldiewilson@hillvalleycalifornia.gov"}' -H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->post("users/", array(
"first_name"=>"Goldie",
"last_name"=>"Wilson",
"email"=>"goldiewilson@hillvalleycalifornia.gov"
));
?>
Example Response
{
"user": {
"id": 4364,
"login_id": 2112,
"email": "goldiewilson@hillvalleycalifornia.gov",
"first_name": "Goldie",
"last_name": "Wilson",
}
}
Show hidden fieldsHide extra fieldsHTTP Request
POST https://api.wheniwork.com/2/users
Parameters
The POST body can include fields from the User Object. You will need
to include at least the 'email' field in the body of the request.
Additional Params
| Key | Description |
|---|---|
| reactivate | boolean Whether to reactivate a previously deleted user. |
Update Existing User
Example Request
curl -X PUT https://api.wheniwork.com/2/users/4364 \
--data '{"email":"newemail@example.com"}' \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->put("users/4364", array(
"email"=>"newemail@example.com"
));
?>
Example Response
{
"user": {
"id": 4364,
"login_id": 2112,
"email": "newemail@example.com",
"first_name": "Goldie",
"last_name": "Wilson",
}
}
Show hidden fieldsHide extra fieldsHTTP Request
PUT https://api.wheniwork.com/2/users/{id}
Parameters
The PUT body can include fields from the User Object.
Additional Params
| Key | Description |
|---|---|
| reactivate | boolean Whether to reactivate a previously deleted user. |
Update User Avatar
Example Request
curl -X POST https://api.wheniwork.com/2/users/avatar/4364 \
--data-binary '@path/to/image.jpg' \
-H "Content-Type: image/jpg" \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->post("users/avatar/4364", array(
"avatar"=> "@" . realpath("path/to/image.jpg") . ";filename=image.jpg"
));
?>
Parameters
You can either send binary content (with a valid Content-Type header) or send a multi-part form upload with an avatar field.
Response
The response will be a JSON object with details about the avatar. The response will always include a redirect to the avatar image, so be sure to disable following redirects if you want to read details about the avatar.
Get User Profile
Example Request
curl https://api.wheniwork.com/2/users/profile \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("users/profile");
?>
Example Response
{
"user": {
"id": 4364,
"login_id": 2112,
"first_name": "Goldie",
"last_name": "Wilson",
}
}
Show hidden fieldsHide extra fieldsGet the authenticated user's profile, which includes all personal information such as name, email, and phone number, and also includes some extra options like sleep_start.
HTTP Request
GET https://api.wheniwork.com/2/users/profile
Update User Profile
Example Request
curl -X POST https://api.wheniwork.com/2/users/profile/ \
--data '{
"first_name": "Jimmy",
"last_name": "Buffett",
"email": "parrothead1@margaritaville.com",
"phone_number": "555-212-8716",
"SECTION_START_before_is_private": true,
"is_private": "false",
"SECTION_END_at_end": true
}' \
-H "W-Token: ilovemyboss"
<?php
$result = $wiw->post("users/alerts", array(
"first_name" => "Jimmy",
"last_name" => "Buffett",
"email" => "parrothead1@margaritaville.com",
"phone_number" => "+15552128716"
));
?>
Example Response
{
"id": 4364,
"login_id": 2112,
"email": "parrothead1@margaritaville.com",
"first_name": "Jimmy",
"last_name": "Buffett",
"phone_number": "+15552128716",
}
Show hidden fieldsHide extra fieldsUpdate the authenticated user's profile information.
HTTP Request
POST https://api.wheniwork.com/2/users/profile
Parameters
The POST body can include fields from the User Profile Object:
User profile Object
| Parameter | Description |
|---|---|
| first_name | string User's first name |
| last_name | string User's last name (surname) |
| string User's email address |
|
| phone_number | string User's phone number for SMS messages |
| is_private | boolean Privacy setting to show email and phone number to other employees (for managers/supervisors, email is always shown). |
Update User Alert Settings
Example Request
curl -X POST https://api.wheniwork.com/2/users/alerts/ \
--data '{
"timeoff": "{'sms': true, 'email': false}",
"swaps": "{'sms': true, 'email': false}",
"schedule": "{'sms': true, 'email': false}",
"reminders": "{'sms': true, 'email': false}",
"availability": "{'sms': true, 'email': false}",
"new_employee": "{'sms': true, 'email': false}",
"attendance": "{'sms': false, 'email': true}",
"reminder_time": "2.0",
"workchat": "{'alerts': true, 'in_app': true, 'badge_icon': true}"
}' \
-H "W-Token: ilovemyboss"
<?php
$result = $wiw->post("users/alerts", array(
"timeoff" => array(
"sms" => "true",
"email" => "false"
)
));
?>
Example Response
{
"success": true
}
HTTP Request
POST https://api.wheniwork.com/2/users/alerts
Parameters
The POST body can include fields from the Alert Settings Object.
User alert settings Object
| Parameter | Description |
|---|---|
| timeoff | Alert Setting Object Whether the user wishes to receive alerts when the status of a time off request changes. |
| swaps | Alert Setting Object Whether the user wishes to receive alerts when the status of a swap or drop request changes. |
| schedule | Alert Setting Object Whether the user wishes to receive alerts when the schedule changes. |
| reminders | Alert Setting Object Whether the user wishes to receive alerts for reminders prior to shifts. |
| availability | Alert Setting Object Whether the user wishes to receive alerts for changes in availability. |
| new_employee | Alert Setting Object Whether the user wishes to receive alerts when a new employee is added. |
| attendance | Alert Setting Object Whether the user wishes to receive alerts for attendance-related events. |
| reminder_time | float Time before an event when a user should be sent notifications, in hours. |
| workchat | Alert Setting Object Whether the user wishes to receive alerts when new workchat messages are received and how they are notified. |
alert setting Object
| Parameter | Description |
|---|---|
| sms | boolean Whether or not SMS messages should be sent for events of this alert type. |
| boolean Whether or not email messages should be sent for events of this alert type. |
|
| alerts | boolean Whether or not push notifications should be sent for events of this alert type. |
| in_app | boolean Whether or not in-app notifications should be sent for events of this alert type. |
| badge_icon | boolean Whether or not banner notifications (iOS only) should be sent for events of this alert type. |
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.
HTTP Request
POST https://api.wheniwork.com/2/users/invite
Parameters
| Key | Description |
|---|---|
| items | string array List of email addresses or phone numbers of users to invite. |
| ids | integer array List of existing user IDs to invite. |
| send_all | boolean Whether to invite all users who do not currently have a login. If this is true, the ids parameter will be 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,
"modified_shifts": [
235132,
235245,
235677,
235812
]
}
Users can be deleted by managers, or by supervisors. If a supervisor is deleting the user, the supervisor must be able to manage all locations the user is attached to.
HTTP Request
DELETE https://api.wheniwork.com/2/users/{id}?delete_shifts=true
Parameters
| Key | Description |
|---|---|
| id | ID of the user to delete. |
| delete_shifts | boolean Indicates whether or not to delete this user's future shifts. If not deleted, those shifts will be moved to Open Shifts. This is an optional parameter. |
Create/Update User Avatar
Example Request
curl -X POST https://api.wheniwork.com/2/users/avatar \
-H "W-Token: ilovemyboss"
-H "Content-Type: image/jpeg"
<?php
$ch = curl_init(https://api.wheniwork.com/2/users/avatar);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: ' . $type]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $image);
$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
?>
Example Response
{
"avatar": {
"hash": "{hash}",
"type": "jpg",
"sizes": {
"small": {
"href": "{userhash}/small",
"path": "2/fb/{userhash}.small.jpg",
"url": "//s3.amazonaws.com/2/fb/{userhash}.small.jpg"
}
},
"medium": {
"href": "/{userhash}/medium",
"path": "4/e1/{userhash}.medium.jpg",
"url": "//s3.amazonaws.com/4/fb/{userhash}.medium.jpg"
},
"created_at": "2016-01-13T22:05:22+00:00",
"updated_at": "2016-01-13T22:05:22+00:00",
"best": "medium"
},
"error": false
}
Creates or updates user avatar.
HTTP Request
POST https://api.wheniwork.com/2/users/avatar
Parameters
| Key | Description |
|---|---|
| user_id | int (optional) ID of the user upload avatar. Will default to current user. |
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.
For more about using Positions, visit the Help Center.
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,
"account_id": 3,
"name": "Stocker",
"color": "1174a6",
},
{
"id": 5,
"account_id": 3,
"name": "Bagger",
"color": "FF6666",
},
{
"id": 6,
"account_id": 3,
"name": "Cashier",
"color": "0066FF",
}
]
}
Show hidden fieldsHide extra fieldsThis method allows you to get a list of all positions in your account.
HTTP Request
GET https://api.wheniwork.com/2/positions
Parameters
| Key | Description |
|---|---|
| show_deleted | boolean Whether to show positions that have been deleted. |
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,
"account_id": 3,
"name": "Stocker",
"color": "1174a6",
}
}
Show hidden fieldsHide extra fieldsHTTP Request
GET https://api.wheniwork.com/2/positions/{position_id}
Parameters
| Key | Description |
|---|---|
| position_id | ID of the position requested. |
Create/Update Position
Example Request
# Create a Position
curl -X POST https://api.wheniwork.com/2/positions/ \
--data '{"name": "Manager"}' \
-H "W-Token: ilovemyboss"
# Update a Position
curl -X PUT https://api.wheniwork.com/2/positions/32 \
--data '{"name": "Manager"}' \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
// Create a Position
$result = $wiw->create("positions", array(
"name" => "Manager",
// ...
));
// Update a Position
$result = $wiw->update("positions/32", array(
"name" => "Manager",
// ...
));
?>
Example Response
{
"position": {
"id": 32,
"account_id": 3,
"name": "Manager",
"color": "1174a6",
}
}
Show hidden fieldsHide extra fieldsCreates a new Position or updates an existing one.
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 or PUT body can include fields from the Position Object.
Delete Existing Position
Example Request
curl -X DELETE https://api.wheniwork.com/2/positions/32 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->delete("positions/32");
?>
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",
"place": {
"business_name": "When I Work",
"address": "60 Plato Blvd, St Paul, MN 55107, United States",
"place_id": "ChIJYfRBzjfVslIRQLB018IGX3o",
"place_type": "point_of_interest,establishment",
"latitude": "44.93739849",
"longitude": "-93.0843011"
}
}
Locations are the main physical locations where your business operates and where employees, managers, and supervisors are assigned.
For more about using Locations, visit the Help Center.
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 | array |
| created_at | date The date the location was created. |
| updated_at | date The last time the location was updated. |
| place | Place Object Object Containing place information |
Place Object
| Parameter | Description |
|---|---|
| business_name | string (Optional) Business Name |
| address | string Place Address |
| place_id | string Place id returned by google |
| place_type | string, array Types returned by google |
| latitude | string, decimal Latitude of place location |
| longitude | string, decimal Longitude of place location |
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"
],
"place": {
"business_name": "When I Work",
"address": "60 Plato Blvd, St Paul, MN 55107, United States",
"place_id": "ChIJYfRBzjfVslIRQLB018IGX3o",
"place_type": "point_of_interest,establishment",
"latitude": "44.93739849",
"longitude": "-93.0843011"
}
}
]
}
Show hidden fieldsHide extra fieldsThis method allows you to get a list of all Locations in your account.
HTTP Request
GET https://api.wheniwork.com/2/locations
Parameters
This endpoint has no parameters.
Listing Nearby Locations and Sites
Example Request
curl https://api.wheniwork.com/2/locations/nearby?coordinates[]=44.937401&coordinates[]=-93.084305 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("locations/nearby", array(
44.937401,
-93.084305
));
?>
Example Response
{
"locations": [
{
"id": 136,
"name": "Downtown",
"address": "9303 Lyon Drive, Hill Valley, CA 12345",
"coordinates": [
44.937401,
-93.083855
],
"place": {
"business_name": "When I Work",
"address": "60 Plato Blvd, St Paul, MN 55107, United States",
"place_id": "ChIJYfRBzjfVslIRQLB018IGX3o",
"place_type": "point_of_interest,establishment",
"latitude": "44.93739849",
"longitude": "-93.0843011"
},
"latitude": 44.937401,
"longitude": 93.083855,
"distance": "37.31790518480344",
"radius": 100
}
],
"sites": [
{
"id": 9,
"account_id": 10000,
"name": "Twin Pines",
"address": "9303 Lyon Drive, Hill Valley, CA 12345",
"coordinates": [
44.937401,
-93.083855
],
"latitude": 44.937401,
"longitude": 93.083855,
"radius": 100,
"distance": "37.31790518480344"
}
]
}
Show hidden fieldsHide extra fieldsParameters
| Key | Description |
|---|---|
| coordinates | array [Latitude, Longitude] |
| accuracy | number Optional accuracy threshold in meters, up to 500 meters. Defaults to zero when omitted. |
HTTP Request
GET https://api.wheniwork.com/2/locations/nearby?coordinates[]={latitude}&coordinates[]={longitude}
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"
],
"place": {
"business_name": "When I Work",
"address": "60 Plato Blvd, St Paul, MN 55107, United States",
"place_id": "ChIJYfRBzjfVslIRQLB018IGX3o",
"place_type": "point_of_interest,establishment",
"latitude": "44.93739849",
"longitude": "-93.0843011"
}
}
}
Show hidden fieldsHide extra fieldsGets the details of a specific Location.
HTTP Request
GET https://api.wheniwork.com/2/locations/{id}
Parameters
| Key | Description |
|---|---|
| id | ID of the location requested. |
Create/Update Location
Example Request
# Create a Location
curl -X POST https://api.wheniwork.com/2/locations/ \
--data '{"name": "Uptown"}' \
-H "W-Token: ilovemyboss"
# Update a Location
curl -X PUT https://api.wheniwork.com/2/locations/136 \
--data '{"name": "Uptown"}' \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
// Create a Location
$result = $wiw->create("locations", array(
"name" => "Uptown",
// ...
));
// Update a Location
$result = $wiw->update("locations/136", array(
"name" => "Uptown",
// ...
));
?>
Example Response
{
"location": {
"id": 136,
"name": "Uptown",
"address": "9303 Lyon Drive, Hill Valley, CA 12345",
"coordinates": [
"34.2390664",
"-118.4332328"
],
"place": {
"business_name": "When I Work",
"address": "60 Plato Blvd, St Paul, MN 55107, United States",
"place_id": "ChIJYfRBzjfVslIRQLB018IGX3o",
"place_type": "point_of_interest,establishment",
"latitude": "44.93739849",
"longitude": "-93.0843011"
}
}
}
Show hidden fieldsHide extra fieldsCreates a new Location or updates an existing one.
Create HTTP Request
POST https://api.wheniwork.com/2/locations/
Update HTTP Requests
PUT https://api.wheniwork.com/2/locations/{id}
Parameters
The POST 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
}
Deletes a Location from your account.
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,
"account_id": 10000,
"location_id": 136,
"name": "Twin Pines",
"color": "cccccc",
"description": "",
"address": "1600 S Azusa Ave, City of Industry, CA 91748",
"coordinates": [
"33.9935161",
"-117.9264044"
],
"latitude": "33.9935161",
"longitude": "-117.9264044",
"place_id": "",
"created_at": "Fri, 13 Jun 2014 11:53:00 -0500",
"updated_at": "Fri, 13 May 2016 10:59:41 -0500",
"is_deleted": false,
"deleted_at": "",
"radius": 1000
}
Sites are off-site places where users of a Location can be assigned and scheduled.
For more about using Sites, visit the Help Center.
Site Object
| Parameter | Description |
|---|---|
| id | integer The unique ID of the site. |
| account_id | integer The ID of the account to which this site belongs. |
| location_id | integer The ID of the location to which this site belongs. If 0, this site belongs to all locations. |
| name | string The name of the site. |
| color | string The hex color used to identify this site in the UI. |
| description | string The description of the job site. |
| address | string The address of the site. |
| coordinates | array The latitude and longitude of the site, if any, as an array of comma separated values. |
| latitude | string The latitude of the site, if any. |
| longitude | string The longitude of the site, if any. |
| place_id | string The ID of the Google Place associated with this site (if any). |
| created_at | datetime The date and time when the site was created. |
| updated_at | datetime The date and time when the site was most recently updated. |
| is_deleted | boolean Whether the site has been deleted or not. |
| deleted_at | datetime The date and time when the site was deleted. |
| radius | integer The maximum distance away from the job site at which employees can clock in. This reflects the "Maximum Distance When Clocking In" Attendance setting. This field is provided for convenience and cannot be changed. |
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,
"account_id": 10000,
"name": "Twin Pines",
},
{
"id": 4,
"account_id": 10000,
"name": "Lone Pine",
}
]
}
Show hidden fieldsHide extra fieldsGets a list of all Sites in your account.
HTTP Request
GET https://api.wheniwork.com/2/sites
Parameters
| Key | Description |
|---|---|
| include_deleted | boolean Whether to include deleted Sites in the results. |
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,
"account_id": 10000,
"name": "Twin Pines",
}
}
Show hidden fieldsHide extra fieldsGets details about a specific Site.
HTTP Request
GET https://api.wheniwork.com/2/sites/{id}
Parameters
| Key | Description |
|---|---|
| id | ID of the site requested. |
Create/Update Site
Example Request
# Create a Site
curl -X POST https://api.wheniwork.com/2/sites/ \
--data '{"name": "Shaded Grove"}' \
-H "W-Token: ilovemyboss"
# Update a Site
curl -X PUT https://api.wheniwork.com/2/sites/9 \
--data '{"name": "Shaded Grove"}' \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
// Create a Site
$result = $wiw->create("sites", array(
"name" => "Shaded Grove",
// ...
));
// Update a Site
$result = $wiw->update("sites/9", array(
"name" => "Shaded Grove",
// ...
));
?>
Example Response
{
"site": {
"id": 9,
"account_id": 10000,
"name": "Shaded Grove",
}
}
Show hidden fieldsHide extra fieldsCreates a new Site or updates an existing one.
Create HTTP Request
POST https://api.wheniwork.com/2/sites/
Update HTTP Requests
PUT https://api.wheniwork.com/2/sites/{id}
Parameters
The POST 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"
}
Shift Blocks are predefined shifts that make it quick to construct a schedule.
For more about using Shift Blocks, visit the Help Center.
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,
"account_id": 0,
"location_id": 14,
"position_id": 7,
"start_time": "16:00:00",
"end_time": "21:30:00",
},
{
"id": 183,
"account_id": 0,
"location_id": 14,
"position_id": 7,
"start_time": "06:00:00",
"end_time": "14:30:00",
},
{
"id": 204,
"account_id": 0,
"location_id": 14,
"position_id": 7,
"start_time": "08:45:00",
"end_time": "16:30:00",
}
]
}
Show hidden fieldsHide extra fieldsGets a list of all Shift Blocks in your account.
HTTP Request
GET https://api.wheniwork.com/2/blocks
Parameters
This endpoint has no parameters.
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,
"account_id": 0,
"location_id": 14,
"position_id": 7,
"start_time": "16:00:00",
"end_time": "21:30:00",
}
}
Show hidden fieldsHide extra fieldsGets the details of a specific Shift Block.
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
Example Request
# Create a Shift Block
curl -X POST https://api.wheniwork.com/2/blocks/ \
--data '{"location_id": 136'}' \
-H "W-Token: ilovemyboss"
# Update a Shift Block
curl -X PUT https://api.wheniwork.com/2/blocks/233 \
--data '{"location_id": 136}' \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
// Create a Shift Block
$result = $wiw->create("blocks", array(
"location_id" => 136,
// ...
));
// Update a Shift Block
$result = $wiw->update("blocks/233", array(
"location_id" => 136,
// ...
));
?>
Example Response
{
"block": {
"id": 233,
"account_id": 0,
"location_id": 136,
"position_id": 7,
"start_time": "16:00:00",
"end_time": "21:30:00",
}
}
Show hidden fieldsHide extra fieldsCreates a new Shift Block or updates an existing one.
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 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,
"hours": 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 allow users to request time off.
For more about making Requests, visit the Help Center.
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 The current status of the request (0 = Pending, 1 = Canceled, 2 = Accepted, 3 = Expired). |
| type | integer The type of the request (0 = Unpaid Time Off, 1 = Paid Time Off, 2 = Sick Leave, 3 = Holiday). |
| hours | float The number of hours of paid time off to use. Only valid for full-day requests that are of type 'Paid Time Off', 'Sick', or 'Holiday'. |
| 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 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("requests", array(
"start" => "2014-03-01",
"end" => "2014-03-31",
// ...
));
?>
Example Response
{
"requests": [
{
"id": 54,
"account_id": 0,
"user_id": 135,
"creator_id": 135,
"status": 0,
"type": 0,
"hours": 0,
"start_time": "Fri, 14 Mar 2014 00:00:00 -0500",
"end_time": "Fri, 21 Mar 2014 00:00:00 -0500",
},
{
"id": 55,
"account_id": 0,
"user_id": 135,
"creator_id": 135,
"status": 0,
"type": 0,
"hours": 0,
"start_time": "Mon, 24 Mar 2014 08:00:00 -0600",
"end_time": "Fri, 28 Mar 2014 08:00:00 -0600",
}
],
"more": false,
"page": 1,
"total": 2,
"messages": [
{
"id": 66,
"account_id": 0,
"user_id": 135,
"request_id": 54,
"title": "Request Approved",
"content": "This Request has been approved",
},
{
"id": 68,
"account_id": 0,
"user_id": 135,
"request_id": 55,
"title": "Request Approved",
"content": "This Request has been approved",
}
],
"users": [
{
"id": 135,
"login_id": 2112,
"first_name": "Goldie",
"last_name": "Wilson",
},
{
"id": 27384,
"login_id": 2112,
"first_name": "Emmett",
"last_name": "Brown",
}
]
}
Show hidden fieldsHide extra fieldsGets a list of Requests for your account.
HTTP Request
GET https://api.wheniwork.com/2/requests
Parameters
| Key | Description |
|---|---|
| start | The start date for the request time-frame. |
| end | The end date 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. |
| user_id | integer Optional. If present, will only return requests for the user with the given id. |
| status | integer Optional. If present, will only return requests with the given status. |
| limit | integer Optional. Number of requests to load per page, default is 5. |
| page | integer Optional. Page of results to load, default 1. |
| include_deleted_users | boolean Return all requests including those made by deleted users. Optional, defaults to false. |
Get Existing Request
Example Request
curl https://api.wheniwork.com/2/requests/54 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("requests/54");
?>
Example Response
{
"request": {
"id": 54,
"account_id": 0,
"user_id": 135,
"creator_id": 135,
"status": 2,
"type": 0,
"hours": 0,
"start_time": "Fri, 14 Mar 2014 00:00:00 -0500",
"end_time": "Fri, 21 Mar 2014 00:00:00 -0500",
},
"messages": [
{
"id": 61,
"account_id": 0,
"user_id": 135,
"request_id": 54,
"title": "Request Approved",
"content": "This Request has been approved",
}
],
"users": [
{
"id": 135,
"login_id": 2112,
"first_name": "Goldie",
"last_name": "Wilson",
}
]
}
Show hidden fieldsHide extra fieldsGets the details of a specific Request.
HTTP Request
GET https://api.wheniwork.com/2/requests/{request_id}
Parameters
| Key | Description |
|---|---|
| request_id | ID of the request. |
Create/Update Request
Example Request
# Create a Request
curl -X POST https://api.wheniwork.com/2/requests/ \
--data '{"user_id": 135, "start_time": "Fri, 14 Mar 2014 00:00:00 -0500", "end_time": "Fri, 21 Mar 2014 00:00:00 -0500"}' \
-H "W-Token: ilovemyboss"
# Update a Request
curl -X PUT https://api.wheniwork.com/2/requests/54 \
--data '{"end_time": "Fri, 21 Mar 2014 00:00:00 -0500"}' \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
// Create a Request
$result = $wiw->create("requests", array(
"user_id" => 135,
"start_time" => "Fri, 14 Mar 2014 00:00:00 -0500",
"end_time" => "Fri, 21 Mar 2014 00:00:00 -0500",
// ...
));
// Update a Request
$result = $wiw->update("requests/54", array(
"end_time" => "Fri, 21 Mar 2014 00:00:00 -0500",
// ...
));
?>
Example Response
{
"request": {
"id": 54,
"account_id": 0,
"user_id": 135,
"creator_id": 135,
"status": 0,
"type": 0,
"hours": 0,
"start_time": "Fri, 14 Mar 2014 00:00:00 -0500",
"end_time": "Fri, 21 Mar 2014 00:00:00 -0500",
}
}
Show hidden fieldsHide extra fieldsCreates a new Request or updates an existing one.
Create HTTP Request
POST https://api.wheniwork.com/2/requests
Update HTTP Request
PUT https://api.wheniwork.com/2/requests/{request_id}
Parameters
The POST or 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 let users swap shifts with each other or drop shifts for other users to pick up.
For more about using Swaps, visit the Help Center.
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,
"account_id": 0,
"user_id": 145,
"type": 1,
"status": 0,
"accepted_id": 0,
}
],
"more": false,
"page": 1,
"total": 1,
"messages": [
{
"id": 61,
"account_id": 0,
"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,
"login_id": 2112,
"first_name": "Goldie",
"last_name": "Wilson",
},
{
"id": 27384,
"login_id": 2112,
"first_name": "Emmett",
"last_name": "Wilson",
}
]
}
Show hidden fieldsHide extra fieldsGets a list of all swaps in your account.
HTTP Request
GET https://api.wheniwork.com/2/swaps
Parameters
| Key | Description |
|---|---|
| open_only | boolean Whether only open swaps should be included in the results. |
| user_id | integer, string array The ID of the user to get swaps for. For multiple users, enter a list of user IDs separated by commas (e.g. 1,5,3). |
| shift_id | integer, string array The ID of the shift to get swaps for. For multiple shifts, enter a list of shift IDs separated by commas (e.g. 1,5,3). |
| status | integer, string array The status or statuses of swaps that should be included in the results. For multiple statuses, enter a list separated by commas (e.g. 4,5). |
| type | integer, string array The type or types of swaps that should be included in the results. For multiple types, enter a list separated by commas (e.g. 2,3). |
| start | datetime Start time for the shift search window. Must be included if end is defined. |
| end | datetime End time for the shift search window. Must be included if start is defined. |
| limit | integer The number of swaps to include per page. Default is 10. |
| page | integer The page of results to fetch. Default is 1. |
Get Existing Swap
Example Request
curl https://api.wheniwork.com/2/swaps/2238 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("swaps/2238");
?>
Example Response
{
"swaps": [
{
"id": 2238,
"account_id": 0,
"user_id": 145,
"type": 1,
"status": 0,
"accepted_id": 0,
}
],
"messages": [
{
"id": 61,
"account_id": 0,
"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,
"login_id": 2112,
"first_name": "Goldie",
"last_name": "Wilson",
},
{
"id": 27384,
"login_id": 2112,
"first_name": "Emmett",
"last_name": "Wilson",
}
]
}
Show hidden fieldsHide extra fieldsGets the details of a specific swap.
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" => array(1047),
"users" => array(
134,
132,
110
)
));
?>
Example Response Object
{
"swaps": [
{
"id": 2238,
"account_id": 0,
"user_id": 145,
"type": 1,
"status": 0,
"accepted_id": 0,
}
],
"messages": [
{
"id": 61,
"account_id": 0,
"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,
"login_id": 2112,
"first_name": "Emmett",
"last_name": "Brown",
},
{
"id": 132,
"login_id": 2112,
"first_name": "Lorraine",
"last_name": "Tannen",
},
{
"id": 110,
"login_id": 2112,
"first_name": "Goldie",
"last_name": "Wilson",
}
]
}
Show hidden fieldsHide extra fieldsCreates a new swap or updates an existing one.
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 POST or PUT body can include fields from the Swap Object.
Delete Existing Swap
Example Request
curl -X DELETE https://api.wheniwork.com/2/swap/2238 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->delete("swap/2238");
?>
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": "Fri, 13 Apr 2014",
"end_date": "Tue, 1 Jun 2014",
"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.
For more about using Availabilities, visit the Help Center.
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 Whether the availability is 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,
"account_id": 77,
"user_id": 371,
"name": "Emmett's availability preferences.",
"description": "Emmett B.'s summer availability",
"start_date": "Fri, 13 Apr 2014",
"end_date": "Tue, 1 Jun 2014",
},
{
"id": 11,
"account_id": 77,
"user_id": 453,
"name": "George's availability",
"description": "George M.'s School Year Availability",
"start_date": "Fri, 13 Apr 2014",
"end_date": "Tue, 1 Jun 2014",
},
{
"id": 12,
"account_id": 77,
"user_id": 456,
"name": "Lorraine's availability",
"description": "Lorraine B.'s Winter Availability",
"start_date": "Fri, 13 Apr 2014",
"end_date": "Tue, 1 Jun 2014",
}
]
}
Show hidden fieldsHide extra fieldsGets a list of availabilities on your account.
HTTP Request
GET https://api.wheniwork.com/2/availabilities
Parameters
| Key | Description |
|---|---|
| user_id | integer, optional The ID of the user to get availabilities for. For multiple users, enter a list of user IDs separated by commas (e.g. 1,5,3). |
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,
"account_id": 77,
"user_id": 371,
"name": "Emmett's availability preferences.",
"description": "Emmett B.'s summer availability",
"start_date": "Fri, 13 Apr 2014",
"end_date": "Tue, 1 Jun 2014",
},
"availabilityitems": [
{
"id": 85,
"availability_id": 10,
"user_id": 4634,
"day": 0,
"type": 1,
"start_time": "07:15:00",
"end_time": "16:00:00",
},
{
"id": 12,
"availability_id": 10,
"user_id": 4634,
"day": 1,
"type": 1,
"start_time": "08:00:00",
"end_time": "18:30:00",
},
{
"id": 13,
"availability_id": 10,
"user_id": 4634,
"day": 3,
"type": 1,
"start_time": "05:00:00",
"end_time": "14:00:00",
},
{
"id": 14,
"availability_id": 10,
"user_id": 4634,
"day": 5,
"type": 1,
"start_time": "011:00:00",
"end_time": "23:15:00",
}
]
}
Show hidden fieldsHide extra fieldsGets the details of a specific availability.
HTTP Request
GET https://api.wheniwork.com/2/availabilities/{availability_id}
Parameters
| Key | Description |
|---|---|
| availability_id | ID of the availability object being requested. |
Create/Update Availability
Example Request
# Create an Availability
curl -X POST https://api.wheniwork.com/2/availabilities/ \
--data '{"user_id": 4364'}' \
-H "W-Token: ilovemyboss"
# Update an Availability
curl -X PUT https://api.wheniwork.com/2/availabilities/10 \
--data '{"user_id": 4364}' \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
// Create an Availability
$result = $wiw->create("availabilities", array(
"user_id" => 4364,
// ...
));
// Update an Availability
$result = $wiw->update("availabilities/233", array(
"user_id" => 4364,
// ...
));
?>
Example Response
{
"availability": {
"id": 10,
"account_id": 77,
"user_id": 4364,
"name": "Emmett's availability preferences.",
"description": "Emmett B.'s summer availability",
"start_date": "Fri, 13 Apr 2014",
"end_date": "Tue, 1 Jun 2014",
}
}
Show hidden fieldsHide extra fieldsCreates a new availability or updates an existing one.
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 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. |
Availability Items
Example Object
{
"id": 85,
"availability_id": 10,
"user_id": 4634,
"day": 0,
"type": 1,
"start_time": "07:15:00",
"end_time": "16:00:00",
}
Show hidden fieldsHide extra fieldsAvailability Items are individual components of a greater Availability object. Where an Availability is an object that defines a user's availability (in general), each Availability object is made up of Availability Items, each of which contains information about a specific day/time for which the user has specified non-default availability.
Availability item Object
| Parameter | Description |
|---|---|
| id | integer The unique ID of the availability item |
| availability_id | integer The ID of the availability object the item is associated with. |
| user_id | integer The ID of the user that the availability item is associated with. |
| day | integer The day of the week (0-6) for the availability item. |
| type | integer The type of the availability item. (1 = Unavailable, 2 = Preferred) |
| start_time | date time The start time of the availability for the specified day. |
| end_time | date time The end time of the availability for the specified day. |
| created_at | datetime Date at which the availability item was created. |
| updated_at | datetime Date the availability item was most recently updated. |
List Availability Items
Example Request
curl https://api.wheniwork.com/2/availabilities/items \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("availabilities/items");
?>
Example Response
{
"availabilityitems": [
{
"id": 85,
"availability_id": 10,
"user_id": 4634,
"day": 0,
"type": 1,
"start_time": "07:15:00",
"end_time": "16:00:00",
},
{
"id": 12,
"availability_id": 10,
"user_id": 4634,
"day": 1,
"type": 1,
"start_time": "08:00:00",
"end_time": "18:30:00",
},
{
"id": 13,
"availability_id": 10,
"user_id": 4634,
"day": 3,
"type": 1,
"start_time": "05:00:00",
"end_time": "14:00:00",
},
{
"id": 14,
"availability_id": 10,
"user_id": 4634,
"day": 5,
"type": 1,
"start_time": "11:00:00",
"end_time": "23:15:00",
}
]
}
Show hidden fieldsHide extra fieldsGets a list of availability items in your account.
HTTP Request
GET https://api.wheniwork.com/2/availabilities/items
Parameters
| Key | Description |
|---|---|
| user_id | array The ID of the user to list availability items for. For multiple users, enter a list of user IDs separated by commas (e.g. 1,5,3). |
| start | datetime The start date and time you are searching in. |
| end | datetime The end date and time you are searching in. |
Create/Update/Delete Availability Items
Example Request
# Update an Availability's Availability Items
curl -X PUT https://api.wheniwork.com/2/availabilities/10 \
--data '{"items": [{"day": 0, "type": 1, "start_time": "07:15:00", "end_time": "16:00:00"}]}' \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
// Update an Availability's Availability Items
$result = $wiw->update("availabilities/10", array(
"items": array(
array(
"day" => 0,
"type" => 1,
"start_time" => "07:15:00",
"end_time" => "16:00:00",
// ...
),
// ...
)
));
?>
Example Response
{
"availability": {
"id": 10,
"account_id": 77,
"user_id": 371,
"name": "Emmett's availability preferences.",
"description": "Emmett B.'s summer availability",
"start_date": "Fri, 13 Apr 2014",
"end_date": "Tue, 1 Jun 2014",
},
"availabilityitems": [
{
"id": 85,
"availability_id": 10,
"user_id": 4634,
"day": 0,
"type": 1,
"start_time": "07:15:00",
"end_time": "16:00:00",
}
]
}
Show hidden fieldsHide extra fieldsCreates new availability items, updates existing ones, or deletes them.
To edit the availability items, you actually perform an update request to the items' parent availability. See Create/Update Availability.
HTTP Request
PUT https://api.wheniwork.com/2/availabilities/items/{availability id}
Note that the ID in the above URL is for an availability, not an availability item.
Parameters
The "items" field of your PUT body should be an array containing all desired availability items, not just those you wish to update.
Each array item in the "items" field can include fields from the Availability Item Object.
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"
}
Payroll 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 end date of the payroll period. |
| notes | string Notes for the payroll period. |
| is_closed | boolean Whether 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": "",
"is_closed": true,
"is_finalized": true,
"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": "",
"is_closed": true,
"is_finalized": true,
"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": "",
"is_closed": true,
"is_finalized": true,
"finalized_at": "Tue, 29 Nov -001 18:00:00 -0600",
}
]
}
Show hidden fieldsHide extra fieldsThis method allows you to list payroll periods or find ones within a specified date range.
HTTP Request
GET https://api.wheniwork.com/2/payrolls/
Parameters
| Key | Description |
|---|---|
| start | datetime Start date of search range |
| end | datetime End date of search range |
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": "",
"is_closed": true,
"is_finalized": true,
"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,
"total": 318.94
},
{
"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
}
]
}
Show hidden fieldsHide extra fieldsHTTP Request
GET https://api.wheniwork.com/2/payrolls/{id}
Parameters
| Key | Description |
|---|---|
| id | ID of the pay period requested. |
The payrollhours field of the response will include Payroll Hours objects:
Payroll hours Object
| Parameter | Description |
|---|---|
| id | integer The unique ID for this payroll hours object. |
| payroll_id | integer The ID of the Payroll this object belongs to. |
| type | integer The type of hours being reported. (1=Regular, 2=OT, 3=PTO, 4=Holiday, 5=Double Time, 6=Sick) |
| user_id | integer The ID of the user who these hours belong to. |
| position_id | integer The ID of the position that is associated with these hours. |
| hours | float The number of hours. |
| rate | float The hourly rate paid for these hours. |
| total | float The total wages for these hours. |
Payroll Stats
Example Request
curl https://api.wheniwork.com/2/payrolls/24/stats \
-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": "",
"is_closed": true,
"is_finalized": true,
"finalized_at": "Tue, 29 Nov -001 18:00:00 -0600",
},
"stats": {
"employees": {
"4364": {
"hours": {
"regular": 40,
"overtime": 4.78,
"double": 0
},
"wages": {
"regular": 800,
"overtime": 95.6,
"double": 0
}
}
},
"positions": {
"32": {
"hours": {
"regular": 40,
"overtime": 4.78,
"double": 0
},
"wages": {
"regular": 800,
"overtime": 95.6,
"double": 0
}
}
},
"days": [
{
"regular": 11.89,
"overtime": 0,
"double": 0
},
{
"regular": 12.28,
"overtime": 0,
"double": 0
},
{
"regular": 10.42,
"overtime": 0,
"double": 0
},
{
"regular": 5.41,
"overtime": 4.78,
"double": 0
}
],
"locations": {
"136": {
"sites": [
{
"hours": {
"regular": 40,
"overtime": 4.78,
"double": 0
},
"wages": {
"regular": 800,
"overtime": 95.6,
"double": 0
}
}
]
}
}
},
"users": [
{
"id": 4364,
"login_id": 2112,
"first_name": "Goldie",
"last_name": "Wilson",
}
],
"locations": [
{
"id": 136,
"name": "Downtown",
"address": "9303 Lyon Drive, Hill Valley, CA 12345",
"coordinates": [
"34.2390664",
"-118.4332328"
],
}
]
}
Show hidden fieldsHide extra fieldsThis method allows you to request aggregate statistics for a payroll period.
HTTP Request
GET https://api.wheniwork.com/2/payrolls/{id}/stats
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"
}
Time 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,
"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,
}
],
"punches": [
{
"id": 150134,
"method_name": "Mobile",
"time_id": 11,
"user_id": 4634,
"location_id": 136,
"site_id": 0,
"type": 1,
},
{
"id": 150135,
"method_name": "Mobile",
"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,
"login_id": 2112,
"first_name": "Goldie",
"last_name": "Wilson",
}
],
"locations": [
{
"id": 136,
"name": "Downtown",
"address": "9303 Lyon Drive, Hill Valley, CA 12345",
"coordinates": [
"34.2390664",
"-118.4332328"
],
}
]
}
Show hidden fieldsHide extra fieldsThis method allows you to list times or find ones within a specified date range.
HTTP Request
GET https://api.wheniwork.com/2/times/
Parameters
| Key | Description |
|---|---|
| start | Start date of search range |
| end | End date of search range |
| user_id | The ID of the user to get times for. To get times for multiple users, you can enter multiple ids separated by commas. |
Get Existing Time
Example Request
curl https://api.wheniwork.com/2/times/11 \
-H "W-Token: ilovemyboss"
Example Response
{
"times": [
{
"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,
}
]
}
Show hidden fieldsHide extra fieldsHTTP 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,
"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,
}
],
"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,
"account_id": 3,
"name": "Stocker",
"color": "1174a6",
}
]
}
Show hidden fieldsHide extra fieldsThis 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/user/{id}
Parameters
| Key | Description |
|---|---|
| id | The ID of the user to get times for. |
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.
Clock In
Example Request
curl -X POST https://api.wheniwork.com/2/times/clockin/ \
--data '{"id":"14","position_id":"102","coordinates":[44.937422,-93.084009],"accuracy":"20"}' \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->post("times/clockin/", array("id":"14","position_id":"102","coordinates":[44.937422,-93.084009],"accuracy":"20"));
?>
Example Post Data
{
"id": 14,
"position_id": 102,
"coordinates": [
44.937422,
-93.084009
],
"accuracy": 20
}
Example Response
{
"user": {
"id": 14,
"email": "goldiewilson@hillvalleycalifornia.gov",
"first_name": "Goldie",
"last_name": "Wilson",
"punch_state": {
"timestamp": "Thu, 02 Oct 2014 20:53:40 -0500",
"can_punch_in": true,
"can_punch_out": false,
"open_time_id": 2585161,
"near_location_id": 100866,
"near_site_id": null,
"punch_in_shift_id": null
}
},
"times": [
{
"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,
}
],
"locations": [
{
"id": 136,
"name": "Downtown",
"address": "9303 Lyon Drive, Hill Valley, CA 12345",
"coordinates": [
"34.2390664",
"-118.4332328"
],
}
]
}
Show hidden fieldsHide extra fieldsCreate A Clock-in
POST https://api.wheniwork.com/2/times/clockin
Post Body
| Key | Example Value | Description |
|---|---|---|
| id | 14 | The ID of the user you are creating the clock-in for. |
| position_id | 102 | The ID of the position the user is clocking in as. This is an optional parameter. |
| coordinates | [44.937422,-93.084009] | The GPS coordinates of the clock-in. This is an optional parameter. |
| accuracy | 20 | The accuracy in meters of the coordinates being sent. |
Clock out
Example Request
curl -X POST https://api.wheniwork.com/2/times/clockout/ \
--data '{"id":"14","position_id":"102","coordinates":[44.937422,-93.084009],"accuracy":"20"}' \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->post("times/clockout/", array("id":"14","position_id":"102","coordinates":[44.937422,-93.084009],"accuracy":"20"));
?>
Example Post Data
{
"id": 14,
"position_id": 102,
"coordinates": [
44.937422,
-93.084009
],
"accuracy": 20
}
Example Response
{
"user": {
"id": 14,
"email": "goldiewilson@hillvalleycalifornia.gov",
"first_name": "Goldie",
"last_name": "Wilson",
"punch_state": {
"timestamp": "Thu, 02 Oct 2014 20:53:40 -0500",
"can_punch_out": true,
"open_time_id": 2585161,
"near_location_id": 100866,
"near_site_id": null,
"punch_out_shift_id": null
}
},
"times": [
{
"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,
}
],
"locations": [
{
"id": 136,
"name": "Downtown",
"address": "9303 Lyon Drive, Hill Valley, CA 12345",
"coordinates": [
"34.2390664",
"-118.4332328"
],
}
]
}
Show hidden fieldsHide extra fieldsCreate A Clock-out
POST https://api.wheniwork.com/2/times/clockout
Post Body
| Key | Example Value | Description |
|---|---|---|
| id | 14 | The ID of the user you are creating the clock-out for. |
| position_id | 102 | The ID of the position the user is clocking out as. This is an optional parameter. |
| coordinates | [44.937422,-93.084009] | The GPS coordinates of the clock-out. This is an optional parameter. |
| accuracy | 20 | The accuracy out meters of the coordinates being sent. |
Delete Existing Time
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"
}
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,
"account_id": 0,
"user_id": 135,
"request_id": 123,
"title": "This is a message title.",
"content": "This request has been canceled.",
},
{
"id": 456,
"account_id": 0,
"user_id": 14,
"request_id": 123,
"title": "Approved",
"content": "This request has been approved",
},
{
"id": 789,
"account_id": 0,
"user_id": 14,
"request_id": 123,
"title": "Canceled",
"content": "This request has been canceled again.",
}
]
}
Show hidden fieldsHide extra fieldsHTTP Request
GET https://api.wheniwork.com/2/messages
Parameters
| Key | Description |
|---|---|
| swap_id | ID of the swap to get messages for. |
| request_id | ID of the request to get messages for. |
| conversation_id | ID of the conversation to get messages for. |
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,
"account_id": 0,
"user_id": 135,
"request_id": 123,
"title": "This is a message title.",
"content": "This request has been canceled.",
}
}
Show hidden fieldsHide extra fieldsHTTP Request
GET https://api.wheniwork.com/2/messages/{message_id}
Parameters
| Key | Description |
|---|---|
| message_id | ID of the message 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 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 an 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.
For more on using Templates, visit the Help Center.
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",
}
]
}
Show hidden fieldsHide extra fieldsHTTP 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",
}
]
}
Show hidden fieldsHide extra fieldsHTTP 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",
}
]
}
Show hidden fieldsHide extra fieldsCreate 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
Annotations
Example Object
{
"id": 41375,
"account_id": 77,
"creator_id": 46753,
"all_locations": false,
"start_date": "2015-02-19T06:00:00+0000",
"end_date": "2015-02-22T05:59:59+0000",
"title": "Closed for painting",
"message": "We are closed while we have the Minneapolis Store painted.",
"color": "93c31f",
"business_closed": true,
"no_time_off": true,
"announcement": false,
"locations": [
{
"id": 7,
"name": "Minneapolis Store"
}
],
"created_at": "Wed, 19 Feb 2014 10:51:33 -0600",
"updated_at": "Wed, 19 Feb 2014 10:51:33 -0600"
}
Annotations convey important information to all staff for the given location(s) and date range.
Any or none of the following tags may apply to an Annotation:
- Time Off Not Allowed
- Business Closed
- Announcement
The "Time Off Not Allowed" tag is the only tag that affects the behavior of another API. Time Off requests will be considered invalid if the request's date range overlaps an Annotation of the "Time Off Not Allowed" type for the user's location(s).
For more on using Annotations, visit the Help Center.
Annotation Object
| Parameter | Description |
|---|---|
| id | integer The unique ID for this annotation. |
| account_id | integer The ID of the account that this annotation is tied to. |
| creator_id | integer ID of the user who originally created the annotation. |
| all_locations | boolean Determines if this annotation applies to all locations on the account. |
| start_date | string ISO8601 timestamp of when the annotation's range begins. |
| end_date | string ISO8601 timestamp of when the annotation's range ends. |
| title | string Title for annotation (required). |
| message | string Message detailing the annotation (optional). |
| color | string Hex color code to represent this annotation (optional). |
| business_closed | boolean Business Closed tag |
| no_time_off | boolean Time Off Not Allowed tag |
| announcement | boolean Announcement tag |
| locations | array of integer for input, array of objects on output Include locations parameter as an array of location ids when listing, creating, or updating annotations. On output, locations will be an array of location objects when all_locations = false. |
| created_at | datetime The date and time the punch was created. |
| updated_at | datetime The date and time the punch was last updated. |
Listing Annotations
Example Request
curl https://api.wheniwork.com/2/annotations?start_date=2015-02-15&end_date=2015-02-21&locations[]=7&locations[]=8 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("annotations",
array(
"start_date" => "2015-02-15",
"end_date" => "2015-02-21",
"locations" => array(7,8)
)
);
?>
Example Response
{
"annotations": [
{
"id": 41375,
"start_date": "2015-02-19T06:00:00+0000",
"end_date": "2015-02-22T05:59:59+0000",
"title": "Closed for painting",
"message": "We are closed while we have the Minneapolis Store painted.",
"business_closed": true,
"no_time_off": true,
"announcement": false,
}
]
}
Show hidden fieldsHide extra fieldsHTTP Request
GET https://api.wheniwork.com/2/annotations
Parameters
All are optional.
| Key | Description |
|---|---|
| start_date | string Will be parsed as Account timezone if ambiguous |
| end_date | string Will be parsed as Account timezone if ambiguous |
| locations | integer, array May be an integer of a single location_id, or an array of location_ids |
| business_closed | boolean |
| no_time_off | boolean |
| announcement | boolean |
Get Existing Annotation
Example Request
curl https://api.wheniwork.com/2/annotations/41375 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("annotations/41375");
?>
Example Response
{
"annotation": {
"id": 41375,
"start_date": "2015-02-19T06:00:00+0000",
"end_date": "2015-02-22T05:59:59+0000",
"title": "Closed for painting",
"message": "We are closed while we have the Minneapolis Store painted.",
"business_closed": true,
"no_time_off": true,
"announcement": false,
}
}
Show hidden fieldsHide extra fieldsHTTP Request
GET https://api.wheniwork.com/2/annotations/{id}
Parameters
| Key | Description |
|---|---|
| id | ID of the annotation. |
Create/Update Annotation
Annotations can be created by managers and supervisors who can supervise the related location(s).
Create HTTP Request
POST https://api.wheniwork.com/2/annotations/
Update HTTP Requests
PUT https://api.wheniwork.com/2/annotations/{id}
Parameters
The POST or PUT body can include fields from the Annotation Object.
Delete Existing Annotation
Example Request
curl -X DELETE https://api.wheniwork.com/2/annotations/136 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->delete("annotations/136");
?>
Example Response
{
"success": true
}
Annotations can be deleted by managers and supervisors who can supervise the related location(s).
HTTP Request
DELETE https://api.wheniwork.com/2/annotations/{id}
Parameters
| Key | Description |
|---|---|
| id | ID of the annotation to be deleted. |
HEAD Call
Example Request
curl -X HEAD https://api.wheniwork.com/2/annotations/136 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->head("annotations/136");
?>
Example Response Headers
{
"Allow": "GET,OPTIONS,POST,PUT,PATCH,DELETE"
}
You can make a HEAD call on a specific Annotation in order to discover which methods are available to the logged in user.
This is particularly useful for determining if a supervisor (who may belong to some-but-not-all related locations) should have write permissions.
HTTP Request
HEAD https://api.wheniwork.com/2/annotations/{id}
Parameters
| Key | Description |
|---|---|
| id | ID of the annotation in question. |
Devices
Example Object
{
"id": 5,
"account_id": 3,
"user_id": 371,
"type": "android",
"token": "123456789_ABCDEFGHI",
"created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
"updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
}
Devices receive push notifications to communicate important information to staff.
Mobile apps use the POST endpoint to register a device and the DELETE endpoint to unregister.
Device Object
| Parameter | Description |
|---|---|
| id | integer The unique ID for this device object |
| account_id | integer The ID of the account that the device belongs to. |
| user_id | integer The ID of the user that the device belongs to. |
| type | string The type of device (currently 'android' or 'ios'). |
| token | string The device's push token from GCM or APNS. |
| created_at | datetime Date at which the device was created. |
| updated_at | datetime Date the device was most recently updated. |
Listing Devices
Example Request
curl -X POST https://api.wheniwork.com/2/devices/ \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("devices/");
?>
Example Response
{
"device": [
{
"id": 1739,
"account_id": 1,
"user_id": 1,
"type": "android",
"token": "androiddevicetoken",
"created_at": "Fri, 25 Sep 2015 08:44:51 -0700",
"updated_at": "Fri, 25 Sep 2015 08:44:54 -0700"
},
{
"id": 1740,
"account_id": 1,
"user_id": 1,
"type": "ios",
"token": "iphonedevicetoken",
"created_at": "Fri, 25 Sep 2015 08:45:21 -0700",
"updated_at": "Fri, 25 Sep 2015 08:45:21 -0700"
}
]
}
HTTP Request
GET https://api.wheniwork.com/2/devices/
Get Existing Device
Example Request
curl -X POST https://api.wheniwork.com/2/devices/1739 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("devices/1739");
?>
Example Response
{
"id": 5,
"user_id": 371,
"token": "123456789_ABCDEFGHI",
}
Show hidden fieldsHide extra fieldsHTTP Request
GET https://api.wheniwork.com/2/devices/{device_id}
Parameters
| Key | Description |
|---|---|
| device_id | ID of the device being requested. |
Create Device
Example POST Data
{
"token": "Abc123",
"type": "android"
}
Example Request
curl -X POST https://api.wheniwork.com/2/devices/ \
--data '{"token":"Abc123","type":"android"}' \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->post("devices/", array(...));
?>
Devices are registered with the server after receiving a push token from Google Cloud Messaging (GCM) or Apple Push Notification Service (APNS).
Create HTTP Request
POST https://api.wheniwork.com/2/devices/
Parameters
| Key | Description |
|---|---|
| token | Push token of the device to register. |
| type | Type of device ("android" or "ios"). |
Delete Existing Device
Example Request
curl -X DELETE https://api.wheniwork.com/2/devices?token=Abc123 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->delete("devices?token=Abc123");
?>
Example Response
{
"success": true
}
Devices are unregistered from the server after the user logs out of the mobile app.
HTTP Request
DELETE https://api.wheniwork.com/devices?token={token}
Parameters
| Key | Description |
|---|---|
| token | Push token to be deleted. |
Industries
Example Object
{
"id": "34",
"parent": "28",
"sic_code": "5251",
"naics_code": "5251",
"name": "Hardware / Home Improvement",
"created_at": "Fri, 11 Jan 2013 06:22:46 -0600",
"sort": "14"
}
Industries identify the economic industry that an account operates in.
Industry Object
| Parameter | Description |
|---|---|
| id | integer The unique ID for this industry object |
| parent | integer The parent ID for this industry object |
| sic_code | integer The unique SIC code |
| naics_code | integer The unique NAICS code |
| name | string The common name of the industry |
| created_at | timestamp RFC 2822 timestamp of when the industry was added |
| sort | integer The preferred sorted place of this industry |
Listing Industries
Example Request
curl -X GET https://api.wheniwork.com/2/industries/ \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("industries/");
?>
Example Response
{
"industries": [
{
"id": 23,
"sic_code": "7999",
"naics_code": "713990",
"name": "Entertainment / Seasonal",
"parent": 0,
"created_at": "Fri, 11 Jan 2013 06:20:55 -0600",
"sort": 10,
"children": [
{
"id": 37,
"sic_code": "8412",
"naics_code": "712110",
"name": "Music / Dance / Art",
"parent": 23,
"created_at": "Fri, 11 Jan 2013 06:21:58 -0600",
"sort": 19
},
{
"id": 26,
"sic_code": "7999",
"naics_code": "713920",
"name": "Ski Area / Seasonal",
"parent": 23,
"created_at": "Fri, 11 Jan 2013 06:21:44 -0600",
"sort": 29
}
]
},
{
"id": 1,
"sic_code": "5812",
"naics_code": "722310",
"name": "Food Service / Hospitality",
"parent": 0,
"created_at": "Fri, 11 Jan 2013 06:12:02 -0600",
"sort": 12,
"children": [
{
"id": 4,
"sic_code": "5813",
"naics_code": "722410",
"name": "Bar / Club / Sports Bar",
"parent": 1,
"created_at": "Fri, 11 Jan 2013 06:13:32 -0600",
"sort": 3
},
{
"id": 6,
"sic_code": "5812",
"naics_code": "722320",
"name": "Catering / Events",
"parent": 1,
"created_at": "Fri, 11 Jan 2013 06:14:00 -0600",
"sort": 5
}
]
},
{
"id": 48,
"sic_code": "",
"naics_code": "",
"name": "Technology / Software",
"parent": 0,
"created_at": "Fri, 11 Jan 2013 06:12:02 -0600",
"sort": 12,
"children": [
]
}
]
}
HTTP Request
GET https://api.wheniwork.com/2/industries/
Get Existing Industry
Example Request
curl -X GET https://api.wheniwork.com/2/industries/34 \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("industries/34");
?>
Example Response
{
"id": "34",
"parent": "28",
"sic_code": "5251",
"naics_code": "5251",
"name": "Hardware / Home Improvement",
"created_at": "Fri, 11 Jan 2013 06:22:46 -0600",
"sort": "14"
}
HTTP Request
GET https://api.wheniwork.com/2/industries/{industry_id}
Parameters
| Key | Description |
|---|---|
| industry_id | ID of the industry being requested. |
Find Matching Industries
To find potentital matches for Google Place Types,
you can send a place request.
Example Request
curl -X GET https://api.wheniwork.com/2/industries/place?types=home_goods_store,locksmith,establishment \
-H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("industries/place?types=home_goods_store,locksmith,establishment");
?>
Example Response
{
"industries": [
{
"id": "34",
"parent": "28",
"sic_code": "5251",
"naics_code": "5251",
"name": "Hardware / Home Improvement",
"created_at": "Fri, 11 Jan 2013 06:22:46 -0600",
"sort": "14"
}
]
}
HTTP Request
GET https://api.wheniwork.com/2/industries/place?types={place_types}
Parameters
| Key | Description |
|---|---|
| types | A comma-separated list of place types. |
Timezones
Example Object
{
"id": "11",
"name": "Central Time (US & Canada)",
"offset": "-5",
"olson_id": "America/Chicago"
}
Timezone objects contain timezone definitions which are used by other API endpoints.
Timezone Object
| Parameter | Description |
|---|---|
| id | integer The unique ID for this timezone |
| name | string The unique ID for this industry object |
| offset | integer The timezone's offset from UTC |
| olson_id | integer The timezone's name in the Olson tz database |
Listing Timezones
Example Request
curl https://api.wheniwork.com/2/timezones/
<?php
$wiw = new Wheniwork();
$result = $wiw->get("timezones");
?>
Example Response
{
"timezones": [
{
"id": "11",
"name": "Central Time (US & Canada)",
"offset": "-5",
"olson_id": "America/Chicago"
},
{
"id": "9",
"name": "Eastern Time (US & Canada)",
"offset": -4,
"olson_id": "America/New_York"
}
]
}
List all timezones in When I Work.
HTTP Request
GET https://api.wheniwork.com/2/timezones
Get Specific Timezone
Example Request
curl https://api.wheniwork.com/2/timezones/11
<?php
$wiw = new Wheniwork();
$result = $wiw->get("timezones/11");
?>
Example Response
{
"timezone": {
"id": "11",
"name": "Central Time (US & Canada)",
"offset": "-5",
"olson_id": "America/Chicago"
}
}
Get a specific timezone by ID.
HTTP Request
GET https://api.wheniwork.com/2/timezones/{timezone_id}
Parameters
| Key | Description |
|---|---|
| timezone_id | ID of the timezone being requested. |
Errors
When I Work uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- The request is not valid |
| 401 | Unauthorized -- The API key is wrong or the query is misplaced |
| 403 | Forbidden -- The request is below the required permission level |
| 404 | Not Found -- The specified request could not be found |
| 405 | Method Not Allowed -- You tried to access a user with an invalid method |
| 406 | Not Acceptable -- You requested a format that isn't JSON |
| 410 | Gone -- The user requested has been removed |
| 418 | An undefined error occurred |
| 429 | Too Many Requests -- The server is not able to address the number of queries |
| 500 | Internal Server Error -- An internal server error occurred |
| 503 | Service Unavailable -- The service is temporarily offline for maintenance |