NAV Navbar
JSON Example PHP Code
  • Overview
  • Webhooks
  • Getting Set Up
  • Requests and Responses
  • Objects
  • 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:

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

    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. At this time, only GET requests are supported (except for batch requests, which use POST), with formatting based on the JSON-RPC Over HTTP specification's GET request.

    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 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 "g57a67b3b-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:

    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.

    olson_timezone

    The Olson 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:

    System-defined pending codes are:

    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:

    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:

    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

    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

    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

    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, 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:

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

    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 "Olson" 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

    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:

    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.

    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.

    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.

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

    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.

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

    user_actions

    The actions that can be performed by the API caller on 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.get

    Request example:

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

    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

    Required parameters:

    id

    Manager note identifier

    managerNote.list

    Request example:

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

    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:

    select object with optional attributes identifying a single manager note or array of manager notes to be returned.

    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

    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

    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

    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

    Level Membership Type
    2 member
    3 coordinator
    4 manager

    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.

    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.

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

    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

    Optional Parameters

    Optional Filters

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

    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.

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

    Assigns a role or multiple roles to a member of a given workgroup. This method can be used to assign or unassign 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 role ids to be assigned to the workgroup member.

    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.

    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.

    tentative

    true if the shift is tentatively covered.

    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.

    covering_workgroup

    If the shift is covered by a workgroup, the workgroup id (currently, never different from the shift's workgroup)

    use_time 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

    extra_credit

    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 full date format (e.g. "2009-04-01").

    display_time

    duration_minutes

    Boolean.

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

    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

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

    content-type extension file type
    application/vnd.ms-excel xls Microsoft Excel
    application/vnd.openxmlformats-officedocument.spreadsheetml.sheet xlsx Microsoft Excel Open XML Spreadsheet
    text/csv csv Comma-separated values

    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,
            "assign_multiple": 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
    assign_multiple|Assign multiple positions to a single member 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

    status_code status description
    0 Verified The file has been uploaded and verified as either valid or invalid
    1 Cancelled An internal server error has occurred, and processing has been interrupted
    3 Loaded The shifts in the file have been created and/or an exception file has been created
    6 Pending The file has been verified, is valid, and the data is waiting to be loaded into the schedule via a Servola process
    7 Awaiting Upload A URL has been generated
    8 Upload Error The file could not be parsed or processed

    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,
       "covering_workgroup" : "226084",
       "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.

    Type Meaning
    frequency Frequency
    days_of_week Days of Week
    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:

    Interval Meaning
    every Every
    every_other Every Other
    every_third Every Third
    every_fourth Every Fourth
    every_fifth Every Fifth
    every_sixth Every Sixth

    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:

    Frequency
    day
    week
    month
    year

    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:

    Day Meaning
    0 Sunday
    1 Monday
    2 Tuesday
    3 Wednesday
    4 Thursday
    5 Friday
    6 Saturday

    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

    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

    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 and covering_workgroup are mutually exclusive, and may only be specified if the shift is covered. tentative may only true if the shift is covered, and 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.

    Type Meaning
    frequency Frequency
    days_of_week Days of Week
    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:

    Interval Meaning
    every Every
    every_other Every Other
    every_third Every Third
    every_fourth Every Fourth
    every_fifth Every Fifth
    every_sixth Every Sixth

    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:

    Frequency
    day
    week
    month
    year

    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:

    Day Meaning
    0 Sunday
    1 Monday
    2 Tuesday
    3 Wednesday
    4 Thursday
    5 Friday
    6 Saturday

    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

    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.

    display_time

    Boolean; if specified and true, the returned shift will include a display_time attribute 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_time

    The time range of the shift, formatted for display.

    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 olson_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:

    Field Description
    id
    start_date
    start_time
    end_date
    end_time
    timezone Timezone defaults to the site's timezone if one is not provided in the request.
    role Role is required for role restriction.
    unpaid_mins Required for overtime checking.
    location Location id of shift (venue).
    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).
    covering_member If specified, requests only shifts covered by the workgroup member.
    external_covering_member If the shift is covered by a member, the external id of the member's account.

    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.

    Type Meaning
    frequency Frequency
    days_of_week Days of Week
    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:

    Interval Meaning
    every Every
    every_other Every Other
    every_third Every Third
    every_fourth Every Fourth
    every_fifth Every Fifth
    every_sixth Every Sixth

    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:

    Frequency
    day
    week
    month
    year

    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:

    Day Meaning
    0 Sunday
    1 Monday
    2 Tuesday
    3 Wednesday
    4 Thursday
    5 Friday
    6 Saturday

    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.

    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)",
                   "olson_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 olson_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",
                "covering_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_workgroup/covering_member, tentative, covered, published, location, role, and urgent attributes are aggregated.

    similar_subject

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

    date

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

    date_subject

    Shifts with the same start_date, subject, covered, published, tentative, 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.

    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.

    covering_workgroup

    If specified, requests only shifts covered by the given workgroup.

    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

    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.

    no_show

    If specified and true, only shifts that have been marked "No Show" will be selected; if specified and false, only shifts that have not been marked "No Show" will be selected.

    workgroup_or_covering

    If true, select shifts where the workgroup OR covering_member/covering_workgroup filter applies. Otherwise, select shifts for which both filters (if specified) apply.

    custom_dropdown_1

    If specified, only shifts with the given custom_dropdown_1 identifiers will be selected. May be a single identifier or an array of identifiers.

    custom_dropdown_2

    If specified, only shifts with the given custom_dropdown_2 identifiers will be selected. May be a single identifier or an array of identifiers.

    custom_dropdown_3

    If specified, only shifts with the given custom_dropdown_3 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.

    is_a_trade

    If tradeboard is enabled, this will return a boolean value if a shift is available to trade.

    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
    custom_text_2
    custom_text_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.

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

    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,
       "covering_workgroup" : "226084",
       "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.

    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.

    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

    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)",
                    "olson_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 olson_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

    Value Type
    3 Start & End Date
    4 Open Ended
    5 All Day

    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

    Value Meaning
    0 New
    2 Approved
    3 Denied

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

    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",
                            "category": "0",
                            "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",
                            "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 olson_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 olson_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

    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.

    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_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:

    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 "olson_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:

    olson_timezone

    The Olson 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)",
                   "olson_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 olson_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:

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

    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.

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

    Request example:

    {"select":{"workgroup":"123456"}}
    

    Response example:

    { "seconds": "0.148687", "jsonrpc": "2.0", "id": "58", "result": {  "count": "1", "page": { "this": { "batch": 10, "start": 1 } },  "workgroup_shift/coverage blocks": [    {      "days": "0",      "duration": "01:35:00",      "end_time": "13:45:00",      "name": "A Test Coverage Block",      "start_time": "12:10:00",      "time_block": "10101", "workgroup": "123456" }]}}
    

    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:

    {
       "select" : {
          "workgroup" : "226085"
       }
    }
    

    Response example:

    {
       "seconds" : "0.148687",
       "jsonrpc" : "2.0",
       "id" : "58",
       "result" : {
          "count" : "1",
          "workgroup_roles" : [
             {
                "workgroup" : "226085",
                "role" : "2282"
             }
          ],
          "page" : {
             "this" : {
                "batch" : 25,
                "start" : 1
             }
          }
       }
    }
    

    Returns information about workgroup/role relationships. Uses pagination.

    Optional parameters: select object with the following optional attributes:

    role

    A single role identifier or an array of identifiers of roles for which to look up workgroup relationships. By default, all roles will be queried.

    workgroup

    A single workgroup identifier or an array of identifiers of workgroups for which to look up role relationships. By default, all workgroups for which the API user is a manager will be queried.

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

    role

    A role identifier.

    workgroup

    A workgroup identifier.

    include_permissions

    Boolean, defaults to false. This parameter is outside of the scope of the select object. 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.

    workgroup.undelete

    Request example:

    {
       "id" : "226089"
    }
    

    Response example:

    {
       "seconds" : "0.052778",
       "jsonrpc" : "2.0",
       "id" : "48",
       "result" : {}
    }
    

    Undeletes a workgroup record.

    Required parameter id, a workgroup identifier or array of workgroup identifiers.

    Optional boolean parameter add_former_workgroup_members (defaults to true) requests that memberships removed when the workgroup was deleted be re-added if possible.

    Response: On success, empty results will be returned.

    workgroup.update

    Request example:

    {
       "name" : "Test Workgroup 226094",
       "id" : "226094"
    }
    

    Response example:

    {
       "seconds" : "0.542458",
       "jsonrpc" : "2.0",
       "id" : "23",
       "result" : {}
    }
    

    Updates a workgroup record.

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

    Response: On success, empty results will be returned.