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:

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,
      "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,
      "login_id": 5
    },
    {
      "id": 5475,
      "account_id": 12345,
      "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,
      "login_id": 5
    }
  ],
  "accounts": [
    {
      "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": null
    },
    {
      "id": 12345,
      "master_id": 0,
      "type": 3,
      "logo": "https://s3.amazonaws.com/files.wheniwork.com/logos/16434.gif",
      "company": "123 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": null
    }
  ]
}
Show hidden fieldsHide extra fields

Be sure to replace iworksoharditsnotfunny with 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,
    "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,
    "login_id": 5
  }
}
Show hidden fieldsHide extra fields

Be sure to replace iworksoharditsnotfunny with 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.
email 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:

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": {
          "show": true,
          "type": "string",
          "description": "(Optional) Business Name",
          "value": "When I Work"
        },
        "address": {
          "show": true,
          "type": "string",
          "description": "Place Address",
          "value": "60 Plato Blvd, St Paul, MN 55107, United States"
        },
        "place_id": {
          "show": true,
          "type": "string",
          "description": "Place id returned by google",
          "value": "ChIJYfRBzjfVslIRQLB018IGX3o"
        },
        "place_type": {
          "show": true,
          "type": "string, array",
          "description": "Types returned by google",
          "value": "point_of_interest,establishment"
        },
        "latitude": {
          "show": true,
          "type": "string, decimal",
          "description": "Latitude of place location",
          "value": "44.93739849"
        },
        "longitude": {
          "show": true,
          "type": "string, decimal",
          "description": "Longitude of place location",
          "value": "-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,
    "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,
    "token": "ilovemyboss"
  },
  "hash": "the_auto_login_hash"
}
Show hidden fieldsHide extra fields

If 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

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.
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,
      "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
    },
    {
      "id": 27384,
      "account_id": 10000,
      "user_id": 101,
      "location_id": 1045,
      "position_id": 19483,
      "site_id": 4351,
      "start_time": "Sat, 08 Mar 2014 09:00:00 -0600",
      "end_time": "Sat, 08 Mar 2014 17:00: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
    }
  ]
}
Show hidden fieldsHide extra fields

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

HTTP Request

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

Parameters

Key Description
start 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.
site_id integer, string array
The ID of the site to get shifts for. For multiple sites, enter a list of site IDs separated by commas.
position_id integer, string array
The ID of the position to get shifts for. For multiple position, enter a list of position 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.

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,
    "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": "Come in early today.",
    "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
  }
}
Show hidden fieldsHide extra fields

Gets 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,
    "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": "Come in early today.",
    "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
  }
}
Show hidden fieldsHide extra fields

Creates 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]}' \
 -H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->post("shifts/acknowledge/", array(
  "ids" => array(
    34542,
    45434
  )
));
?>

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.

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,
      "account_id": 10000,
      "user_id": 528479,
      "location_id": 1045,
      "position_id": 19483,
      "site_id": 4351,
      "start_time": "Mon, 28 Dec 2015 08:00:00 -0600",
      "end_time": "Mon, 28 Dec 2015 16:00: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
    },
    {
      "id": 27385,
      "account_id": 10000,
      "user_id": 845179,
      "location_id": 1045,
      "position_id": 19483,
      "site_id": 4351,
      "start_time": "Tue, 29 Dec 2015 08:00:00 -0600",
      "end_time": "Tue, 29 Dec 2015 16:00: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
    },
    {
      "id": 27386,
      "account_id": 10000,
      "user_id": 528479,
      "location_id": 1045,
      "position_id": 19483,
      "site_id": 4351,
      "start_time": "Wed, 30 Dec 2015 08:00:00 -0600",
      "end_time": "Wed, 30 Dec 2015 16:00: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
    }
  ]
}
Show hidden fieldsHide extra fields

This 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.

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": null
}

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 in the PHP docs.
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

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

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/11 \
 -H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("account/11");
?>

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

HTTP Request

GET https://api.wheniwork.com/2/account/{account_id}

Parameters

Key Description
account_id ID of the account object to be retrieved.

If the account being queried for is a primary account, the response provides an object with two members: an account object, which specifies the primary account for a given user, and an array, accounts, containing all subaccounts of the primary account.

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.

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 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,
    "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.

Users

Example Object

{
  "id": 4364,
  "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.
account_id integer
ID of the primary account for this user.
role integer
The user's role.
1 = Admin
2 = Manager
3 = Employee (Default)
4 = Lead (Unused)
5 = Supervisor
email 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,
      "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
    },
    {
      "id": 27384,
      "account_id": 10000,
      "role": 2,
      "email": "jen.parker@example.com",
      "first_name": "Jennifer",
      "last_name": "Parker",
      "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
    }
  ]
}
Show hidden fieldsHide extra fields

Get 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,
    "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,
    "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
  }
}
Show hidden fieldsHide extra fields

HTTP 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,
    "account_id": 10000,
    "role": 2,
    "email": "newemail@example.com",
    "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
  }
}
Show hidden fieldsHide extra fields

HTTP 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,
    "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
  }
}
Show hidden fieldsHide extra fields

Get 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,
  "account_id": 10000,
  "role": 2,
  "email": "parrothead1@margaritaville.com",
  "first_name": "Jimmy",
  "last_name": "Buffett",
  "phone_number": "+15552128716",
  "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
}
Show hidden fieldsHide extra fields

Update 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)
email 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"
}' \
 -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.

alert setting Object

Parameter Description
sms boolean
Whether or not SMS messages should be sent for events of this alert type.
email boolean
Whether or not email messages 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
ids integer array
List of IDs of users 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.

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",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    },
    {
      "id": 5,
      "account_id": 3,
      "name": "Bagger",
      "color": "FF6666",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    },
    {
      "id": 6,
      "account_id": 3,
      "name": "Cashier",
      "color": "0066FF",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    }
  ]
}
Show hidden fieldsHide extra fields

This 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",
    "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
    "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
  }
}
Show hidden fieldsHide extra fields

HTTP 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",
    "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
    "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
  }
}
Show hidden fieldsHide extra fields

Creates 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": ""
}

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"
      ],
      "created_at": "Sat, 26 Oct 1985 01:20:00 -0500",
      "updated_at": "Wed, Oct 21 2015 16:29:00 -0500",
      "place": ""
    },
    {
      "id": 137,
      "name": "Uptown",
      "address": "100 Courthouse Square, 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": ""
    }
  ]
}
Show hidden fieldsHide extra fields

This 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
      ],
      "created_at": "Sat, 26 Oct 1985 01:20:00 -0500",
      "updated_at": "Wed, Oct 21 2015 16:29:00 -0500",
      "place": "",
      "latitude": 44.937401,
      "longitude": 93.083855,
      "distance": "37.31790518480344",
      "radius": 100
    }
  ],
  "sites": [
    {
      "id": 9,
      "name": "Twin Pines",
      "location_id": 136,
      "address": "9303 Lyon Drive, Hill Valley, CA 12345",
      "coordinates": [
        44.937401,
        -93.083855
      ],
      "latitude": 44.937401,
      "longitude": 93.083855,
      "distance": "37.31790518480344",
      "radius": 100
    }
  ]
}
Show hidden fieldsHide extra fields

Parameters

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"
    ],
    "created_at": "Sat, 26 Oct 1985 01:20:00 -0500",
    "updated_at": "Wed, Oct 21 2015 16:29:00 -0500",
    "place": ""
  }
}
Show hidden fieldsHide extra fields

Gets 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"
    ],
    "created_at": "Sat, 26 Oct 1985 01:20:00 -0500",
    "updated_at": "Wed, Oct 21 2015 16:29:00 -0500",
    "place": ""
  }
}
Show hidden fieldsHide extra fields

Creates 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,
  "name": "Twin Pines",
  "location_id": 136,
  "address": "1600 S Azusa Ave, City of Industry, CA 91748",
  "coordinates": [
    "33.9935161",
    "-117.9264044"
  ]
}

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.
name string
The name of the site.
location_id integer
The ID of the location that the site belongs to.
address string
The address of the site.
coordinates array

Listing Sites

Example Request

curl https://api.wheniwork.com/2/sites \
 -H "W-Token: ilovemyboss"
<?php
$wiw = new Wheniwork("ilovemyboss");
$result = $wiw->get("sites");
?>

Example Response

{
  "sites": [
    {
      "id": 9,
      "name": "Twin Pines",
      "location_id": 136,
      "address": "1600 S Azusa Ave, City of Industry, CA 91748",
      "coordinates": [
        "33.9935161",
        "-117.9264044"
      ]
    },
    {
      "id": 4,
      "name": "Lone Pine",
      "location_id": 136,
      "address": "1600 S Azusa Ave, City of Industry, CA 91748",
      "coordinates": [
        "33.9935161",
        "-117.9264044"
      ]
    }
  ]
}
Show hidden fieldsHide extra fields

Gets 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,
    "name": "Twin Pines",
    "location_id": 136,
    "address": "1600 S Azusa Ave, City of Industry, CA 91748",
    "coordinates": [
      "33.9935161",
      "-117.9264044"
    ]
  }
}
Show hidden fieldsHide extra fields

Gets 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,
    "name": "Shaded Grove",
    "location_id": 136,
    "address": "1600 S Azusa Ave, City of Industry, CA 91748",
    "coordinates": [
      "33.9935161",
      "-117.9264044"
    ]
  }
}
Show hidden fieldsHide extra fields

Creates 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",
      "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"
    },
    {
      "id": 183,
      "account_id": 0,
      "location_id": 14,
      "position_id": 7,
      "start_time": "06:00:00",
      "end_time": "14: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"
    },
    {
      "id": 204,
      "account_id": 0,
      "location_id": 14,
      "position_id": 7,
      "start_time": "08:45:00",
      "end_time": "16: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"
    }
  ]
}
Show hidden fieldsHide extra fields

Gets 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",
    "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"
  }
}
Show hidden fieldsHide extra fields

Gets 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",
    "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"
  }
}
Show hidden fieldsHide extra fields

Creates 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,
  "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).
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,
      "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"
    },
    {
      "id": 55,
      "account_id": 0,
      "user_id": 135,
      "creator_id": 135,
      "status": 0,
      "type": 0,
      "start_time": "Mon, 24 Mar 2014 08:00:00 -0600",
      "end_time": "Fri, 28 Mar 2014 08:00:00 -0600",
      "created_at": "Wed, 19 Feb 2014 10:51:33 -0600",
      "updated_at": "Wed, 19 Feb 2014 10:51:33 -0600"
    }
  ],
  "messages": [
    {
      "id": 66,
      "account_id": 0,
      "user_id": 135,
      "request_id": 54,
      "swap_id": 0,
      "conversation_id": 0,
      "title": "Request Approved",
      "content": "This Request has been approved",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    },
    {
      "id": 68,
      "account_id": 0,
      "user_id": 135,
      "request_id": 55,
      "swap_id": 0,
      "conversation_id": 0,
      "title": "Request Approved",
      "content": "This Request has been approved",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    }
  ],
  "users": [
    {
      "id": 135,
      "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
    },
    {
      "id": 27384,
      "account_id": 10000,
      "role": 2,
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "first_name": "Emmett",
      "last_name": "Brown",
      "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
    }
  ]
}
Show hidden fieldsHide extra fields

Gets 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 End time for the request time-frame.
since_id Return all requests created since the request with given ID.
max_id Return all requests created before the request with the given ID.
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,
    "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"
  },
  "messages": [
    {
      "id": 61,
      "account_id": 0,
      "user_id": 135,
      "request_id": 54,
      "swap_id": 0,
      "conversation_id": 0,
      "title": "Request Approved",
      "content": "This Request has been approved",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    }
  ],
  "users": [
    {
      "id": 135,
      "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
    }
  ]
}
Show hidden fieldsHide extra fields

Gets 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,
    "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"
  }
}
Show hidden fieldsHide extra fields

Creates 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,
      "statuses": [
        {
          "user_id": 23,
          "status": 0,
          "shift_id": 0
        },
        {
          "user_id": 24,
          "status": 0,
          "shift_id": 0
        }
      ]
    }
  ],
  "messages": [
    {
      "id": 61,
      "account_id": 0,
      "user_id": 135,
      "request_id": 123,
      "swap_id": "2238",
      "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"
    }
  ],
  "shifts": [
    {
      "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
    }
  ],
  "users": [
    {
      "id": 4364,
      "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
    },
    {
      "id": 27384,
      "account_id": 10000,
      "role": 2,
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "first_name": "Emmett",
      "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
    }
  ]
}
Show hidden fieldsHide extra fields

Gets 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 0.

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,
      "statuses": [
        {
          "user_id": 23,
          "status": 0,
          "shift_id": 0
        },
        {
          "user_id": 24,
          "status": 0,
          "shift_id": 0
        }
      ]
    }
  ],
  "messages": [
    {
      "id": 61,
      "account_id": 0,
      "user_id": 135,
      "request_id": 123,
      "swap_id": 2238,
      "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"
    }
  ],
  "shifts": [
    {
      "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
    }
  ],
  "users": [
    {
      "id": 4364,
      "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
    },
    {
      "id": 27384,
      "account_id": 10000,
      "role": 2,
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "first_name": "Emmett",
      "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
    }
  ]
}
Show hidden fieldsHide extra fields

Gets 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,
      "statuses": [
        {
          "user_id": 23,
          "status": 0,
          "shift_id": 0
        },
        {
          "user_id": 24,
          "status": 0,
          "shift_id": 0
        }
      ]
    }
  ],
  "messages": [
    {
      "id": 61,
      "account_id": 0,
      "user_id": 135,
      "request_id": 123,
      "swap_id": 2238,
      "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"
    }
  ],
  "shifts": [
    {
      "id": 1047,
      "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
    },
    {
      "id": 1046,
      "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
    }
  ],
  "users": [
    {
      "id": 134,
      "account_id": 10000,
      "role": 2,
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "first_name": "Emmett",
      "last_name": "Brown",
      "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
    },
    {
      "id": 132,
      "account_id": 10000,
      "role": 2,
      "email": "goldiewilson@hillvalleycalifornia.gov",
      "first_name": "Lorraine",
      "last_name": "Tannen",
      "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
    },
    {
      "id": 110,
      "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
    }
  ]
}
Show hidden fieldsHide extra fields

Creates 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",
      "ongoing": false,
      "repeat": 1,
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    },
    {
      "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",
      "ongoing": false,
      "repeat": 1,
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    },
    {
      "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",
      "ongoing": false,
      "repeat": 1,
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    }
  ]
}
Show hidden fieldsHide extra fields

Gets 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",
    "ongoing": false,
    "repeat": 1,
    "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
    "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
  },
  "availabilityitems": [
    {
      "id": 85,
      "availability_id": 10,
      "user_id": 4634,
      "day": 0,
      "type": 1,
      "start_time": "07:15:00",
      "end_time": "16:00:00",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    },
    {
      "id": 12,
      "availability_id": 10,
      "user_id": 4634,
      "day": 1,
      "type": 1,
      "start_time": "08:00:00",
      "end_time": "18:30:00",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    },
    {
      "id": 13,
      "availability_id": 10,
      "user_id": 4634,
      "day": 3,
      "type": 1,
      "start_time": "05:00:00",
      "end_time": "14:00:00",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    },
    {
      "id": 14,
      "availability_id": 10,
      "user_id": 4634,
      "day": 5,
      "type": 1,
      "start_time": "011:00:00",
      "end_time": "23:15:00",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    }
  ]
}
Show hidden fieldsHide extra fields

Gets 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",
    "ongoing": false,
    "repeat": 1,
    "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
    "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
  }
}
Show hidden fieldsHide extra fields

Creates 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",
  "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
  "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
}
Show hidden fieldsHide extra fields

Availability 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",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    },
    {
      "id": 12,
      "availability_id": 10,
      "user_id": 4634,
      "day": 1,
      "type": 1,
      "start_time": "08:00:00",
      "end_time": "18:30:00",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    },
    {
      "id": 13,
      "availability_id": 10,
      "user_id": 4634,
      "day": 3,
      "type": 1,
      "start_time": "05:00:00",
      "end_time": "14:00:00",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    },
    {
      "id": 14,
      "availability_id": 10,
      "user_id": 4634,
      "day": 5,
      "type": 1,
      "start_time": "11:00:00",
      "end_time": "23:15:00",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    }
  ]
}
Show hidden fieldsHide extra fields

Gets 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",
    "ongoing": false,
    "repeat": 1,
    "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
    "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
  },
  "availabilityitems": [
    {
      "id": 85,
      "availability_id": 10,
      "user_id": 4634,
      "day": 0,
      "type": 1,
      "start_time": "07:15:00",
      "end_time": "16:00:00",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    }
  ]
}
Show hidden fieldsHide extra fields

Creates 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"
}

User Object

Parameter Description
id integer
The unique ID for this payroll item.
account_id integer
The account ID that this payroll item belongs to.
creator_id integer
The user ID of the person who created the payroll item.
start_date datetime
The start date of the payroll period.
end_date datetime
The 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,
      "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"
    },
    {
      "id": 25,
      "account_id": 0,
      "creator_id": 0,
      "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",
      "created_at": "Wed, 19 Feb 2014 10:51:33 -0600",
      "updated_at": "Wed, 19 Feb 2014 10:51:33 -0600"
    },
    {
      "id": 26,
      "account_id": 0,
      "creator_id": 0,
      "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",
      "created_at": "Wed, 19 Feb 2014 10:51:33 -0600",
      "updated_at": "Wed, 19 Feb 2014 10:51:33 -0600"
    }
  ]
}
Show hidden fieldsHide extra fields

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

HTTP Request

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

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,
    "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"
  },
  "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 fields

HTTP Request

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

Parameters

Key Description
id ID of the pay period requested.

Payroll Stats

Example Request

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

Example Response

{
  "payroll": {
    "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"
  },
  "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,
      "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
    }
  ],
  "locations": [
    {
      "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": ""
    }
  ]
}
Show hidden fieldsHide extra fields

This 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"
}

User Object

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

Listing Times

Example Request

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

Example Response

{
  "times": [
    {
      "id": 11,
      "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"
    }
  ],
  "punches": [
    {
      "id": 150134,
      "account_id": 0,
      "time_id": 11,
      "user_id": 4634,
      "location_id": 136,
      "site_id": 0,
      "type": 1,
      "latitude": 34.2390664,
      "longitude": -118.4332328,
      "accuracy": 0,
      "altitude": "259.224731",
      "ip_address": "127.0.0.1",
      "is_alerted": true,
      "alert_type": 8,
      "created_at": "Wed, 19 Feb 2014 10:51:33 -0600",
      "updated_at": "Wed, 19 Feb 2014 10:51:33 -0600"
    },
    {
      "id": 150135,
      "account_id": 0,
      "time_id": 11,
      "user_id": 4634,
      "location_id": 136,
      "site_id": 0,
      "type": 2,
      "latitude": 34.2390664,
      "longitude": -118.4332328,
      "accuracy": 0,
      "altitude": "259.224731",
      "ip_address": "127.0.0.1",
      "is_alerted": true,
      "alert_type": 8,
      "created_at": "Wed, 19 Feb 2014 10:51:33 -0600",
      "updated_at": "Wed, 19 Feb 2014 10:51:33 -0600"
    }
  ],
  "shifts": [
    {
      "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
    }
  ],
  "users": [
    {
      "id": 4364,
      "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
    }
  ],
  "locations": [
    {
      "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": ""
    }
  ]
}
Show hidden fieldsHide extra fields

This 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,
      "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"
    }
  ]
}
Show hidden fieldsHide extra fields

HTTP Request

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

Parameters

Key Description
id ID of the time requested.

Get User Times

Example Request

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

Example Response

{
  "user": {
    "id": 4634,
    "email": "goldiewilson@hillvalleycalifornia.gov",
    "first_name": "Goldie",
    "last_name": "Wilson",
    "positions": [
      32,
      5
    ],
    "locations": [
      136
    ],
    "punch_state": {
      "timestamp": "Wed, 02 Apr 2014 16:21:36 -0500",
      "can_punch_in": false,
      "can_punch_out": true,
      "open_time_id": 158049,
      "near_location_id": null,
      "near_site_id": null,
      "punch_in_shift_id": 1000
    }
  },
  "times": [
    {
      "id": 11,
      "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"
    }
  ],
  "shifts": [
    {
      "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
    }
  ],
  "locations": [
    {
      "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": ""
    }
  ],
  "positions": [
    {
      "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"
    }
  ]
}
Show hidden fieldsHide extra fields

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

HTTP Request

GET https://api.wheniwork.com/2/times/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,
      "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"
    }
  ],
  "locations": [
    {
      "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": ""
    }
  ]
}
Show hidden fieldsHide extra fields

Create 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,
      "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"
    }
  ],
  "locations": [
    {
      "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": ""
    }
  ]
}
Show hidden fieldsHide extra fields

Create 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,
      "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"
    },
    {
      "id": 456,
      "account_id": 0,
      "user_id": 14,
      "request_id": 123,
      "swap_id": 0,
      "conversation_id": 0,
      "title": "Approved",
      "content": "This request has been approved",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    },
    {
      "id": 789,
      "account_id": 0,
      "user_id": 14,
      "request_id": 123,
      "swap_id": 0,
      "conversation_id": 0,
      "title": "Canceled",
      "content": "This request has been canceled again.",
      "created_at": "Thu, 06 Mar 2014 21:12:14 -0600",
      "updated_at": "Thu, 06 Mar 2014 22:17:14 -0600"
    }
  ]
}
Show hidden fieldsHide extra fields

HTTP 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,
    "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"
  }
}
Show hidden fieldsHide extra fields

HTTP 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,
      "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"
    }
  ],
  "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",
      "break_time": 0.5,
      "color": "9a8dd9",
      "notes": "All company meeting!",
      "linked_users": ""
    }
  ]
}
Show hidden fieldsHide extra fields

HTTP Request

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

Get Existing template

Example Request

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

Example Response

{
  "templates": [
    {
      "id": 12,
      "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"
    }
  ],
  "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",
      "break_time": 0.5,
      "color": "9a8dd9",
      "notes": "All company meeting!",
      "linked_users": ""
    },
    {
      "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",
      "break_time": 0.5,
      "color": "9a8dd9",
      "notes": "All company meeting!",
      "linked_users": ""
    },
    {
      "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",
      "break_time": 0.5,
      "color": "9a8dd9",
      "notes": "All company meeting!",
      "linked_users": ""
    }
  ]
}
Show hidden fieldsHide extra fields

HTTP Request

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

Parameters

Key Description
template_id ID of the template being requested.

Create/Update template

Example Request Object

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

Example Response Object

{
  "templates": [
    {
      "id": 12,
      "account_id": 1946,
      "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.",
      "created_at": "Wed, 19 Feb 2014 10:51:33 -0600",
      "updated_at": "Wed, 19 Feb 2014 10:51:33 -0600",
      "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",
      "break_time": 0.5,
      "color": "9a8dd9",
      "notes": "All company meeting!",
      "linked_users": ""
    }
  ]
}
Show hidden fieldsHide extra fields

Create HTTP Request

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

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

Update HTTP Requests

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

Parameters

The PUT body can include fields from the Template Object.

Delete Existing Template

Example Request

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

Example Response

{
  "success": true
}

HTTP Request

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

Parameters

Key Description
template_id ID of the template to be deleted.

Plans

Example Object

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

Get all plans.

Plan Object

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

Listing Plans

Example Request

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

HTTP Request

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

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:

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,
      "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"
    }
  ]
}
Show hidden fieldsHide extra fields

HTTP 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,
    "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"
  }
}
Show hidden fieldsHide extra fields

HTTP 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.

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,
  "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"
}
Show hidden fieldsHide extra fields

HTTP 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.

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