Overview

Shiftboard offers a rich set of Application Programming Interfaces (APIs) to allow external systems to interact with the Shiftboard platform. These APIs take the form of JSON-RPC web service calls or Webhooks. Most Shiftboard application, account, authorization, systems management, and site provisioning data is accessible and the API is continually extended to encompass more of the Shiftboard data and functionality.

All requests and responses are encoded using JavaScript Object Notation (JSON) and encrypted using 256-bit Secure Sockets Layer (SSL). Unencrypted requests are not accepted. Using JSON, HMAC, and Base64 libraries, it should be easy to create, update, list and delete objects within the Shiftboard application. These libraries should be available for all programming languages.

All requests include your organization's unique Access Key ID and are digitally signed by computing an HMAC SHA1 signature of the request with your private (secret) Signature Key. Your private Signature Key should NEVER be transmitted or shared with anyone.

Please see the Requests section for details on making digitally signed requests.

Scope

Virtually every end-user interaction can be implemented using the web service. In fact, all of Shiftboard's end-user applications use the web service. In addition, various types of management functionality not available to end-users are exposed via the web service.

The Shiftboard APIs are constantly evolving. Please ask about any objects or extended functionality that can help meet the requirements of your project.

Webhooks

Shiftboard can make an HTTP request to a customer-specified endpoint when specific events occur. Supported events include the following:

• account created
• account updated
• account deleted
• shift created
• shift updated
• shift deleted
• workgroup membership created
• workgroup membership updated
• workgroup membership deleted

Each of these events can be subscribed to independently (enabled/disabled and endpoint specified).

The webhook call is an HTTP GET request with the URL parameterized with the ID of the affected object. For example, if the account.create endpoint is specified as ‘http://test.com/account/create/' then a notification will look like ‘http://test.com/account/create/###’ where ### is the ID of the newly created account. The ID can be the internal Shiftboard ID, the external Customer ID (if the site is configured to support that), or a customer-specified custom field on the shift object.

For shifts, ‘###’ is the ID of the shift.

For workgroup memberships, there are two IDs: ‘###/###’. The first is the workgroup ID, and the second is the account ID of the member.

For more information, or to get a webhook configured for your site, please contact your Account Manager.

Reference: Webhooks

Getting Set Up

Before you use the Shiftboard Web Services API, you must register with Shiftboard and obtain:

• an Access Key ID (a 36 character sequence)

  • For example: 135fc788-762b-46a6-a80f-3491c14ad26f

• a secret Signature Key (a 40-character sequence)

  • For example: bkvqNVSokbDZVHvt+RzqsrVzI0w7fhcU/jo/eUcY

The Access Key ID is associated with an API Account which will be added to your organization's Shiftboard. You include the Access Key ID in all requests to the Shiftboard Web Services API to identify yourself as the sender of the request, and the associated API Account is used to authorize the requested action.

The Access Key ID is not a secret. To provide proof that you truly are the sender of the request, you also include a digital signature calculated using your secret Signature Key.

Requests and Responses

Shiftboard Web Services are based on the JSON-RPC 2.0 specification, with some extensions. GET and POST requests are supported, but POST is preferred (except for batch requests, which require POST), with formatting based on the JSON-RPC Over HTTP specification.

Selection Criteria

Methods that may apply selection criteria take a select attribute. The value of this attribute is an object with method-dependent attributes. The select attribute is optional for some methods and required for others. Default values may apply for some methods.

Batches

There are three kinds of "batching" in the API: Pagination, Performance Batching, and Batch Requests.

Pagination

For example, to perform an initial request with a page size of 25, include a page attribute in your request:

page: {batch:25}

If there is more than one page of results available, the response will include a page attribute like this:

page: {next: {batch:"25",start:26}, this: {batch:"25",start:1}}

Use the value of the next attribute as the page attribute to get another page:

page: {batch:"25",start:26}

and you will get a response including this:

page: {next: {batch:"25",start:51},
prev: {batch:"25",start:1},
this: {batch:"25",start:26}

(The next attribute will only be present if in fact there is yet another page of data available.)

Methods that return paginated results optionally take a page attribute. The value of this attribute is an object with batch and start attributes. batch specifies the number of records to be returned with each request and must be between 1 and 1000. If not specified, the default is 10. start specifies the record number with which results should start. If not specified, the default is 1.

The response results may include a count attribute giving the total number of records matching the selection criteria, if available.

If records were found, it will include a page attribute giving a pagination object (in the format used by the page request attribute) for this page, the next page, and/or the prev page, as applicable.

Performance Batching

Two requests in one batch. Note batch:true in each, and system.endBatch call at end.

location.create
{
 workgroup:1,
 name:"General Electric",
 zip:"12345",
 batch:true
}

location.create
{
 workgroup:1,
 name:"White House",
 address:"1600 Pennsylvania Ave NW",
 city:"Washington",
 state:"District of Columbia",
 batch:true
}

system.endBatch
{}

This second type of batching involves speeding up requests: if a large number of non-interdependent requests will be sent, a batch attribute can be specified to enable them to be processed more quickly, with a system.endBatch request sent at the end to perform necessary operations that were deferred.

This mode should not be used when processing interdependent requests, for example, adding locations and also adding shifts that use those locations or adding workgroup relationships to those locations.

Batch Requests

Request example:

[
  {
    "id": 1,
    "jsonrpc": "2.0",
    "method": "shift.list",
    "params": {
      "select": {
        "end_date": "2018-01-31",
        "start_date": "2018-01-01"
      }
    }
  },
  {
    "id": 2,
    "jsonrpc": "2.0",
    "method": "location.create",
    "params": {
      "workgroup": 1,
      "name": "General Electric",
      "zip": "12345"
    }
  }
]

Response example (abbreviated):

[
  {
    "id": "1",
    "jsonrpc": "2.0",
    "result": {
      "shifts": [
        {
          "end_date": "2018-01-08T17:00:00",
          "id": "1111111",
          "start_date": "2018-01-08T09:00:00",
          "timezone": "Pacific Time (US/Can) (GMT-08:00)",
          "workgroup": "1"
        }
      ]
    },
  },
  {
    "id": "2",
    "jsonrpc": "2.0",
    "result": {
      "id": "284442"
    }
  }
]

The third type of batching is for sending multiple individual API calls in a single request. The API supports the JSON-RPC 2.0 specification for batches, using POST requests, where instead of supplying a JSON object of parameters, an array of objects is supplied.

Each object in the array contains the jsonrpc, id, method, and params keys. The access_key_id and signature parameters are put in the query string, not in the POST contents. The request signature is for the entire POST contents.

Responses will also be an array, with the "id" in the response object matching the "id" in the request object. If no "id" is supplied in a request object, no response will be given for that part of the request.

Requests

Request Format

A Shiftboard Web Services API request is issued via an HTTP POST or GET request (or POST, for batch requests) to https://api.shiftdata.com. Each request may have the following components:

id

An integer or string. Not used except in that a response should return the same value as passed in the request. This field can be used by the client to correlate a response with its request.

For batch requests, no results will be returned for an individual request unless an id is supplied for that request.

jsonrpc

Version of the JSON-RPC specification for this request. Must always be the string "2.0".

method

A string giving the name of the procedure to be invoked.

params

A object (RFC 4627) that holds the actual parameter values for the invocation of the procedure. All Shiftboard Web Services API methods require params, minimally an empty object ({}). See Objects and Common Attributes.

access_key_id

A 36 character string identifying the client to the Shiftboard Web Services API. May be provided either in the GET request query string or in a cookie.

signature

A 28 character digital signature authenticating the source of this request, computed as described below. May be provided either in the GET request query string or in a cookie.

Those components that may contain characters other than alphanumerics, '-', '.', '_', or '~' should be URI encoded (RFC 3986), as is normal for an HTTP GET request query string.

Request Signature

Given the method name "echo" and the params "{ }", the data
to be signed is "methodechoparams{ }".  Given a signature key
"Xuzh+MDxcW9/CLPD1Z2wiSX51LVrQrStEZPQWk0P", the resulting
base64-encoded HMAC SHA1 signature is "gJ5Oy1E5W4u9XpjWyMoJytlScU8=".
Given an API access key of "57a67b3b-34e4-4c07-a8ca-e7ecb77a7f33",
a complete request would be

"https://api.shiftdata.com/?id=885&jsonrpc=2.0&method=echo&params=eyB9&signature=gJ5Oy1E5W4u9XpjWyMoJytlScU8%3D&access_key_id=57a67b3b-34e4-4c07-a8ca-e7ecb77a7f33"

$AccessKey = "ACCESS_KEY";
$Method = "account.list";
$Params = "{ }";
$Request = "method" . $Method . "params" . $Params;
$ShifboardSecretKey = "SECRET_KEY";
$Params = urlencode(base64_encode($Params));
$Sig = urlencode(base64_encode(hash_hmac('sha1', $Request, $ShifboardSecretKey, true)));

$URL = "https://api.shiftdata.com/servola/api/api.cgi?&access_key_id=" . $AccessKey . "&jsonrpc=2.0&id=1&method=" . $Method . "&params=" . $Params . "&signature=" . $Sig;

Each request is digitally signed by taking components of the request and computing an HMAC SHA1 signature for them using a secret Signature Key (which itself should never be transmitted). The calculated signature is then base64 encoded. The HMAC SHA1 algorithm is described in RFC 2104.

The data to be signed for GET requests is composed of four parts concatenated with no separator:

• The 6 character string method
• The name of the method being called
• The 6 character string params
• The text being passed as params, prior to any base64 or URI encoding

For POST requests, the data to be signed is simply the entire contents of the POST request.

Responses

Response Format

The response to a Shiftboard Web Services API request is a object (RFC 4627) with the following attributes:

id

The id provided in the request. If an error prevented the request from being parsed, this attribute may be null.

jsonrpc

Version of the JSON-RPC specification for this response. Will always be the string "2.0".

result

A object providing the results of the request. Only present when the request was successful. Contents are method-dependent: see Objects and Common Attributes.

error

A object providing error information. Only present when the request failed.

seconds

If provided, number of seconds spent processing the request and formatting a response.

Successful Responses

The attributes returned in response results vary; see Objects.

Error Responses

A properly formatted and authorized request should not result in an error; please contact Shiftboard Support for assistance.

Objects

account object

account: basic attributes

id

A unique identifier for this account.

external_id

The external identifier for this account.

NOTE: This field is only used or returned when external ids are enabled for the site.

first_name

last_name

surname

Currently unused.

middle_name

Currently unused.

screen_name

title

Currently unused.

address

address_second

Second address line

city

state

Full name of state/province/subdivision.

zip

Postal code.

region

Currently unused.

country

email

Email address or dummy login email address. If a dummy address or email is being returned from this address, the bad_email attribute will be true.

bad_email

Boolean; true if the email address is a dummy login email address or email to the email address is being returned.

home_phone

mobile_phone

other_phone

Work/other phone.

pager

fax

is_supervisor

Indicates if this account a supervisor of another member of the site.

supervisor_id

The account's direct_manager id.

direct_manager

The identifier of the account's direct manager they are supervised by.

url

Web/blog address.

timezone

Timezone for this account.

iana_timezone

The IANA timezone for this account.

profile_type

profile type identifier for this account.

org_hold

Boolean. Indicates whether this account is on hold.

org_pending

Pending code indicating on-boarding status of this account. Site configurable pending code labels default to:

• "0" Current

• "1" Pending Registration

• "2" In-Process

• "3" Wait-Listed

• "4" Temp/Seasonal Hold

• "5" Stop Process

• "6" Made Contact/Msg

• "7" Awaiting Reregistration

System-defined pending codes are:

• "1001" Expired Certification
• "1002" Documents Missing
• "1003" Documents Verified

account_points

The current points value for the account (see the accountPoints object).

account: extended attributes

(not all attributes are available for all organizations)

external_id

External ID for this account, if this organization uses external IDs.

notification_preference

Notification preference for this account. Valid values:

• "0" No Notifications

• "1" Send Notifications

get_reminders

Boolean. Enables receiving of reminder messages.

get_confirmations

Boolean. Enables receiving of confirmation messages.

digest_type

Type of notification digest for this account. Valid values:

• "0" Send Immediately (no digest)

• "1" Send Daily

• "2" Send Weekly

sms_txt_number

Number used for SMS (text) messages. If site does not have Premium SMS enabled, must also specify carrier.

carrier

Carrier ID for SMS (text) messages. Only used if site does not have Premium SMS enabled.

level

User level in the organization

• "2" member

• "3" coordinator

• "4" manager

user_type

Will be admin if a super-user, user otherwise.

overtime_exempt

Boolean.

pay_rate

flat_rate

start_date

paycode

Paycode identifier

pay_rate_overrides

Boolean. If false, indicates that for this account, pay_rate does not override the rate associated with the account's paycode.

seniority

Boolean.

seniority_rank

Seniority rank from 1 to 999999999, 1 being the highest rank.

seniority_date

Seniority date.

profile_updated

Time profile information for this account was last updated

updated

Time non-profile information for this account was last updated

account.acceptPrivacyPolicy

Request example:

{}

Response example:

{
   "id" : "1",
   "jsonrpc" : "2.0",
   "result" : {},
   "seconds" : 0.08004
}

Accepts the site privacy policy for the logged-in account. Read the policy at https://www.shiftboard.com/privacy/.

account.create

Request example:

{
   "bad_email" : 1,
   "temp_password" : "test_password",
   "first_name" : "Joe",
   "last_name" : "Tester"
}

Response example:

{
   "seconds" : "0.482992",
   "jsonrpc" : "2.0",
   "id" : "30",
   "result" : {
      "id" : 952
   }
}

Creates a new account record.

Required Parameters

first_name, last_name, and either email or the bad_email flag set true.

Optional Parameters

Other attributes of a account object may be specified. In addition, the following attributes may be specified:

exists_ok

If the specified email address is already in use for an account on Shiftboard for some other Organization, the specified account attributes are not allowed to overwrite the existing account information. Normally, an error is returned indicating that the email address was already in use. If exists_ok is true, the existing account is added to the current organization's accounts instead. In this case, only email and per-organization attributes (external_id and profile_type) and options (add_default_workgroups and send_welcome_letter) are used; any other attributes specified will be discarded (including temp_password and openid).

add_default_workgroups

If true, the new account will be added to any workgroups marked as organization default workgroups.

send_welcome_letter

If true, the standard welcome letter, including the temporary password, will be sent to the account's email address (the email parameter).

temp_password

Normally, a random password is generated for the new account which is only revealed to the new user in the welcome email. If specified, temp_password is used instead.

openid

An openid url that will allow authentication to this account via

https://www.shiftboard.com/login/openid?http...

where http... is the designated url, URI-escaped. E.g. for openid http://www.example.com/, use the login link

https://www.shiftboard.com/login/openid?http%3A%2F%2Fwww.example.com%2F

If this openid is already in use for any account in Shiftboard, an error will be returned.

Response

On success, an id attribute will provide the identifier for the new account. If exists_ok was specified, an existed boolean attribute is returned indicating whether the email address was already in use for an account on Shiftboard.

account.delete

Request example:

{
   "id" : "947"
}

Response example:

{
   "seconds" : "0.173293",
   "jsonrpc" : "2.0",
   "id" : "49",
   "result" : {}
}

Deletes an account record.

Required parameters

id or external_id

Optional parameters

unconfirm_future_shifts

Specify true if shifts on or after today for this account should be unconfirmed.

unpublish_future_shifts

Specify true if shifts being unconfirmed should also be unpublished.

notify

Defaults to false. Specify true to indicate a notification email should be sent to the owner of the deleted account.

Response

On success, empty results will be returned.

account.deleteDocument

Deletes an account document for a given account.

Required parameters

id or external_id and document_number

Response

On success, empty results will be returned.

account.deleteImage

Deletes the user image for a given account.

Required parameters

id or external_id

Response

On success, empty results will be returned.

account.deleteResume

Deletes the resume for a given account.'

Required parameters

id or external_id

Response

On success, empty results will be returned.

account.expiredCertification

Request example:

{
   "id" : "947"
}

Response example:

{
   "seconds" : "0.173293",
   "jsonrpc" : "2.0",
   "id" : "49",
   "result" : {}
}

If an account is not on hold (org_hold is true and org_pending is 0), sets it to Expired Certification org_pending status. Otherwise, does nothing.

Required parameters: id or external_id

Optional parameters:

unconfirm_future_shifts: Specify true if shifts on or after today for this account should be unconfirmed.

unpublish_future_shifts: Specify true if such shifts should be unpublished.

Response: On success, empty results will be returned.

account.get

Request example:

{
   "id" : 911
}

Response example:

{
   "seconds" : "0.057072",
   "jsonrpc" : "2.0",
   "id" : "3",
   "result" : {
      "home_phone" : "",
      "bad_email" : false,
      "state" : "",
      "last_name" : "Tester",
      "email" : "test911@93.julian.example.com",
      "city" : "",
      "fax" : "",
      "url" : "",
      "address" : "",
      "id" : "911",
      "country" : "",
      "org_hold" : false,
      "timezone" : "",
      "middle_name" : "",
      "region" : "",
      "surname" : "",
      "profile_type" : "1",
      "other_phone" : "",
      "zip" : "",
      "org_pending" : "0",
      "pager" : "",
      "mobile_phone" : "",
      "title" : "",
      "first_name" : "Joe"
   }
}

Returns information about a single account.

Required parameters

id or external_id

Optional parameters

account_points_list

Boolean; if specified and true, the results returned will include the account_points_list key. The value will be an array of 0 or more elements, or null if account points are not available for the API call. See accountPoints.list.

extended

Boolean; if specified and true or user_actions is true, the results returned will include an extended set of attributes; otherwise a basic set of attributes will be returned.

image

Boolean; if specified and true, the results returned will include an image_url attribute giving a url to the account's user image or null if no image is available.

image_expiration

Specifies the valid lifetime of the returned URL in seconds; default 300, maximum 604800 (1 week).

qrcode

Boolean; if specified and true, the results returned will include a qrcode attribute giving the data for generating the account's qrcode.

timeclock_status

Boolean; if specified and true, the results returned will include a clocked_in attribute indicating that the account is currently clocked in and a can_clock_in_out attribute indicating whether there is authorization to clock this account in or out.

user_actions

Boolean; if specified and true, a user_actions object will be returned with attributes indicating what actions should be presented to the user to be performed on this account

add_availability

delete_availability

show_availability

Attributes may not be returned for applications that are not enabled for this user/organization.

The response results will be an account object containing basic or basic and extended account fields.

account.getDocument

Returns an account document for a single account.

Required parameters

id or external_id and document_number

Optional parameters

expiration (defaults to 300) to specify valid lifetime of the returned URL in seconds. Maximum 604800 (1 week).

The response results will have an attribute url whose value can be used to fetch the account document.

account.getImage

Request example:

{
   "expiration" : 600,
   "id" : 911
}

Response example:

{
   "seconds" : "0.057072",
   "jsonrpc" : "2.0",
   "id" : "3",
   "result" : {
      "url" : "https://www.shiftboard.com/servola/fetch.cgi?ss=269071;id=269119;expires=1355314332;signature=k_dWIcZ9Mk3HPSzkHgWvtOghFj8"
   }
}

Returns image information about a single account.

Required parameters

id or external_id

Optional parameters

expiration (defaults to 300) to specify valid lifetime of the returned URL in seconds. Maximum 604800 (1 week).

The response results will have an attribute url whose value can be used to fetch the account image.

account.getResume

Returns resume information about a single account.

Required parameters

id or external_id

Optional parameters

expiration (defaults to 300) to specify valid lifetime of the returned URL in seconds. Maximum 604800 (1 week).

The response results will have an attribute url whose value can be used to fetch the account resume.

account.list

Request example:

{}

Response example:

{
   "seconds" : "0.015316",
   "jsonrpc" : "2.0",
   "id" : "3",
   "result" : {
      "count" : "1",
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      },
      "accounts" : [
         {
            "home_phone" : "18007467531",
            "bad_email" : false,
            "state" : "Washington",
            "last_name" : "Testing 2",
            "email" : "132997@servola.org",
            "city" : "Seattle",
            "fax" : "",
            "url" : "",
            "address" : "720 3rd Ave, Suite 2200",
            "id" : "2",
            "country" : "United States",
            "org_hold" : false,
            "timezone" : "Pacific Time (US/Can) (GMT-08:00)",
            "region" : "",
            "middle_name" : "",
            "profile_type" : "1",
            "surname" : "",
            "other_phone" : "",
            "zip" : "98104",
            "org_pending" : "0",
            "pager" : "",
            "mobile_phone" : "",
            "title" : "",
            "first_name" : "Auto"
         }
      ]
   }
}

Returns information about accounts. Uses pagination. Uses select criteria.

Optional parameters

select

An object specifying selection criteria for this request. Allowed criteria are:

account

A single account identifier or an array of identifiers to select.

workgroup

A single workgroup identifier or an array of identifiers to select.

direct_manager

A single direct manager identifier or an array of identifiers to select. Must have TRACK SUPERVISORS feature enabled in order to use this filter. Results will be filtered to only those accounts who are supervised by the direct manager(s) specified.

email

A single email address or an array of them to select.

external_id

A single external_id or an array of them to select, if used by the site.

profile_type

A profile type identifier for which to select accounts.

org_hold

Hold status (boolean)

org_pending

On-boarding status

search

A generic search string; select accounts containing this string in any of: first_name, last_name, first and last names combined, screen name, or, if used by the site, external_id.

extended

Boolean; if specified and true, the results returned will include an extended set of attributes; otherwise a basic set of attributes will be returned for each account.

image

Boolean; if specified and true, the results returned will include an image_url attribute giving a url to the account's user image or null if no image is available.

image_expiration

Specifies the valid lifetime of the returned URL in seconds; default 300, maximum 604800 (1 week).

qrcode

Boolean; if specified and true, the results returned will include a qrcode attribute giving the data for generating the account's qrcode.

shared

Boolean; if specified and true, the results returned will also include accounts in workgroups that are shared to the account.

sort

A single sort criterion or an array of criteria in order from major to minor. Each criterion is either an attribute name (one of first_name, last_name, account_points, or id) or an object with two attributes, name (one of the supported sort attribute names) and direction (asc or desc).

timeclock_status

Boolean; if specified and true, the results returned will include a clocked_in attribute indicating that the account is currently clocked in and a can_clock_in_out attribute indicating whether there is authorization to clock this account in or out.

Response

The response results accounts attribute will be an array of the current page of accounts. Each element of the array will be an account object containing basic or basic and extended account fields.

account.listByWorkgroup

Request example:

{
   "select" : {
      "workgroup" : "226094"
   }
}

Response example:

{
   "seconds" : "0.045885",
   "jsonrpc" : "2.0",
   "id" : "35",
   "result" : {
      "members" : [
         {
            "home_phone" : "18007467531",
            "bad_email" : false,
            "state" : "Washington",
            "last_name" : "Testing 1",
            "email" : "132995@servola.org",
            "city" : "Seattle",
            "fax" : "",
            "url" : "",
            "address" : "720 3rd Ave, Suite 2200",
            "id" : "2",
            "country" : "United States",
            "org_hold" : false,
            "timezone" : "Pacific Time (US/Can) (GMT-08:00)",
            "region" : "",
            "middle_name" : "",
            "profile_type" : "1",
            "surname" : "",
            "other_phone" : "",
            "zip" : "98104",
            "org_pending" : "0",
            "pager" : "",
            "mobile_phone" : "",
            "title" : "",
            "first_name" : "Auto"
         },
         {
            "home_phone" : "",
            "bad_email" : false,
            "state" : "",
            "last_name" : "Tester",
            "email" : "test949@69.julian.example.com",
            "city" : "",
            "fax" : "",
            "url" : "",
            "address" : "",
            "id" : "949",
            "country" : "",
            "org_hold" : false,
            "timezone" : "",
            "middle_name" : "",
            "region" : "",
            "surname" : "",
            "profile_type" : "1",
            "other_phone" : "",
            "zip" : "",
            "org_pending" : "0",
            "pager" : "",
            "mobile_phone" : "",
            "title" : "",
            "first_name" : "Joe"
         },
         {
            "home_phone" : "",
            "bad_email" : false,
            "state" : "",
            "last_name" : "Tester",
            "email" : "test950@69.julian.example.com",
            "city" : "",
            "fax" : "",
            "url" : "",
            "address" : "",
            "id" : "950",
            "country" : "",
            "org_hold" : false,
            "timezone" : "",
            "middle_name" : "",
            "region" : "",
            "surname" : "",
            "profile_type" : "1",
            "other_phone" : "",
            "zip" : "",
            "org_pending" : "0",
            "pager" : "",
            "mobile_phone" : "",
            "title" : "",
            "first_name" : "Joe"
         },
         {
            "home_phone" : "",
            "bad_email" : false,
            "state" : "",
            "last_name" : "Tester",
            "email" : "test951@69.julian.example.com",
            "city" : "",
            "fax" : "",
            "url" : "",
            "address" : "",
            "id" : "951",
            "country" : "",
            "org_hold" : false,
            "timezone" : "",
            "middle_name" : "",
            "region" : "",
            "surname" : "",
            "profile_type" : "1",
            "other_phone" : "",
            "zip" : "",
            "org_pending" : "0",
            "pager" : "",
            "mobile_phone" : "",
            "title" : "",
            "first_name" : "Joe"
         }
      ],
      "count" : "4",
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      }
   }
}

Returns information about accounts with membership in a workgroup. Uses pagination.

Required parameters

select object with a workgroup attribute identifying the workgroup whose members should be returned. E.g. {select:{workgroup:12345}}.

Optional parameters

search

A generic search string; select accounts containing this string in any of: first_name, last_name, first and last names combined, screen name, or, if used by the site, external_id.

sort

A single sort criterion or an array of criteria in order from major to minor. Each criterion is either an attribute name (one of first_name, last_name, or id) or an object with two attributes, name (one of the supported sort attribute names) and direction (asc or desc).

extended

Boolean; if specified and true, the results returned will include an extended set of attributes; otherwise a basic set of attributes will be returned for each account.

The response results members attribute will be an array of the current page of members. Each element of the array will be a member object.

Currently, this method only returns members with org_hold false and org_pending code "0" (Current).

account.listMemberships

Request example:

{
   "select" : {
      "member" : 950
   }
}

Response example:

{
   "seconds" : "0.058298",
   "jsonrpc" : "2.0",
   "id" : "36",
   "result" : {
      "count" : "1",
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      },
      "workgroups" : [
         {
            "zip" : "60616",
            "name" : "Test Workgroup 226094",
            "id" : "226094",
            "code" : "A001"
         }
      ]
   }
}

Returns information about workgroups to which a member belongs. Uses pagination. Uses select criteria.

Optional parameters

select

An object specifying selection criteria for this request

member

The member for which to select workgroups; defaults to the current user.

level

The membership level for which to select workgroups. The filter is a lower limit; any workgroups which the member matches with specified level and above, will be returned.

external_member

The member for which to select workgroups, identified by their external_id; defaults to the current user.

search

A generic search string; select workgroups containing this string in name or code.

union_with_member

Member identifier. If provided, this method will return only those workgroups in which both the member/caller and the sepcified union_with_member belong to.

union_with_external_member

Member identifier, identified by their external_id. If provided, and external identifiers are enabled for the site; this method will return only those workgroups in which both the member/caller and the sepcified union_with_member belong to.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the workgroups attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned workgroups.

The response results workgroups attribute will be an array of the current page of selected workgroups. Each element of the array will be a workgroup object containing basic workgroup fields.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the workgroups results, with only selected minimal attributes provided

sort

A single sort criterion or an array of criteria in order from major to minor. Each criterion is either an attribute name (one of name, or code) or an object with two attributes, name (one of the supported sort attribute names) and direction (asc or desc).

account

id, first_name, last_name, and screen_name attributes are provided.

account.listOpenids

Request example:

{
   "account" : 918
}

Response example:

{
   "seconds" : "0.050461",
   "jsonrpc" : "2.0",
   "id" : "44",
   "result" : {
      "count" : 1,
      "account_openids" : [
         {
            "openid" : "http://openid4.example.com/",
            "id" : "785"
         }
      ]
   }
}

Returns information about account_openid objects for a given account.

Required parameters

account or external_account

The response results account_openids attribute will be an array of the account_openid objects for the designated account.

account.listUpdated

Request example:

{
   "select" : {
      "updated_since" : 1284655937
   }
}

Response example:

{
   "seconds" : "0.057788",
   "jsonrpc" : "2.0",
   "id" : "19",
   "result" : {
      "count" : "1",
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      },
      "accounts" : [
         {
            "home_phone" : "",
            "bad_email" : false,
            "state" : "",
            "last_name" : "Tester",
            "email" : "test913@93.julian.example.com",
            "city" : "",
            "fax" : "",
            "url" : "",
            "address" : "",
            "id" : "913",
            "country" : "",
            "org_hold" : false,
            "timezone" : "",
            "middle_name" : "",
            "region" : "",
            "surname" : "",
            "profile_type" : "1",
            "other_phone" : "",
            "zip" : "",
            "org_pending" : "0",
            "pager" : "",
            "mobile_phone" : "",
            "title" : "",
            "first_name" : "Updated"
         }
      ]
   }
}

Returns information about accounts created or updated since a given date. Uses pagination. Uses select criteria.

Optional parameters

extended

Boolean; if specified and true, the results returned will include an extended set of attributes; otherwise a basic set of attributes will be returned for each account.

select

An object specifying selection criteria for this request. Note that updated_since will have a default value if not specified. The available criteria include all account.list selection criteria with the addition of

updated_since

A system.timestamp previously returned by the system.timestamp method. Only accounts updated since this date will be selected. Defaults to 24 hours ago. If more than 30 days ago, only accounts updated in the last 30 days will be selected.

profile_update

If specified and true, report accounts whose profile information has been updated. Otherwise, report only accounts whose non-profile information has been updated.

The response results accounts attribute will be an array of the current page of accounts. Each element of the array will be an account object containing basic account fields.

account.resetPassword

Request example:

{
   "account" : 945
}

Response example:

{
   "seconds" : "0.060454",
   "jsonrpc" : "2.0",
   "id" : "6",
   "result" : {}
}

Resets the password for an account to a randomly chosen value and sends the new password to the account's email address. If the account has no email address or is not receiving email, no error will result and the password will be changed.

Required parameters

account or external_account, a single account identifier or an array of identifiers of accounts for which to reset the password.

No more than 10000 accounts may be specified in a single request.

Response

On success, empty results will be returned.

Note that this method may be deprecated in the future and replaced with a method to initiate a user-controlled password reset process.

account.self

Request example:

{}

Response example:

{
   "seconds" : "0.04608",
   "jsonrpc" : "2.0",
   "id" : "4",
   "result" : {
      "home_phone" : "18007467531",
      "bad_email" : false,
      "state" : "Washington",
      "last_name" : "Testing 1",
      "email" : "132995@servola.org",
      "city" : "Seattle",
      "fax" : "",
      "url" : "",
      "address" : "720 3rd Ave, Suite 2200",
      "id" : "2",
      "country" : "United States",
      "org_hold" : false,
      "timezone" : "Pacific Time (US/Can) (GMT-08:00)",
      "region" : "",
      "middle_name" : "",
      "profile_type" : "1",
      "surname" : "",
      "other_phone" : "",
      "zip" : "98104",
      "org_pending" : "0",
      "pager" : "",
      "mobile_phone" : "",
      "title" : "",
      "first_name" : "Auto"
   }
}

Returns information about the account associated with the API key making the request.

Optional parameters

extended

Boolean; if specified and true or user_actions is true, the results returned will include an extended set of attributes; otherwise a basic set of attributes will be returned.

image

Boolean; if specified and true, the results returned will include an image_url attribute giving a url to the account's user image or null if no image is available.

image_expiration

Specifies the valid lifetime of the returned URL in seconds; default 300, maximum 604800 (1 week).

qrcode

Boolean; if specified and true, the results returned will include a qrcode attribute giving the data for generating the account's qrcode.

user_actions

Boolean; if specified and true, a user_actions object will be returned with attributes indicating what actions should be presented to the user to be performed on this account

add_availability

delete_availability

show_availability

Attributes may not be returned for applications that are not enabled for this user/organization.

user_permissions

An array of named permissions to check; if specified, a user_permissions object will be returned with the given named permissions as attributes and Boolean values indicating whether each named permission is allowed.

The response results will be an account object containing basic or basic and extended account fields.

If the account is a manager of the organization or one or more workgroups, the additional attribute workgroup_manager will be true. If the account is a coordinator of one or more workgroups, the additional attribute workgroup_coordinator will be true.

If user_actions were requested, a user_actions attribute will also be returned.

account.sendPassword

Request example:

{
   "account" : 944
}

Response example:

{
   "seconds" : "0.075872",
   "jsonrpc" : "2.0",
   "id" : "3",
   "result" : {}
}

Sends a password reset link for an account to the account's email address. If the account has no email address or is not receiving email, no error will result.

Required parameters

account or external_account, a single account identifier or an array of identifiers of accounts for which to send the password reset.

No more than 10000 accounts may be specified in a single request.

Response

On success, empty results will be returned.

account.sendWelcomeLetter

Request example:

{
   "account" : 917
}

Response example:

{
   "seconds" : "0.081154",
   "jsonrpc" : "2.0",
   "id" : "40",
   "result" : {}
}

Send a welcome email to the account's email address, giving them their password. If the account has no email address or is not receiving email, no error will result.

Required parameters: account or external_account, a single account identifier or an array of identifiers of accounts for which to send a welcome letter.

account

A single account identifier or an array of identifiers to select. No more than 10000 accounts may be specified in a single request.

external_account

A single external ID (or an array of them if used by the site). No more than 10000 accounts may be specified in a single request.

workgroup

Optional, only send welcome email to accounts that belongs to the specified group

unsent

Optional, an integer value. * value is possive - number of months since the welcome email was sent out last time. * value is '0' - welcome email will be sent out to all accounts. * value is '-1' - welcome email will only be sent out to new members the welcome email has never been sent out to before.

profile_type

Optional, either a single value or an array of profile-types (the enumeration key of the profile-type, example value [2,3])

Response

On success, empty results will be returned.

account.update

Request example:

{
   "email" : "test952@69.julian.example.com",
   "bad_email" : 0,
   "notification_preference" : 1,
   "id" : 952
}

Response example:

{
   "seconds" : "0.157625",
   "jsonrpc" : "2.0",
   "id" : "31",
   "result" : {}
}

Updates an account object.

Required parameters

id or external_id

Optional parameters

unconfirm_future_shifts

Specify true if, when org_hold is being changed to true and/or org_pending is being changed to a non-0 value, shifts on or after today for this account should be unconfirmed.

unpublish_future_shifts

Specify true if shifts being unconfirmed should also be unpublished.

Other account object attributes may be specified.

NOTE: Updating another account's email address or notification options is not allowed if the account is active with more than one organization's Shiftboard.

Response

On success, empty results will be returned.

account.updateDocument

Updates an account document for a single account.

Required parameters

id or external_id and document_number

Optional parameters

expiration (defaults to 300) to specify valid lifetime of the returned URL in seconds. Maximum 3600 (1 hour).

The response results will have an attribute url to which the new/updated document may be POSTed.

Upon success, the request to the url will return an HTTP 204 status code.

account.updateImage

Updates the user image for a single account.

Required parameters

id or external_id

Optional parameters

expiration (defaults to 300) to specify valid lifetime of the returned URL in seconds. Maximum 3600 (1 hour).

The response results will have an attribute url to which the new/updated user image may be POSTed.

Upon success, the request to the url will return an HTTP 204 status code.

account.updateResume

Updates the resume for a single account.

Required parameters

id or external_id

Optional parameters

expiration (defaults to 300) to specify valid lifetime of the returned URL in seconds. Maximum 3600 (1 hour).

The response results will have an attribute url to which the new/updated resume may be POSTed.

When posting to the returned url, one of the following content-types should be specified:

• application/vnd.openxmlformats-officedocument.wordprocessingml.document
• application/msword
• text/plain
• text/rtf
• application/pdf
• application/vnd.ms-office

Upon success, the request to the url will return an HTTP 204 status code.

accountPoints object

accountPoints: basic attributes

id

A unique identifier for this points record.

account_points

The points for the record. A number from -100.000 to 100.000.

created_by

The ID of the account that created the record.

created_by_name

The screen name of created_by.

created_date

The datetime the points were created, in UTC.

date

The date the points are for (e.g., the start_date of the shift, or the date supplied in accountPoints.create), in the site’s timezone.

display_date

The date formatted for the user.

display_expiration_date

The expiration_date formatted for the user.

expiration_date

The date (no time) the points expire.

reason

The text reason for the points. For ad hoc points, it is just the text of reason (a string from 0 to 4096 bytes). For attendance points, it is the label associated with reason_id.

reason_id

The ID of the reason given for the points, if created by an attendance action. Else null.

shift

A shift object, if attached to a shift. Else null.

type

One of ad_hoc, absent, arrive_late, or leave_early.

accountPoints.create

Request example:

{
   "account" : 113,
   "date" : "2020-07-02",
   "account_points" : 10,
   "reason" : "wore a New York Yankees t-shirt"
}

Response example:

{
   "result" : {
      "id" : 1001
   }
}

Creates a new ad hoc accountPoints record.

Required Parameters

account_points. Additionally, either date OR shift (a shift ID) is required, and either account OR external_account.

Optional Parameters

reason

Response

On success, an id attribute will provide the identifier for the new accountPoints record.

accountPoints.delete

Request example:

{
   "id" : 1001
}

Response example:

{
   "result" : {}
}

Deletes an ad hoc accountPoints record.

Required Parameters

id

Response

On success, returns an empty object.

accountPoints.list

Request example:

{
   "account" : 113
}

Response example:

{
   "result" : {
      "account_points" : [
         {
            "account": "113",
            "account_points" : 10,
            "created_by" : 114,
            "created_by_name" : "Deb Nicol",
            "created_date" : "2020-07-02T20:59:19Z",
            "date" : "2020-07-02",
            "display_date" : "Thursday, July 2, 2020",
            "display_expiration_date" : "Friday, Jan 1, 2100",
            "expiration_date" : "2100-01-01",
            "id" : 1001,
            "reason" : "wore a New York Yankees t-shirt",
            "reason_id" : null,
            "shift" : null,
            "type" : "ad_hoc",
            "user_actions" : {
               "delete" : true,
               "edit" : true,
            }
         },
         {
            "account": "113",
            "account_points" : 1,
            "created_by" : 113,
            "created_by_name" : "Jet the Dog",
            "created_date" : "2020-07-01T13:50:22Z",
            "date" : "2020-07-01",
            "display_date" : "Wednesday, July 1, 2020",
            "display_expiration_date" : "Thursday, July 1, 2021",
            "expiration_date" : "2021-07-01",
            "id" : 994,
            "reason" : "Emergency",
            "reason_id" : 36425,
            "shift" : {
               "display_adj_start_time" : "11:50pm",
               "display_date" : "2020-07-15",
               "display_end_time" : "11:30am (Thurs)",
               "display_start_time" : "11:30pm",
               "display_time" : "11:30pm - 11:30am (Thurs)",
               "end_date" : "2020-07-01T20:00:00Z",
               "id" : 323451686,
               "local_arrive_late_datetime" : "2020-07-15T23:50:00",
               "local_end_date" : "2020-07-16T11:30:00",
               "local_start_date" : "2020-07-15T23:30:00",
               "local_timezone" : "Central Time (US/Can) (GMT-06:00)",
               "start_date" : "2020-07-01T13:00:00Z",
               "workgroup" : 2699032,
               "workgroup_label" : "Team A"
            },
            "type" : "absent",
            "user_actions" : {
                "delete" : false,
                "edit" : false
            }
         }
      ],
      "total" : 11,
      "user_actions" : {
         "create" : true
      }
   }
}

Returns active accountPoints records for an account, sorted in reverse order by date.

Required parameters

account or external_account

Optional parameters

user_actions

Boolean; if specified and true, a user_actions object will be returned with attributes indicating what actions may be presented to the user to perform on each accountPoints object (edit, delete), and accountPoints actions on the account itself (create).

Attendance account points cannot be edited or deleted directly, so booleans for those will always be false.

Response

The response results account_points attribute will be an array of accountPoints. Each element of the array will be an accountPoints object, including a user_actions attribute.

Also returned will be a total attribute with the current total points for the account, and a user_actions attribute.

accountPoints.shiftList

Request example:

{
   "select" : {
      "covering_member" : "114"
   }
}

Exactly the same as shift.list, except for the following differences:

• date parameters may not be specified; shifts after today (in the organization's timezone) or shifts whose points would already be expired will be excluded
• the results are ordered by shift start date, in reverse order

accountPoints.update

Request example:

{
   "id" : 1001,
   "date" : "2020-07-02",
   "account_points" : 10,
   "reason" : "wore a New York Yankees t-shirt"
}

Response example:

{
   "result" : {
      "id" : 1003
   }
}

Updates an ad hoc accountPoints record. A new record, with a new ID, will be created in its place, with the updated information.

Required Parameters

id

Optional Parameters

reason, date OR shift (a shift ID), account_points

Response

On success, an id attribute will provide the identifier for the new accountPoints record.

attestation object

attestation objects have the following attributes:

id

Unique identifier (UUID) for this attestation. Automatically generated with attestation.create.

attestation_type_id

ID for the related attestationType object. Required.

account

The account identifier for this attestation. Either account or external_account is required.

external_account

The external account identifier for this attestation. Either account or external_account is required.

active

Boolean for whether this attestation is active. Default is the auto_activation setting of the attestationType.

valid

Boolean for whether this attestation is valid, based on whether it meets the requirements of the attestationType (for example, if name_setting is required in the type, and name is NULL in the attestation, the attestation is invalid). An invalid attestation will not be used for shift conflict checking.

name

Name of the attestation object (255-character string). Optional (depending on attestationType settings).

start_date

Date at which this attestation starts; null if attestation extends indefinitely into the past. Optional (depending on attestationType settings).

end_date

Date at which this attestation ends; null if attestation extends indefinitely into the future. Optional (depending on attestationType settings).

timezone

An IANA timezone name, e.g. America/Los_Angeles. See IANA Time Zone Database for more information. Default is the timezone of the account, or if not set, the site.

document

Boolean for whether this attestation has an attached document.

Additionally, there is a special kind of attestation objects called an "exemption" record, used for when an account is exempt from that attestationType. It is created/deleted with separate methods (attestation.exempt and attestation.unexempt), and never modified.

Exemption attestation objects have the following attributes:

id

Unique identifier (UUID) for this attestation. Automatically generated with attestation.create.

account

The account identifier for this attestation. Either account or external_account is required.

external_account

The external account identifier for this attestation. Either account or external_account is required.

exempt

Boolean for whether this attestation is an exemption record.

attestationType object

attestationType objects have the following attributes:

id

Unique identifier (UUID) for this attestation. Automatically generated with attestationType.create.

name

Name of the attestation type (255-character string). Must be unique. Required.

enabled

Boolean for whether this attestation type is enabled. Default is true.

hold_account

Boolean for whether accounts with this attestation type will be put on hold on when the account falls into an "expired" state (i.e., it has attestations of this type that have expired, and currently has no active attestations of this type). Used only with advanced onboarding. Default is false.

auto_activation

Boolean for whether a new attestation record defaults to active. Default is true.

name_required

start_date_required

end_date_required

document_required

Setting for whether the attestation field is required for an attestation of this type. When one of these settings is changed, the attestations of that type are not modified, though whether they are valid may change. optional: in the API and UI, but not required to be valid. required: in the API and UI, and required to be valid. unused: not in the API or UI, and not required to be valid. One of optional, required, unused. Default is optional.

EXAMPLE 1: If an attestation has a start_date and then the attestation type's start_date_required is set to unused, the record will be treated as though its start_date is blank, though the stored start_date will not change.

EXAMPLE 2: If start_date_required is then changed to optional or required, the stored start_date will be used.

EXAMPLE 3: If the stored start_date is blank and start_date_required is changed from optional or unused to required, the attestation will no longer be valid.

attestationType.list

Request example:

{
  "select" : {
    "workgroup" : "226084"
  }
}

Response example:

{
  "id" : "1",
  "jsonrpc" : "2.0",
  "result" : {
    "attestationTypes" : [
      {
        "auto_activation" : false,
        "document_required" : "optional",
        "enabled" : true,
        "end_date_required" : "optional",
        "hold_account" : false,
        "id" : "01234567-890a-bcde-f012-3456789abcde",
        "name" : "Contract",
        "name_required" : "optional",
        "permissions" : "{}",
        "start_date_required" : "optional"
      },
      {
        "auto_activation" : false,
        "document_required" : "optional",
        "enabled" : true,
        "end_date_required" : "optional",
        "hold_account" : false,
        "id" : "12345678-90ab-cdef-0123-456789abcdef",
        "name" : "Certifications",
        "name_required" : "optional",
        "permissions" : "{}",
        "start_date_required" : "optional"
      }
    ]
  },
  "seconds" : "0.089939"
}

Returns attestation type records for the org.

Required Parameters

• select - An object specifying selection criteria for this request. Allowed criteria are:
  • workgroup (team)

Response

On success, the selected attestationType records will be returned as an array in the "attestationTypes" key.

availability object

availability objects have the following attributes:

id

Unique identifier for this availability.

account

Account identifier for this availability.

external_account

The external account identifier for this object.

NOTE: This field is only used or returned when external ids are enabled for the site.

busy

false if the availability record indicates availability; true if it indicates unavailability.

start_date

Date at which this availability starts; null if availability extends indefinitely into the past.

end_date

Date at which this availability ends; null if availability extends indefinitely into the future.

start_time

Start time for each date of this availability, in RFC 3339 partial time format (e.g. "13:00:00"), or null if the availability extends from the beginning of the day.

note: It is not possible to specify the seconds for start_time. This value should always be set to: "00"

end_time

End time for each date of this availability, in RFC 3339 partial time format (e.g. "13:00:00"), or null if the availability extends to the end of the day.

note: It is not possible to specify the seconds for end_time. This value should always be set to: "00"

workgroup

Workgroup identifier for this availability or null if no workgroup

sunday

monday

tuesday

wednesday

thursday

friday

saturday

true for all days of the week (within the date range, if specified) to which this availability applies.

availability.approve

Approves request to change an availability record.

Parameters:

id

Required. id of the availability record for which to be approved/denied change.

approve

Required. Boolean, indicates that, availability record is approved or denied. True is approved, false is denied.

message

Optional. A text message that is included in notification message.

Response: On success, empty results will be returned.

availability.create

Creates a new availability record.

Required Parameters:

account

account identifier or array of account identifiers

NOTE: If you are calling this method with the account parameter, external_account will be ignored (if included).

external_account

external account identifier or array of external account identifiers

NOTE: If you are calling this method with the account parameter, external_account will be ignored (if included).

external_account

external account identifier or array of external account identifiers

NOTE: If you are calling this method with the external_account parameter, account will be ignored (if included).

busy

false if the availability record indicates availability; true if it indicates unavailability.

Any availability object attributes may be specified. If no day of week attributes are specified, all applicable (i.e. within the date range, if specified) days of the week will default to true; otherwise, at least one applicable day of week attribute must be true.

Additionally, if start_date and end_date are not specified, a date attribute may be specified with a single date or array of dates for which to create availability records.

Response: On success, if either the account or date parameters is an array, an empty object is returned; otherwise, an id attribute will provide the identifier for the new availability record.

availability.delete

Request example:

{
   "id" : "2753"
}

Response example:

{
   "seconds" : "0.058344",
   "jsonrpc" : "2.0",
   "id" : "67",
   "result" : {}
}

Deletes an availability record.

Required parameter: id.

Response: On success, empty results will be returned.

availability.get

Returns information about an availability record.

Parameters:

id

Required. id of the availability record for which to return information.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the availability attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned availability record.

The response results availability attribute will be the selected availability object.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the availability results or in its associated shift, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

availability.list

Request example:

{
   "select" : {
      "account" : 1
   }
}

Response example:

{
   "seconds" : "0.089939",
   "jsonrpc" : "2.0",
   "id" : "10",
   "result" : {
      "availability" : [
         {
            "sunday" : false,
            "friday" : true,
            "account" : "1",
            "start_time" : "11:00:00",
            "tuesday" : true,
            "monday" : true,
            "end_time" : "12:00:00",
            "end_date" : null,
            "wednesday" : true,
            "saturday" : false,
            "thursday" : true,
            "id" : "236471",
            "start_date" : "2013-04-01",
            "busy" : true
         },
         {
            "sunday" : false,
            "friday" : false,
            "account" : "1",
            "start_time" : "05:00:00",
            "tuesday" : false,
            "monday" : false,
            "end_time" : "11:00:00",
            "end_date" : null,
            "wednesday" : false,
            "saturday" : true,
            "thursday" : false,
            "id" : "237006",
            "start_date" : null,
            "busy" : false
         }
      ],
      "count" : "5",
      "page" : {
         "this" : {
            "batch" : 10,
            "start" : 1
         }
      }
   }
}

Returns information about account availability data. Uses select criteria. Uses pagination.

Parameters:

select

An object specifying selection criteria for this request. The available criteria include:

account

The account identifier or array of account identifiers for which to return availability.

external_account

The external account identifier or array of external account identifiers for which to return availability.

start_date

end_date

The date range for which to return availability (including any availability that extends before and/or after the given date range); either or both dates may be null to indicate a date range extending indefinitely into the past or future, respectively. start_date defaults to today, end_date to null.

start_time

end_time

Start and end time in RFC 3339 partial time format (e.g. 13:45:00). Return only availability records that encompass this time range; if either is specified, both must be.

workgroup

Workgroup identifier if only availability specific to a given workgroup should be returned, or null if only availability not specific to any workgroup should be returned.

busy

True if only Busy availability should be returned; false if only Available availability should be returned.

sunday

monday

tuesday

wednesday

thursday

friday

saturday

Booleans; return only availability for the given days of the week.

any_selected_day

Boolean, default false. If true, return availability for any of the selected days; if false, return availability records that are for all of the selected days.

org_hold

Boolean account hold status.

org_pending

Account onboarding status.

scope

A value of 'by_account' requests availability for a specific account (defaulting to the user's account if no account criterion is provided). A value of 'siteadmin' requests all availability for the entire site and is only allowed for site administrators. A value of 'managed_workgroups' requests availability for members of the workgroups managed by the user and is only allowed for workgroup managers. 'siteadmin' is the default for site administrators, 'managed_workgroups' is the default for managers, and 'by_account' is the default for others.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the availability attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned availability records.

The response results availability attribute will be an array of the current page of availability. Each element of the array will be an availability object.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the availability results, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

sort

A single sort criterion or an array of criteria in order from major to minor. Each criterion is either an attribute name (one of first_name, last_name) or an object with two attributes, name (one of the supported sort attribute names) and direction (asc or desc).

availability.update (not currently available)

Please let us know if you would like access to this method.

calendar object

calendar objects have the following attributes:

start_date

The starting date for querying the calendar object.

end_date

The ending date for querying the calendar object.

calendar.summary

Request example:

{
   "shifts" : {
      "coverage_type" : [
         "mine",
         "available",
         "confirmed"
      ]
   },
   "include_shifts" : true,
   "include_tradeboard" : true,
   "timeOffRequests" : {
      "member" : 1,
      "status" : 0
   },
   "workgroups" : [],
   "include_timeOff" : true,
   "tradeboard" : {
      "trade_complete" : true
   },
   "end_date" : "2017-02-28",
   "start_date" : "2017-02-01"
}

Response example:

{
   "seconds" : "0.391969",
   "jsonrpc" : "2.0",
   "id" : "3",
   "result" : {
      "summaries" : [
         {
            "trades" : false,
            "confirmed" : true,
            "date" : "2017-04-01",
            "timeOffRequest" : false,
            "mine" : true,
            "available" : true
         },
         {
            "trades" : true,
            "confirmed" : true,
            "date" : "2017-04-02",
            "timeOffRequest" : true,
            "mine" : true,
            "available" : true
         },
         {
            "trades" : true,
            "confirmed" : true,
            "date" : "2017-04-03",
            "timeOffRequest" : true,
            "mine" : true,
            "available" : true
         }
      ]
   }
}

Get a summarized list of data for a given date range.

Required parameters:

start_date

end_date

Optional parameters:

workgroups

Selects only the included workgroups, if and only if array contains elements

include_shifts

Include shift information. If not defined, this property is set to true

shifts

Additional configuration for what shift information to display. Options are as follows:

coverage_type

Coverage type array with possible values of `mine`, `available`, `confirmed`, `signup_list`, and `no_pick_up`. If not specified, all of these types are included in the response.

include_timeOff

Include time off information. If not defined, this property is set to true

timeOffRequests

Additional configuration for what time off information to display. Options are as follows:

status

Accepts any valid timeOffRequest status

member

Only show data relevant to the specified member. Accepts the internal Shiftboard Member ID (small integer).

external_member

Only show data relevant to the specified member. Accepts an external Member ID (only if site is configured to use external IDs).

include_tradeboard

Include tradeboard information. If not defined, this property is set to true.

tradeboard

Additional configuration for what tradeboard information to display. The only option is:

trade_complete

Accepts Tradeboard's trade_complete

Response: On success, an array of summaries will be returned.

On error, one of the following error codes may be returned:

• Missing start_date
• Missing end_date
• Invalid exists value
• Invalid exists criteria

client object

client objects have the following attributes:

id

A unique identifier for this client.

name

The name of this client. Maximum length 128 characters.

business_name

Business name. Maximum length 100 characters.

address

Address line (e.g. "123 Main St"). Maximum length 100 characters.

address_second

Second address line. Maximum length 100 characters.

city

City. Maximum length 100 characters.

state

Abbreviation or full name of state/province/subdivision. Maximum length 64 characters.

zip

Postal code. Maximum length 12 characters.

country

Country. Maximum length 24 characters.

contact_first_name

First name of contact person. Maximum length 100 characters.

contact_last_name

Last name of contact person. Maximum length 100 characters.

contact_phone

Phone number of contact person. Maximum length 100 characters.

contact_email

Email address of contact person. Maximum length 255 characters.

Notes

special_instructions

client.create

Request example:

{
   "workgroup" : "226072",
   "name" : "client 887"
}

Response example:

{
   "seconds" : "0.391969",
   "jsonrpc" : "2.0",
   "id" : "3",
   "result" : {
      "id" : "988"
   }
}

Request example with "exists_ok" set:

{
   "workgroup" : "226072",
   "name" : "client 887",
   "exists_ok": true
}

Response example when client didn't already exist:

{
   "seconds" : "0.391969",
   "jsonrpc" : "2.0",
   "id" : "3",
   "result" : {
      "id" : "988",
      "new": true
   }
}

Response example when client already existed:

{
   "seconds" : "0.391969",
   "jsonrpc" : "2.0",
   "id" : "3",
   "result" : {
      "id" : "988",
      "new": false
   }
}

Creates a new client record.

Parameters: Any attributes of a client object (except id) may be specified. A unique name parameter must be specified. Additionally, a workgroup parameter must be specified to create initial workgroup relationships for this client. It may be either a single workgroup identifier or an array of identifiers of workgroups that use this client.

Response: On success, an id attribute will provide the identifier for the new client.

client.delete

Deletes a client.

Required parameter: id.

On success, empty results will be returned.

client.get

Request example:

{
   "id" : "988"
}

Response example:

{
   "seconds" : "0.065741",
   "jsonrpc" : "2.0",
   "id" : "7",
   "result" : {
      "special_instructions" : "test special instructions",
      "country" : "USA",
      "contact_phone" : "5555551212",
      "contact_last_name" : "test",
      "name" : "client 887",
      "contact_first_name" : "client",
      "state" : "WA",
      "city" : "testmetro",
      "zip" : "90210",
      "notes" : "test note",
      "address_second" : "apt 1 test",
      "contact_email" : "test@example.com",
      "id" : "988",
      "address" : "123 test st",
      "business_name" : "test"
   }
}

Returns information about a single client.

Required parameter: id

The response results will be a client object.

client.list

Request example:

{
   "select" : {
      "client" : "988"
   }
}

Response example:

{
   "seconds" : "0.065741",
   "jsonrpc" : "2.0",
   "id" : "7",
   "result" : {
      "count" : "1",
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      },
      "clients" : [
         {
            "special_instructions" : "test special instructions",
            "country" : "USA",
            "contact_phone" : "5555551212",
            "contact_last_name" : "test",
            "name" : "client 887",
            "contact_first_name" : "client",
            "state" : "WA",
            "city" : "testmetro",
            "zip" : "90210",
            "notes" : "test note",
            "address_second" : "apt 1 test",
            "contact_email" : "test@example.com",
            "id" : "988",
            "address" : "123 test st",
            "business_name" : "test"
         }
      ]
   }
}

Returns information about clients. Uses pagination.

Optional parameters:

select

An object specifying selection criteria for this request. Allowed criteria are:

client

A single client identifier or array of client identifiers.

search

A generic search string; select clients containing this string in their name.

workgroup

The response results clients attribute will be an array of the current page of clients. Each element of the array may have the following attributes:

id

A unique identifier for this client.

name

The name of this client.

client.update

Request example:

{
   "special_instructions" : "test special instructions",
   "contact_phone" : "5555551212",
   "contact_last_name" : "test",
   "country" : "USA",
   "contact_first_name" : "client",
   "state" : "WA",
   "city" : "testmetro",
   "zip" : 90210,
   "notes" : "test note",
   "contact_email" : "test@example.com",
   "address_second" : "apt 1 test",
   "address" : "123 test st",
   "id" : "988",
   "business_name" : "test"
}

Response example:

{
   "seconds" : "0.04165",
   "jsonrpc" : "2.0",
   "id" : "6",
   "result" : {}
}

Updates a client object.

Required parameter: id. Any other client object attributes may be specified.

Response: On success, empty results will be returned.

coverageBlock object

Basic Attributes

id

A unique identifier for this coverage block

name

Coverage block name

days

Number of days for this coverage block

dur

String; duration of the coverage block in: hours, minutes, and seconds

start_time

Starting time for the coverage block

end_time

End time for the coverage block

breaks

Number of breaks during the coverage block

unpaid_mins

Number of minutes of unpaid time off during the coverage block

coverageBlock.list

Request example:

{
    "select": {
        "time_block": 20175
    }
}

Response example:

{
  "count": 1,
  "page": {
    "this": {
      "batch": 10,
      "start": 1
    }
  },
  "shift/coverage blocks": [
    {
      "breaks": "",
      "days": "0",
      "dur": "8:00:00",
      "end_time": "17:00:00",
      "id": "20175",
      "name": "8hr coverage block",
      "start_time": "09:00:00",
      "unpaid_mins": 0
    }
  ]
}

Returns information about coverage blocks. Uses pagination.

Optional parameters:

select object with a time_block attribute identifying a single coverage block or array of coverage blocks to be returned. E.g. {select:{time_block:12345}}.

select object with a workgroup attribute identifying a single workgroup to be returned. E.g. {select:{time_block:12345, workgroup: 54321}}.

show_only_workgroup_listables

Only return results for the workgroup specified (in select).

exclude_site

Boolean; if a manager of the team, don't include coverage blocks associated with the site itself with those for the team.

department object

department objects have the following attributes:

id

A unique identifier for this department.

name

The name of this department. Maximum length 128 characters.

department.create

Request example:

{
   "workgroup" : "226086",
   "name" : "Test Department 0.0207031441686816"
}

Response example:

{
   "seconds" : "0.19451",
   "jsonrpc" : "2.0",
   "id" : "55",
   "result" : {
      "id" : "949"
   }
}

Creates a new department record.

Parameters: Any attributes of a department object (except id) may be specified. A unique name parameter must be specified. Additionally, a workgroup parameter must be specified to create initial workgroup relationships for this department. It may be either a single workgroup identifier or an array of identifiers of workgroups that use this department.

Response: On success, an id attribute will provide the identifier for the new department.

department.delete

Deletes a department.

Required parameter: id.

On success, empty results will be returned.

department.get

Request example:

{
   "id" : "948"
}

Response example:

{
   "seconds" : "0.093228",
   "jsonrpc" : "2.0",
   "id" : "4",
   "result" : {
      "name" : "department 977",
      "id" : "948"
   }
}

Returns information about departments. Uses pagination.

Optional parameters: select object with a department attribute identifying a single department or array of departments to be returned. E.g.{select:{department:12345}}

The response results departments attribute will be an array of the current page of departments. Each element of the array may have the following attributes:

id

A unique identifier for this department.

name

The name of this department.

department.list

Request example:

{
   "select" : {
      "department" : "948"
   }
}

Response example:

{
   "seconds" : "0.093228",
   "jsonrpc" : "2.0",
   "id" : "4",
   "result" : {
      "count" : "1",
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      },
      "departments" : [
         {
            "name" : "department 977",
            "id" : "948"
         }
      ]
   }
}

Returns information about departments. Uses pagination.

Optional parameters:

select

An object specifying selection criteria for this request. Allowed criteria are:

department

A single department identifier or array of department identifiers.

search

A generic search string; select departments containing this string in their name.

workgroup

Single workgroup to filter results to be returned.

NOTE: If the call is made on behalf of a manager, the caller must also specify the boolean value exclude_site to limit the results to only the workgroup specified.

show_only_workgroup_listables

Only return results for the workgroup.

exclude_site

Boolean; if a manager of the team, don't include departments associated with the site itself with those for the team.

sitewide

Boolean; query for all departments across all workgroups that the user has access to. Enabled by default for manager accounts.

The response results departments attribute will be an array of the current page of departments. Each element of the array may have the following attributes:

id

A unique identifier for this department.

name

The name of this department.

description

Description of the department

department.update

Request example:

{
   "workgroup" : "226086",
   "name" : "Test Department 949",
   "id" : "949"
}

Response example:

{
   "seconds" : "0.116093",
   "jsonrpc" : "2.0",
   "id" : "56",
   "result" : {}
}

Updates a department object.

Required parameter: id. Any other department object attributes may be specified.

Response: On success, empty results will be returned.

directManager object

direct manager objects have the following attributes:

id

A unique identifier for this direct manager.

name

The name of the direct manager

account

The Shiftboard id of the direct manager account

external_account

The external id of the direct manager account

NOTE: The external_account identifier will only be returned when the site is configured to use external identifiers.

directManager.get

Request example:

{
   "id" : "1"
}

Response example:

{
   "seconds" : "0.093228",
   "jsonrpc" : "2.0",
   "id" : "12345",
   "result" : {
      "account": "99",
      "id" : "1",
      "name" : "First Last",
   }
}

Returns information about a direct manager.

Required parameter: id

The response result will be a direct manager object that contains the following attributes:

id

A unique identifier for this direct manager.

name

The name of this direct manager.

account

The account id of the direct manager.

external_account

The external id of the direct manager (if external identifiers are enabled for the site)

directManager.list

Request example:

{
   "select" : {
      "direct_manager" : "948"
   }
}

Response example:

{
   "seconds" : "0.093228",
   "jsonrpc" : "2.0",
   "id" : "4",
   "result" : {
      "count" : "1",
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      },
      "direct_managers" : [
         {
            "account": 12345,
            "id" : "1",
            "name" : "First Last"
         }
      ]
   }
}

Returns information about direct managers. Uses pagination.

Optional parameters: select object with a direct_manager attribute identifying a single direct manager or array of direct managers to be returned. E.g.{select:{direct_manager:12345}}

The response results direct_managers attribute will be an array of the current page of direct managers. Each element of the array may have the following attributes:

Optional parameters:

select

An object specifying selection criteria for this request. Allowed criteria are:

direct_manager

A single direct_manager identifier or array of direct_manager identifiers.

search

A generic search string; select direct_managers containing this string in their name.

workgroup

Single workgroup to filter results to be returned.

NOTE: If the call is made on behalf of a manager, the caller must also specify the boolean value exclude_site to limit the results to only the workgroup specified.

show_only_workgroup_listables

Only return results for the workgroup.

exclude_site

Boolean; if a manager of the team, don't include direct_managers associated with the site itself with those for the team.

sitewide

Boolean; query for all direct_managers across all workgroups that the user has access to. Enabled by default for manager accounts.

The response results direct_managers attribute will be an array of the current page of direct_managers. Each element of the array may have the following attributes:

id

A unique identifier for this direct manager.

name

The name of this direct manager.

account

The Shiftboard id of the direct manager account

external_account

The external id of the direct manager account

NOTE: The external_account identifier will only be returned when the site is configured to use external identifiers.

location object

location objects have the following attributes:

id

A unique identifier for this location.

name

The name of this location. Maximum length 96 characters.

description

A description of this location. Maximum length 255 characters.

address

Address line (e.g. "123 Main St"). Maximum length 100 characters.

address_second

Second address line. Maximum length 100 characters.

city

City. Maximum length 100 characters.

state

Abbreviation or full name of state/province/subdivision. Maximum length 64 characters.

zip

Postal code. Maximum length 12 characters.

country

Country. Maximum length 24 characters.

contact_first_name

First name of contact person. Maximum length 100 characters.

contact_last_name

Last name of contact person. Maximum length 100 characters.

contact_phone

Phone number of contact person. Maximum length 100 characters.

contact_email

Email address of contact person. Maximum length 255 characters.

notes

special_instructions

latlon

Optional latitude/longitude for more precise map location, e.g. "34.015137,-118.791438".

derived_latlon

Latitude/longitude as calculated by the system, when possible; not updateable.

geofence_radius

Allowed geofence radius for clocking in to shifts with this location, in meters; only the following values are allowed: "-1" (no restriction), "10", "25", "50", "100", "250", or null to use the site setting value.

geofence_allow_ivr

Boolean; allow clocking in to shifts with this location via IVR, even when geofencing is enforced and a geofence radius is set.

location.create

Request example:

{
   "workgroup" : "226092",
   "zip" : 90210,
   "name" : "Test Location 0.287588880766943",
   "description": "A test location named with a random floating-point identifier"
}

Response example:

{
   "seconds" : "1.616022",
   "jsonrpc" : "2.0",
   "id" : "15",
   "result" : {
      "id" : "29120"
   }
}

Creates a new location record.

Parameters: Any attributes of a location object (except id) may be specified. A unique name parameter and either a zip parameter or all of address, city, and state must be specified. Additionally, a workgroup parameter must be specified to create initial workgroup relationships for this location. It may be either a single workgroup identifier or an array of identifiers of workgroups that use this location.

Response: On success, an id attribute will provide the identifier for the new location.

location.delete

Request example:

{
   "id" : "12345"
}

Response example:

{
   "seconds" : "0.058344",
   "jsonrpc" : "2.0",
   "id" : "42",
   "result" : {}
}

Deletes a location record.

Required parameter: id.

Response: On success, empty results will be returned.

location.list

Request example:

{
   "select" : {
      "location" : "29117"
   }
}

Response example:

{
   "seconds" : "0.052861",
   "jsonrpc" : "2.0",
   "id" : "10",
   "result" : {
      "count" : "1",
      "locations" : [
         {
            "id" : "29117",
            "name" : "location 556",
            "description" : "Not really his real address...",
            "address" : "1 Main St",
            "address_second" : "Apt 1I",
            "city" : "Beverly Hills",
            "contact_email" : "test@example.com",
            "contact_first_name" : "Luke",
            "contact_last_name" : "Perry",
            "contact_phone" : "555-555-1212",
            "country" : "USA",
            "latlon" : "",
            "notes" : "That's we're we want to be",
            "special_instructions" : "Livin' in Beverly Hills",
            "state" : "California",
            "zip" : "90210"
         }
      ],
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      }
   }
}

Returns information about locations. Uses pagination.

Optional parameters:

select

An object specifying selection criteria for this request. Allowed criteria are:

location

A single location identifier or array of location identifiers.

search

A generic search string; select locations containing this string in their name.

department

Single department or array of departments to be returned.

workgroup

Single workgroup to filter results to be returned.

NOTE: If the call is made on behalf of a manager, the caller must also specify the boolean value exclude_site to limit the results to only the workgroup specified.

show_only_workgroup_listables

Only return results for the workgroup.

exclude_site

Boolean; if a manager of the team, don't include locations associated with the site itself with those for the team.

sitewide

Boolean; query for all locations across all workgroups that the user has access to. Enabled by default for manager accounts.

The response results locations attribute will be an array of the current page of locations. Each element of the array may have the following attributes:

id

A unique identifier for this location.

name

The name of this location.

address

Address line (e.g. "123 Main St").

address_second

Second address line.

city

state

Full name of state/province/subdivision.

zip

Postal code.

country

contact_first_name

contact_last_name

contact_phone

notes

special_instructions

latlon

location.update

Request example:

{
   "workgroup" : "226092",
   "name" : "Test Location 29120",
   "id" : "29120"
}

Response example:

{
   "seconds" : "0.942479",
   "jsonrpc" : "2.0",
   "id" : "16",
   "result" : {}
}

Updates a location object.

Required parameter: id. Any other location object attributes may be specified.

Response: On success, empty results will be returned.

managerNote object

managerNote: basic attributes

id

A unique identifier for this managerNote.

account

Identifier of the account to which this managerNote is assigned.

activity_date

The date of the manager note activity

admin_only

Boolean; indicates this managerNote is accessible only to site administrators

created_by

The account identifier of the account that created the manager note record

creation_date

The date and UTC time the manager note record was created

last_updated

Date and UTC time managerNote was updated

custom_boolean_[number]

Boolean; If enabled in the application settings, the value of the custom boolean associated with the manager note record

custom_dropdown_[number]

If enabled in the application settings, the value of the custom dropdown selected associated with the manager note record

custom_textarea_[number]

If enabled in the application settings, the value of the custom textarea associated with the manager note record

note_type

The selected note type of the manager note record or null if no type

notes

The notes associated with the manager note record

score

The score associated with the manager note record

shift

The shift associated with the manager note record or null if no shift

updated_by

The site user who last updated the manager note record

workgroup

The workgroup associated with the manager note record

Not all fields will be configured to be used for all organizations or set for all managerNote.

managerNote.customFields

Request example:

{}

Response example:

{
   "custom_fields" : [
      {
         "label" : "ImaBoolean",
         "name" : "custom_boolean_1",
         "type" : "boolean"
      },
      {
         "label" : "ImaDropdown",
         "name" : "custom_dropdown_3",
         "type" : "dropdown",
         "values" : [
            "a",
            "b",
            "c"
         ]
      },
      {
         "label" : "ImaTextarea",
         "name" : "custom_textarea_2",
         "type" : "textarea"
      }
   ]
}

Returns information about configured manager notes custom fields.

Parameters: none

managerNote.get

Request example:

{
   "select" : {
      "start_date" : "2019-01-01",
      "end_date" : "2019-01-01",
   },
   "user_actions" : true
}

Response example:

{
    "manager_note": {
        "account": "1",
        "activity_date": null,
        "admin_only": false,
        "created_by": "1",
        "creation_date": "2019-01-01 18:27:36",
        "custom_boolean_1": true,
        "custom_dropdown_1": "first option",
        "custom_textarea_1": "text found in the text area",
        "id": "11111",
        "last_updated": "2019-01-01 18:27:36",
        "note_type": "1234",
        "notes": "These are some notes",
        "org_id": "1",
        "score": "11",
        "shift": "12345",
        "updated_by": "1",
        "user_actions": {
            "delete": true,
            "edit": true
        },
        "workgroup": "999999"
    },
    "referenced_objects": {
        "account": [
            {
                "id": "1",
                "name": "User Account Name"
            }
        ],
        "custom_dropdown": [
            {
                "name": "custom_dropdown_1",
                "values": [
                    "first option",
                    "second option",
                ]
            }
        ],
        "note_type": [
            {
                "id": "1234",
                "name": "Note Type Selected",
                "org_id": "1"
            }
        ],
        "score": [
            "11 - Excellent"
        ],
        "workgroup": [
            {
                "id": "999999",
                "name": "Workgroup Name"
            }
        ]
    }
}

Returns information about a manager note

Parameters:

id

Required. id of the manager note for which to return information.

user_actions

Boolean; if specified and true, a user_actions object will be returned with attributes indicating what actions may be presented to the user to perform on this manager note.

managerNote.list

Request example:

{
   "select" : {
      "start_date" : "2019-01-01",
      "end_date" : "2019-01-01",
   },
   "user_actions" : true
}

Response example:

{
    "count": "2",
    "manager_notes": [
        {
            "account": "2",
            "activity_date": null,
            "admin_only": false,
            "created_by": "1",
            "creation_date": "2019-01-01 18:27:36",
            "id": "12345",
            "note_type": "7317",
            "notes": "These are some notes",
            "score": "11",
            "shift": null,
            "updated_by": null,
            "user_actions": {
                "delete": true,
                "edit": true
            },
            "workgroup": "9999"
        },
        {
            "account": "7",
            "activity_date": null,
            "admin_only": false,
            "created_by": "1",
            "creation_date": "2019-01-01 12:27:09",
            "id": "685471",
            "note_type": "1",
            "notes": "These are some notes",
            "score": "8",
            "shift": null,
            "updated_by": null,
            "user_actions": {
                "delete": false,
                "edit": false
            },
            "workgroup": "1111"
        }
    ],
    "page": {
        "this": {
            "batch": 10,
            "start": 1
        }
    },
    "referenced_objects": {
        "account": [
            {
                "id": "2",
                "name": "Account Name"
            },
            {
                "id": "7",
                "name": "Account Name"
            }
        ],
        "note_type": [
            {
                "id": "1",
                "name": "Note type",
                "org_id": "11111"
            }
        ],
        "score": [
            "11 - Excellent",
            "8 - Good"
        ],
        "workgroup": [
            {
                "id": "9999",
                "name": "Workgroup Name"
            },
            {
                "id": "1111",
                "name": "Workgroup Name"
            }
        ]
    }
}

Returns information about manager notes. Uses pagination.

Optional parameters:

user_actions

Boolean; if specified and true, a user_actions object will be returned with attributes indicating what actions may be presented to the user for each manager note returned.

select

An object specifying selection criteria for this request.

workgroup

Workgroup identifier; filter results by workgroup

account

Account identifier; filter results by account

admin_only

Boolean; Only return notes that are or are not accessible only to the site administrator

start_date

Creation start date; if included, end_date is required. Filter results to those notes created in the specified date range.

end_date

Creation end date; if included, start_date is required. Filter results to those notes created in the specified date range.

activity_start_date

Activity start date; if included, activity_end_date is required. Filter results to those notes with activity in the specified date range.

activity_start_date

Activity end date; if included, activity_start_date is required. Filter results to those notes with activity in the specified date range.

shift

Shift identifier; filter results by shift

note_type

Note type identifier; filter results by note type

no_activity

Boolean; limit results to those manager notes that have had no activity

managerNote.create

Request example:

{
   "account": 1,
   "score": 10,
   "admin_only": true,
   "notes": "Notes to be read by admin only",
   "shift": 12345
}

Response example:

{
    "id": 123456789
}

Creates a new manager note.

Required Parameters:

account

Account identifier

Optional Parameters:

All manager note attributes are allowed with the exception of creation_date, user_actions, and last_updated

managerNote.delete

Request example:

{
   "id": 1234567890
}

Response example:

{}

Deletes a new manager note. This method requires that the caller is a site administrator or the manager who created the note.

Required Parameters:

id

Manager note identifier

managerNote.update

Request example:

{
   "id": 123456789,
   "score": 9
}

Response example:

{}

Updates a new manager note.

Required Parameters:

id

Account identifier

Optional Parameters:

Most of the manager notes attributes can be modified, with the exception of creation_date, user_actions, account, and last_updated

managerNoteType object

managerNoteType objects have the following attributes:

id

A unique identifier for this managerNoteType.

name

A unique name for this managerNoteType.

managerNoteType.list

Request example:

{}

Response example:

{
    "manager_note_type": [
        {
            "id": "1111",
            "name": "Progress"
        },
        {
            "id": "1112",
            "name": "Review"
        }
    ]
}

Retrieves a list of manager note types.

This list is always accessible to site admins, and managers. Depending on site settings, coordinators may also be able to retrieve this list.

managerNoteType.create

Request example:

{
   "name": "Manager Note Type Name"
}

Response example:

{
    "id": 12345
}

Creates a new manager note type.

Note: This method is only accessible to site administrators.

Required Parameters

• name - A unique name is required

managerNoteType.delete

Request example:

{
   "id": 12345
}

Response example:

{}

Delete a new manager note type.

Note: This method is only accessible to site administrators.

Required Parameters

• id

managerNoteType.update

Request example:

{
   "id": 12345,
   "name": "Updated Manager Note Type Name"
}

Response example:

{}

Updates a new manager note type.

Note: This method is only accessible to site administrators.

Required Parameters

• id
• name - A unique name is required

membership object

membership objects have the following attributes:

id

Pseudo-id (workgroup-member) for callers that need a fixed ID string.

member

The account identifier for this membership.

external_account

The external account identifier for this object.

NOTE: This field is only used or returned when external ids are enabled for the site.

workgroup

The workgroup identifier for this membership.

level

creation_date

The datetime (in UTC) that this object was created.

membership.create

Request example:

{
   "workgroup" : [ "226094", "12345" ],
   "level" : 4,
   "member" : [
      949,
      950
   ]
}

Response example:

{
   "seconds" : "0.064361",
   "jsonrpc" : "2.0",
   "id" : "34",
   "result" : {}
}

Creates new workgroup/account memberships.

Required parameters:

member

A single account identifier or an array of identifiers of accounts for which to create memberships for each specified workgroup.

NOTE: If you are calling this method with the external_member parameter, member is not required.

external_member

A single external account identifier or an array of external identifiers of accounts for which to create memberships for each specified workgroup.

NOTE: If you are calling this method with the member parameter, external_member is not required, and will be ignored.

workgroup

A single workgroup identifier or an array of identifiers of workgroups for which to create memberships for each specified account.

level

User level for which to create memberships.

tier

Optional; tier at which to create memberships if membership tiers are enabled.

No more than 10,000 memberships may be specified in one request.

If one or more of the specified memberships already exist, the remaining memberships (if any) will be created and no error will be returned. Existing user levels will remain unchanged.

Response: On success, empty results will be returned.

membership.delete

Request example:

{
   "workgroup" : "226094",
   "member" : 950
}

Response example:

{
   "seconds" : "0.055246",
   "jsonrpc" : "2.0",
   "id" : "37",
   "result" : {}
}

Deletes workgroup/account memberships.

Required parameters:

member

A single account identifier or an array of identifiers of accounts for which to delete memberships for each specified workgroup.

NOTE: If you are calling this method with the external_member parameter, member is not required.

external_member

A single external account identifier or an array of external identifiers of accounts for which to delete memberships for each specified workgroup.

NOTE: If you are calling this method with the member parameter, external_member is not required.

workgroup

A single workgroup identifier or an array of identifiers of workgroups for which to delete memberships for each specified account. Currently, only a single workgroup may be specified.

If one or more of the specified memberships doesn't exist, the remaining memberships (if any) will be deleted and no error will be returned.

Response: On success, empty results will be returned.

membership.list

Request example:

{
   "select" : {
      "workgroup" : [
         2,
         1171
      ]
   }
}

Response example:

{
   "seconds" : "0.035573",
   "jsonrpc" : "2.0",
   "id" : "",
   "result" : {
      "memberships" : [
         {
            "id" : "2-2",
            "creation_date" : "2018-01-02 02:24:00",
            "workgroup" : "2",
            "level" : "2",
            "member" : "2",
            "profile_type_id" : "1"
         },
         {
            "id" : "1171-2",
            "creation_date" : "2018-01-02 02:24:00",
            "workgroup" : "1171",
            "level" : "2",
            "member" : "2".
            "profile_type_id" : "1"
         },
         {
            "id" : "2-3",
            "creation_date" : "2018-01-02 02:24:00",
            "workgroup" : "2",
            "level" : "2",
            "member" : "3",
            "profile_type_id" : "1"
         },
         {
            "id" : "1171-3",
            "creation_date" : "2018-01-02 02:24:00",
            "workgroup" : "1171",
            "level" : "2",
            "member" : "3",
            "profile_type_id" : "1"
         }
      ],
      "referenced_objects" : {
         "workgroup" : [
            {
               "name" : "Front Desk",
               "id" : "1171"
            },
            {
               "name" : "Ushers",
               "id" : "2"
            }
         ],
         "account" : [
            {
               "email" : "pjones@example.com",
               "external_id" : "42648",
               "id" : "2",
               "first_name" : "Paul",
               "last_name" : "Jones",
               "screen_name" : "Paul Jones"
            },
            {
               "email" : "susana@example.com",
               "external_id" : "46037",
               "id" : "3",
               "first_name" : "Susan",
               "last_name" : "Adams",
               "screen_name" : "Susan Adams"
            }
         ]
      },
      "count" : "9569",
      "page" : {
         "next" : {
            "batch" : 2,
            "start" : 3
         },
         "this" : {
            "batch" : 2,
            "start" : 1
         }
      }
   }
}

Returns information about workgroup/account memberships. Uses pagination. Uses select criteria.

Required parameters:

select

An object specifying selection criteria for this request. Either member or workgroup must be specified. The available criteria include:

member

A single account identifier or an array of account identifiers indicating accounts for whom to return memberships.

NOTE: If you are calling this method with the external_member parameter, member is not required.

exclude_workgroup

A single workgroup identifier, or an array of workgroup identifiers. Any accounts returned must not belong to these workgroups.

include_workgroup

A single workgroup identifier. Any accounts returned must belong to this workgroup.

external_member

A single external account identifier or an array of external account identifiers indicating accounts for whom to return memberships.

NOTE: If you are calling this method with the external_member parameter, member is not required.

workgroup

A single workgroup identifier or an array of workgroup identifiers indicating workgroup for which to return memberships.

level

User level of memberships to return.

tier

Tier or array of tiers of memberships to return.

org_hold

Boolean; if specified and true, indicates that accounts on hold should be included in the returned results.

org_pending

Boolean; if specified and true, indicates that accounts with pending status should be included in the returned results.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the memberships attribute, the results should include a referenced_objects attribute giving information about the accounts and workgroups referred to by the returned memberships.

The response results memberships attribute will be an array of the current page of memberships. Each element of the array will be a membership object.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the memberships results, with only selected minimal attributes provided:

account

id, first_name, last_name, screen_name, and email attributes are provided.

workgroup

id and name attributes are provided.

membership.listExcluded

Request example:

{
    "workgroup" : [
       2,
       1171
    ]
}

Response example:

{
   "seconds" : "0.035573",
   "jsonrpc" : "2.0",
   "id" : "",
   "result" : {
      "count" : 2,
      "members" : [
         {
            "member" : "2",
            "profile_type_id" : "1"
         },
         {
            "member" : "3",
            "profile_type_id" : "1"
         }
      ],
      "referenced_objects" : {
         "account" : [
            {
               "email" : "pjones@example.com",
               "external_id" : "42648",
               "id" : "2",
               "first_name" : "Paul",
               "last_name" : "Jones",
               "screen_name" : "Paul Jones"
            },
            {
               "email" : "susana@example.com",
               "external_id" : "46037",
               "id" : "3",
               "first_name" : "Susan",
               "last_name" : "Adams",
               "screen_name" : "Susan Adams"
            }
         ]
      },
      "page" : {
         "next" : {
            "batch" : 2,
            "start" : 3
         },
         "this" : {
            "batch" : 2,
            "start" : 1
         }
      }
   }
}

Returns information about accounts that are not members of the given workgoups. Uses pagination. Uses select criteria.

Required parameters:

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the memberships attribute, the results should include a referenced_objects attribute giving information about the accounts referred to.

The response results members attribute will be an array of the current page of accounts. Each element of the array will be a member object.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the members results, with only selected minimal attributes provided:

account

id, first_name, last_name, screen_name, and email attributes are provided.

membership.tierList

Request example:

{
}

Response example:

{
   "seconds" : "0.017018",
   "jsonrpc" : "2.0",
   "id" : "3",
   "result" : {
      "tiers": {
         "10" : "Platinum",
         "7" : "Copper",
         "8" : "Silver",
         "9" : "Gold"
      }
   }
}

Shows membership tiers that are enabled.

Response: An object with tier identifiers ("1" through "10") as attributes and the corresponding labels for those tiers as values.

membership.update

Request example:

{
   "workgroup" : 132994,
   "level" : 4,
   "member" : 946
}

Response example:

{
   "seconds" : "0.068018",
   "jsonrpc" : "2.0",
   "id" : "3",
   "result" : {}
}

Updates user levels for workgroup/account memberships.

Required parameters:

member

A single account identifier or an array of identifiers of accounts for which to update memberships for each specified workgroup.

NOTE: If you are calling this method with the external_member parameter, member is not required.

external_member

A single external account identifier or an array of external identifiers of accounts for which to update memberships for each specified workgroup.

NOTE: If you are calling this method with the member parameter, external_member is not required.

workgroup

A single workgroup identifier or an array of identifiers of workgroups for which to update memberships for each specified account. Currently, only a single workgroup may be specified.

level

User level to which to update memberships.

tier

Optional; tier to which to update memberships if membership tiers are enabled.

If one or more of the specified memberships doesn't exist, the remaining memberships (if any) will be updated and no error will be returned.

Response: On success, empty results will be returned.

message object

message.broadcast

Request example:

{
  "message" : "everyone get out of the building now",
  "subject" : "read this when you have time",
  "sender" : {
    "name" : "Your Boss",
    "email" : "your.boss@example.com"
  },
  "cc" : true,
  "sms" : true,
  "workgroups" : ["1", "2"],
  "location" : "3",
  "client" : "4",
  "department" : "5",
  "role" : "6",
  "reference_id" : "my event id",
  "profile_type" : "7",
  "tier" : "8",
  "level" : ["level"],
  "score" : {
    "no_score" : true,
    "value" : "10",
    "cmp" : ">="
  },
  "org_hold" : false,
  "org_pending" : 2,
  "restrict_delivery" : {
    "type" : "with_assignment",
    "start_date" : "2018-07-01T00:00:00",
    "end_date" : "2018-08-01T00:00:00",
    "dates" : ["2018-08-02","2018-08-03"]
  },
  "link_account" : true,
  "link_referrals" : true,
  "link_schedule" : true,
  "login_info" : true,
  "personalize" : true,
  "zip" : {
    "zip_code" : "98101",
    "range" : "50"
  }
}

Response example:

{
  "id" : "1",
  "jsonrpc" : "2.0",
  "result": {
    "sent": [
      {
        "account": "My User",
        "email": "my.user@example.com",
        "id": "8"
      },
      {
        "account": "Your User",
        "email": "your.user@example.com",
        "id": "92"
      }
    ],
    "sent_count": 2,
    "warning": [
      {
        "message": "Message could not be sent to addresses marked as undeliverable",
        "unsent": [
          {
            "account": "Some User",
            "email": "some.user@example.com",
            "id": "234"
          }
        ],
        "unsent_count": 1
      }
    ]
  },
  "seconds" : "0.089939"
}

Sends a broadcast message. Only site admins can send messages to everyone. Managers can send messages to the workgroups they manage; coordinators can do the same, if the site is set to allow it.

Required Parameters

• subject - text string of the message subject
• level - array of strings for what level of accounts to send to. For site messages: member, team_mgr, site_admin; For workgroup messages: member, coordinator, manager (ignored for coordinators)
• workgroups - array of workgroup IDs to send to (required unless site admin)

Optional Parameters

• return_sent_accounts - the number of accounts to return a success for in result.sent; if this limit is exceeded, no results are returned (default 0, no results)
• return_unsent_accounts - the number of accounts to return warnings for in result.warning.emails; if this limit is exceeded, no warnings are returned (default 0, no results)
• message - plain text message
• sender - object describing the sender of the message
  • email - email address of the sender (default: email address of the sending account)
  • name - name of the sender (default: none)
• cc - boolean to send copy back to sending account (default: false)
• sms - boolean to also send message via SMS (default: false)
• link_account - boolean to include the account link in the message (default false)
• link_referrals - boolean to include the referral link in the message (default false)
• link_schedule - boolean to include the schedule link in the message (default false)
• login_info - boolean to include the login info in the message (default false)
• personalize - boolean to personalize the message (default false)

Optional Filters

Filters further resrict which accounts to send the message to. Defaults are no additional restrictions.

• tier - an exact team tier (must match the account's tier for one or more of the specified workgroups) (numeric value)
• profile_type - the profile of the accounts to send to
• org_hold - boolean whether to send users on admin hold (default false)
• org_pending - an onboarding status (may only be specified if org_hold is false)
• score - object describing the score of the accounts to send to
  • value - the score value
  • cmp - a string for the comparison operator, one of: >= (or better; default), <= (or worse), == (exactly)
  • no_score - also include accounts with no score
• zip - object of ZIP code restrictions
  • zip_code - ZIP code to restrict to
  • range - distance in miles from the ZIP code (default: 0)
• restrict_delivery - object describing who to further restrict delivery to. It has a type, and then other restrictions, including date ranges for the type, etc.
  • Example: if without_assignment is selected, with a start_date of 2018-08-01, end_date of 2018-08-07, and location of 1001, then only accounts who were not assigned a shift for that location, between those dates, will be sent the message.
  • NOTES
    • options relating to shifts specifically only apply to a type of with_assignment, without_assignment, and without_acknowledgment
    • signed_on and not_signed_on only apply to org messages, not workgroup messages
    • no options apply to a type of everyone
    • start_date and end_date must both be set for start_date, end_date, dates, or start_time to be used
  • type - string of one of the following values
    • everyone - all matching accounts (default)
    • with_assignment - if the account was assigned a shift
    • without_assignment - if the account was not assigned a shift
    • signed_on - if the account was signed on
    • not_signed_on - if the account was not signed on
    • without_acknowledgment - if the account did not acknowledge a shift
  • start_date - a date at or after to restrict the type (signed on, didn't sign on, had assignment, didn't have assignment, or didn't acknolwedge, at or after this datetime)
  • end_date - a date at or before to restrict the type
  • dates - array of additional arbitrary dates for restricting
  • start_time - the time the shift started (in HH:MM:SS format)
  • location - the location ID for the shift
  • client - the client ID for the shift
  • department - the department ID for the shift
  • role - the role ID for the shift
  • reference_id - the reference ID for the shift

Response

On success, include the list of addresses sent to in the sent key, and a list of warning objects, if any addresses could not be sent to.

message.direct

Request example:

{
  "message" : "everyone get out of the building now",
  "subject" : "read this when you have time",
  "account" : [1, 23, 45, 72],
  "sms" : true,
  "urgent" : true
}

Response example:

{
  "id" : "1",
  "jsonrpc" : "2.0",
  "result": {
      "sent": [
        {
          "account": "Bri Lum",
          "email": "364@servola.org",
          "email_sent": "1",
          "id": "364",
          "sms_sent": ""
        },
        {
          "account": "Charlie Watts",
          "email": "2834156@servola.org",
          "email_sent": "1",
          "id": "2834156",
          "sms_sent": "1"
        }
      ],
      "sent_count": 2,
      "warning": [
        {
          "message": "Message could not be sent to addresses marked as undeliverable",
          "unsent": [
            {
              "account": "Andrew Allison",
              "email": "3953240@ishifts.com",
              "email_sent": "",
              "id": "3953240",
              "sms_sent": ""
            },
            {
              "account": "Bri Lum",
              "email": "364@servola.org",
              "email_sent": "1",
              "id": "364",
              "sms_sent": ""
            }
          ],
          "unsent_count": 2
        },
        {
          "message": "Not Authorized to send email to account",
          "unsent": [
            {
              "account": "Paul Allison",
              "email": "2834193@servola.org",
              "id": "2834193"
            }
          ],
          "unsent_count": 1
        }
      ]
    },
  "seconds" : "0.03719"
}

Sends a direct message. Only site admins can send messages to everyone. Managers can send messages to members of the workgroups they manage; coordinators can do the same, if the site is set to allow it, members can can only send messages to primary contact of their workgroup and to contact for the site.

Required Parameters

One of account and external_account is required * account - the account (shiftboard_id) to direct message or an array of account identifiers

NOTE: If you are calling this method with the account parameter, external_account will be ignored (if included).

• external_account - the external_account (external_id) to direct message or an array of external account identifiers

Optional Parameters

• subject - text string of the message subject

• message - plain text message

• urgent - boolean to mark message as urgent (default: false)

• sms - boolean to also send message via SMS if site configured (default: false)

Response

On success, include the list of addresses sent to in the sent key, and a list of warning objects, if any addresses could not be sent to or if sender is not authorized to send to account. The section warning can have two sub-sections, one for messages that was not fully sent out due to either a bad email address or missing sms number. The other section contains account that user is not authorized to message.

Note that account "Bri Lum" is included in both section 'sent' and in 'warning' for messages marked as undeliverable. The reason is that the request was to email and sms but in this case no sms was sent out. See the two status indicators "sms_sent" and "email_sent"

news object

news.get

Request example:

{}

Response example:

{
   "seconds" : "0.065741",
   "jsonrpc" : "2.0",
   "id" : "7",
   "result" : {
      "news" : {
         "member" : "Member news goes here",
         "team" : {
            "Example" : {
               "news" : "This is the news section for my Workgroup"
            }
         },
         "manager" : "Manager news goes here"
      }
   }
}

Returns the news for managers, teams, and members.

Optional parameters:

org_id

openid object

openid objects have the following attributes:

id

A unique identifier for this openid object.

account

external_account

openid

openid.create

Request example:

{
   "openid" : "http://openid4.example.com/",
   "account" : 918
}

Response example:

{
   "seconds" : "0.064778",
   "jsonrpc" : "2.0",
   "id" : "43",
   "result" : {
      "id" : 785
   }
}

Adds an openid to an existing account.

Required Parameters:

account

A single account identifier or an array of identifiers of accounts.

NOTE: If you are calling this method with the external_account parameter, account is not required.

external_account

A single external account identifier or an array of external identifiers of accounts.

NOTE: If you are calling this method with the account parameter, external_account is not required.

openid

An openid url that will allow authentication to this account via

https://www.shiftboard.com/login/openid?http...

where http... is the designated url, URI-escaped. E.g. for openid http://www.example.com/, use the login link

https://www.shiftboard.com/login/openid?http%3A%2F%2Fwww.example.com%2F

If this openid is already in use for any account in Shiftboard, an error will be returned.

Response: On success, an id attribute will provide the identifier for the new account_openid.

openid.delete

Request example:

{
   "id" : "785"
}

Response example:

{
   "seconds" : "0.051149",
   "jsonrpc" : "2.0",
   "id" : "46",
   "result" : {}
}

Deletes an account_openid object.

Required Parameter: id. Deleting an account_openid object is not allowed if the account is active with more than one organization's Shiftboard.

Response: On success, empty results will be returned.

openid.update

Request example:

{
   "openid" : "http://openid4.example.com/new",
   "id" : 785
}

Response example:

{
   "seconds" : "0.064496",
   "jsonrpc" : "2.0",
   "id" : "45",
   "result" : {}
}

Updates an account_openid object.

Required Parameter: id. Any other account_openid object attributes may be specified. If openid is updated and the new openid is already in use for any account in Shiftboard, an error will be returned. Updating an account_openid object is not allowed if the account is active with more than one organization's Shiftboard.

Response: On success, empty results will be returned.

paycode object

paycode objects have the following attributes:

id

A unique identifier for this paycode.

name

The name of this paycode. Maximum length 64 characters.

description

A description for this paycode.

pay_rate

Pay rate (e.g. "10.00")

paycode.create

Creates a new paycode record.

Parameters: Any attributes of a paycode object (except id) may be specified. A unique name parameter must be specified.

Response: On success, an id attribute will provide the identifier for the new paycode.

paycode.delete

Deletes a paycode.

Required parameter: id.

On success, empty results will be returned.

paycode.get

Request example:

{
   "id" : 2020
}

Response example:

{
   "seconds" : "0.025599",
   "jsonrpc" : "2.0",
   "id" : "7",
   "result" : {
      "pay_rate" : "15.00",
      "name" : "universal minimum wage",
      "id" : "2020",
      "description" : ""
   }
}

Returns information about a single paycode.

Required parameter: id.

The response results will be a paycode object.

paycode.list

Request example:

{
   "select" : {
      "paycode" : 2020
   }
}

Response example:

{
   "seconds" : "0.025599",
   "jsonrpc" : "2.0",
   "id" : "7",
   "result" : {
      "count" : "1",
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      },
      "paycodes" : [
         {
            "pay_rate" : "15.00",
            "name" : "universal minimum wage",
            "id" : "2020",
            "description" : ""
         }
      ]
   }
}

Returns information about paycodes. Uses pagination.

Optional parameters: select object with a paycode attribute identifying a single paycode or array of paycodes to be returned. E.g.{select:{paycode:12345}}

The response results paycodes attribute will be an array of paycode objects for the current page of paycodes.

paycode.update

Updates a paycode object.

Required parameter: id. Any other paycode object attributes may be specified.

Response: On success, empty results will be returned.

paytype object

paytype objects have the following attributes:

id

A unique identifier for this paytype.

name

The name of this paytype. Maximum length 64 characters.

description

A description for this paytype.

paytype.list

Request example:

{
    "select" : {
       "paytype" : [2020, 2021]
    }
}

Response example:

{
    "seconds" : "0.025599",
    "jsonrpc" : "2.0",
    "id" : "7",
    "result" : {
       "count" : "1",
       "page" : {
          "this" : {
             "batch" : 25,
             "start" : 1
          }
       },
       "paytypes" : [
          {
             "id" : "2020",
             "name" : "Per Diem",
             "description" : "Daily rate"
          },
          {
             "id" : "2021",
             "name" : "Mileage",
             "description" : "Mileage Reimbursement"
          }
       ]
    }
}

Returns information about paytypes. Uses pagination.

Optional parameters: select object with a paytype attribute identifying a single paytype or array of paytypes to be returned. E.g.{select:{paytype:12345}}

The response results paytypes attribute will be an array of paytype objects for the current page of paytypes.

profileConfiguration object

profileConfiguration objects have the following attributes:

id

profile_option

integer identifying the system profile item for which this is the configuration; such profile items may be used at most once per profile type

profile_type

page

section

column

sort

label

type

read_authorization

write_authorization

constraint_list

Only used for some types; format varies by type

form_name

Internally used string unique to each profile_option

profileConfiguration.list

Request example:

{
   "select" : {
      "profile_option" : 130,
      "page" : 1,
      "profile_type" : 1
   }
}

Response example:

{
   "seconds" : "0.012632",
   "jsonrpc" : "2.0",
   "id" : "10",
   "result" : {
      "profile_configuration" : [
         {
            "page" : "1",
            "section" : "3",
            "column" : "2",
            "sort" : "8",
            "constraint_list" : "",
            "profile_type" : "1",
            "profile_option" : "130",
            "write_authorization" : "Managers and higher",
            "label" : "First Name of Reference",
            "type" : "varchar100",
            "id" : "2692",
            "read_authorization" : "Members and higher"
         }
      ]
   }
}

Returns information about profile configuration. Uses select criteria.

Parameters:

select

An object specifying selection criteria for this request. The available criteria include:

profile_type

The profileType identifier for which to return profile configuration

profile_option

The profile option for which to return configurations

page

The page within the profile_type for which to return configurations

form_name

A form_name string or array of such strings for which to return configurations

The response results profile_configuration attribute will be an array of profileConfiguration objects.

profileData object

profileData objects have the following attributes:

account

external_account

profile_option

integer identifying the profile item for which this is the data

value

value of this profile item, or if the profile item has more than one value, an array of values.

profileData.list

Request example:

{
   "select" : {
      "account" : 1
   }
}

Response example:

{
   "seconds" : "0.105116",
   "jsonrpc" : "2.0",
   "id" : "",
   "result" : {
      "count" : 4,
      "page" : {
         "this" : {
            "batch" : 10,
            "start" : 1
         }
      },
      "profile_data" : [
         {
            "profile_option" : "620",
            "account" : "1",
            "value" : "(encrypted)"
         },
         {
            "profile_option" : "16",
            "account" : "1",
            "value" : "206-555-1234"
         },
         {
            "profile_option" : "186",
            "account" : "1",
            "value" : "Brother"
         },
         {
            "profile_option" : "37",
            "account" : "1",
            "value" : [
               "Data Entry",
               "Driver"
            ]
         }
      ]
   }
}

Returns information about account profile data. Uses select criteria. Uses pagination.

Parameters:

select

An object specifying selection criteria for this request. Minimally either account or profile_type must be specified. The available criteria include:

account

The account identifier or array of account identifiers for which to return profile data. When requesting profile data for multiple accounts, it is recommended the caller use an array of account identifiers to increase efficiency, and reduce the overhead of making multiple requests to the API.

NOTE: If you are calling this method with the external_account parameter, account is not required.

external_account

The external account identifier or array of external account identifiers for which to return profile data. When requesting profile data for multiple accounts, it is recommended the caller use an array of account identifiers to increase efficiency, and reduce the overhead of making multiple requests to the API.

NOTE: If you are calling this method with the account parameter, external_account is not required.

profile_type

The profileType identifier for which to return profile data; defaults to the profile type of the first account specified.

workgroup

If specified, only select data for accounts which are members of this workgroup.

profile_option

The profile option for which to return data.

The response results profile_data attribute will be an array of the current page of profile data. Each element of the array will be a profileData object.

profileData.update

Request example:

{
   "account" : 1,
   "profile_data" : [
      {
         "profile_option" : 186,
         "value" : "Sister"
      },
      {
         "profile_option" : 16,
         "value" : "206-555-4321"
      }
   ]
}

Response example:

{
   "seconds" : "0.204804",
   "jsonrpc" : "2.0",
   "id" : "",
   "result" : {}
}

Updates multiple profileData objects for a given account.

Required parameters:

account

The account identifier or array of account identifiers for which to update profile data. When requesting profile data for multiple accounts, it is recommended the caller use an array of account identifiers to increase efficiency, and reduce the overhead of making multiple requests to the API.

NOTE: If you are calling this method with the external_account parameter, account is not required.

external_account

The external account identifier or array of external account identifiers for which to update profile data. When requesting profile data for multiple accounts, it is recommended the caller use an array of account identifiers to increase efficiency, and reduce the overhead of making multiple requests to the API.

NOTE: If you are calling this method with the account parameter, external_account is not required.

profile_data

Array of objects with profile_option and value attributes designating which profile options are to be updated and their new values.

Response: On success, empty results will be returned.

profileType object

profileType objects have the following attributes:

id

A unique identifier for this profile type.

name

The name of this profile type.

profileType.list

Request example:

{}

Response example:

{
   "seconds" : "0.039222",
   "jsonrpc" : "2.0",
   "id" : "1",
   "result" : {
      "count" : "2",
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      },
      "profile_types" : [
         {
            "name" : "Basic Profile",
            "id" : "1",
            "pages" : [
                {
                    "id" : "2",
                    "name" : "Page 1",
                    "sort" : "1",
                },
                {
                    "id" : "3",
                    "name" : "Page 2",
                    "sort" : "2",
                }
            ]
         },
         {
            "name" : "Staff",
            "id" : "2",
            "pages" : [
                {
                    "id" : "1",
                    "name" : "Basic Information"",
                    "sort" : "1",
                }
            ]
         }
      ]
   }
}

Returns information about profile types. Uses pagination.

Optional parameters: select object with a profile_type attribute identifying a single profile type to be returned. E.g. {select:{profile_type:12345}}

The response results profile_types attribute will be an array of the current page of profile_types. Each element of the array will be a profile_type object.

registration object

registration objects have the following attributes:

id

A unique identifier for this registration.

profile_type

profileType identifier for this registration.

data

An array of objects, each of which has a form_name and a value attribute.

registration.create

Request example:

{
   "data" : [
      {
         "value" : "Tester",
         "form_name" : "last_name"
      },
      {
         "value" : "Joe",
         "form_name" : "first_name"
      },
      {
         "value" : "joe.tester@example.com",
         "form_name" : "email"
      },
      {
         "value" : "12345",
         "form_name" : "zip"
      },
      {
         "value" : "M",
         "form_name" : "tshirt_size"
      },
      {
         "value" : "English",
         "form_name" : "fluent_languages"
      },
      {
         "value" : "Mandarin Chinese",
         "form_name" : "fluent_languages"
      },
      {
         "value" : 5,
         "form_name" : "birthdate_day"
      },
      {
         "value" : 4,
         "form_name" : "birthdate_month"
      },
      {
         "value" : 1972,
         "form_name" : "birthdate_year"
      }
   ],
   "profile_type" : 1
}

Response example:

{
   "seconds" : "0.082992",
   "jsonrpc" : "2.0",
   "id" : "31",
   "result" : {
      "id" : 43
   }
}

Creates a new registration record.

Parameters: profile_type must be specified. data must be specified and must include any required registration form fields.

User pictures and resumes are not yet supported.

date, month/day, or month/year types should be given in two or three separate fields (e.g. birthdate_day, birthdate_month, birthdate_year) with integer values.

Response: On success, an id attribute will provide the identifier for the new registration.

resource object

Basic Attributes

id

A unique identifier for this resource

name

Resource name

description

Description of the resource

notes

Notes about the resource

resource.list

Request example:

{
    "select": {
        "resource": 52
    }
}

Response example:

{
  "count": 1,
  "page": {
    "this": {
      "batch": 10,
      "start": 1
    }
  },
  "resources": [
    {
      "description": "This is a Test Resource",
      "id": "52",
      "name": "TestResource",
      "notes": "Test resource notes",
    }
  ]
}

Returns information about resources. Uses pagination.

Optional parameters:

select object with a resource attribute identifying a single resource or array of resources to be returned. E.g. {select:{resource:12345}}.

select object with a workgroup attribute identifying a single workgroup to be returned. E.g. {select:{resource:12345, workgroup: 54321}}.

show_only_workgroup_listables

Only return results for the workgroup specified (in select).

exclude_site

Boolean; if a manager of the team, don't include resources associated with the site itself with those for the team.

role object

role objects have the following attributes:

id

A unique identifier for this role.

name

The name of this role. Maximum length 48 characters.

role.create

Request example:

{
   "workgroup" : "226086",
   "name" : "Test Role 0.699796458722442"
}

Response example:

{
   "seconds" : "0.319621",
   "jsonrpc" : "2.0",
   "id" : "51",
   "result" : {
      "id" : "2282"
   }
}

Creates a new role record.

Parameters: Any attributes of a role object (except id) may be specified. A unique name parameter must be specified. Additionally, a workgroup parameter must be specified to create initial workgroup relationships for this role. It may be either a single workgroup identifier or an array of identifiers of workgroups that use this role.

Response: On success, an id attribute will provide the identifier for the new role.

role.delete

Deletes a role.

Required parameter: id.

On success, empty results will be returned.

role.get

Request example:

{
   "id" : "2281"
}

Response example:

{
   "seconds" : "0.115639",
   "jsonrpc" : "2.0",
   "id" : "4",
   "result" : {
      "name" : "role 813",
      "id" : "2281"
   }
}

Returns information about roles. Uses pagination.

Optional parameters: select object with a role attribute identifying a single role or array of roles to be returned. E.g. {select:{role:12345}}

The response results roles attribute will be an array of the current page of roles. Each element of the array may have the following attributes:

id

A unique identifier for this role.

name

The name of this role.

role.assign

Request example:

{
   "workgroup" : 56789,
   "account" : 12345,
   "role" : [
      1,
      2,
      3
   ]
}

Response example:

{
   "seconds" : "0.115639",
   "jsonrpc" : "2.0",
   "id" : "4",
   "result" : {}
}

Enables or disables roles for a member of a workgroup that uses restricted roles.

external_account

external account ID to be updated, if this organization uses external IDs.

account

account to be updated

workgroup

workgroup the member belongs to

role

One or more ids of roles that are associated with the given workgroup.

enable

false if the specified roles shoud be disabled for this member; otherwise the specified roles will be enabled.

role.list

Request example:

{
   "select" : {
      "role" : "2281"
   }
}

Response example:

{
   "seconds" : "0.115639",
   "jsonrpc" : "2.0",
   "id" : "4",
   "result" : {
      "roles" : [
         {
            "name" : "role 813",
            "id" : "2281"
         }
      ],
      "count" : "1",
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      }
   }
}

Returns information about roles. Uses pagination.

Optional parameters:

select

An object specifying selection criteria for this request. Allowed criteria are:

role

A single role identifier or array of role identifiers.

search

A generic search string; select roles containing this string in their name.

workgroup

Single workgroup to filter results to be returned.

NOTE: If the call is made on behalf of a manager, the caller must also specify the boolean value exclude_site to limit the results to only the workgroup specified.

show_only_workgroup_listables

Only return results for the workgroup.

exclude_site

Boolean; if a manager of the team, don't include roles associated with the site itself with those for the team.

sitewide

Boolean; query for all roles across all workgroups that the user has access to. Enabled by default for manager accounts.

The response results roles attribute will be an array of the current page of roles. Each element of the array may have the following attributes:

id

A unique identifier for this role.

name

The name of this role.

role.update

Request example:

{
   "workgroup" : "226086",
   "name" : "Test Role 2282",
   "id" : "2282"
}

Response example:

{
   "seconds" : "0.141744",
   "jsonrpc" : "2.0",
   "id" : "52",
   "result" : {}
}

Updates a role object.

Required parameter: id. Any other role object attributes may be specified.

Response: On success, empty results will be returned.

shift object

shift: basic attributes

id

A unique identifier for this shift.

count

The number of positions represented by this shift record.

qty

The total number of positions represented by this and associated records.

start_date

The date or date and time on which this shift begins. For an all-day shift, this is date in RFC 3339 full date format (e.g. "2009-04-01"). Otherwise, this is a datetime (e.g. "2009-04-01T13:00:00").

end_date

The date and time on which this shift ends, (e.g. "2009-04-01T17:00:00"). Not specified for all-day or open-ended shifts.

dur_hrs Integer; shift duration in hours. Required when creating a shift with a use_time value of 2. Likewise this value will only be returned when querying for shifts whose use_time value is equal to 2.

dur_mins Integer; shift duration in minutes. Required when creating a shift with a use_time value of 2. Likewise this value will only be returned when querying for shifts whose use_time value is equal to 2.

timezone

The timezone for which the shift is scheduled.

workgroup

The shift's workgroup.

subject

The shift's subject. Maximum length 100 characters.

location

The location id for the shift, if specified.

role

The role id for the shift, if specified.

client

The client id for the shift, if specified.

department

The department id for the shift, if specified.

covered

true if the shift is covered.

published

true if the shift is published.

urgent

true if the shift is critical to have covered.

covering_member

If the shift is covered by a member, the id of the member's account.

external_covering_member

If the shift is covered by a member, the external id of the member's account.

use_time (deprecated)

Integer; shift type identifier. Valid use_time values are in the range of 1-5. 1: shift/coverage block 2: start time/duration 3: start/end time 4: open ended/tbd 5: anytime

time_block

Integer; time block identifier. Required when creating a shift with a use_time value of 1. Likewise this value will only be returned when querying for shifts whose use_time value is equal to 1.

shift: extended attributes

details

Additional details about the shift.

no_pick_up

Boolean

signup_list

Boolean

no_trade

Boolean

reference_id

work_status_type

The workStatusType id for the shift, if specified.

linktitle

linkurl

room_floor

zipcode

pay_rate

base_rate

no_credit

Boolean

extra_credit

absent_reason

Integer

arrive_late_datetime

Datetime

arrive_late_reason

Integer

arrive_late_reason_label

String

leave_early_datetime

Datetime

leave_early_reason

Integer

leave_early_reason_label

String

custom_text_1

custom_text_2

custom_text_3

custom_multipick

Array of custom_multipick identifiers for the shift

acknowledged

Boolean; shift has been acknowledged or declined (declined if acknowledge_decline_reason is not null).

acknowledged_at

Date/time of acknowledgement or most recent modification to the acknowledgement.

acknowledge_decline_reason

Decline reason identifier; present only if declined.

acknowledged_notes

resource

Array of resource identifiers for this shift

custom_dropdown_1

custom_dropdown_2

custom_dropdown_3

custom_dropdown_4

custom_dropdown_5

custom_dropdown_6

custom_dropdown_7

custom_dropdown_8

custom_dropdown_9

custom_dropdown_10

custom_dropdown_11

custom_dropdown_12

custom_dropdown_13

custom_dropdown_14

custom_dropdown_15

custom_textarea

created

UTC time shift was created

status_updated

UTC time shift was published, unpublished, assigned, confirmed, or unconfirmed

updated

UTC time shift was otherwise updated

breaks

Array of breaks for the shift; each break has the following attributes:

name

start_time

The time in which a shift break starts, in RFC 3339 partial-time format (e.g. 15:30:00). When creating/updating breaks, an offset from the beginning of the shift may be used instead, in +HH:MM or +minutes format.

display_time

duration_minutes

paid

Boolean.

is_a_trade

Boolean; true if this shift has been offered for trade by the covering member.

Not all fields will be configured to be used for all organizations or set for all shifts.

absent_reason - integer

arrive_late_reason - integer

leave_early_reason - integer

delete_on_unconfirm - boolean

shift.acknowledge

Request example:

{
   "id" : 2753501
}

Response example:

{
   "seconds" : "0.280633",
   "jsonrpc" : "2.0",
   "id" : "3",
   "result" : {
      "message" : "You have acknowledged this position:\n\nWednesday, May 20, 2015, 9:55am to 11:55am\nFront Desk"
   }
}

Acknowledge or decline a shift.

Required parameter

id

Optional parameters:

acknowledge_decline_reason

acknowledge decline reason identifier, if the acknowledgement is to decline.

acknowledged_notes

Response: On success, a message attribute will provide a brief notification message.

shift.assign

This method is used by workgroup managers and site admins to assign a shift. By default, all conflict checking that is enabled for the site will be applied (can be overridden with the assignability_checks attribute); the publication state of the shift does not change (can be set to published by sending: "publish": true); and the shift is only acknowledged if auto-ack is on for this workgroup (can force acknowledgement by sending: "acknowledge": true).

Request example:

{
  "id" : 2753501,
  "covering_member" : 47,
}

Response example:

{
   "seconds" : "0.280633",
   "jsonrpc" : "2.0",
   "id" : "3",
   "result" : {
      "message" : "You have assigned this position:\n\nWednesday, May 20, 2015, 9:55am to 11:55am\nAssignee: John Doe\nFront Desk"
   }
}

Assign a shift. Can also publish the shift and/or mark the shift as acknowledged.

Required parameter

id

ID of the shift to be assigned.

covering_member or external_covering_member

ID of member to whom the shift is to be assigned.

Optional parameters

publish

set to true to publish the shift

acknowledge

set to true to acknowledge shift

no_notify

set to true to disable notification

assignability_checks

set to false to disable processing of Assignability parameters

Assignability parameters

To use assignability checks, the assignability_checks parameter must be true or not specified; additionally, the following options may be available, based on enabled features:

conflicts_ok - boolean

daily_overtime_ok - boolean

weekly_overtime_ok - boolean

timeoff_ok - boolean

consecutive_days - boolean

short_turnaround - boolean

ignore_attestation_types - boolean

attestation_type - array of attestationTypeId

ignore_role - boolean

shift.bulkDelete

Delete multiple shifts with a single call. This method processes bulk deletes asynchronously, meaning the caller will be returned a success message immediately (assuming valid parameters were sent), and the processing of these shift delete operations will happen out-of-band. Once all shift deletions have completed, a report will be emailed to the API caller. This report will detail the number of successes, failures, and provide details about why a failure occurred.

Request example:

{
   "shifts" : [2753501, 2753502],
}

Response example:

{
   "seconds" : "0.178901",
   "jsonrpc" : "2.0",
   "id" : "43",
   "result" : {
        "message": "Bulk delete has been started. You will receive an email with results."
    }
}

Updates multiple shift objects in a single call.

Required parameter

shifts - Array of shift identifiers.

Optional Parameters

Most other shift object attributes may be specified. Please see the shift.update documentation for more information.

Deletes a shift record.

Required parameter: id.

Optional Parameters:

notify_on_delete Boolean; if the shift is assigned, notify covering member upon deletion of the shift.

notify_message Custom text to be included when notifying shift owner upon deletion of shift.

shift.bulkUpload

Prepare the system to ingest and process a spreadsheet file containing one or more shift records. Upon executing this method, the caller will receive a unique identifier and unique upload URL that is valid for the next 10 minutes. The identifier can be used in conjunction with shift.bulkUploadStatus to poll the current status of the bulk upload operation.

In order to upload a file to the URL specified, the file should be POSTed with the content-type header matching the file type for the file being uploaded. If a file is POSTed with a content-type header that does not match the file type being uploaded to the server, an error will occur and the file will NOT be processed.

Valid file types are xls, xlsx, and csv.

Valid content-type headers and file associations

Request example:

{}

Response example:

{
   "id": 12345,
   "url": "https://www.shiftboard.com/servola/docs/upload.cgi?ss=9999999;type=shift_upload;expires=1735689600;signature=AAABBBBCCCCDDDEEEFFF;id=12345"
}

Required parameters

None

Optional Parameters

None

shift.bulkUploadGetSettings

Retrieve a list of configuration settings related to bulk upload operations. This list of configuration settings will include all site specific bulk upload operation settings as well as any site configuration overrides previously configured by the caller.

Request example:

{}

Response example:

{
    "bulk_upload_settings": {
        "add_org_custom_multipick": true,
        "add_org_custom_multipick_2": false,
        "add_org_member": true,
        "add_org_venue": true,
        "add_team": false,
        "add_time_block": false,
        "auto_conflicts_ok": false,
        "auto_is_available": true,
        "auto_timeoff_ok": false,
        "by_seniority": false,
        "conflicts_ok": false,
        "include_holds": true,
        "is_available": false,
        "notify": true,
        "past_dates": false,
        "seniority_required": false,
        "single_shift_per_day": true,
        "timeoff_ok": false,
        "use_acct_org_id_off": false
    }
}

Required parameters

None

Optional Parameters

None

Configuration Settings

Where items do not already exist setting|Description| --|-- add_team|Create New Teams add_venue|Create New Locations add_role|Create New Roles add_client|Create New Clients add_department|Create New Departments add_custom_multipick|Create New MP Labels add_custom_multipick_2|Create New Custom Multipick add_resource|Create New Resources add_time_block|Create New Shift/Coverage Blocks

Where associations do not already exist setting|Description| --|-- add_org_venue|Add Locations/Maps to Teams add_org_role|Add Roles to Teams add_org_client|Authorize Clients to Teams add_org_department|Authorize Departments to Teams add_org_custom_multipick|Authorize MP Labels to Teams add_org_custom_multipick_2|Authorize Custom Multipick to Teams add_org_resource|Authorize Resources to Teams add_org_time_block|Add Shift Blocks to Teams

When making assignments setting|Description| --|-- conflicts_ok|Allow Conflicts
is_available|Listed in Available
timeoff_ok|Ignore approved Time Off
include_holds|Assign to members in hold/inactive status add_org_member|Add necessary Team memberships - (you must be an authorized manager)

When using auto-assignments setting|Description| --|-- by_seniority|Honor Seniority
seniority_required|Skipping members without Seniority auto_conflicts_ok|Allow Conflicts
auto_is_available|Listed in Available
auto_timeoff_ok|Ignore approved Time Off
single_shift_per_day|Restrict members to a single shift per day

Load Past Coverage setting|Description| --|-- past_dates|Allow expired/past dates

Send Notifications setting|Description| --|-- notify|For assigned/auto-assigned positions

shift.bulkUploadGetTemplates

Retrieve a list of URLS that identify site specific or general spreadhseet templates for bulk upload operations. These templates can be used for proper formatting required for the system to ingest spreadsheets uploaded to a shift.bulkUpload generated URL.

Request example:

{}

Response example:

{
    "bulk_upload_templates": {
        "extended": "https://www.servola.com/servola/fetch.cgi?ss=9999999;type=shift_select_template;expires=1569506891;signature=yk-hqoq49vdhdq-_RhEed1cMpxc;id=extended",
        "simple": "https://www.servola.com/servola/fetch.cgi?ss=9999999;type=shift_select_template;expires=1569506891;signature=WerevztiM5S87NUK3sSjBVCO3JM;id=simple",
        "standard": "https://www.servola.com/servola/fetch.cgi?ss=9999999;type=shift_select_template;expires=1569506891;signature=fNU7bCK97kJt_T8BQz3u3QmqvIc;id=standard",
        "universal": "https://www.servola.com/servola/fetch.cgi?ss=9999999;type=shift_select_template;expires=1569506891;signature=NmgXece9beOta36RQEW1GXcdgSc;id=universal"      
    }
}

Required parameters

None

Optional Parameters

None

shift.bulkUploadUpdateSettings

Update configuration settings related to bulk upload operations. These configuration settings are caller specific, and do not have any effect on bulk configuration settings for the site or other users.

Request example:

{
   "notify": true,
   "add_org_member": false
}

Response example:

{}

Required parameters

None

Optional Parameters

Any of the configuration options returned from shift.bulkUploadGetSettings are valid.

shift.bulkUploadStatus

Provide a means to poll for the status of bulk upload operations. This method is used in conjunction with return values from shift.bulkUpload. The caller can use the identifier returned by the aformentioned method to see the current status of a file that has been posted to the bulk upload URL associated with this identifier.

Request example:

{
   "id": 12345
}

Response example:

{
    "error_count": 0,
    "errors": [],
    "rows": "1",
    "status": "Loaded",
    "status_code": "3"
}

Required parameters

id

unique identifier associated with the file posted to the upload URL returned from shift.bulkUpload

Optional Parameters

None

Status codes and definitions

shift.bulkUpdate

This method is for modifying the same details on multiple shifts. This method processes bulk updates asynchronously, meaning the caller will be returned a success message immediately (assuming valid parameters were sent), and the processing of these shift update operations will happen out-of-band. Once all updates have been completed, a report will be emailed to the API caller. This report will detail the number of successes, failures, and provide details about why a failure occurred.

Request example:

{
   "count" : 1,
   "timezone" : "Greenwich Mean Time : Dublin, Lisbon, London (GMT)",
   "subject" : "updated",
   "qty" : 1,
   "published" : true,
   "workgroup" : "226084",
   "end_date" : "2010-09-17T14:30:00",
   "covered" : true,
   "start_date" : "2010-09-17T14:00:00",
   "shifts" : [2753501, 2753502],
}

Response example:

{
   "seconds" : "0.178901",
   "jsonrpc" : "2.0",
   "id" : "43",
   "result" : {
        "message": "Bulk update has been started. You will receive an email with results."
    }
}

Updates multiple shift objects in a single call.

Required parameter

shifts - Array of shift identifiers.

Optional Parameters

start_time

If specified, all shifts that have a set start time will be updated to begin at this new start time. NOTE: Updating the start time will have no affect on the dates on which these shifts occur.

end_time

If specified, all shifts that have a set end time will be updated to end at this new end time. NOTE: Updating the end time will have no affect on the dates on which these shifts occur.

additional attributes

Most other shift object attributes may be specified. Please see the shift.update documentation for more information.

shift.bulkCopy

This method is for copying a single or multiple shifts to a date in the future. This method processes bulk copies asynchronously, meaning the caller will be returned a success message immediately (assuming valid parameters were sent), and the copying of shifts will happen out-of-band. Once all shifts in the range have been copied, a report will be emailed to the API caller.

Request example:

{
   "select": {
      "start_date": "2019-01-01",
      "end_date": "2019-01-15",
      "member": 12345,
      "workgroup": 11111,
   },
   "copy_forward_date": "2019-02-01",
   "copy_forward_assigned": true,
   "copy_forward_published": true,
   "is_available": false,
   "conflicts_ok": true,
   "daily_overtime_ok": false,
   "weekly_overtime_ok": true
}

Response example:

{
   "seconds" : "0.178901",
   "jsonrpc" : "2.0",
   "id" : "43",
   "result" : {
        "message": "Bulk copy has been started. You will receive an email with results."
    }
}

Copies multiple shift objects to a date in the future using a single call to the API. The structure of the shifts selected, including breaks, repeating days, and times will be copied forward starting at the new date specified. All filters use select criteria.

Required parameter

copy_forward_date - Day in the future to copy the shifts to.

Optional Parameters

copy_forward_assigned

Boolean; preserve assignment for copied shifts.

copy_forward_autoassign

Boolean; autoassign copied shifts.

copy_forward_published

Boolean; publish copied shifts. Defaults to true.

copy_forward_unassign_on_conflict

Boolean; If true, will unassign conflicting shifts, otherwise the shift will be left assigned and unpublished. If both copy_forward_unassign_on_conflict and copy_forward_autoassign are set to true conflicting shifts will be unassigned and then autoassigned to other workers that are not in conflict.

start_date

Filter for shifts beginning at this date. Uses select criteria.

end_date

Filter for shifts that end on or before this date. Uses select criteria.

start_time

Filter for shifts that begin on the start date specified at this start time. Uses select criteria.

dur_hrs

Duration in hours. Uses select criteria.

dur_mins

Duration in minutes. Uses select criteria.

workgroup

Filter for shifts that belong to this workgroup. Can be specified as a singluar or an array of ids. Uses select criteria.

member

Filter for shifts that are assigned to this member. Uses select criteria.

profile_type

Filter for shifts that are assigned to this profile type. Uses select criteria.

Repeating shift parameters

It is possible to filter for shifts using a repeating interval pattern. In order to do so, some additional parameters are required in the select criteria:

repeating_shift

Boolean; specifies the caller is creating a series of repeating shifts.

repeating_shift_type

Type of repeating shift.

repeating_shift_end_date

The date of the final shift in the repeating series in RFC 3339 full date format (e.g. "2018-01-01").

repeating_shift_interval

Specifies the interval in which the series will be created. Valid interval options are below:

NOTE: every_fifth and every_sixth are only available when creating daily shifts.

repeating_shift_frequency

Specifies the frequency for a frequency based repeating series. Valid frequency options are below:

NOTE: Parameter is required when repeating_shift_type is frequency

repeating_shift_days_of_week

Array. Specifies which days of the week to create shifts for in a repeating series. Valid options are below:

NOTE: Parameter is required when repeating_shift_type is days_of_week

additional_dates

Array. Additional shift dates to be created alongside the specified repeating series. Dates must be in RFC 3339 full date format (e.g. "2018-01-01")

Assignability parameters

It is possible to modify the assignment of the copied shifts using assignability checks. Below are a list of options that will affect how the copied shifts will be assigned:

is_available - boolean

by_seniority - boolean

seniority_required - boolean

single_shift_per_day - boolean

conflicts_ok - boolean

daily_overtime_ok - boolean

weekly_overtime_ok - boolean

timeoff_ok - boolean

consecutive_days - boolean

short_turnaround - boolean

ignore_attestation_types - boolean

attestation_type - array of attestationTypeId

ignore_role - boolean

shift.confirm

This method is used by anyone to pick up a shift for themselves. By default, all conflict checking that is enabled for the site and is applicable to pick-up shifts is applied (this cannot be changed), and the shift will be acknowledged (this cannot be changed).

Request example:

{
   "id" : 2753501
}

Response example:

{
   "seconds" : "0.443989",
   "jsonrpc" : "2.0",
   "id" : "2",
   "result" : {
      "message" : "You have accepted this position:\n\nWednesday, May 20, 2015, 9:55am to 11:55am\nFront Desk"
   }
}

Confirms a shift.

Required parameter

id: ID of the shift to be assigned.

Optional parameters

covering_member or external_covering_member: Assign the specified user to the shift (rather than assigning the current user). Only available to workgroup managers.

Assignability parameters

To use assignability checks, the assignability_checks parameter must be true; then, the following options may be available, based on enabled features:

is_available - boolean

by_seniority - boolean

seniority_required - boolean

single_shift_per_day - boolean

conflicts_ok - boolean

daily_overtime_ok - boolean

weekly_overtime_ok - boolean

timeoff_ok - boolean

consecutive_days - boolean

short_turnaround - boolean

ignore_attestation_types - boolean

attestation_type - array of attestationTypeId

ignore_role - boolean

Response

On success, a message attribute will provide a brief notification message. If the shift had a count > 1, a new shift object will have been created and the id of the new shift will also be returned.

shift.create

Request example:

{
   "workgroup" : "226085",
   "department" : "949",
   "location" : "29118",
   "start_date" : "2010-09-17T12:00:00",
   "role" : "2282"
}

Response example:

{
   "seconds" : "1.007354",
   "jsonrpc" : "2.0",
   "id" : "57",
   "result" : {
      "id" : 2753502
   }
}

Creates a new shift record.

Parameters

Most attributes of a shift object except id may be specified. Minimally, workgroup and start_date parameters must be specified. timezone will default to the organization's timezone. location will default to the workgroup's default location, if set. external_covering_member/covering_member are mutually exclusive, and may only be specified if the shift is covered. If either is specified as an array, single positions of the shift will be assigned to the indicated members. covered may only be true if the shift is published. Start and end dates may only fall on even five minute times. Either count or qty may be specified and both will be set for the new shift, defaulting to 1; if both are specified, they must be equal. count must be 1 for a covered shift.

Optional parameters

notify_on_create Boolean; send a notification message to the covering member for this shift.

notify_message Additional text to include in notification message.

Repeating shift parameters

It is possible to use this method to create a series of repeating (repeating) shifts. In order to do so, some additional parameters are required:

repeating_shift

Boolean; specifies the caller is creating a series of repeating shifts.

repeating_shift_type

Type of repeating shift.

repeating_shift_end_date

The date of the final shift in the repeating series in RFC 3339 full date format (e.g. "2018-01-01").

repeating_shift_interval

Specifies the interval in which the series will be created. Valid interval options are below:

NOTE: every_fifth and every_sixth are only available when creating daily shifts.

repeating_shift_frequency

Specifies the frequency for a frequency based repeating series. Valid frequency options are below:

NOTE: Parameter is required when repeating_shift_type is frequency

repeating_shift_days_of_week

Array. Specifies which days of the week to create shifts for in a repeating series. Valid options are below:

NOTE: Parameter is required when repeating_shift_type is days_of_week

additional_dates

Array. Additional shift dates to be created alongside the specified repeating series. Dates must be in RFC 3339 full date format (e.g. "2018-01-01")

Assignability parameters

To use assignability checks, the assignability_checks parameter must be true; then, the following options may be available, based on enabled features:

is_available - boolean

by_seniority - boolean

seniority_required - boolean

single_shift_per_day - boolean

conflicts_ok - boolean

daily_overtime_ok - boolean

weekly_overtime_ok - boolean

timeoff_ok - boolean

consecutive_days - boolean

short_turnaround - boolean

ignore_attestation_types - boolean

attestation_type - array of attestationTypeId

ignore_role - boolean

Delayed publication parameters

Depending on enabled site features, a shift can be scheduled for publishing some date and time in the future, with optionally different datetimes per tier. NB: When setting any of the delayed publication dates, all of them must be set; previous values will be ignored.

For tiers, the higher tiers (10 is highest) have to be the same as, or earlier than, the lower tiers (1 is lowest), or an error will be returned. Setting a lower tier and leaving higher tiers empty will set the empty, higher tiers to the same value as the closest lower tier.

All of the dates are set in datetime format (e.g. "2009-04-01T13:00:00Z"), in UTC. They can also be set to the string now, instead of a datetime.

To publish immediately to a single tier, merely that tier to now.

Setting the shift's published value from true to false, or false to true, removes all publication dates.

tier1_publish_date_utc..tier10_publish_date_utc - datetime

The individual datetimes for each tier. Only tiers supported for the organization are shown. If tier support is not enabled, none are shown. If a value is set to null, the shift will not be published to members at that tier.

publish_date_utc - datetime

The earliest publish datetime of the shift (if tiers used, the earliest of those datetimes). If set, publish_date_utc will override and blank out all of the tier publish datetimes.

publish_level - integer (read-only)

The current publish level of the shift. For example, if tier6_publish_date_utc is in the past, and tier5_publish_date_utc is in the future, then publish_level will be 6.

Response

On success, an id attribute will provide the identifier for the new shift. When creating a series of repeating shifts, the id returned will be an array of identifiers, one id for each of the shifts created in the series.

shift.customDropdownList

Request example:

{}

Response example:

{
    "custom_listable_1": {
        "25013": "Listable 1 Value A",
        "25014": "Listable 1 Value B"
    },
    "custom_listable_2": {
        "25015": "Listable 2 Value A",
        "25016": "Listable 2 Value B",
        "25017": "Listable 2 Value C"
    },
    "custom_listable_3": {
        "25018": "Listable 3 Value A",
        "25019": "Listable 3 Value B",
        "25020": "Listable 3 Value C",
        "25021": "Listable 3 Value D"
    }
}

Returns information about shift related custom dropdown list objects.

Required Parameter: none

Optional Parameters: none

Response: On success, an object will be returned containing all shift custom dropdown listables that have been created, and are enabled for the site.

shift.customMultipickList

Request example:

{}

Response example:

{
    "custom_multipick": [
        {
            "description": "Multipick Value One",
            "id": "5551209",
            "name": "One"
        },
        {
            "description": "Multipick Value Two",
            "id": "5551210",
            "name": "Two"
        }
    ],
    "custom_multipick_2": [
        {
            "description": "Choice A",
            "id": "5551211",
            "name": "A"
        },
        {
            "description": "Choice B",
            "id": "5551212",
            "name": "B"
        },
        {
            "description": "Choice C",
            "id": "5551213",
            "name": "C"
        }
    ],
    "custom_multipick_3": []
}

Returns information about shift related custom multi-pick list objects.

Required Parameter: none

Optional Parameters: none

Response: On success, an object will be returned containing all shift custom multi-pick listables that have been created, and are enabled for the site.

shift.customTextList

Request example:

{}

Response example:

{
    "custom_text_1": {
        "label": "Custom Text 1",
        "permissions": {
            "auth_read": 2,
            "auth_write": 4
        }
    },
    "custom_text_2": {
        "label": "Custom Text 2",
        "permissions": {
            "auth_read": 2,
            "auth_write": 4
        }
    },
    "custom_text_3": {
        "label": "Custom Text 3",
        "permissions": {
            "auth_read": 5,
            "auth_write": 2
        }
    },
    "custom_textarea": {
        "label": "Custom Text Area",
        "permissions": {
            "auth_read": 2,
            "auth_write": "4"
        }
    }
}

Returns permissions for shift related custom multi text/text area objects.

Required Parameter: none

Optional Parameters: none

Response: On success, an object will be returned containing all shift custom text objects that have been created, and are enabled for the site.

shift.delete

Request example:

{
   "id" : "2753500"
}

Response example:

{
   "seconds" : "0.058344",
   "jsonrpc" : "2.0",
   "id" : "67",
   "result" : {}
}

Deletes a shift record.

Required parameter: id.

Optional Parameters:

notify_on_delete Boolean; notify covering member upon deletion of the shift.

notify_message Custom text to be included when notifying shift owner upon deletion of shift.

Response: On success, empty results will be returned.

shift.deleteSignup

Deletes a member from a shift's signup list.

Parameters:

id

Required. id of the shift for which to remove a sign up.

member

Required. id of the account to remove from the sign up list (defaults to the current user). May be a single id or an array of ids.

NOTE: If you are calling this method with the member parameter, external_member will be ignored (if included).

external_member

Required. external id of the account to remove from the sign up list (defaults to the current user). May be a single id or an array of ids.

NOTE: If you are calling this method with the external_member parameter, member will be ignored (if included).

Response: On success, empty results will be returned.

shift.get

Request example:

{
   "id" : 2753499
}

Response example:

{
   "seconds" : "0.062897",
   "jsonrpc" : "2.0",
   "id" : "25",
   "result" : {
      "shift" : {
         "reference_id" : "",
         "linkurl" : "",
         "work_status_type" : "0",
         "signup_list" : false,
         "id" : "2753499",
         "start_date" : "2010-09-17T12:00:00",
         "count" : "1",
         "timezone" : "Pacific Time (US/Can) (GMT-08:00)",
         "subject" : "",
         "urgent" : false,
         "zipcode" : "60616",
         "details" : "",
         "qty" : "1",
         "workgroup" : "226081",
         "published" : false,
         "covered" : false,
         "no_pick_up" : false,
         "room_floor" : "",
         "linktitle" : ""
      }
   }
}

Returns information about a coverage shift.

Parameters:

id

Required. id of the shift for which to return information.

extended

Boolean; if not specified or true or user_actions is true, the results returned will be an extended set of attributes; otherwise a basic set of attributes will be returned for each shift.

user_actions

Boolean; if specified and true, a user_actions object will be returned with attributes indicating what actions (e.g. cover, uncover, assign, delete, acknowledge) may be presented to the user.

absent - boolean, attendance feature available for this shift

absent_reasons - list of 0 or more reason objects; keys are id (int), reason (text), selected (boolean), and account_points (float)

arrive_late - boolean, allowed to set arrive_late_reason for this shift

arrive_late_max_adjust - int, maximum number of minutes from the start time that a shift may be marked late

arrive_late_remove - boolean, whether or not the user can remove the arrive late reason/datetime (they may still be able to create or edit, depending on values of arrive_late and arrive_late_reasons)

arrive_late_reasons - same as absent_reasons

assign - can assign shift

change - can modify shift

change_custom_text_N - can modify the numbered custom text field of the shift

cover - can cover shift

create_note - can create manager note for shift

delete - can delete shift

leave_early - boolean, allowed to set leave_early for this shift

leave_early_max_adjust - int, maximum number of minutes from the end time that a shift may be marked early

leave_early_remove - boolean, whether or not the user can remove the arrive late reason/datetime (they may still be able to create or edit, depending on values of leave_early and leave_early_reasons)

leave_early_reasons - same as absent_reasons

publish - can publish shift

reassign - can reassign shift

timeclock - can clock in to shift

uncover - can unassign shift

unpublish - can unpublish shift

view_custom_text_N - can view the numbered custom text field of the shift

display_time

Boolean; if specified and true, the returned shift will include other attributes giving a string presentation of when the shift is scheduled.

denormalize

denormalize is deprecated; where possible, the results referenced_objects attribute should be used instead.

Boolean; if specified and true, all identifiers (except the shift id itself) in the returned shift object will be replaced with corresponding names, etc. suitable for display, and the following attributes may be added:

location_details

An object providing one or more of the following attributes, when available: zipcode, address, city, state, country, latitude, longitude.

display_date

The start date of the shift, formatted for display (including weekday name).

display_adj_end_time

The end time of the shift, formatted for display, adjusted for late/early.

display_adj_start_time

The start time of the shift, formatted for display, adjusted for late/early.

display_end_time

The end time of the shift, formatted for display.

display_start_time

The start time of the shift, formatted for display.

display_time

The time range of the shift, formatted for display.

local_arrive_late_datetime

The (possibly TZ-adjusted) datetime that the member arrived late

local_end_date

The (possibly TZ-adjusted) end datetime of the shift

local_leave_early_datetime

The (possibly TZ-adjusted) datetime that the member left early

local_start_date

The (possibly TZ-adjusted) start datetime of the shift

local_timezone

The timezone the local times are adjusted for. When updating arrive_late_datetime or leave_early_datetime (using the starting values from local_start_date / local_end_date), also pass local_timezone to ensure the API can convert the time to the correct timezone (optionally use a local_timezone of GMT to submit the values in GMT).

referenced_objects

Boolean, defaults to true unless denormalize is true. Indicates that, in addition to the shift attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned shift.

The response results shift attribute will be the selected shift object.

If user_actions were requested, a user\_actions attribute will also be returned.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the shift results, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

client

id and name attributes are provided.

department

id and name attributes are provided.

location

id and name attributes are provided.

role

id and name attributes are provided.

timezone

name and iana_timezone attributes are provided.

workStatusType

id and name attributes are provided.

workgroup

id and name attributes are provided.

acknowledgeDeclineReason

id and label attributes are provided.

image

Boolean; if specified and true, the results returned will include an image_url attribute giving a url to the shift's covering_member's user image or null if no image is available.

custom_multipick

id and name attributes are provided.

custom_dropdown_1

id and name attributes are provided.

custom_dropdown_2

id and name attributes are provided.

custom_dropdown_3

id and name attributes are provided.

custom_dropdown_4

id and name attributes are provided.

custom_dropdown_5

id and name attributes are provided.

custom_dropdown_6

id and name attributes are provided.

custom_dropdown_7

id and name attributes are provided.

custom_dropdown_8

id and name attributes are provided.

custom_dropdown_9

id and name attributes are provided.

custom_dropdown_10

id and name attributes are provided.

custom_dropdown_11

id and name attributes are provided.

custom_dropdown_12

id and name attributes are provided.

custom_dropdown_13

id and name attributes are provided.

custom_dropdown_14

id and name attributes are provided.

custom_dropdown_15

id and name attributes are provided.

resource

id, name, and label attributes are provided.

shift.getAssignmentList

Request example:

{
   "workgroup" : 12345,
   "shift" : {
      "id" : 123456789
   }
}

Response example:

{
   "seconds" : "0.058344",
   "jsonrpc" : "2.0",
   "id" : "67",
   "result" : {
      "unassignable" : {
         "5" : "John Smith - Has Conflicts (My Team)"
      },
      "assignable" : {
         "1" : "Bob Doe",
         "2" : "Jane Doe"
      },
      "assignable_order" : [ "2", "1" ],
      "unassignable_order" : [ "5" ]
   }
}

Returns availability information as to who is and is not assignable to a shift. The shift in this case could be one that currently exists, or a shift to be created later.

Required parameters:

workgroup

The id for the workgroup.

Optional parameters:

shift

Object. The shift object allows for the following optional parameters:

additional_dates

Array. Additional shift dates to be checked alongside the specified shift and/or repeating series. Dates must be in RFC 3339 full date format (e.g. "2018-01-01")

Repeating shift parameters

It is possible to use this method to check a series of repeating shifts. In order to do so, some additional parameters are required:

repeating_shift

Boolean; specifies the caller is checking a series of repeating shifts.

repeating_shift_type

Type of repeating shift.

repeating_shift_end_date

The date of the final shift in the repeating series in RFC 3339 full date format (e.g. "2018-01-01").

repeating_shift_interval

Specifies the interval for the series. Valid interval options are below:

NOTE: every_fifth and every_sixth are only available when checking daily shifts.

repeating_shift_frequency

Specifies the frequency for a frequency based repeating series. Valid frequency options are below:

NOTE: The repeating_shift_frequency parameter is required when repeating_shift_type is frequency

repeating_shift_days_of_week

Array. Specifies which days of the week to check shifts for in a repeating series. Valid options are below:

NOTE: The repeating_shift_days_of_week parameter is required when repeating_shift_type is days_of_week

limit

Maximum number of results to return; default site dropdown list limit.

use_time

Needed if open ended or all day should do overtime/conflict/availability/timeoff checking.

include_holds

Boolean; default false (members on hold not included).

conflicts_ok

Boolean; default false (conflicts checked, if date/times specified).

daily_overtime_ok

Boolean; default false (conflicts checked, if date/times specified).

display_screen_name

Boolean; default false. This property if provided, will display an account's screen name in the results instead of the default full name.

display_account_info

Boolean; default false. This property if provided, will display a limited set of account details in the results instead of the default full name.

weekly_overtime_ok

Boolean; default false (conflicts checked, if date/times specified).

is_available

Boolean; default false (availability not checked).

timeoff_ok

Boolean; default true (timeoff not checked).

seniority_required

Boolean; default false, ignored unless sorting by_seniority.

single_shift_per_day

Boolean; default false.

is_autoassignable

Boolean; default false.

standby

Boolean; default false, standby signups only

role_restriction

Boolean; default false; apply role restrictions, if there is a role and the team uses restrictions.

ignore_role

Boolean; default false; ignore role restrictions.

min_level

Default 1, maximum level to exclude (e.g. 3 to exclude non-manager, 2 to exclude members).

max_level

Maximum level to include (e.g. 2 to exclude coordinators/managers).

phrase

Match in first name, last name, fullname

coverage_signup_list_eid

Exclude members already signed up for this eid (start_date must also be specified).

accounts

List of accounts to limit results to.

exclude_accounts

List of accounts to exclude from results to.

profile_type

Only members with this profile type.

extended_filter

Request example with extended_filter specified:

{
   "workgroup" : 12345,
   "shift" : {
      "id" : 123456789
   },
   "profile_type": 1,
   "extended_filter": { "emergency_contact": "Joe Blow" }
}

Specification to filter on profile options (profile_type must be specified). A complete list of valid options can be found by calling the profileConfiguration.list method. The relevant fields are profile\_type and form\_name.

range

Range of accounts in miles from venue zipcode.

min_score

Minimum score.

no_score

Include members with no score (min_score must be specified).

by_seniority

Order by those with seniority by seniority date or rank, then with seniority and no date/rank, then no seniority (random within those). The order can be found in the assignable_order and unassignable_order arrays in the response.

randomize

Return results in random order.

mandatory_days_off

Mandatory days off settings (hash).

tier

The user's tier.

tier_ge

The user's minimum tier.

lang

The user's language (or if user has not set one, the site's default).

consecutive_days

Allow shifts on N consecutive days if beta feature is enabled (boolean).

short_turnaround

Allow shifts that have a short (N hours) turnaround if beta feature is enabled (boolean).

ignore_attestation_types

Array of attestationType IDs to ignore.

shift.getOfferedTrade

Request example:

{
   "id" : "56789012",
   "extended" : true
}

Response example:

{
   "seconds" : "0.128193",
   "jsonrpc" : "2.0",
   "id" : "15",
   "result" : {
      "referenced_objects" : {
         "workgroup" : [
            {
               "name" : "Help Desk",
               "id" : "412345"
            }
         ],
         "department" : [
            {
               "name" : "Distribution",
               "label" : "Distribution",
               "id" : "9942"
            }
         ],
         "timezone" : [
            {
               "name" : "Pacific Time (US/Can) (GMT-08:00)",
               "iana_timezone" : "America/Los_Angeles"
            }
         ],
         "location" : [
            {
               "name" : "Training / Meetings",
               "id" : "92580"
            }
         ],
         "shift" : [
            {
               "display_time" : "1pm to 2pm",
               "department" : "9942",
               "reference_id" : "",
               "linkurl" : "",
               "work_status_type" : "5",
               "start_date" : "2014-01-29T13:00:00",
               "signup_list" : false,
               "id" : "56789012",
               "count" : "1",
               "timezone" : "Pacific Time (US/Can) (GMT-08:00)",
               "display_date" : "January 29, 2014",
               "location" : "92580",
               "subject" : "",
               "covering_member" : "47",
               "urgent" : false,
               "zipcode" : "94132",
               "qty" : "1",
               "details" : "details!",
               "workgroup" : "412345",
               "published" : true,
               "no_credit" : false,
               "end_date" : "2014-01-29T14:00:00",
               "covered" : true,
               "no_pick_up" : false,
               "no_trade" : false,
               "room_floor" : "room/floor",
               "linktitle" : ""
            }
         ],
         "account" : [
            {
               "id" : "39",
               "screen_name" : null,
               "last_name" : "Foster",
               "first_name" : "Joanie"
            },
            {
               "seniority_order" : "19999-12-31 23:59:59",
               "id" : "47",
               "profile_type" : "3",
               "screen_name" : "Stan Wilson",
               "last_name" : "Wilson",
               "first_name" : "Stan"
            }
         ],
         "workStatusType" : [
            {
               "name" : "Salary/Exempt",
               "id" : "5"
            }
         ]
      },
      "tradeboard" : {
         "trade_completed" : "2014-01-21T20:40:38Z",
         "shift" : "56789012",
         "notes" : "Need to see the dentist; please take this trade",
         "id" : "12345",
         "traded_to" : "47",
         "traded_by" : "39",
         "trade_complete" : true
      }
   }
}

Returns information about a tradeboard posting for a coverage shift.

Parameters:

id

Required. id of the shift for which to return information.

extended

Boolean; if specified and true, the results returned will include an extended set of attributes; otherwise a basic set of attributes will be returned for each tradeboard posting.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the tradeboard attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned tradeboard posting.

The response results tradeboard attribute will be the selected tradeboard object.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the tradeboard results or in its associated shift, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

NOTE: external_id will also be returned in the results if external ids are enabled for the site.

client

id and name attributes are provided.

department

id and name attributes are provided.

location

id and name attributes are provided.

role

id and name attributes are provided.

shift

All basic shift attributes will be provided. If the extended parameter is true, extended shift attributes will also be provided. Additionally, display_date and display_time attributes contain formatted strings describing the shift's start and end time.

timezone

name and iana_timezone attributes are provided.

workStatusType

id and name attributes are provided.

workgroup

id and name attributes are provided.

shift.list

Request example:

{
   "select" : {
      "workgroup" : "226084"
   }
}

Response example:

{
   "seconds" : "0.081433",
   "jsonrpc" : "2.0",
   "id" : "44",
   "result" : {
      "shifts" : [
         {
            "count" : "1",
            "timezone" : "Greenwich Mean Time : Dublin, Lisbon, London (GMT)",
            "subject" : "updated",
            "qty" : "1",
            "workgroup" : "226084",
            "published" : true,
            "covered" : true,
            "end_date" : "2010-09-17T14:30:00",
            "id" : "2753501",
            "start_date" : "2010-09-17T14:00:00"
         }
      ],
      "count" : "1",
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      }
   }
}

Returns information about coverage shifts. Uses pagination. Uses select criteria.

Optional parameters:

extended

Boolean; if specified and true or user_actions is true, the results returned will include an extended set of attributes; otherwise a basic set of attributes will be returned for each shift.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the shifts attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned shifts.

display_time

Boolean; if specified and true, the results returned will include a display_time attribute giving a string presentation of when the shift is scheduled.

aggregation_mode

If specified, aggregated results are returned. Options are:

similar

Shifts with the same start_date, end_date, timezone, workgroup, covering_member, covered, published, location, role, and urgent attributes are aggregated.

similar_subject

Shifts with the same start_date, end_date, timezone, subject, covering_member, covered, published, location, role, and urgent attributes are aggregated.

date

Shifts with the same start_date, workgroup, covered, published, and urgent attributes are aggregated.

date_subject

Shifts with the same start_date, subject, covered, published, and urgent attributes are aggregated.

Each result element will have an aggregate_count attribute indicating how many elements were aggregated. count and qty will be summed for the aggregated elements; other fields that are not aggregated over will be omitted from results that aggregate more than one element.

image

Boolean; if specified and true, the results returned will include an image_url attribute giving a url to the shift's covering_member's user image or null if no image is available.

image_expiration

Specifies the valid lifetime of the returned URL in seconds; default 300, maximum 604800 (1 week).

timeclock_status

Boolean; if specified and true, the results returned will include a clocked_in attribute indicating that the shift's covering_member is currently clocked in (though not necessarily for this shift) and a can_clock_in_out attribute indicating whether there is authorization to clock that covering member in or out.

no_location

Boolean; if specified and true, the results returned will include shifts that do not have an assigned location (in addition to the locations specified in select), false excludes shifts without locations.

direct_manager_account

Account ID; if specified, shifts will be filtered by the account ID of the manager of members to whom the shifts are assigned

external_direct_manager_account

External Account ID; if specified, shifts will be filtered by the external account ID of the manager of members to whom the shifts are assigned

shared

Boolean; if specified and true, the results returned will also include shifts that are covered and published from workgroups that are shared to the account.

user_actions

Boolean; if specified and true, a user_actions object will be returned with attributes indicating what actions (e.g. cover, uncover, assign, delete, acknowledge) may be presented to the user.

labels

Boolean; if specified and true, displayable labels are returned for many id attributes. E.g. in addition to "role":"123", "role_label":"Bartender" will be returned.

select

Select shifts which start between January 1st, 2018 and January 7th, 2018 (inclusive), are published, and have not been filled.

 {
     select: {
         start_date: "2018-01-01",
         end_date: "2018-01-07",
         published: true,
         covered: false
     }
}

An object specifying selection criteria for this request. Note that start_date and end_date will have default values if not specified. The available criteria include:

start_date

The earliest date of coverage to select, in RFC 3339 full date format (e.g. "2009-04-01"). Defaults to today.

end_date

The latest date of coverage to select, in RFC 3339 full date format. Defaults to 7 days after the start_date.

display_start_date

The earliest date of coverage to select, in RFC 3339 full date format (e.g. "2009-04-01"). This should be used instead of start_date when selecting shifts that include workers across multiple timezones.

display_end_date

The latest date of coverage to select, in RFC 3339 full date format. This should be used instead of end_date when selecting shifts that include workers across multiple timezones.

published

If specified, true requests only published shifts, false requests only unpublished shifts.

covered

If specified, true requests only covered shifts, false requests only uncovered shifts.

urgent

If specified, true requests only urgent shifts, false requests only non-urgent shifts.

no_pick_up

If specified, true requests only "No Pick-Up" shifts, false requests only non-"No Pick-Up" shifts.

signup_list

If specified, true requests only Signup List shifts, false requests only non-Signup List shifts.

location

If specified, requests only shifts with the given locations (either a single location id or an array of ids). Use 0 for shifts with no location.

role

If specified, requests only shifts with the given roles (either a single role id or an array of ids). Use 0 for shifts with no role.

client

If specified, and the site is configured to use client for schedule items, requests only shifts with the given roles (either a single client id or an array of ids). Use 0 for shifts with no client.

department

If specified, and the site is configured to use department for schedule items, requests only shifts with the given departments (either a single department id or an array of ids). Use 0 for shifts with no department.

start_time

If specified, requests only shifts with the given starting times (either a single time or an array of times), in RFC 3339 partial time format (e.g. "13:00:00").

workgroup

If specified, requests only shifts for the given workgroups. May be a single workgroup or an array of workgroups.

scope

If specified, a value of 'my_calendar' requests shifts normally shown to a user on the calendar, that is, shifts for workgroups for which the user is a coordinator or manager, shifts covered by the user, or approved, open shifts for workgroups for which the user is a member. A value of 'siteadmin' requests all shifts for the entire site and is only allowed for site administrators. A value of 'managed_workgroups' requests shifts for the workgroups managed by the user and is only allowed for workgroup managers. A value of 'report' is like 'siteadmin' for site administrators and like 'managed_workgroups' for others. 'siteadmin' is the default for site administrators while 'my_calendar' is the default for all others.

reference_id

If specified, requests only shifts with the given reference IDs (case insensitive) (either a single reference ID or an array of reference IDs).

subject

If specified, only shifts with the matching subject (subject or body of the shift) will be selected.

keywords

If specified, only select shifts with the keywords given as an array or a single string (which is treated as whitespace separated keywords unless 'exact' matching). keywords parameter works together with parameter 'match'.

match

String, defaults to 'any'. Works together with 'keywords' parameter. Recognizes three values: 'any', 'all' and 'exact'. If 'any' is specified, it will match if any word from 'subject' parameter appears in either 'subject' or in 'details' of the shift. If 'all' is specified, it will match if all words from 'subject' parameter appears in either 'subject' or all words appear in 'details' of the shift. If 'exact' is specified, it will match if a keyword is an exact match with 'subject' parameter and the entirety of the 'subject' field or exact match with the entirety of the 'details' field of the shift.

covering_member

If specified, requests only shifts covered by the workgroup members. May be a single account id or an array.

NOTE: If you are calling this method with the external_covering_member parameter, covering_member will be ignored, and is not required.

external_covering_member

If specified, requests only shifts covered by the workgroup members. May be a single account id or an array.

NOTE: If you are calling this method with the covering_member parameter, external_covering_member will be ignored, and is not required.

exclude_covering_member

If specified, excludes shifts covered by the workgroup members. May be a single account id or an array.

only_deleted_workgroups

If specified and true, only shifts for deleted workgroups will be selected; if specified and false, shifts for both deleted and non-deleted workgroups will be selected. Otherwise (the default), only shifts for non-deleted workgroups will be selected.

profile_type

If specified, only shifts with covering members with this profile type identifier will be selected.

acknowledged

If specified and true, only shifts that have been acknowledged (including being declined) will be selected.

custom_multipick, custom_multipick_2,3,...

If specified, only shifts with the given custom multipick identifier (and possibly other custom multipick identifiers) will be selected.

resource

If specified, only shifts with the given resource identifier (and possibly other resource identifiers) will be selected.

attendee_filled

If specified and false, only shifts for which additional attendees may be added will be selected; if specified and true, only shifts which have attendees but for which no additional attendees may be added will be selected.

absent

If specified and true, only shifts that have been marked "Absent" will be selected; if specified and false, only shifts that have not been marked "Absent" will be selected.

arrive_late

If specified and true, only shifts that have been marked "Arrive Late" will be selected; if specified and false, only shifts that have not been marked "Arrive Late" will be selected.

leave_early

If specified and true, only shifts that have been marked "Leave Early" will be selected; if specified and false, only shifts that have not been marked "Leave Early" will be selected.

attendance

An enumerated string (or array of them) of absent, arrive_late, or leave_early. Shifts matching any of the supplied strings will be returned. An empty array will select only shifts that match none of absent, arrive_late, or leave_early.

workgroup_or_covering

If true, select shifts where the workgroup OR covering_member filter applies. Otherwise, select shifts for which both filters (if specified) apply.

custom_dropdown_1,2,3,...

If specified, only shifts with the given custom dropdown identifiers will be selected. May be a single identifier or an array of identifiers.

custom_dropdown_4

If specified, only shifts with the given custom_dropdown_4 identifiers will be selected. May be a single identifier or an array of identifiers.

custom_dropdown_5

If specified, only shifts with the given custom_dropdown_5 identifiers will be selected. May be a single identifier or an array of identifiers.

custom_dropdown_6

If specified, only shifts with the given custom_dropdown_6 identifiers will be selected. May be a single identifier or an array of identifiers.

custom_dropdown_7

If specified, only shifts with the given custom_dropdown_7 identifiers will be selected. May be a single identifier or an array of identifiers.

custom_dropdown_8

If specified, only shifts with the given custom_dropdown_8 identifiers will be selected. May be a single identifier or an array of identifiers.

custom_dropdown_9

If specified, only shifts with the given custom_dropdown_9 identifiers will be selected. May be a single identifier or an array of identifiers.

custom_dropdown_10

If specified, only shifts with the given custom_dropdown_10 identifiers will be selected. May be a single identifier or an array of identifiers.

custom_dropdown_11

If specified, only shifts with the given custom_dropdown_11 identifiers will be selected. May be a single identifier or an array of identifiers.

custom_dropdown_12

If specified, only shifts with the given custom_dropdown_12 identifiers will be selected. May be a single identifier or an array of identifiers.

custom_dropdown_13

If specified, only shifts with the given custom_dropdown_13 identifiers will be selected. May be a single identifier or an array of identifiers.

custom_dropdown_14

If specified, only shifts with the given custom_dropdown_14 identifiers will be selected. May be a single identifier or an array of identifiers.

custom_dropdown_15

If specified, only shifts with the given custom_dropdown_15 identifiers will be selected. May be a single identifier or an array of identifiers.

coverage_type

One of or an array of the following (if an array, any shifts that meet at least one of the criteria are selected):

mine

Select only shifts published and assigned to the current user.

confirmed

Select only shifts published and assigned to someone other than the current user.

available

Select only shifts published and not assigned.

room_floor

If specified, only shifts with the given room_floor (case insensitive) will be selected. May be a single value or an array of values.

custom_text_1,2,3,...

If specified, only shifts with the given custom text value (case insensitive) will be selected. May be a single value or an array of values. Ignored unless the user is a site administrator or, if the custom text field is readable by managers, you have specified a scope of report or managed_workgroups (see scope above) and the user is a manager.

start_time_from, start_time_through

Times in RFC 3339 partial-time format (e.g. "12:34:00"). Must be an even minute. If specified, only shifts with a start_time in the given range will be selected. If start_time_from is greater than start_time_through, shifts with a start_time on or after start_time_from OR on or before start_time_through will be selected.

end_time_from, end_time_through

Times in RFC 3339 partial-time format (e.g. "12:34:00"). Must be an even minute. If specified, only shifts with a end_time in the given range will be selected. If end_time_from is greater than end_time_through, shifts with a end_time on or after end_time_from OR on or before end_time_through will be selected.

display_start_time_from, display_start_time_through

Like start_time_from and start_time_through, except that it will filter using the display time.

display_end_time_from, display_end_time_through

Like end_time_from and end_time_through, except that it will filter using the display time.

org_hold

True if only assigned shifts with an assignee in hold status should be returned. False if only assigned shifts with an assignee not in hold status should be returned.

org_pending

Return assigned shifts where the assignee has this onboarding status.

The response results shifts attribute will be an array of the current page of selected shifts. Each element of the array will be an shift object containing basic or basic and extended shift fields.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the shifts results, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

client

id and name attributes are provided.

department

id and name attributes are provided.

location

id and name attributes are provided.

role

id and name attributes are provided.

timezone

name and iana_timezone attributes are provided.

workStatusType

id and name attributes are provided.

workgroup

id and name attributes are provided.

acknowledge_decline_reason

id and label attributes are provided.

custom_multipick

id and name attributes are provided.

custom_dropdown_1

id and name attributes are provided.

custom_dropdown_2

id and name attributes are provided.

custom_dropdown_3

id and name attributes are provided.

custom_dropdown_4

id and name attributes are provided.

custom_dropdown_5

id and name attributes are provided.

custom_dropdown_6

id and name attributes are provided.

custom_dropdown_7

id and name attributes are provided.

custom_dropdown_8

id and name attributes are provided.

custom_dropdown_9

id and name attributes are provided.

custom_dropdown_10

id and name attributes are provided.

custom_dropdown_11

id and name attributes are provided.

custom_dropdown_12

id and name attributes are provided.

custom_dropdown_13

id and name attributes are provided.

custom_dropdown_14

id and name attributes are provided.

custom_dropdown_15

id and name attributes are provided.

resource

id, name, and label attributes are provided.

shift.listUpdated

Request example:

{
   "select" : {
      "updated_since" : 1284656001
   }
}

Response example:

{
   "seconds" : "0.056182",
   "jsonrpc" : "2.0",
   "id" : "36",
   "result" : {
      "shifts" : [
         {
            "count" : "1",
            "timezone" : "Pacific Time (US/Can) (GMT-08:00)",
            "subject" : "updated",
            "qty" : "1",
            "published" : false,
            "workgroup" : "226082",
            "covered" : false,
            "start_date" : "2010-09-17T12:00:00",
            "id" : "2753500"
         }
      ],
      "count" : "1",
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      }
   }
}

Returns information about coverage shifts created or updated since a given date. Uses pagination. Uses select criteria.

Optional parameters:

extended

Boolean; if specified and true, the results returned will include an extended set of attributes; otherwise a basic set of attributes will be returned for each shift.

select

An object specifying selection criteria for this request. Note that updated_since will have a default value if not specified. The available criteria include all shift.list selection criteria with the addition of:

updated_since

A system.timestamp previously returned by the system.timestamp method. Only shifts updated since this date will be selected. Defaults to 24 hours ago. If more than 30 days ago, only shifts updated in the last 30 days will be selected.

status_update

If specified and true, report only shifts whose status has been updated. Confirm, unconfirm, assign, reassign, publish, and unpublish actions are considered status changes. Otherwise, report only shifts whose other data has been updated.

The response results shifts attribute will be an array of the current page of selected shifts. Each element of the array will be a shift object.

shift.markAbsent

Request example:

{
   "id" : 2753499,
   "absent_reason" : 2,
   "duplicate" : true
}

Response example:

{
    "seconds": 0.205401,
    "jsonrpc": "2.0",
    "id": "1",
    "result": {
      "new_id": 2753500
    }
}

Marks a shift as absent.

Parameters:

id

Required. id of the shift for which to return information.

absent_reason

Optional. ID of the reason for the absence.

duplicate

Optional. Boolean for whether to duplicate the shift when marking absent.

The response results will be an empty object on success, unless duplicate is true, in which case the new shift ID will be returned.

shift.notification

Returns notification information about a coverage shift. This method is experimental and subject to change without notice.

Parameters:

id

Required. id of the shift for which to return information.

The response results shift attribute will be an object with selected attributes of the shift object.

The response results accounts attribute will be an array of objects with selected attributes of accounts that should be notified.

shift.signup

Signs up a member to a shift's signup list.

Parameters:

id

Required. id of the shift for which to sign up.

member

id of the account to sign up (defaults to the current user)

NOTE: If you are calling this method with the member parameter, external_member will be ignored (if included).

external_member

external id of the account to sign up (defaults to the current user)

NOTE: If you are calling this method with the external_member parameter, member will be ignored (if included).

message

optional message

Response: On success, empty results will be returned.

shift.signupList

Returns information about signups for a coverage shift.

Parameters:

id

Required. id of the shift for which to return information.

referenced_objects

Boolean, defaults to true. Indicates that the results should include a referenced_objects attribute giving information about objects referred to in the returned signups.

Upon success, the returned object will have the following attributes:

already_signed_up

Boolean. The user is already signed up for this signup list.

can_manage_list

Boolean. The user can add/remove/process/message signup list members.

can_remove_signup

Boolean. The user can remove their signup for this signup list.

can_signup

Boolean. The user can sign up for this signup list.

signups

An array of signups the user is authorized to see for the selected shift. Each signup object will have the following attributes:

member

account identifier

message

optional message provided at time of signup

processed

Boolean.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the shift results, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

shift.summary

Request example:

{
   "aggregate" : "start_date",
   "exists" : {
      "critical" : {
         "published" : true,
         "covered" : false,
         "urgent" : true
      },
      "unpublished" : {
         "published" : false
      },
      "confirmed" : {
         "published" : true,
         "covered" : true,
         "exclude_covering_member" : 123
      },
      "mine" : {
         "published" : true,
         "covered" : true,
         "covering_member" : 123
      },
      "available" : {
         "published" : true,
         "covered" : false,
         "urgent" : false
      }
   },
   "select" : {
      "workgroup" : [
         123456,
         234567
      ],
      "end_date" : "2015-06-30",
      "start_date" : "2015-06-01"
   }
}

Response example:

{
   "seconds" : "0.362897",
   "jsonrpc" : "2.0",
   "id" : "25",
   "result" : {
      "referenced_objects" : {},
      "summary" : [
         {
            "critical" : false,
            "unpublished" : false,
            "confirmed" : false,
            "start_date" : "2015-06-03",
            "mine" : true,
            "available" : false
         },
         {
            "critical" : true,
            "unpublished" : false,
            "confirmed" : false,
            "start_date" : "2015-06-08",
            "mine" : true,
            "available" : true
         },
         {
            "critical" : false,
            "unpublished" : true,
            "confirmed" : false,
            "start_date" : "2015-06-12",
            "mine" : false,
            "available" : true
         }
      ]
   }
}

This method is experimental and subject to change.

Returns summary information about selected shifts.

Parameters:

select

Selection criteria. For defaults and allowed criteria, refer to shift.list.

aggregate

Shift attribute name or array of names by which to summarize; defaults to start_date. Currently supported values: start_date.

auto_aggregate

Boolean; options, if specified and true, the returned result will be grouped by Start Date and either Workgroup or Subject depending on the Application setting for Schedules/Calenders "Display by Subject(Not Workgroup)". If setting is Yes, result is grouped by Start Date and Subject, if set to No, the result is grouped by Start Date and Workgroup.

Difference between aggreate for Workgroup and Subject. When the Application setting for Schedules/Calenders "Display by Subject(Not Workgroup)" is No, the aggregate is for a Start Date and Workgroup, the Label contain the Workgroup Name, and there is also a field to indicate the id for the workgroup, called "workgroup". When the Application setting is Yes, the aggregate is for Start Date and Subject, the Label will be the Subject or the special value "Misc." This special value is used when the subject is missing. Also, there is an extra field called "label_orig", this contains the real subject, this means, the true value for Subject and it is be the empty string.

See the example

Request example: ```JSON { "auto_aggregate": true, "exists": { "available": { "covered": false, "published": true }, "confirmed": { "acknowledged": true, "covered": true, "published": true }, "unacknowledged": { "acknowledged": false, "covered": true, "published": true }, "unpublished": { "published": false }, "unpublished_available": { "covered": false, "published": false }, "unpublished_confirmed": { "covered": true, "published": false } }, "include_count": true, "select": { "display_end_date": "2020-04-03", "display_start_date": "2020-02-29" } }

> Response example:

```JSON
{
  "referenced_objects": {},
  "summary": [
    {
      "key": "2020-03-01",
      "value": [
        {
          "available": 0,
          "confirmed": 0,
          "date": "2020-03-01",
          "label": "CMT",
          "unacknowledged": 1,
          "unpublished": 0,
          "unpublished_available": 0,
          "unpublished_confirmed": 0,
          "workgroup": "2834160"
        }
      ]
    },
    {
      "key": "2020-03-17",
      "value": [
        {
          "available": 2,
          "confirmed": 1,
          "date": "2020-03-17",
          "label": "CNA",
          "unacknowledged": 1,
          "unpublished": 3,
          "unpublished_available": 1,
          "unpublished_confirmed": 2,
          "workgroup": "2834161"
        },
        {
          "available": 0,
          "confirmed": 1,
          "date": "2020-03-17",
          "label": "Home Health Aides",
          "unacknowledged": 0,
          "unpublished": 1,
          "unpublished_available": 1,
          "unpublished_confirmed": 0,
          "workgroup": "2834157"
        },
        {
          "available": 0,
          "confirmed": 1,
          "date": "2020-03-17",
          "label": "RN",
          "unacknowledged": 0,
          "unpublished": 0,
          "unpublished_available": 0,
          "unpublished_confirmed": 0,
          "workgroup": "2834158"
        }
      ]
    },
    {
      "key": "2020-03-26",
      "value": [
        {
          "available": 1,
          "confirmed": 0,
          "date": "2020-03-26",
          "label": "CMT",
          "unacknowledged": 0,
          "unpublished": 1,
          "unpublished_available": 1,
          "unpublished_confirmed": 0,
          "workgroup": "2834160"
        },
        {
          "available": 0,
          "confirmed": 0,
          "date": "2020-03-26",
          "label": "Home Health Aides",
          "unacknowledged": 1,
          "unpublished": 1,
          "unpublished_available": 1,
          "unpublished_confirmed": 0,
          "workgroup": "2834157"
        }
      ]
    }
  ]
}

exists

Object with arbitrarily named attributes with selection criteria objects as values.

shared

Boolean; if specified and true, the results returned will also include shifts that are covered and published from workgroups that are shared to the account.

include_count

Boolean; if specified and true, the results returned will also include the totals for each attribute returned.

referenced_objects

Boolean, defaults to true. For future use. Indicates that, in addition to the summary attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned summary data.

The response results summary attribute will provide an array containing an element for each distinct set of values found of the specified aggregate attributes. Each element will be an object with an attribute for each of the specified aggregate attributes giving the value found, and additional attributes for each named set of additional criteria specified in exists giving a Boolean value to indicate whether shifts with those additional criteria were found with the given aggregate attribute values.

shift.unconfirm

Request example:

{
   "id" : 2753501
}

Response example:

{
   "seconds" : "0.123864",
   "jsonrpc" : "2.0",
   "id" : "46",
   "result" : {}
}

Confirms a shift.

Required parameter: id.

Response: On success, empty results will be returned. Note that if the shift had a quantity, the particular shift that was unconfirmed may have been merged with other unconfirmed shifts and deleted.

shift.update

This method is for changing details about a shift. When assigning a shift no conflict checking of that assignment will be done unless explicitly enabled via the assignability_checks and conflicts_ok parameters. Furthermore, by default the assignment will not be acknowledged nor published. To acknowledge the assignment see the shift.acknowledge or shift.assign methods. To publish a shift, set the published parameter to true.

Request example:

{
   "count" : 1,
   "timezone" : "Greenwich Mean Time : Dublin, Lisbon, London (GMT)",
   "subject" : "updated",
   "qty" : 1,
   "published" : true,
   "workgroup" : "226084",
   "end_date" : "2010-09-17T14:30:00",
   "covered" : true,
   "start_date" : "2010-09-17T14:00:00",
   "id" : 2753501
}

Response example:

{
   "seconds" : "0.178901",
   "jsonrpc" : "2.0",
   "id" : "43",
   "result" : {}
}

Updates a shift object.

Required parameter

id. Most other shift object attributes may be specified.

Optional Parameters

notify Boolean; notify covering member upon update, or notify the workgroup on publishing an uncovered shift.

The count of a shift is the number of positions available for that specific shift, whereas the qty is the total positions for all related shifts. Counts may not be directly modified: to increase or decrease available counts, modify the qty field, which will update the qty for all related shifts, increasing or decreasing the count only for the related uncovered shift. Therefore, qty cannot be decreased below the total count for all related covered shifts. If qty is set to the total count for all related covered shifts, the uncovered shift, now with count 0, is deleted.

If covering_member is specified as an array, single positions of the shift will be assigned to the indicated members.

To set absent_reason, no_credit must also be set to true (even if already true).

To set arrive_late_reason or leave_early_reason, arrive_late_datetime and leave_early_datetime must also be set.

Setting arrive_late_reason or leave_early_reason will un-set absent_reason / no_credit; similarly, setting the latter will un-set the former. arrive_late_reason and leave_early_reason can be set together, but if either is set in the same update call as absent_reason / no_credit, the system will return an error.

Assignability parameters

To use assignability checks, the assignability_checks parameter must be true; then, the following options may be available, based on enabled features:

is_available - boolean

by_seniority - boolean

seniority_required - boolean

single_shift_per_day - boolean

conflicts_ok - boolean

daily_overtime_ok - boolean

weekly_overtime_ok - boolean

timeoff_ok - boolean

consecutive_days - boolean

short_turnaround - boolean

ignore_attestation_types - boolean

attestation_type - array of attestationTypeId

ignore_role - boolean

Response

On success, if the shift was updated, empty results will be returned. If the shift had a count > 1 and the update was only applied to a portion of the count, a new shift object will have been created and the id of the new shift will be returned. If qty is modified on a covered shift, the id of the modified uncovered shift will be returned.

shift.whosOn

Request example:

{}

Response example:

{
    "count": "1",
    "page": {
        "this": {
            "batch": 10,
            "start": 1
        }
    },
    "referenced_objects": {
        "account": [
            {
                "first_name": "First",
                "id": "1",
                "last_name": "Last",
                "screen_name": "First Last",
                "seniority_order": "12014-09-12 08:57:52"
            }
        ],
        "location": [
            {
                "id": "1234",
                "name": "API Test Site"
            }
        ],
        "timezone": [
            {
                "name": "Pacific Time (US/Can) (GMT-08:00)",
                "iana_timezone": "America/Los_Angeles"
            }
        ],
        "workgroup": [
            {
                "id": "11111",
                "name": "CNA"
            }
        ]
    },
    "shifts": [
        {
            "client": null,
            "count": "1",
            "covered": true,
            "covering_member": "9",
            "department": null,
            "display_time": "Anytime",
            "id": "123456",
            "location": "1234",
            "name": "",
            "published": true,
            "qty": "1",
            "role": null,
            "start_date": "2019-01-01",
            "subject": "",
            "timezone": "Pacific Time (US/Can) (GMT-08:00)",
            "urgent": false,
            "use_time": "5",
            "workgroup": "11111"
        }
    ]
}

Returns information about coverage shifts currently underway. Uses #pagination.

Optional parameters

extended

Boolean; if specified and true, the results returned will include an extended set of attributes; otherwise a basic set of attributes will be returned for each shift.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the shifts attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned shifts.

image

Boolean; if specified and true, the results returned will include an image_url attribute giving a url to the shift's covering_member's user image or null if no image is available.

image_expiration

Specifies the valid lifetime of the returned URL in seconds; default 300, maximum 604800 (1 week).

timeclock_status

Boolean; if specified and true, the results returned will include a clocked_in attribute indicating that the shift's covering_member is currently clocked in (though not necessarily for this shift) and a can_clock_in_out attribute indicating whether there is authorization to clock that covering member in or out.

The response results "shifts" attribute will be an array of the current page of shifts. Each element of the array will be an shift object containing basic or basic and extended shift fields and a "display_time" attribute giving a string presentation of when the shift is scheduled.

If requested, the response results "referenced_objects" attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the "shifts" results, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

client

id and name attributes are provided.

department

id and name attributes are provided.

location

id and name attributes are provided.

role

id and name attributes are provided.

timezone

name and iana_timezone attributes are provided.

workStatusType

id and name attributes are provided.

workgroup

id and name attributes are provided.

select

An object specifying selection criteria for this request

not_clocked_in

Boolean, if specified and true, the result will be filter to only return workers who has not clocked.

system object

system.echo

Request example:

{
   "false" : false,
   "true" : true,
   "null" : null
}

Response example:

{
   "seconds" : "0.040819",
   "jsonrpc" : "2.0",
   "id" : "3",
   "result" : {
      "false" : false,
      "true" : true,
      "null" : null
   }
}

For use in client testing only. Returns the object passed as params as its result.

system.endBatch

Request example:

{}

Response example:

{
   "seconds" : "0.273929",
   "jsonrpc" : "2.0",
   "id" : "41",
   "result" : {}
}

Ends a batch of requests.

See Performance Batching for more details.

system.getUserKeys

Requests api keys and secrets for user accounts in sites controlled by the calling api user. Reserved for use by certain api users.

Request example

{
  "external_id": "12345678"
}

Response example

{
  "seconds": "0.055196",
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "sites": [
      {
        "org_id": "132994",
        "site_id": "1349",
        "business_unit": "West Texas",
        "site_name": "SB Test 1",
        "access_key": "5a177d26-2e8b-11e9-ba0c-5fa51e230eef",
        "secret_key": "1DzCrI0+Iu2oZ0m5d3W9kAFKOT9w+hvS6p0srnn/"
      }
    ]
  }
}

Finds accounts not in onboarding or on hold with a given external_id in those sites the calling api user controls and returns api keys to access those sites as that account and site information.

Required parameters:

external_id

The response results sites attribute will be an array of objects with org_id, site_id, business_unit, site_name, access_key, and secret_key attributes.

If no account is found, the sites array will be empty.

system.timestamp

Request example:

{}

Response example:

{
   "seconds" : "0.039812",
   "jsonrpc" : "2.0",
   "id" : "2",
   "result" : {
      "localtime" : "2014-09-17T14:08:28-0700",
      "timezone" : "America/Los_Angeles",
      "timestamp" : 1410988108,
      "24_hour_clock" : true
   }
}

Returns the current time. The timestamp attribute is epoch seconds, for later use as the updated_since select criterion by some methods. The localtime attribute is the RFC 3339 date-time for the current time in the organization's timezone. The "24_hour_clock" attribute is true if the organization is configured to display time in a 24-hour format. The timezone attribute is the organization's selected time zone.

system.whoami

Returns account, the account id for the registered API user.

Request example:

{}

Response example:

{
   "seconds" : "0.04893",
   "jsonrpc" : "2.0",
   "id" : "1",
   "result" : {
      "account" : "2"
   }
}

NOTE: external_account, the external account id for the registered API user will be included if external ids are enabled for the site.

teamCategory object

teamCategory objects have the following attributes:

id

A unique identifier for this category.

category

The numeric identifier for the workgroup category to which this team category belongs.

label

The label for this team category.

teamCategory.list

Request example:

{}

Response example:

{
   "seconds" : "0.051276",
   "jsonrpc" : "2.0",
   "id" : "21",
   "result" : [
      {
         "label" : "Sales",
         "category" : 1,
         "id" : 2743
      }
   ]
}

Lists all current team categories.

teamCategory.create

Request example:

{
   "label" : "Sales",
   "category" : 1
}

Response example:

{
   "seconds" : "0.051276",
   "jsonrpc" : "2.0",
   "id" : "21",
   "result" : {
      "label" : "Sales",
      "category" : 1,
      "id" : 2351
   }
}

Creates a new team category.

Only five (5) team categories are allowed.

Required parameters:

category

The numeric identifier for the category.

label

The label for this category.

Response: On success, the created teamCategory will be returned.

teamCategory.update

Request example:

{
   "label" : "Corporate Relations",
   "id" : 2334
}

Response example:

{
   "seconds" : "0.051276",
   "jsonrpc" : "2.0",
   "id" : "21",
   "result" : {
      "label" : "Corporate Relations",
      "category" : 3,
      "id" : 2334
   }
}

Updates the label on a team category.

Required parameters:

id

The unique identifier for the category.

label

The new label for this category.

Response: On success, the updated teamCategory will be returned

teamCategory.delete

Request example:

{
   "id" : 2313
}

Response example:

{
   "seconds" : "0.051276",
   "jsonrpc" : "2.0",
   "id" : "21",
   "result" : {}
}

Deletes a team category.

Required parameters:

id

The unique identifier for the category.

Response: On success, an empty results will be returned

teamCategoryItem object

teamCategoryItem objects have the following attributes:

id

A unique identifier for this category item.

category

The numeric identifier for the category of this item.

name

The name for this category item.

teamCategoryItem.list

Request example:

{
   "select" : {
      "category" : 3
   }
}

Response example:

{
   "seconds" : "0.051276",
   "jsonrpc" : "2.0",
   "id" : "21",
   "result" : {
      "count" : 2,
      "page" : {
         "this" : {
            "batch" : 10,
            "start" : 1
         }
      },
      "items" : [
         {
            "name" : "Inside Sales",
            "category" : 3,
            "id" : 2329
         },
         {
            "name" : "Outside Sales",
            "category" : 3,
            "id" : 2327
         }
      ]
   }
}

Lists all items associated with a team category. Uses pagination.

Optional parameters: select object with a category or label attribute identifying a single numerical category of items to be returned and a deleted Boolean attribute to indicate deleted teamCategoryItems should be returned. E.g. {"select":{"category":3}}

teamCategoryItem.add

Request example:

{
   "name" : "Inside Sales",
   "category" : 1
}

Response example:

{
   "seconds" : "0.051276",
   "jsonrpc" : "2.0",
   "id" : "21",
   "result" : {
      "name" : "Inside Sales",
      "category" : 1,
      "id" : 2335
   }
}

Creates a new item under a team category.

Required parameters:

id

A unique identifier for this category item.

name

The name for this category item.

Response: On success, the created teamCategoryItem will be returned.

teamCategoryItem.undelete

Request example:

{
   "id" : 2334
}

Response example:

{
   "seconds" : "0.051276",
   "jsonrpc" : "2.0",
   "id" : "21",
   "result" : {}
}

Undeletes a deleted team category item.

Required parameters:

id

A unique identifier for this category item.

Response: On success, empty results will be returned

teamCategoryItem.update

Request example:

{
   "name" : "SE Regional",
   "id" : 2334
}

Response example:

{
   "seconds" : "0.051276",
   "jsonrpc" : "2.0",
   "id" : "21",
   "result" : {
      "name" : "SE Regional",
      "category" : 2,
      "id" : 2334
   }
}

Updates the name of an item within a team category.

Required parameters:

id

A unique identifier for this category item.

name

The name for this category item.

Response: On success, the updated teamCategoryItem will be returned

teamCategoryItem.delete

Request example:

{
   "id" : 2432
}

Response example:

{
   "seconds" : "0.051276",
   "jsonrpc" : "2.0",
   "id" : "21",
   "result" : {}
}

Deletes an item within a team category.

Required parameters:

id

The unique identifier for the category item.

Response: On success, an empty results will be returned

timeOffRequest object

timeOffRequest: basic attributes

id

A unique identifier for this timeOffRequest.

start_date

The date or date and time on which this timeOffRequest begins. For an all-day timeOffRequest, this is date in RFC 3339 full date format (e.g. "2009-04-01"). Otherwise, this is a datetime (e.g. "2009-04-01T13:00:00").

end_date

The date and time on which this timeOffRequest ends, (e.g. "2009-04-01T17:00:00"). Not specified for all-day or open-ended timeOffRequests.

use_time

Time off request type

timezone

workgroup

The timeOffRequest's workgroup or null if no workgroup

member

The account for which this is a request

external_member

The external account identifier for which this is a request

summary

Summary information about this request

status

paid

Boolean; indicates whether this time off is paid or unpaid

category

Category for this time off request, or null if the request has no category.

timeOffRequest: extended attributes

details

Additional details for this request

admin_notes

(site administrators only)

status_reason

Reason for approval or denial of request

last_status_update

Datetime of last status update for this request

status_update_by

account that last updated this request's status

timeOffRequest.approve

Approves a time off request.

Required parameter:

id

Time off request identifier or array of time off request identifiers.

Optional parameter:

status_reason

If not specified, status_reason will remain unchanged.

unconfirm

Boolean. In case of conflicts the conflicted shifts will be unconfirmed.

unpublish

Boolean. In case of conflicts the conflicted shifts will be unpublished.

Response: On success, empty results will be returned if neither unconfirmed/unpublished has been specified.

If a conflict was found and if either unconfirmed/unpublished was specified, the result set will have one field "conflicts" containing an array of conflict descriptions. Each element describes one conflict in terms of start date for the shift, the team name and a text with details for the conflict.

timeoffid

The id for the timeoff request that caused a conflict

person

The display name for the person of the timeoff request. This is also the person that was assigned to the shift. The shift might no longer be assigned.

shiftid

The id of the conflicting shift

end_date

The end date of the conflicting shift

end_time

The end time of the conflicting shift

start_date

The start date of the conflicting shift

start_time

The start time of the conflicting shift

team

The team name of the conflicting shift. Be aware that the team name might not match the team of specified in the time off. This could be the case for instance if the time off request was specified without a team and that the user requesting the information has privilege to the team that the conflicting shift belongs to.

text

A description of what caused the conflict. This is normally how many hours that are overlapping.

{
  "success": true,
  "data": {
    "conflicts": [
      {
        "end_date": "2019-03-04",
        "end_time": "14:25:00",
        "person": "Sally Swanson",
        "shiftid": "249930061",
        "start_date": "2019-03-04",
        "start_time": "06:45:00",
        "team": "Home Health Aides",
        "text": "Conflicts by 7 hrs 40 mins",
        "timeoffid": "744530"
      }
    ]
  }
}

timeOffRequest.create

Creates a new timeOffRequest record.

Parameters: Any attributes of a timeOffRequest object except "id", "last_status_update", or "status_update_by" may be specified. Minimally, "start_date" and "member/external_member" must be specified. "timezone" defaults to the organization's timezone. "status" defaults to "0" (New). "paid" defaults to false. Start and end dates may only fall on even five minute times.

Response: On success, an id attribute will provide the identifier for the new timeOffRequest.

timeOffRequest.delete

Deletes a timeOffRequest record.

Required parameter: id.

Response: On success, empty results will be returned.

timeOffRequest.deny

Denies a time off request.

id

Time off request identifier or array of time off request identifiers.

Optional parameter: status_reason. If not specified, status_reason will remain unchanged.

Response: On success, empty results will be returned.

timeOffRequest.get

Returns information about a timeOffRequest.

Parameters:

id

Required. id of the timeOffRequest for which to return information.

extended

Boolean; if specified and false, the results returned will be a basic set of attributes; otherwise an extended set of attributes will be returned for each timeOffRequest.

user_actions

Boolean; if specified and true, a user_actions object will be returned with attributes indicating what actions (e.g. delete, update) may be presented to the user.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the timeOffRequest attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned time off request.

display_time

Boolean; if specified and true, the results returned will include a display_time attribute giving a string presentation of what time range the time off is requested.

The response results "timeOffRequest" attribute will be the selected timeOffRequest object.

If user_actions were requested, a user_actions attribute will also be returned.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the "timeOffRequest" results, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

NOTE: external_id will also be returned in the results if external ids are enabled for the site.

id, first_name, last_name, and screen_name attributes are provided.

timezone

name and iana_timezone attributes are provided.

workgroup

id and name attributes are provided.

timeOffRequest.list

Returns information about timeOffRequests. Uses pagination. Uses select criteria.

Optional parameters:

extended

Boolean; if specified and true, the results returned will include an extended set of attributes; otherwise a basic set of attributes will be returned for each timeOffRequest.

user_actions

Boolean; if specified and true, a user_actions object will be returned for each timeOffRequest with attributes indicating what actions (e.g. delete, update, approve) may be presented to the user.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the timeOffRequests attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned time off request.

display_time

Boolean; if specified and true, the results returned will include a display_time attribute giving a string presentation of what time range the time off is requested.

select

An object specifying selection criteria for this request. Note that start_date and end_date will have default values if not specified. The available criteria include:

start_date

The earliest date of coverage to select, in RFC 3339 full date format (e.g. "2009-04-01"). Defaults to today.

end_date

The latest date of coverage to select, in RFC 3339 full date format. Defaults to 7 days after the start_date.

profile_type

If specified, requests only timeOffRequests for accounts having one of the specified profile_type(s). The specified value is the profile_type_id or array of profile_type_id(s) for the account requesting the timeoff.

status

If specified, requests only timeOffRequests with the status.

member

If specified, requests only timeOffRequests for the given account.

The response results "timeOffRequests" attribute will be an array of the current page of selected timeOffRequests. Each element of the array will be an timeOffRequest object containing basic or basic and extended timeOffRequest fields.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the "timeOffRequest" results, with only selected minimal attributes provided:

NOTE: If you are calling this method with the external_member parameter, member is not required.

external_member

If specified, requests only timeOffRequests for the given account.

NOTE: If you are calling this method with the member parameter, external_member is not required, and will be ignored.

account

id, first_name, last_name, and screen_name attributes are provided.

timezone

name and iana_timezone attributes are provided.

workgroup

id and name attributes are provided.

sort

If specified, the name of a preconfigured sort criteria. There are three valid values that can be used: creation_date, start_date and name.

creation_date sorts by creation_date in descending order so the most recent request are listed first. If a day contains multiple time off requests, the day is further sorted by start_time, end_date and end_time.

start_date sorts by start_date in descending order (most future day to past). If a day contain multiple time off requests then these are further sorted by start_time, then by end_date in descending order then end_time

name sorts by last_name then first_name. If a person has multiple time off request then these are further sorted by start_date in descenting order and then start_time

timeOffRequest.update

Updates a timeOffRequest object.

Required parameter: id. Any timeOffRequest object attributes other than last_status_update and status_update_by may be specified.

Response: On success, if the timeOffRequest was updated, empty results will be returned.

timecard object

timecard: basic attributes

id

A unique identifier for this timecard

workgroup

Workgroup identifier

account

Account identifier

external_account

External account identifier. Can be used in lieu of account if external identifiers are enabled for the site.

NOTE: If both account and external_account are included, the external_account value will be ignored.

shift

Shift identifier or null if there is no shift associated with this timecard object

approved

true if the timecard is approved

processed

true if the timecard is processed

start_date

Start date in RFC 3339 full-date format (e.g. "2009-04-01")

start_time

Start time in RFC 3339 partial-time format (e.g. "23:55:00") or null if no start time was provided

duration

Duration in HHH:MM:SS format (e.g. "1:05:00" or "120:00:00")

timecard: extended attributes

work_status_type

The workStatusType id for the timecard

location

The location id for the timecard, if specified

role

The role id for the timecard, if specified

client

The client id for the timecard, if specified

department

The department id for the timecard, if specified

mileage

Mileage for the timecard, if specified

expense_notes

Expense notes, if specified

notes

Notes, if specified

manager_notes

Manager notes, if specified

Not all fields will be exposed to all users.

Not all fields will be configured to be used for all organizations or set for all timecards.

timecard.approve

Request example:

{ "id": [123456, 654321], "approved": true }

Response example:

{"seconds":"0.052778","jsonrpc":"2.0","id":"48","result":{"approved":2}}

Approve one or more timecard records.

Parameters: id One or more timecards to approve approved Boolean; approve or un-approve one or more timecards

Response: On success, the number of "approved" or "unapproved" results are returned.

timecard.create

Creates a new timecard record.

Parameters: Any attributes of a timecard object (except id) may be specified.

Response: On success, an id attribute will provide the identifier for the new timecard.

timecard.delete

Request example:

{
   "id" : "226089"
}

Response example:

{
   "seconds" : "0.052778",
   "jsonrpc" : "2.0",
   "id" : "48",
   "result" : {}
}

Deletes a timecard record.

Required parameter: id.

Response: On success, empty results will be returned.

timecard.exportTRAXPayroll

Initiates a TRAXPayroll timecard export.

Parameters:

inline_content

If true, report data will be directly returned; if false, a one-time url for fetching the report data will be returned.

select

Selection criteria (optional):

start_date

Earliest timecard start date to select; defaults to 30 days ago. If overtime is enabled, the day of week must match the configured workweek start day.

end_date

Latest timecard start date to select; defaults to today. If overtime is enabled, the day of week must match the weekday before the configured workweek start day (i.e. the end of the workweek).

workgroup

Single workgroup identifier or array of workgroup identifiers to report

account

Single account identifier or array of account identifiers to report

NOTE: If you are calling this method with the account parameter, external_account is not required.

external_account

Single external account identifier or array of external account identifiers to report

NOTE: If you are calling this method with the account parameter, external_account is not required, and will be ignored.

approved

true to select only approved timecards, false to select only timecards not yet approved

processed

true to select only processed timecards, false to select only timecards not yet processed

client

department

role

work_status_type

location

use_workweek_start_time

Boolean; if specified and true, modifies the selection to be from the configured workweek start time on the specified start_date to the configured workweek start time on the day following the specified end_date; if weekly overtime is enabled and the configured workweek start time is not midnight, this must be specified as true.

Response: If inline_content is true, a content attribute will provide an array of the requested data; otherwise, a url attribute giving a link that may be used one time only, within 5 minutes of the API request, to generate the requested report.

timecard.get

Returns information about a timecard object.

Parameters:

id

Required. id of the timecard object for which to return information.

extended

Boolean; if specified and false, the results returned will be a basic set of attributes; otherwise an extended set of attributes will be returned for each timecard.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the timecard attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned timecard.

editable_fields

Boolean; if specified and true, the results returned will include a list of timecard fields that are editable by the caller (based on auth level).

The response results timecard attribute will be the selected timecard object.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the timecard results, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

NOTE: external_id will also be returned in the results if external ids are enabled for the site

client

id and name attributes are provided.

department

id and name attributes are provided.

location

id and name attributes are provided.

role

id and name attributes are provided.

workStatusType

id and name attributes are provided.

workgroup

id and name attributes are provided.

timecard.list

Returns information about timecard objects. Uses pagination. Uses select criteria.

Optional parameters:

extended

Boolean; if specified and true, the results returned will include an extended set of attributes; otherwise a basic set of attributes will be returned for each timecard object.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the timecards attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned timecard objects.

select

An object specifying selection criteria for this request. Note that start_date and end_date will have default values if not specified. The available criteria include:

start_date

Earliest timecard start date to select; defaults to 30 days ago

end_date

Latest timecard start date to select; defaults to today

workgroup

Single workgroup identifier or array of workgroup identifiers to report

account

Single account identifier or array of account identifiers to report

NOTE: If you are calling this method with the account parameter, external_account is not required, and will be ignored.

external_account

Single external account identifier or array of external account identifiers to report

NOTE: If you are calling this method with the account parameter, external_account is not required, and will be ignored.

approved

true to select only approved timecards, false to select only timecards not yet approved

processed

true to select only processed timecards, false to select only timecards not yet processed

client

department

role

work_status_type

location

The response results timecards attribute will be an array of the current page of selected timecard objects. Each element of the array will be an timecard object containing basic or basic and extended timecard fields.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the timecards results, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

client

id and name attributes are provided.

department

id and name attributes are provided.

location

id and name attributes are provided.

role

id and name attributes are provided.

workStatusType

id and name attributes are provided.

workgroup

id and name attributes are provided.

timecard.process

Request example:

{ "id": [123456, 654321], "processed": true }

Response example:

{"seconds":"0.052778","jsonrpc":"2.0","id":"48","result":{"processed":2}}

Process one or more timecard records.

Parameters: id One or more timecards to process process Boolean; process or un-process one or more timecards

Response: On success, the number of "approved" or "unapproved" results are returned.

timecard.report

Generates a pre-authorized link to download a timecard report.

Parameters:

report_type

One of: basic (default), extended, adherence

format

One of: csv (default), xls, xlsx

select

Selection criteria (optional):

start_date

Earliest timecard start date to select; defaults to 30 days ago.

end_date

Latest timecard start date to select; defaults to today.

workgroup

Single workgroup identifier or array of workgroup identifiers to report

account

Single account identifier or array of account identifiers to report

NOTE: If you are calling this method with the account parameter, external_account is not required, and will be ignored.

external_account

Single external account identifier or array of external account identifiers to report

NOTE: If you are calling this method with the account parameter, external_account is not required, and will be ignored.

approved

true to select only approved timecards, false to select only timecards not yet approved

processed

true to select only processed timecards, false to select only timecards not yet processed

client

department

role

work_status_type

location

Response: A url attribute giving a link that may be used one time only, within 5 minutes of the API request, to generate the requested report.

timecard.update

Updates a timecard object.

Required parameter: id. Any other timecard object attributes may be specified.

Response: On success, empty results will be returned.

timecard.customDropdownList

Request example:

{}

Response example:

{
    "custom_listable_1": {
        "1550": "Red",
        "1551": "Blue",
        "1552": "Green"
    },
    "custom_listable_2": {
        "1553": "Breakfast",
        "1554": "Lunch",
        "1555": "Dinner"
    },
    "custom_listable_4": {
        "1558": "Baseball",
        "1559": "Skiing",
        "1560": "Soccer",
        "1561": "Football"
    }
}

Returns information about timecard related custom dropdown list objects.

Required Parameter: none

Optional Parameters: none

Response: On success, an object will be returned containing all timecard custom drop down listables that have been created, and are enabled for the site.

timecard.shiftList

Request example:

{
   "member" : "1"
}

Response example:

{
   "seconds" : "2.811506",
   "jsonrpc" : "2.0",
   "id" : "21",
   "result" : {
                 "referenced_objects": {
                       "workgroup": {
                         "123456": "My Team"
                       }
                 },
                 "shifts": [
                    {
                        "agent": "12345",
                        "approved": "1",
                        "client": null,
                        "count": "1",
                        "covered": true,
                        "department": null,
                        "display_time": "7am - 11:10am",
                        "dur_hrs": "4",
                        "dur_mins": "10",
                        "end_date": "2018-02-06T11:10:00",
                        "id": "1234567890",
                        "name": "",
                        "qty": "1",
                        "role": "0",
                        "start_date": "2018-02-06T07:00:00",
                        "subject": "",
                        "timezone": "Pacific Time (US/Can) (GMT-08:00)",
                        "urgent": false,
                        "use_time": "2",
                        "venue": "0",
                        "workgroup": "123456"
                    }
                 ]
   }
}

Returns list of shifts (un)associated with timecards depending on timekeepr settings configured in Shiftboard

Required parameters:

member

Integer; The id of the member to query on.

The response results "shifts" attribute will be an array of the selected timecard objects that are (un)associated with shifts.

timeclock object

timeclock: basic attributes

id

A unique identifier for this timeclock object

workgroup

A workgroup identifier or null if not clocked in

account

Account identifier

external_account

External account identifier

clocked_in

Time that the user clocked in

clocked_out

Time that the user clocked out or null if not clocked out

shift

shift identifier or null if there is no shift associated with this timeclock object

timeclock: extended attributes

clocked_in_local

Time that the user clocked in, in the organization's timezone

clocked_out_local

Time that the user clocked out, in the organization's timezone, or null if not clocked out

timezone

The organization's timezone

clockin_notes

(if specified)

clockout_notes

(if specified)

clockin_ipaddr

(if specified)

clockout_ipaddr

(if specified)

clockin_phone

(if specified)

clockout_phone

(if specified)

clockin_location

clockout_location

Location of clockin/clockout, if known. An object with the following attributes:

latitude

longitude

time

accuracy

meters of 68% confidence of latitude/longitude

clockin_device_id

(if specified)

clockout_device_id

(if specified)

timeclock.clockIn

Request example:

{}

Response example:

{
   "seconds" : "2.903725",
   "jsonrpc" : "2.0",
   "id" : "37",
   "result" : {
      "id" : 62064
   }
}

Clocks in a given account.

Parameters:

account

optional, defaults to current user

NOTE: If you are calling this method with the account parameter, external_account is not required, and will be ignored.

external_account

optional, defaults to current user

NOTE: If you are calling this method with the account parameter, external_account is not required, and will be ignored.

workgroup

optional, defaults to clocking in to the organization

shift

the shift to associate with this clock in; optional or required depending on organization settings

clocked_in

optional, the time to record the user as having clocked in

phone

optional, phone number used to clock in (for IVR systems)

latitude

optional, latitude of clock in

longitude

optional, longitude of clock in

location_accuracy

optional, meters of 68% confidence of latitude/longitude

location_time

optional, time of latitude/longitude/accuracy fix.

note: location_time must be defined when including latitude, longitude, and/or location_accuracy, otherwise these parameters will be ignored.

device_id

optional, arbitrary string identifying timeclock device

ip_address

IP address that originated this clock in (defaults to address issuing this api request)

notes

optional, arbitrary text

Response: On success, returns id of the newly created timeclock object.

timeclock.clockOut

Request example:

{}

Response example:

{
   "seconds" : "2.944529",
   "jsonrpc" : "2.0",
   "id" : "43",
   "result" : {
      "timecard" : 111673
   }
}

Clocks out a given account and creates a timecard for the clock in.

Parameters:

account

optional, defaults to current user

NOTE: If you are calling this method with the account parameter, external_account is not required, and will be ignored.

external_account

optional, defaults to current user

NOTE: If you are calling this method with the account parameter, external_account is not required, and will be ignored.

workgroup

optional, defaults to the organization; must match the workgroup to which the account is clocked in

approve

boolean, default false; indicates whether the timecard object created for this clock in should be approved

clocked_out

optional, the time to record the user as having clocked out

latitude

optional, latitude of clock in

longitude

optional, longitude of clock in

location_accuracy

optional, meters of 68% confidence of latitude/longitude

location_time

optional, time of latitude/longitude/accuracy fix.

note: location_time must be defined when including latitude, longitude, and/or location_accuracy, otherwise these parameters will be ignored.

device_id

optional, arbitrary string identifying timeclock device

ip_address

IP address that originated this clock out (defaults to address issuing this api request)

notes

optional, arbitrary text

Response: On success, returns timecard, the id of the newly created timecard object.

timeclock.get

Returns information about a timeclock object.

Parameters:

id

Required. id of the timeclock object for which to return information.

extended

Boolean; if specified and false, the results returned will be a basic set of attributes; otherwise an extended set of attributes will be returned for each timeclock.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the timeclock attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned timeclock.

The response results timeclock attribute will be the selected timeclock object.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the timeclocks results, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

NOTE: external_id will also be returned in the results if external ids are enabled for the site

timezone

name and iana_timezone attributes are provided.

workgroup

id and name attributes are provided.

timeclock.list

Returns information about timeclock objects. Uses pagination. Uses select criteria.

Optional parameters:

extended

Boolean; if specified and true, the results returned will include an extended set of attributes; otherwise a basic set of attributes will be returned for each timeclock object.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the timeclocks attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned timeclock objects.

select

An object specifying selection criteria for this request. Note that start_date and end_date will have default values if not specified. The available criteria include:

start_date

Earliest clock in date to select

end_date

Latest clock in date to select

clocked_out

Boolean; true to include only already clocked out timeclock records, false to include only not yet clocked out timeclock records. Omit to include all records.

workgroup

Single workgroup identifier or array of workgroup identifiers to report

account

Single account identifier or array of account identifiers to report

NOTE: If you are calling this method with the account parameter, external_account is not required, and will be ignored.

external_account

Single external account identifier or array of external account identifiers to report

NOTE: If you are calling this method with the account parameter, external_account is not required, and will be ignored.

The response results timeclocks attribute will be an array of the current page of selected timeclock objects. Each element of the array will be an timeclock object containing basic or basic and extended timeclock fields.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the timeclocks results, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

timezone

name and iana_timezone attributes are provided.

workgroup

id and name attributes are provided.

timeclock.report

Request example:

{
   "format" : "xls",
   "report_type" : "total_hour",
   "select" : {
      "start_date" : "2012-10-01"
   }
}

Response example:

{
   "seconds" : "2.811506",
   "jsonrpc" : "2.0",
   "id" : "21",
   "result" : {
      "url" : "https://www.shiftboard.com/servola/fetch.cgi?ss=14;type=report;key=5085a260feff2760;signature=kRMtQqcLl0SULDYifhdg3OH4uIU;format=excel"
   }
}

Generates a pre-authorized link to download a timeclock report.

Parameters:

report_type

Required. One of: basic, extended, total_hour

format

One of: csv (default), xls, xlsx

select

Selection criteria (optional):

start_date

Earliest clock in date to report (or, for total_hour report, earliest date during which someone was clocked in)

end_date

Latest clock in date to report (or, for total_hour report, latest date during which someone was clocked in)

clocked_out

Boolean; true to include only already clocked out timeclock records, false to include only not yet clocked out timeclock records. Omit to include all records.

workgroup

Single workgroup identifier or array of workgroup identifiers to report

account

Single account identifier or array of account identifiers to report

NOTE: If you are calling this method with the account parameter, external_account is not required, and will be ignored.

external_account

Single external account identifier or array of external account identifiers to report

NOTE: If you are calling this method with the account parameter, external_account is not required, and will be ignored.

Response: A url attribute giving a link that may be used one time only, within 5 minutes of the API request, to generate the requested report.

timeclock.status

Request example:

{}

Response example:

{
   "seconds" : "2.811506",
   "jsonrpc" : "2.0",
   "id" : "21",
   "result" : {
      "workgroup" : null,
      "account" : "4826",
      "shift" : null,
      "clocked_in" : null,
      "clocked_out" : null
   }
}

Reports clocked in/out status of an account.

Parameters:

account

Optional, defaults to current user

NOTE: If you are calling this method with the account parameter, external_account is not required, and will be ignored.

external_account

Optional, defaults to current user

NOTE: If you are calling this method with the account parameter, external_account is not required, and will be ignored.

latitude

Optional, latitude of clock in. If specified, longitude and location_accuracy must also be specified.

longitude

Optional, longitude of clock in. If specified, latitude and location_accuracy must also be specified.

location_accuracy

Optional, meters of 68% confidence of latitude/longitude. If specified, latitude and longitude must also be specified.

Response: On success, returns basic timeclock attributes. If the account is clocked in, they will reflect that timeclock object; otherwise, timeclock attributes other than account will be null.

If not clocked in and shifts can be associated to timeclock entries, an additional boolean shift_required attribute will be present and indicate whether an associated shift is required and a shifts_available attribute will provide an array of possible shifts to associate (with those shifts most likely to be intended first), each element of the array providing the following attributes:

category

A string with the value current, next, or previous, indicating whether the shift is scheduled for now, in the future, or in the past.

shift

The shift identifier to specify when clocking in.

workgroup

The workgroup identifier to specify when clocking in.

description

A string describing when and for what team the shift is scheduled.

timezone

The timezone of the shift.

Additionally, if latitude/longitude/location_accuracy are specified, each element of the array will provide the following 3 attributes:

geofence_radius

The allowed geofence radius in meters, or null if there is no restriction.

distance_outside

The distance in meters of the user's location outside the allowed geofence, or 0 if the user is not outside.

geofence_timeclock_allowed

If the shift requires the member to be within the geofenced area, this boolean is false if the member is outside the area (that is, geofence_status is inaccurate, or outside).

geofence_status

A string describing the user's position with respect to the geofence. One of:

no_restriction

There is no geofence restriction for this shift.

unknown_location

There is no latitude/longitude known for this shift

inaccurate

The location provided is not accurate enough.

inside

The user is within the geofence.

inside_edge

The user's location is within the geofence, but the circle of accuracy extends outside it.

outside_edge

The user's location is outside the geofence, but the circle of accuracy extends inside it.

outside

The user is outside the geofence.

The shifts_available array entries will be sorted as follows:

• First sort by category: current, followed by next, then previous

• If current, sort by "most recently started," then "longest shift"

• If next, sort by "next to start," then "longest shift"

• If previous, sort by "most recently ended," then "longest shift"

The response will provide an additional org_level attribute, indicating the account's level in the organization (2, 3, or 4), as well as screen_name, first_name, and last_name account attributes.

timeclock.whosOn

Returns information about timeclock entries currently clocked in. Uses pagination.

Optional parameters:

extended

Boolean; if specified and true, the results returned will include an extended set of attributes; otherwise a basic set of attributes will be returned for each timeclock entry.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the timeclocks attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned timeclock entries.

image

Boolean; if specified and true, the results returned will include an image_url attribute giving a url to the timeclock's account's user image or null if no image is available.

image_expiration

Specifies the valid lifetime of the returned URL in seconds; default 300, maximum 604800 (1 week).

The response results "timeclocks" attribute will be an array of the current page of timeclock entries. Each element of the array will be a timeclock object containing basic or basic and extended timeclock fields. Additionally, a can_clockout boolean attribute will be returned indicating whether the api user is authorized to clock out this timeclock entry.

If requested, the response results "referenced_objects" attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the "timeclocks" results, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

timezone

name and iana_timezone attributes are provided.

timezone object

timezone objects have the following minimal attributes:

name

A unique displayable name used to identify this timezone. Currently, one of the following strings:

• "International Date Line West (GMT-12:00)"
• "Midway Island, Samoa (GMT-11:00)"
• "Hawaii (GMT-10:00)"
• "Alaska (GMT-09:00)"
• "Pacific Time (US/Can) (GMT-08:00)"
• "Arizona (GMT-07:00)"
• "Mountain Time (US/Can) (GMT-07:00)"
• "Chihuahua, La Paz, Mazatlan (GMT-07:00)"
• "Saskatchewan (GMT-06:00)"
• "Central Time (US/Can) (GMT-06:00)"
• "Guadalajara, Mexico City, Monterrey (GMT-06:00)"
• "Indiana (East) (GMT-05:00)"
• "Bogota, Lima, Quito (GMT-05:00)"
• "Eastern Time (US/Can) (GMT-05:00)"
• "Caracas, La Paz (GMT-04:30)"
• "Atlantic Time (Can) (GMT-04:00)"
• "Santiago (GMT-04:00)"
• "Newfoundland (GMT-03:30)"
• "Buenos Aires, Georgetown (GMT-03:00)"
• "Mid-Atlantic (GMT-02:00)"
• "Cape Verde Is. (GMT-01:00)"
• "Azores (GMT-01:00)"
• "Casablanca, Monrovia (GMT)"
• "Greenwich Mean Time : Dublin, Lisbon, London (GMT)"
• "Brussels, Copenhagen, Madrid, Paris (GMT+01:00)"
• "Belgrade, Bratislava, Budapest, Prague (GMT+01:00)"
• "Amsterdam, Berlin, Bern, Rome, Vienna (GMT+01:00)"
• "Sarajevo, Skopje, Warsaw, Zagreb (GMT+01:00)"
• "Harare, Pretoria (GMT+02:00)"
• "Cairo (GMT+02:00)"
• "Jerusalem (GMT+02:00)"
• "Athens, Beirut, Istanbul, Minsk (GMT+02:00)"
• "Bucharest (GMT+02:00)"
• "Helsinki, Kyiv, Riga, Sofia, Vilnius (GMT+02:00)"
• "Nairobi (GMT+03:00)"
• "Kuwait, Riyadh (GMT+03:00)"
• "Moscow, St. Petersburg, Volgograd (GMT+03:00)"
• "Baghdad (GMT+03:00)"
• "Tehran (GMT+03:30)"
• "Abu Dhabi, Muscat (GMT+04:00)"
• "Baku, Tbilisi, Yerevan (GMT+04:00)"
• "Kabul (GMT+04:30)"
• "Islamabad, Karachi, Tashkent (GMT+05:00)"
• "Chennai, Kolkata, Mumbai, New Delhi (GMT+05:30)"
• "Kathmandu (GMT+05:45)"
• "Astana, Dhaka (GMT+06:00)"
• "Almaty, Novosibirsk (GMT+06:00)"
• "Rangoon (GMT+06:30)"
• "Bangkok, Hanoi, Jakarta (GMT+07:00)"
• "Krasnoyarsk (GMT+07:00)"
• "Beijing, Chongqing, Hong Kong, Urumqi (GMT+08:00)"
• "Kuala Lumpur, Singapore (GMT+08:00)"
• "Taipei (GMT+08:00)"
• "Perth (GMT+08:00)"
• "Irkutsk, Ulaan Bataar (GMT+08:00)"
• "Seoul (GMT+09:00)"
• "Osaka, Sapporo, Tokyo (GMT+09:00)"
• "Yakutsk (GMT+09:00)"
• "Darwin (GMT+09:30)"
• "Adelaide (GMT+09:30)"
• "Brisbane (GMT+10:00)"
• "Guam, Port Moresby (GMT+10:00)"
• "Vladivostok (GMT+10:00)"
• "Hobart (GMT+10:00)"
• "Canberra, Melbourne, Sydney (GMT+10:00)"
• "Magadan, Solomon Is., New Caledonia (GMT+11:00)"
• "Fiji, Kamchatka, Marshall Is. (GMT+12:00)"
• "Auckland, Wellington (GMT+12:00)"
• "Nuku'alofa (GMT+13:00)"

iana_timezone

The IANA timezone name for this timezone (e.g. America/Los_Angeles).

timezone objects have the following additional basic attributes:

standard_offset

The offset from UTC when DST is not being observed (e.g. -08:00).

abbreviations

The standard abbreviation(s) for this timezone (e.g. PST/PDT).

timezone.get

Returns information about a timezone.

Parameters:

name

Required. The unique display name of the timezone for which to return information.

The response results timezone attribute will be the selected timezone object.

timezone.list

Returns information about timezones. Uses pagination.

Parameters: None

The response results timezones attribute will be an array of the current page of selected timezones. Each element of the array will be an timezone object containing basic timezone attributes.

tradeboard object

tradeboard: basic attributes

id

A unique identifier for this tradeboard.

shift

shift identifier for this trade.

traded_by

account identifier originally assigned this shift.

traded_to

account identifier that accepted this trade, or null if the trade is not completed.

trade_complete

Boolean.

status

Integer with one of the following values: - 1 - Pending - Trade is awaiting permission to be offered - 2 - Offered - Trade is offered - 3 - Unapproved - Trade is awaiting approval of completion - 4 - Complete - Trade is completed

tradeboard: extended attributes

notes

trade_completed

time at which this trade was completed.

tradeboard.accept

Request example:

{
   "id" : 2753501
}

Response example:

{
   "seconds" : "0.188065",
   "jsonrpc" : "2.0",
   "id" : "45",
   "result" : {}
}

Takes a shift offered on the tradeboard.

Required parameter: id.

Response: On success, empty results will be returned.

tradeboard.approve

This API call can be used in two situations.

The first situation is when an employee request permission to post a shift to be traded. In this case the API is called to approve or deny the shift to be traded to another employees.

The second situation is when a shift has been posted as a trade and an employee is requesting to cover the shift. In this cass the API is called to approve or deny the employee to cover the shift.

Parameters:

id

Required. id of the tradeboard posting for which to be approved or denied.

approval

Required. Boolean indicating if tradeboard is approved or denied to either be put up for trade (situation 1) or for being cover by another employee (situation 2)

notes

Optional. Text that is attached to notification. This can be used when a shift is submitted to be posted as a trade. The text will be attached to the request to trade. This parameter is only used when the shift is requested to be posted as a trade (situation 1).

no_notify

Optional. Boolean indicating if a notification is created when the trade is requested to be covered by another employee. If "true", a notification will be send out. If "false", no notification will be send out. This parameter is only used when the trade is approved/denied to be covered by another employee (situation 2 )

tradeboard.create

Request example:

{
   "shift" : 12345678
}

Response example:

{
   "seconds" : "0.207354",
   "jsonrpc" : "2.0",
   "id" : "59",
   "result" : {
      "id" : 92873
   }
}

Creates a new tradeboard posting.

Required Parameter:

shift

shift identifier for this trade.

Optional Parameters:

notes

Response: On success, an id attribute will provide the identifier for the new tradeboard posting.

tradeboard.delete

Request example:

{
   "id" : "2753"
}

Response example:

{
   "seconds" : "0.058344",
   "jsonrpc" : "2.0",
   "id" : "67",
   "result" : {}
}

Deletes a tradeboard posting.

Required parameter: id.

Response: On success, empty results will be returned.

tradeboard.get

Request example:

{
   "id" : "123456",
   "extended" : true
}

Response example:

{
   "seconds" : "0.128193",
   "jsonrpc" : "2.0",
   "id" : "15",
   "result" : {
      "referenced_objects" : {
         "workgroup" : [
            {
               "name" : "Help Desk",
               "id" : "412345"
            }
         ],
         "department" : [
            {
               "name" : "Distribution",
               "label" : "Distribution",
               "id" : "9942"
            }
         ],
         "timezone" : [
            {
               "name" : "Pacific Time (US/Can) (GMT-08:00)",
               "iana_timezone" : "America/Los_Angeles"
            }
         ],
         "location" : [
            {
               "name" : "Training / Meetings",
               "id" : "92580"
            }
         ],
         "shift" : [
            {
               "display_time" : "1pm to 2pm",
               "department" : "9942",
               "reference_id" : "",
               "linkurl" : "",
               "work_status_type" : "5",
               "start_date" : "2014-01-29T13:00:00",
               "signup_list" : false,
               "id" : "56789012",
               "count" : "1",
               "timezone" : "Pacific Time (US/Can) (GMT-08:00)",
               "display_date" : "January 29, 2014",
               "location" : "92580",
               "subject" : "",
               "covering_member" : "47",
               "urgent" : false,
               "zipcode" : "94132",
               "qty" : "1",
               "details" : "details!",
               "workgroup" : "412345",
               "published" : true,
               "no_credit" : false,
               "end_date" : "2014-01-29T14:00:00",
               "covered" : true,
               "no_pick_up" : false,
               "no_trade" : false,
               "room_floor" : "room/floor",
               "linktitle" : ""
            }
         ],
         "account" : [
            {
               "id" : "39",
               "screen_name" : null,
               "last_name" : "Foster",
               "first_name" : "Joanie"
            },
            {
               "seniority_order" : "19999-12-31 23:59:59",
               "id" : "47",
               "profile_type" : "3",
               "screen_name" : "Stan Wilson",
               "last_name" : "Wilson",
               "first_name" : "Stan"
            }
         ],
         "workStatusType" : [
            {
               "name" : "Salary/Exempt",
               "id" : "5"
            }
         ]
      },
      "tradeboard" : {
         "trade_completed" : "2014-01-21T20:40:38Z",
         "shift" : "56789012",
         "notes" : "Need to see the dentist; please take this trade",
         "id" : "123456",
         "traded_to" : "47",
         "traded_by" : "39",
         "trade_complete" : true
      }
   }
}

Returns information about a tradeboard posting.

Parameters:

id

Required. id of the tradeboard posting for which to return information.

extended

Boolean; if specified and true, the results returned will include an extended set of attributes; otherwise a basic set of attributes will be returned for each tradeboard posting.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the tradeboard attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned tradeboard posting.

The response results tradeboard attribute will be the selected tradeboard object.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the tradeboard results or in its associated shift, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

NOTE: external_id will also be returned in the results if external ids are enabled for the site.

client

id and name attributes are provided.

department

id and name attributes are provided.

location

id and name attributes are provided.

role

id and name attributes are provided.

shift

All basic shift attributes will be provided. If the extended parameter is true, extended shift attributes will also be provided. Additionally, display_date and display_time attributes contain formatted strings describing the shift's start and end time.

timezone

name and iana_timezone attributes are provided.

workStatusType

id and name attributes are provided.

workgroup

id and name attributes are provided.

tradeboard.list

Request example:

{
   "select" : {
      "end_date" : "2014-07-18",
      "start_date" : "2014-07-12"
   }
}

Response example:

{
   "seconds" : "0.087686",
   "jsonrpc" : "2.0",
   "id" : "3",
   "result" : {
      "referenced_objects" : {
         "workgroup" : [
            {
               "name" : "Floor Staff",
               "id" : "226093"
            }
         ],
         "account" : [
            {
               "id" : "20",
               "screen_name" : "Johnny Smith",
               "last_name" : "John",
               "first_name" : "Smith"
            }
         ],
         "shift" : [
            {
               "workgroup" : "226093",
               "display_time" : "10am to 11am",
               "display_date" : "July 13, 2014",
               "id" : "25687871"
            }
         ]
      },
      "tradeboard" : [
         {
            "shift" : "25687871",
            "id" : "1123",
            "trade_complete" : false,
            "traded_by" : "20",
            "traded_to" : null
         }
      ],
      "count" : "1",
      "page" : {
         "this" : {
            "batch" : 10,
            "start" : 1
         }
      }
   }
}

Returns information about tradeboard postings. Uses pagination. Uses select criteria.

Optional parameters:

extended

Boolean; if specified and true, the results returned will include an extended set of attributes; otherwise a basic set of attributes will be returned for each tradeboard posting.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the tradeboard attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned tradeboard postings.

select

An object specifying selection criteria for this request. Note that start_date and end_date will have default values if not specified. The available criteria include:

start_date

The earliest date of coverage to select, in RFC 3339 full date format (e.g. "2009-04-01"). Defaults to today.

end_date

The latest date of coverage to select, in RFC 3339 full date format. Defaults to 14 days after the start_date.

trade_complete

If specified, true requests only completed trades, false requests only uncompleted trades.

The response results tradeboard attribute will be an array of the current page of selected tradeboard postings. Each element of the array will be a tradeboard object containing basic or basic and extended tradeboard fields.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the tradeboard results or their associated shifts, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

NOTE: external_id will also be returned in the results if external ids are enabled for the site.

shift

id and workgroup attributes are provided. Additionally, display_date and display_time attributes contain formatted strings describing the shift's start and end time.

workgroup

id and name attributes are provided.

tradeboard.update

Request example:

{
   "notes" : "I'd like to trade for a shift the following Wednesday",
   "id" : 2345
}

Response example:

{
   "seconds" : "0.178901",
   "jsonrpc" : "2.0",
   "id" : "43",
   "result" : {}
}

Updates a tradeboard posting's notes.

Required parameter: id.

Optional parameter: notes.

Response: On success, empty results will be returned.

voucher object

voucher objects have the following minimal attributes:

id

A unique identifier for this voucher.

account

Identifier of the account to which this voucher is assigned.

cancelled

Boolean.

credit_earned

Numeric, two decimal places

credit_used

Numeric, two decimal places

expiration_date

Date credit expires/expired (UTC)

earned_date

Date credit was earned (UTC)

voucher.balance

Checks the user's voucher balance of available credit.

Parameters:

org_id

optional, organization for which to return voucher products; defaults to the user's organization; if specified, must be that or that organization's parent

Response: On success, returns a balance attribute and a voucher_product attribute giving an array of available product objects with id, name, and credits attributes.

voucher.refund

Refunds credit to the user's voucher balance.

Parameters:

voucher_transaction_id

id of transaction to refund

receipt

receipt attribute previously returned by voucher.use

latitude

optional, latitude of clock in

longitude

optional, longitude of clock in

location_accuracy

optional, meters of 68% confidence of latitude/longitude

location_time

optional, time of latitude/longitude/accuracy fix

device_id

optional, arbitrary string identifying issuing device

device_name

optional, arbitrary string with a displayable name for device

org_id

optional, organization for which to update the voucher transaction; defaults to the user's organization; if specified, must be that or that organization's parent

Response: On success, returns empty results.

voucher.use

Uses credit from the user's voucher balance.

Parameters:

credit

amount of credit to use.

latitude

optional, latitude of clock in

longitude

optional, longitude of clock in

location_accuracy

optional, meters of 68% confidence of latitude/longitude

location_time

optional, time of latitude/longitude/accuracy fix

device_id

optional, arbitrary string identifying issuing device

device_name

optional, arbitrary string with a displayable name for device

voucher_product

optional, the particular product for which credits are being redeemed

org_id

optional, organization for which to record the voucher transaction; defaults to the user's organization; if specified, must be that or that organization's parent

Response: On success, returns a voucher_transaction_id attribute and a string receipt attribute.

workStatusType object

workStatusType objects have the following minimal attributes:

id

A unique identifier for this workStatusType.

name

A displayable name used to identify this workStatusType.

workStatusType.get

Returns information about a workStatusType.

Parameters:

id

Required. The unique identifier of the workStatusType for which to return information.

The response results "workStatusType" attribute will be the selected workStatusType object.

workStatusType.list

Returns information about workStatusTypes. Uses pagination.

Parameters: None

The response results "workStatusTypes" attribute will be an array of the current page of selected workStatusTypes. Each element of the array will be an workStatusType object containing basic workStatusType attributes.

workgroup object

workgroup: basic attributes

id

A unique identifier for this workgroup.

name

The name of this workgroup.

zip

The postal code for this workgroup.

code

The nickname or code for this workgroup.

contact_account

The account identifier of the primary contact for this workgroup.

external_contact_account

The external account identifier of the primary contact for this workgroup. This field is optional, and should be used instead of contact_account if your site is configured to support external identifiers and you wish to key off of the external id instead.

Extended workgroup objects may also have these attributes:

org_default

Boolean; true if new organization accounts by default get membership in this workgroup.

description

Workgroup description shown to current members.

auto_add

Boolean; true if members may add themselves to this workgroup; false if add requests require manager approval.

view_public

Boolean; true if recruiting new members within the organization.

view_public_non_org

Boolean; true if recruiting new members from outside the organization.

public_email

Email address to include in recruiting information.

public_phone

Phone number to include in recruiting information.

public_code

Summary description of workgroup to include in recruiting information.

public_info

Long description of workgroup to include in recruiting information.

self_remove

Boolean; true if members can remove themselves from membership in this workgroup.

allow_readonly

An integer corresponding to the various possible values for sharing:

• 0: none
• 1: share with this workgroup
• 2: share with specified groups
• 3: share with all workgroup for the site

(This value cannot be set directly, see allow_shared)

allow_shared

Boolean; true shifts for this workgroup are shown in the shared schedule view (depending on the value of allow_readonly: "allow_readonly":0 means "allow_shared":false, and other values of allow_readonly are "allow_shared":true).

To set this, either set a boolean, or an integer, corresponding to allow_readonly.

allow_shared_groups

An object of workgroups (ID => name) to share with (if "allow_readonly":2).

To set this, use a comma-separated string of workgroup IDs. Can only be set with workgroup.update, not workgroup.create.

show_confirmed

Boolean; true if the count of covered shifts by date for this workgroup is visible to all workgroup members.

member_add_shift

Boolean; true if workgroup members are allowed to add their own covered shifts to the schedule.

show_open

Boolean; true if the count of open shifts by date for this workgroup is shown to all workgroup members.

cancel_period

Number of days prior to a shift within which a workgroup member may cancel.

allowed_conflict_mins

Number of minutes of overlap between shifts with the same location and workgroup to consider not a conflict.

timezone

location

Default location identifier for this workgroup's shifts.

url

Workgroup website.

address

Mailing address address line.

city

Mailing address city.

state

Full name of mailing address state/province/subdivision.

country

Full name of mailing address country.

office_phone

mobile_phone

other_phone

fax

pager

(Not all attributes will be provided to all users.)

level

User level within the workgroup.

• 2 - member
• 3 - coordinator
• 4 - manager

workgroup.create_clients

Creates new workgroup/client relationships.

Required parameters:

client

A single client identifier or an array of identifiers of clients for which to create workgroup relationships for each specified workgroup.

workgroup

A single workgroup identifier or an array of identifiers of workgroups for which to create client relationships for each specified client.

No more than 10000 workgroup client relationships may be specified in one request.

If one or more of the specified workgroup client relationships already exist, the remaining relationships (if any) will be created and no error will be returned.

Response: On success, empty results will be returned.

workgroup.addDepartments

Request example:

{
   "workgroup" : "226073",
   "department" : "948"
}

Response example:

{
   "seconds" : "0.041209",
   "jsonrpc" : "2.0",
   "id" : "6",
   "result" : {}
}

Creates new workgroup/department relationships.

Required parameters:

department

A single department identifier or an array of identifiers of departments for which to create workgroup relationships for each specified workgroup.

workgroup

A single workgroup identifier or an array of identifiers of workgroups for which to create department relationships for each specified department.

No more than 10000 workgroup department relationships may be specified in one request.

If one or more of the specified workgroup department relationships already exist, the remaining relationships (if any) will be created and no error will be returned.

Response: On success, empty results will be returned.

workgroup.addLocations

Request example:

{
   "workgroup" : "226074",
   "location" : "29117"
}

Response example:

{
   "seconds" : "0.792919",
   "jsonrpc" : "2.0",
   "id" : "12",
   "result" : {}
}

Creates new workgroup/location relationships.

Required parameters:

location

A single location identifier or an array of identifiers of locations for which to create workgroup relationships for each specified workgroup.

workgroup

A single workgroup identifier or an array of identifiers of workgroups for which to create location relationships for each specified location.

No more than 10000 workgroup location relationships may be specified in one request.

If one or more of the specified workgroup location relationships already exist, the remaining relationships (if any) will be created and no error will be returned.

Response: On success, empty results will be returned.

workgroup.addRoles

Request example:

{
   "workgroup" : "226077",
   "role" : "2281"
}

Response example:

{
   "seconds" : "0.067753",
   "jsonrpc" : "2.0",
   "id" : "6",
   "result" : {}
}

Creates new workgroup/role relationships.

Required parameters:

role

A single role identifier or an array of identifiers of roles for which to create workgroup relationships for each specified workgroup.

workgroup

A single workgroup identifier or an array of identifiers of workgroups for which to create role relationships for each specified role.

No more than 10000 workgroup role relationships may be specified in one request.

If one or more of the specified workgroup role relationships already exist, the remaining relationships (if any) will be created and no error will be returned.

Response: On success, empty results will be returned.

workgroup.create

Request example:

{
   "zip" : 60616,
   "name" : "Test Workgroup 48659",
   "code" : "A001"
}

Response example:

{
   "seconds" : "0.358585",
   "jsonrpc" : "2.0",
   "id" : "22",
   "result" : {
      "id" : "226094"
   }
}

Creates a new workgroup record.

Parameters: Any attributes of a workgroup object (except id) may be specified. A unique name parameter must be specified. Some workgroup attributes will default from organization values or configuration settings if not specified or invalid.

Response: On success, an id attribute will provide the identifier for the new workgroup.

workgroup.delete

Request example:

{
   "id" : "226089"
}

Response example:

{
   "seconds" : "0.052778",
   "jsonrpc" : "2.0",
   "id" : "48",
   "result" : {}
}

Deletes a workgroup record.

workgroup.deleteClients

Request example:

{
   "client" : "988",
   "workgroup" : "226072"
}

Response example:

{
   "seconds" : "0.056321",
   "jsonrpc" : "2.0",
   "id" : "10",
   "result" : {}
}

Required parameter: id.

Response: On success, empty results will be returned.

Deletes workgroup/client relationships.

Required parameters:

client

A single client identifier or an array of identifiers of clients for which to delete workgroup relationships for each specified workgroup.

workgroup

A single workgroup identifier or an array of identifiers of workgroups for which to delete client relationships for each specified client.

No more than 10000 workgroup client relationships may be specified in one request.

If one or more of the specified workgroup client relationships doesn't exist, the remaining relationships (if any) will be deleted and no error will be returned.

Response: On success, empty results will be returned.

workgroup.deleteDepartments

Request example:

{
   "workgroup" : "226073",
   "department" : "948"
}

Response example:

{
   "seconds" : "0.061248",
   "jsonrpc" : "2.0",
   "id" : "8",
   "result" : {}
}

Deletes workgroup/department relationships.

Required parameters:

department

A single department identifier or an array of identifiers of departments for which to delete workgroup relationships for each specified workgroup.

workgroup

A single workgroup identifier or an array of identifiers of workgroups for which to delete department relationships for each specified department.

No more than 10000 workgroup department relationships may be specified in one request.

If one or more of the specified workgroup department relationships doesn't exist, the remaining relationships (if any) will be deleted and no error will be returned.

Response: On success, empty results will be returned.

workgroup.deleteLocations

Request example:

{
   "workgroup" : "226074",
   "location" : "29117"
}

Response example:

{
   "seconds" : "0.809674",
   "jsonrpc" : "2.0",
   "id" : "8",
   "result" : {}
}

Deletes workgroup/location relationships.

Required parameters:

location

A single location identifier or an array of identifiers of locations for which to delete workgroup relationships for each specified workgroup.

workgroup

A single workgroup identifier or an array of identifiers of workgroups for which to delete location relationships for each specified location.

No more than 10000 workgroup location relationships may be specified in one request.

If one or more of the specified workgroup location relationships doesn't exist, the remaining relationships (if any) will be deleted and no error will be returned.

Response: On success, empty results will be returned.

workgroup.deleteRoles

Request example:

{
   "workgroup" : "226077",
   "role" : "2281"
}

Response example:

{
   "seconds" : "0.067934",
   "jsonrpc" : "2.0",
   "id" : "8",
   "result" : {}
}

Deletes workgroup/role relationships.

Required parameters:

role

A single role identifier or an array of identifiers of roles for which to delete workgroup relationships for each specified workgroup.

workgroup

A single workgroup identifier or an array of identifiers of workgroups for which to delete role relationships for each specified role.

No more than 10000 workgroup role relationships may be specified in one request.

If one or more of the specified workgroup role relationships doesn't exist, the remaining relationships (if any) will be deleted and no error will be returned.

Response: On success, empty results will be returned.

workgroup.get

Request example:

{
   "id" : "226093",
   "extended" : true,
   "include_permissions" : true
}

Response example:

{
  "permissions": {
    "add_member_message": {
      "auth_write": true
    },
    "agent_private_only": {
      "auth_write": true
    },
    "allow_readonly": {
      "auth_write": true
    },
    "allow_shared": {
      "auth_write": true
    },
    "allow_shared_groups": {
      "auth_write": true
    },
    "allowed_conflict_mins": {
      "auth_write": true
    },
    "auto_shift_acknowledge": {
      "auth_write": true
    },
    "cancel_period": {
      "auth_write": true
    },
    "coordinator_assign": {
      "auth_write": true
    },
    "def_paytype": {
      "auth_write": true
    },
    "def_time_block": {
      "auth_write": true
    },
    "member_add_shift": {
      "auth_write": true
    },
    "no_pickups_message": {
      "auth_write": true
    },
    "no_trade": {
      "auth_write": true
    },
    "reminder_confirmation_custom_message": {
      "auth_write": true
    },
    "restrict_add_members": {
      "auth_write": true
    },
    "restrict_set_member_levels": {
      "auth_write": true
    },
    "restricted_roles": {
      "auth_write": true
    },
    "self_remove": {
      "auth_write": true
    },
    "show_confirmed": {
      "auth_write": true
    },
    "show_open": {
      "auth_write": true
    },
    "standby_min_score": {
      "auth_write": true
    },
    "standby_no_score": {
      "auth_write": true
    },
    "standby_notification_message": {
      "auth_write": true
    },
    "standby_notifications": {
      "auth_write": true
    },
    "standby_range": {
      "auth_write": true
    },
    "standby_use_range": {
      "auth_write": true
    },
    "standby_use_score": {
      "auth_write": true
    },
    "use_app_20": {
      "auth_write": true
    },
    "use_app_29": {
      "auth_write": true
    }
  },
  "referenced_objects": {
    "account": [
      {
        "first_name": "John",
        "id": "1",
        "last_name": "Smith",
        "screen_name": "John Smith"
      }
    ]
  },
  "workgroup": {
    "add_member_message": null,
    "address": "",
    "agent_private_only": "0",
    "allow_readonly": "3",
    "allow_shared": true,
    "allow_shared_groups": {},
    "allowed_conflict_mins": "360",
    "auto_add": true,
    "auto_shift_acknowledge": false,
    "cancel_period": "-1",
    "city": "",
    "code": "The Nacho Team",
    "contact_account": "1",
    "coordinator_assign": false,
    "country": "United States",
    "def_pay_rate": "0.00",
    "def_paytype": null,
    "def_time_block": null,
    "description": "Team Nacho has no location.",
    "fax": "",
    "flat_rate": null,
    "id": "928136",
    "level": 4,
    "location": "0",
    "member_add_shift": true,
    "mobile_phone": null,
    "name": "Team Nacho",
    "no_pickups_message": null,
    "no_trade": "0",
    "office_phone": "n/a",
    "org_default": false,
    "other_phone": null,
    "pager": null,
    "public_code": null,
    "public_email": "john.smith@servola.org",
    "public_info": "This group is for members only.\r\n\r\nAdd this group or inquire about membership",
    "public_phone": "n/a",
    "reminder_confirmation_custom_message": null,
    "restrict_add_members": "0",
    "restrict_set_member_levels": "0",
    "restricted_roles": "0",
    "self_remove": false,
    "show_confirmed": false,
    "show_open": false,
    "standby_min_score": null,
    "standby_no_score": null,
    "standby_notification_message": null,
    "standby_notifications": null,
    "standby_range": null,
    "standby_use_range": null,
    "standby_use_score": null,
    "state": "Washington",
    "team_category_1": null,
    "team_category_2": null,
    "team_category_3": null,
    "team_category_4": null,
    "team_category_5": null,
    "timezone": "Pacific Time (US/Can) (GMT-08:00)",
    "url": "https://www.shiftboard.com/johnsmithtest",
    "use_app_20": null,
    "use_app_29": null,
    "view_public": true,
    "view_public_non_org": true,
    "zip": ""
  }
}

Returns information about a workgroup.

Parameters:

id

Required. id of the workgroup for which to return information.

extended

Boolean; if specified and false, the results returned will be a basic set of attributes; otherwise an extended set of attributes will be returned for each shift.

include_permissions

Boolean, defaults to false. Indicates that, in addition to the workgroup attribute, the results should include a permissions attribute giving information about write permission for individual fields returned in workgroup attribute. The fields that are listed in permissions section are those workgroup fields that can be configured.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the workgroup attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned workgroup.

The response results workgroup attribute will be the selected workgroup object.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the workgroup results, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

workgroup.list

Request example:

{
   "select" : {
      "workgroup" : "226093"
   },
   "extended" : true
}

Response example:

{
   "seconds" : "0.051276",
   "jsonrpc" : "2.0",
   "id" : "21",
   "result" : {
      "count" : "1",
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      },
      "workgroups" : [
         {
            "contact_account" : "948",
            "public_info" : "some public info",
            "state" : "California",
            "org_default" : true,
            "url" : "http://www.servola.org/",
            "address" : "1 Main St",
            "id" : "226093",
            "allowed_conflict_mins" : "90",
            "code" : "thecode",
            "level": 2,
            "location" : "29120",
            "timezone" : "Greenwich Mean Time : Dublin, Lisbon, London (GMT)",
            "public_phone" : "5555551212",
            "view_public" : true,
            "show_confirmed" : true,
            "name" : "Test Workgroup 226093",
            "description" : "some info",
            "zip" : "90210",
            "mobile_phone" : "5555551212",
            "view_public_non_org" : true,
            "auto_add" : true,
            "public_email" : "test@servola.org",
            "public_code" : "public code",
            "city" : "Beverly Hills",
            "fax" : "5555551212",
            "allow_shared" : true,
            "self_remove" : true,
            "country" : "USA",
            "office_phone" : "5555551212",
            "cancel_period" : "5",
            "member_add_shift" : false,
            "show_open" : true,
            "other_phone" : "5555551212",
            "pager" : "5555551212"
         }
      ]
   }
}

Returns information about workgroups. Uses pagination. Uses select criteria.

Optional parameters:

select

An object specifying selection criteria for this request. May specify selected workgroup object attributes and values to select. The following additional criteria may be specified:

deleted

true if deleted workgroups should be returned.

search

A generic search string; select workgroups containing this string in name or code.

extended

Boolean; if specified and true, the results returned will include an extended set of attributes; otherwise a basic set of attributes will be returned for each workgroup.

level

Filter workgroups based on the caller's membership level. The filter is a lower limit; any workgroups the caller has access to and is the specified level and above, will be returned.

shared

Boolean; if specified and true, the results returned will also include workgroups that are shared to the account.

referenced_objects

Boolean, defaults to true. Indicates that, in addition to the workgroups attribute, the results should include a referenced_objects attribute giving information about objects referred to by the returned workgroups.

The response results workgroups attribute will be an array of the current page of selected workgroups. Each element of the array will be a workgroup object containing basic or basic and extended workgroup fields.

If requested, the response results referenced_objects attribute will be an object containing one or more object type names as attributes; for each object type the value will be an array of those instances of that type of object which are referred to in the workgroups results, with only selected minimal attributes provided:

account

id, first_name, last_name, and screen_name attributes are provided.

workgroup.listJoinable

For sites that allow for internal team recruitment, this method will list all public workgroups that are accepting new members from within the site. Only workgroups that the requesting member is not already a member of will be returned.

Request example:

{}

Response example:

{ "id" : "1", "jsonrpc" : "2.0", "result" : { "count" : "2", "page" : { "this" : { "batch" : "20", "start" : 1 } }, "workgroups" : [ { "code" : "", "contact_account" : "88810", "id" : "23041", "level" : 1, "name" : "First Joinable Workgroup", "user_actions" : { "delete" : false, "edit" : false, "view" : false, "view_members" : false }, "zip" : "98765" }, { "code" : "", "contact_account" : "88810", "id" : "23052", "level" : 1, "name" : "Second Joinable Workgroup", "user_actions" : { "delete" : false, "edit" : false, "view" : false, "view_members" : false }, "zip" : "98765" } ] }, "seconds" : 0.090942 }

Returns information about workgroups. Uses pagination. Uses select criteria.

workgroup.listClients

Request example:

{
   "select" : {
      "workgroup" : "226072"
   }
}

Response example:

{
   "seconds" : "0.040039",
   "jsonrpc" : "2.0",
   "id" : "9",
   "result" : {
      "count" : "1",
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      },
      "workgroup_clients" : [
         {
            "client" : "988",
            "workgroup" : "226072"
         }
      ]
   }
}

Returns information about workgroup/client relationships. Uses pagination.

Optional parameters: select object with the following optional attributes:

client

A single client identifier or an array of identifiers of clients for which to look up workgroup relationships. By default, all clients will be queried.

workgroup

A single workgroup identifier or an array of identifiers of workgroups for which to look up client relationships. By default, all workgroups for which the API user is a manager will be queried.

The response results workgroup_clients attribute will be an array of the current page of workgroup client relationships. Each element of the array may have the following attributes:

client

A client identifier.

workgroup

A workgroup identifier.

workgroup.listCoverageBlocks

Returns information about workgroup/coverage block relationships. Uses pagination. Uses select criteria.

Optional parameters: "select" object with the following optional attributes:

workgroup A single workgroup identifier or an array of identifiers of workgroups for which to look up coverage block relationships. By default, all workgroups for which the API user is a manager will be queried.

The response results "workgroup_shift/coverage blocks" attribute will be an array of the current page of workgroup coverage block relationships. Each element of the array may have the following attributes: days Number of days the coverage block spans. duration Number of hours the coverage block spans. end_time The time in which the coverage block ends. name The name of the coverage block. start_time The time in which the coverage block starts. time_block The coverage block identifier. workgroup A workgroup identifier.

workgroup.listDepartments

Request example:

{
   "select" : {
      "workgroup" : "226085"
   }
}

Response example:

{
   "seconds" : "0.050097",
   "jsonrpc" : "2.0",
   "id" : "60",
   "result" : {
      "count" : "1",
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      },
      "workgroup_departments" : [
         {
            "workgroup" : "226085",
            "department" : "949"
         }
      ]
   }
}

Returns information about workgroup/department relationships. Uses pagination.

Optional parameters: select object with the following optional attributes:

department

A single department identifier or an array of identifiers of departments for which to look up workgroup relationships. By default, all departments will be queried.

workgroup

A single workgroup identifier or an array of identifiers of workgroups for which to look up department relationships. By default, all workgroups for which the API user is a manager will be queried.

The response results workgroup_departments attribute will be an array of the current page of workgroup department relationships. Each element of the array may have the following attributes:

department

A department identifier.

workgroup

A workgroup identifier.

workgroup.listLocations

Request example:

{
   "select" : {
      "workgroup" : "226085"
   }
}

Response example:

{
   "seconds" : "0.056378",
   "jsonrpc" : "2.0",
   "id" : "59",
   "result" : {
      "count" : "1",
      "page" : {
         "this" : {
            "batch" : 25,
            "start" : 1
         }
      },
      "workgroup_locations" : [
         {
            "workgroup" : "226085",
            "location" : "29118"
         }
      ]
   }
}

Returns information about workgroup/location relationships. Uses pagination.

Optional parameters: select object with the following optional attributes:

location

A single location identifier or an array of identifiers of locations for which to look up workgroup relationships. By default, all locations will be queried.

workgroup

A single workgroup identifier or an array of identifiers of workgroups for which to look up location relationships. By default, all workgroups for which the API user is a manager will be queried.

The response results workgroup_locations attribute will be an array of the current page of workgroup location relationships. Each element of the array may have the following attributes:

location

A location identifier.

workgroup

A workgroup identifier.

workgroup.listResources

Returns information about workgroup/resource relationships. Uses pagination. Uses select criteria.

Optional parameters: "select" object with the following optional attributes: resource A single resource identifier or an array of identifiers of resources for which to look up workgroup relationships. By default, all resources will be queried. workgroup A single workgroup identifier or an array of identifiers of workgroups for which to look up resource relationships. By default, all workgroups for which the API user is a manager will be queried.

The response results "workgroup_resources" attribute will be an array of the current page of workgroup resource relationships. Each element of the array may have the following attributes: resource A resource identifier. workgroup A workgroup identifier.

Request example:

{"select":{"workgroup":"226085"}}

Response example:

{"seconds":"0.148687","jsonrpc":"2.0","id":"58","result":{"workgroup_resources":[{"workgroup":"226085","resource":"2"}],"count":"1","page":{"this":{"batch":25,"start":1}}}}

workgroup.listRoles

Request example: