www.shiftdata.com
Open in
urlscan Pro
44.237.100.176
Public Scan
Submitted URL: http://shiftdata.com/
Effective URL: https://www.shiftdata.com/
Submission: On March 07 via api from US — Scanned from DE
Effective URL: https://www.shiftdata.com/
Submission: On March 07 via api from US — Scanned from DE
Form analysis 0 forms found in the DOM
Text Content
NAV
JSON Example PHP Code
Overview
* Scope
Webhooks Getting Set Up Requests and Responses
* Selection Criteria
* Batches
* Pagination
* Performance Batching
* Batch Requests
* Requests
* Request Format
* Request Signature
* Responses
* Response Format
* Successful Responses
* Error Responses
Objects
* account object
* account: basic attributes
* account: extended attributes
* account.acceptPrivacyPolicy
* account.create
* account.delete
* account.deleteDocument
* account.deleteImage
* account.deleteResume
* account.expiredCertification
* account.get
* account.getDocument
* account.getImage
* account.getResume
* account.list
* account.listByWorkgroup
* account.listMemberships
* account.listOpenids
* account.listUpdated
* account.resetPassword
* account.self
* account.sendPassword
* account.sendWelcomeLetter
* account.update
* account.updateDocument
* account.updateImage
* account.updateResume
* accountPoints object
* accountPoints: basic attributes
* accountPoints.create
* accountPoints.delete
* accountPoints.list
* accountPoints.shiftList
* accountPoints.update
* attestation object
* attestationType object
* attestationType.list
* availability object
* availability.approve
* availability.create
* availability.delete
* availability.get
* availability.list
* availability.update (not currently available)
* calendar object
* calendar.summary
* client object
* client.create
* client.delete
* client.get
* client.list
* client.update
* coverageBlock object
* Basic Attributes
* coverageBlock.list
* department object
* department.create
* department.delete
* department.get
* department.list
* department.update
* directManager object
* directManager.get
* directManager.list
* location object
* location.create
* location.delete
* location.list
* location.update
* managerNote object
* managerNote: basic attributes
* managerNote.customFields
* managerNote.get
* managerNote.list
* managerNote.create
* managerNote.delete
* managerNote.update
* managerNoteType object
* managerNoteType.list
* managerNoteType.create
* managerNoteType.delete
* managerNoteType.update
* membership object
* membership.create
* membership.delete
* membership.list
* membership.listExcluded
* membership.tierList
* membership.update
* message object
* message.broadcast
* message.direct
* news object
* news.get
* openid object
* openid.create
* openid.delete
* openid.update
* paycode object
* paycode.create
* paycode.delete
* paycode.get
* paycode.list
* paycode.update
* paytype object
* paytype.list
* profileConfiguration object
* profileConfiguration.list
* profileData object
* profileData.list
* profileData.update
* profileType object
* profileType.list
* registration object
* registration.create
* resource object
* Basic Attributes
* resource.list
* role object
* role.create
* role.delete
* role.get
* role.assign
* role.list
* role.update
* shift object
* shift: basic attributes
* shift: extended attributes
* shift.acknowledge
* shift.assign
* shift.bulkDelete
* shift.bulkUpload
* shift.bulkUploadGetSettings
* shift.bulkUploadGetTemplates
* shift.bulkUploadUpdateSettings
* shift.bulkUploadStatus
* shift.bulkUpdate
* shift.bulkCopy
* shift.confirm
* shift.create
* shift.customDropdownList
* shift.customMultipickList
* shift.customTextList
* shift.delete
* shift.deleteSignup
* shift.get
* shift.getAssignmentList
* shift.getOfferedTrade
* shift.list
* shift.listUpdated
* shift.markAbsent
* shift.notification
* shift.signup
* shift.signupList
* shift.summary
* shift.unconfirm
* shift.update
* shift.whosOn
* system object
* system.echo
* system.endBatch
* system.getUserKeys
* system.timestamp
* system.whoami
* teamCategory object
* teamCategory.list
* teamCategory.create
* teamCategory.update
* teamCategory.delete
* teamCategoryItem object
* teamCategoryItem.list
* teamCategoryItem.add
* teamCategoryItem.undelete
* teamCategoryItem.update
* teamCategoryItem.delete
* timeOffRequest object
* timeOffRequest: basic attributes
* timeOffRequest: extended attributes
* timeOffRequest.approve
* timeOffRequest.create
* timeOffRequest.delete
* timeOffRequest.deny
* timeOffRequest.get
* timeOffRequest.list
* timeOffRequest.update
* timecard object
* timecard: basic attributes
* timecard: extended attributes
* timecard.approve
* timecard.create
* timecard.delete
* timecard.exportTRAXPayroll
* timecard.get
* timecard.list
* timecard.process
* timecard.report
* timecard.update
* timecard.customDropdownList
* timecard.shiftList
* timeclock object
* timeclock: basic attributes
* timeclock: extended attributes
* timeclock.clockIn
* timeclock.clockOut
* timeclock.get
* timeclock.list
* timeclock.report
* timeclock.status
* timeclock.whosOn
* timezone object
* timezone.get
* timezone.list
* tradeboard object
* tradeboard: basic attributes
* tradeboard: extended attributes
* tradeboard.accept
* tradeboard.approve
* tradeboard.create
* tradeboard.delete
* tradeboard.get
* tradeboard.list
* tradeboard.update
* voucher object
* voucher.balance
* voucher.refund
* voucher.use
* workStatusType object
* workStatusType.get
* workStatusType.list
* workgroup object
* workgroup: basic attributes
* workgroup.create_clients
* workgroup.addDepartments
* workgroup.addLocations
* workgroup.addRoles
* workgroup.create
* workgroup.delete
* workgroup.deleteClients
* workgroup.deleteDepartments
* workgroup.deleteLocations
* workgroup.deleteRoles
* workgroup.get
* workgroup.list
* workgroup.listJoinable
* workgroup.listClients
* workgroup.listCoverageBlocks
* workgroup.listDepartments
* workgroup.listLocations
* workgroup.listResources
* workgroup.listRoles
* workgroup.undelete
* workgroup.update
* Privacy Policy
* Contact Us
OVERVIEW
Shiftboard offers a rich set of Application Programming Interfaces (APIs) to
allow external systems to interact with the Shiftboard platform. These APIs take
the form of JSON-RPC web service calls or Webhooks. Most Shiftboard application,
account, authorization, systems management, and site provisioning data is
accessible and the API is continually extended to encompass more of the
Shiftboard data and functionality.
All requests and responses are encoded using JavaScript Object Notation (JSON)
and encrypted using 256-bit Secure Sockets Layer (SSL). Unencrypted requests are
not accepted. Using JSON, HMAC, and Base64 libraries, it should be easy to
create, update, list and delete objects within the Shiftboard application. These
libraries should be available for all programming languages.
All requests include your organization's unique Access Key ID and are digitally
signed by computing an HMAC SHA1 signature of the request with your private
(secret) Signature Key. Your private Signature Key should NEVER be transmitted
or shared with anyone.
Please see the Requests section for details on making digitally signed requests.
SCOPE
Virtually every end-user interaction can be implemented using the web service.
In fact, all of Shiftboard's end-user applications use the web service. In
addition, various types of management functionality not available to end-users
are exposed via the web service.
The Shiftboard APIs are constantly evolving. Please ask about any objects or
extended functionality that can help meet the requirements of your project.
WEBHOOKS
Shiftboard can make an HTTP request to a customer-specified endpoint when
specific events occur. Supported events include the following:
* account created
* account updated
* account deleted
* shift created
* shift updated
* shift deleted
* workgroup membership created
* workgroup membership updated
* workgroup membership deleted
Each of these events can be subscribed to independently (enabled/disabled and
endpoint specified).
The webhook call is an HTTP GET request with the URL parameterized with the ID
of the affected object. For example, if the account.create endpoint is specified
as ‘http://test.com/account/create/' then a notification will look like
‘http://test.com/account/create/###’ where ### is the ID of the newly created
account. The ID can be the internal Shiftboard ID, the external Customer ID (if
the site is configured to support that), or a customer-specified custom field on
the shift object.
For shifts, ‘###’ is the ID of the shift.
For workgroup memberships, there are two IDs: ‘###/###’. The first is the
workgroup ID, and the second is the account ID of the member.
For more information, or to get a webhook configured for your site, please
contact your Account Manager.
Reference: Webhooks
GETTING SET UP
Before you use the Shiftboard Web Services API, you must register with
Shiftboard and obtain:
* an Access Key ID (a 36 character sequence)
* For example: 135fc788-762b-46a6-a80f-3491c14ad26f
* a secret Signature Key (a 40-character sequence)
* For example: bkvqNVSokbDZVHvt+RzqsrVzI0w7fhcU/jo/eUcY
Caution: Your Signature Key is a secret, which only you and Shiftboard should
know. It is important to keep it confidential to protect your account. Store it
securely in a safe place. Never include it in your requests to Shiftboard, and
never e-mail it to anyone. Do not share it outside your organization, even if an
inquiry appears to come from Shiftboard. No one who legitimately represents
Shiftboard will ever ask you for your secret Signature Key.
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 "57a67b3b-34e4-4c07-a8ca-e7ecb77a7f33",
a complete request would be
"https://api.shiftdata.com/?id=885&jsonrpc=2.0&method=echo¶ms=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 . "¶ms=" . $Params . "&signature=" . $Sig;
Each request is digitally signed by taking components of the request and
computing an HMAC SHA1 signature for them using a secret Signature Key (which
itself should never be transmitted). The calculated signature is then base64
encoded. The HMAC SHA1 algorithm is described in RFC 2104.
The data to be signed for GET requests is composed of four parts concatenated
with no separator:
* The 6 character string method
* The name of the method being called
* The 6 character string params
* The text being passed as params, prior to any base64 or URI encoding
For POST requests, the data to be signed is simply the entire contents of the
POST request.
RESPONSES
RESPONSE FORMAT
The response to a Shiftboard Web Services API request is a object (RFC 4627)
with the following attributes:
ID
The id provided in the request. If an error prevented the request from being
parsed, this attribute may be null.
JSONRPC
Version of the JSON-RPC specification for this response. Will always be the
string "2.0".
RESULT
A object providing the results of the request. Only present when the request was
successful. Contents are method-dependent: see Objects and Common Attributes.
ERROR
A object providing error information. Only present when the request failed.
SECONDS
If provided, number of seconds spent processing the request and formatting a
response.
SUCCESSFUL RESPONSES
The attributes returned in response results vary; see Objects.
ERROR RESPONSES
A properly formatted and authorized request should not result in an error;
please contact Shiftboard Support for assistance.
OBJECTS
ACCOUNT OBJECT
ACCOUNT: BASIC ATTRIBUTES
ID
A unique identifier for this account.
EXTERNAL_ID
The external identifier for this account.
NOTE: This field is only used or returned when external ids are enabled for the
site.
FIRST_NAME
LAST_NAME
SURNAME
Currently unused.
MIDDLE_NAME
Currently unused.
SCREEN_NAME
TITLE
Currently unused.
ADDRESS
ADDRESS_SECOND
Second address line
CITY
STATE
Full name of state/province/subdivision.
ZIP
Postal code.
REGION
Currently unused.
COUNTRY
EMAIL
Email address or dummy login email address. If a dummy address or email is being
returned from this address, the bad_email attribute will be true.
BAD_EMAIL
Boolean; true if the email address is a dummy login email address or email to
the email address is being returned.
HOME_PHONE
MOBILE_PHONE
OTHER_PHONE
Work/other phone.
PAGER
FAX
IS_SUPERVISOR
Indicates if this account a supervisor of another member of the site.
SUPERVISOR_ID
The account's direct_manager id.
DIRECT_MANAGER
The identifier of the account's direct manager they are supervised by.
URL
Web/blog address.
TIMEZONE
Timezone for this account.
IANA_TIMEZONE
The IANA timezone for this account.
PROFILE_TYPE
profile type identifier for this account.
ORG_HOLD
Boolean. Indicates whether this account is on hold.
ORG_PENDING
Pending code indicating on-boarding status of this account. Site configurable
pending code labels default to:
* "0" Current
* "1" Pending Registration
* "2" In-Process
* "3" Wait-Listed
* "4" Temp/Seasonal Hold
* "5" Stop Process
* "6" Made Contact/Msg
* "7" Awaiting Reregistration
System-defined pending codes are:
* "1001" Expired Certification
* "1002" Documents Missing
* "1003" Documents Verified
ACCOUNT_POINTS
The current points value for the account (see the accountPoints object).
ACCOUNT: EXTENDED ATTRIBUTES
(not all attributes are available for all organizations)
EXTERNAL_ID
External ID for this account, if this organization uses external IDs.
NOTIFICATION_PREFERENCE
Notification preference for this account. Valid values:
* "0" No Notifications
* "1" Send Notifications
GET_REMINDERS
Boolean. Enables receiving of reminder messages.
GET_CONFIRMATIONS
Boolean. Enables receiving of confirmation messages.
DIGEST_TYPE
Type of notification digest for this account. Valid values:
* "0" Send Immediately (no digest)
* "1" Send Daily
* "2" Send Weekly
SMS_TXT_NUMBER
Number used for SMS (text) messages. If site does not have Premium SMS enabled,
must also specify carrier.
CARRIER
Carrier ID for SMS (text) messages. Only used if site does not have Premium SMS
enabled.
LEVEL
User level in the organization
* "2" member
* "3" coordinator
* "4" manager
USER_TYPE
Will be admin if a super-user, user otherwise.
OVERTIME_EXEMPT
Boolean.
PAY_RATE
FLAT_RATE
START_DATE
PAYCODE
Paycode identifier
PAY_RATE_OVERRIDES
Boolean. If false, indicates that for this account, pay_rate does not override
the rate associated with the account's paycode.
SENIORITY
Boolean.
SENIORITY_RANK
Seniority rank from 1 to 999999999, 1 being the highest rank.
SENIORITY_DATE
Seniority date.
PROFILE_UPDATED
Time profile information for this account was last updated
UPDATED
Time non-profile information for this account was last updated
ACCOUNT.ACCEPTPRIVACYPOLICY
> Request example:
{}
> Response example:
{
"id" : "1",
"jsonrpc" : "2.0",
"result" : {},
"seconds" : 0.08004
}
Try it!
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
}
}
Try it!
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" : {}
}
Try it!
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
Try it!
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
Try it!
Deletes the user image for a given account.
REQUIRED PARAMETERS
id or external_id
RESPONSE
On success, empty results will be returned.
ACCOUNT.DELETERESUME
Try it!
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" : {}
}
Try it!
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"
}
}
Try it!
Returns information about a single account.
REQUIRED PARAMETERS
id or external_id
OPTIONAL PARAMETERS
ACCOUNT_POINTS_LIST
Boolean; if specified and true, the results returned will include the
account_points_list key. The value will be an array of 0 or more elements, or
null if account points are not available for the API call. See
accountPoints.list.
EXTENDED
Boolean; if specified and true or user_actions is true, the results returned
will include an extended set of attributes; otherwise a basic set of attributes
will be returned.
IMAGE
Boolean; if specified and true, the results returned will include an image_url
attribute giving a url to the account's user image or null if no image is
available.
IMAGE_EXPIRATION
Specifies the valid lifetime of the returned URL in seconds; default 300,
maximum 604800 (1 week).
QRCODE
Boolean; if specified and true, the results returned will include a qrcode
attribute giving the data for generating the account's qrcode.
TIMECLOCK_STATUS
Boolean; if specified and true, the results returned will include a clocked_in
attribute indicating that the account is currently clocked in and a
can_clock_in_out attribute indicating whether there is authorization to clock
this account in or out.
USER_ACTIONS
Boolean; if specified and true, a user_actions object will be returned with
attributes indicating what actions should be presented to the user to be
performed on this account
ADD_AVAILABILITY
DELETE_AVAILABILITY
SHOW_AVAILABILITY
Attributes may not be returned for applications that are not enabled for this
user/organization.
The response results will be an account object containing basic or basic and
extended account fields.
ACCOUNT.GETDOCUMENT
Try it!
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"
}
}
Try it!
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
Try it!
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"
}
]
}
}
Try it!
Returns information about accounts. Uses pagination. Uses select criteria.
OPTIONAL PARAMETERS
SELECT
An object specifying selection criteria for this request. Allowed criteria are:
ACCOUNT
A single account identifier or an array of identifiers to select.
WORKGROUP
A single workgroup identifier or an array of identifiers to select.
DIRECT_MANAGER
A single direct manager identifier or an array of identifiers to select. Must
have TRACK SUPERVISORS feature enabled in order to use this filter. Results will
be filtered to only those accounts who are supervised by the direct manager(s)
specified.
EMAIL
A single email address or an array of them to select.
EXTERNAL_ID
A single external_id or an array of them to select, if used by the site.
PROFILE_TYPE
A profile type identifier for which to select accounts.
ORG_HOLD
Hold status (boolean)
ORG_PENDING
On-boarding status
SEARCH
A generic search string; select accounts containing this string in any of:
first_name, last_name, first and last names combined, screen name, or, if used
by the site, external_id.
EXTENDED
Boolean; if specified and true, the results returned will include an extended
set of attributes; otherwise a basic set of attributes will be returned for each
account.
IMAGE
Boolean; if specified and true, the results returned will include an image_url
attribute giving a url to the account's user image or null if no image is
available.
IMAGE_EXPIRATION
Specifies the valid lifetime of the returned URL in seconds; default 300,
maximum 604800 (1 week).
QRCODE
Boolean; if specified and true, the results returned will include a qrcode
attribute giving the data for generating the account's qrcode.
SHARED
Boolean; if specified and true, the results returned will also include accounts
in workgroups that are shared to the account.
SORT
A single sort criterion or an array of criteria in order from major to minor.
Each criterion is either an attribute name (one of first_name, last_name,
account_points, or id) or an object with two attributes, name (one of the
supported sort attribute names) and direction (asc or desc).
TIMECLOCK_STATUS
Boolean; if specified and true, the results returned will include a clocked_in
attribute indicating that the account is currently clocked in and a
can_clock_in_out attribute indicating whether there is authorization to clock
this account in or out.
RESPONSE
The response results accounts attribute will be an array of the current page of
accounts. Each element of the array will be an account object containing basic
or basic and extended account fields.
ACCOUNT.LISTBYWORKGROUP
> Request example:
{
"select" : {
"workgroup" : "226094"
}
}
> Response example:
{
"seconds" : "0.045885",
"jsonrpc" : "2.0",
"id" : "35",
"result" : {
"members" : [
{
"home_phone" : "18007467531",
"bad_email" : false,
"state" : "Washington",
"last_name" : "Testing 1",
"email" : "132995@servola.org",
"city" : "Seattle",
"fax" : "",
"url" : "",
"address" : "720 3rd Ave, Suite 2200",
"id" : "2",
"country" : "United States",
"org_hold" : false,
"timezone" : "Pacific Time (US/Can) (GMT-08:00)",
"region" : "",
"middle_name" : "",
"profile_type" : "1",
"surname" : "",
"other_phone" : "",
"zip" : "98104",
"org_pending" : "0",
"pager" : "",
"mobile_phone" : "",
"title" : "",
"first_name" : "Auto"
},
{
"home_phone" : "",
"bad_email" : false,
"state" : "",
"last_name" : "Tester",
"email" : "test949@69.julian.example.com",
"city" : "",
"fax" : "",
"url" : "",
"address" : "",
"id" : "949",
"country" : "",
"org_hold" : false,
"timezone" : "",
"middle_name" : "",
"region" : "",
"surname" : "",
"profile_type" : "1",
"other_phone" : "",
"zip" : "",
"org_pending" : "0",
"pager" : "",
"mobile_phone" : "",
"title" : "",
"first_name" : "Joe"
},
{
"home_phone" : "",
"bad_email" : false,
"state" : "",
"last_name" : "Tester",
"email" : "test950@69.julian.example.com",
"city" : "",
"fax" : "",
"url" : "",
"address" : "",
"id" : "950",
"country" : "",
"org_hold" : false,
"timezone" : "",
"middle_name" : "",
"region" : "",
"surname" : "",
"profile_type" : "1",
"other_phone" : "",
"zip" : "",
"org_pending" : "0",
"pager" : "",
"mobile_phone" : "",
"title" : "",
"first_name" : "Joe"
},
{
"home_phone" : "",
"bad_email" : false,
"state" : "",
"last_name" : "Tester",
"email" : "test951@69.julian.example.com",
"city" : "",
"fax" : "",
"url" : "",
"address" : "",
"id" : "951",
"country" : "",
"org_hold" : false,
"timezone" : "",
"middle_name" : "",
"region" : "",
"surname" : "",
"profile_type" : "1",
"other_phone" : "",
"zip" : "",
"org_pending" : "0",
"pager" : "",
"mobile_phone" : "",
"title" : "",
"first_name" : "Joe"
}
],
"count" : "4",
"page" : {
"this" : {
"batch" : 25,
"start" : 1
}
}
}
}
Try it!
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"
}
]
}
}
Try it!
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"
}
]
}
}
Try it!
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"
}
]
}
}
Try it!
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" : {}
}
Try it!
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"
}
}
Try it!
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" : {}
}
Try it!
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" : {}
}
Try it!
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" : {}
}
Try it!
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
Try it!
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
Try it!
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
Try it!
Updates the resume for a single account.
REQUIRED PARAMETERS
id or external_id
OPTIONAL PARAMETERS
expiration (defaults to 300) to specify valid lifetime of the returned URL in
seconds. Maximum 3600 (1 hour).
The response results will have an attribute url to which the new/updated resume
may be POSTed.
When posting to the returned url, one of the following content-types should be
specified:
* application/vnd.openxmlformats-officedocument.wordprocessingml.document
* application/msword
* text/plain
* text/rtf
* application/pdf
* application/vnd.ms-office
Upon success, the request to the url will return an HTTP 204 status code.
ACCOUNTPOINTS OBJECT
ACCOUNTPOINTS: BASIC ATTRIBUTES
ID
A unique identifier for this points record.
ACCOUNT_POINTS
The points for the record. A number from -100.000 to 100.000.
CREATED_BY
The ID of the account that created the record.
CREATED_BY_NAME
The screen name of created_by.
CREATED_DATE
The datetime the points were created, in UTC.
DATE
The date the points are for (e.g., the start_date of the shift, or the date
supplied in accountPoints.create), in the site’s timezone.
DISPLAY_DATE
The date formatted for the user.
DISPLAY_EXPIRATION_DATE
The expiration_date formatted for the user.
EXPIRATION_DATE
The date (no time) the points expire.
REASON
The text reason for the points. For ad hoc points, it is just the text of reason
(a string from 0 to 4096 bytes). For attendance points, it is the label
associated with reason_id.
REASON_ID
The ID of the reason given for the points, if created by an attendance action.
Else null.
SHIFT
A shift object, if attached to a shift. Else null.
TYPE
One of ad_hoc, absent, arrive_late, or leave_early.
ACCOUNTPOINTS.CREATE
> Request example:
{
"account" : 113,
"date" : "2020-07-02",
"account_points" : 10,
"reason" : "wore a New York Yankees t-shirt"
}
> Response example:
{
"result" : {
"id" : 1001
}
}
Try it!
Creates a new ad hoc accountPoints record.
REQUIRED PARAMETERS
account_points. Additionally, either date OR shift (a shift ID) is required, and
either account OR external_account.
OPTIONAL PARAMETERS
reason
RESPONSE
On success, an id attribute will provide the identifier for the new
accountPoints record.
ACCOUNTPOINTS.DELETE
> Request example:
{
"id" : 1001
}
> Response example:
{
"result" : {}
}
Deletes an ad hoc accountPoints record.
REQUIRED PARAMETERS
id
RESPONSE
On success, returns an empty object.
ACCOUNTPOINTS.LIST
> Request example:
{
"account" : 113
}
> Response example:
{
"result" : {
"account_points" : [
{
"account": "113",
"account_points" : 10,
"created_by" : 114,
"created_by_name" : "Deb Nicol",
"created_date" : "2020-07-02T20:59:19Z",
"date" : "2020-07-02",
"display_date" : "Thursday, July 2, 2020",
"display_expiration_date" : "Friday, Jan 1, 2100",
"expiration_date" : "2100-01-01",
"id" : 1001,
"reason" : "wore a New York Yankees t-shirt",
"reason_id" : null,
"shift" : null,
"type" : "ad_hoc",
"user_actions" : {
"delete" : true,
"edit" : true,
}
},
{
"account": "113",
"account_points" : 1,
"created_by" : 113,
"created_by_name" : "Jet the Dog",
"created_date" : "2020-07-01T13:50:22Z",
"date" : "2020-07-01",
"display_date" : "Wednesday, July 1, 2020",
"display_expiration_date" : "Thursday, July 1, 2021",
"expiration_date" : "2021-07-01",
"id" : 994,
"reason" : "Emergency",
"reason_id" : 36425,
"shift" : {
"display_adj_start_time" : "11:50pm",
"display_date" : "2020-07-15",
"display_end_time" : "11:30am (Thurs)",
"display_start_time" : "11:30pm",
"display_time" : "11:30pm - 11:30am (Thurs)",
"end_date" : "2020-07-01T20:00:00Z",
"id" : 323451686,
"local_arrive_late_datetime" : "2020-07-15T23:50:00",
"local_end_date" : "2020-07-16T11:30:00",
"local_start_date" : "2020-07-15T23:30:00",
"local_timezone" : "Central Time (US/Can) (GMT-06:00)",
"start_date" : "2020-07-01T13:00:00Z",
"workgroup" : 2699032,
"workgroup_label" : "Team A"
},
"type" : "absent",
"user_actions" : {
"delete" : false,
"edit" : false
}
}
],
"total" : 11,
"user_actions" : {
"create" : true
}
}
}
Try it!
Returns active accountPoints records for an account, sorted in reverse order by
date.
REQUIRED PARAMETERS
account or external_account
OPTIONAL PARAMETERS
USER_ACTIONS
Boolean; if specified and true, a user_actions object will be returned with
attributes indicating what actions may be presented to the user to perform on
each accountPoints object (edit, delete), and accountPoints actions on the
account itself (create).
Attendance account points cannot be edited or deleted directly, so booleans for
those will always be false.
RESPONSE
The response results account_points attribute will be an array of accountPoints.
Each element of the array will be an accountPoints object, including a
user_actions attribute.
Also returned will be a total attribute with the current total points for the
account, and a user_actions attribute.
ACCOUNTPOINTS.SHIFTLIST
> Request example:
{
"select" : {
"covering_member" : "114"
}
}
Try it!
Exactly the same as shift.list, except for the following differences:
* date parameters may not be specified; shifts after today (in the
organization's timezone) or shifts whose points would already be expired will
be excluded
* the results are ordered by shift start date, in reverse order
ACCOUNTPOINTS.UPDATE
> Request example:
{
"id" : 1001,
"date" : "2020-07-02",
"account_points" : 10,
"reason" : "wore a New York Yankees t-shirt"
}
> Response example:
{
"result" : {
"id" : 1003
}
}
Updates an ad hoc accountPoints record. A new record, with a new ID, will be
created in its place, with the updated information.
REQUIRED PARAMETERS
id
OPTIONAL PARAMETERS
reason, date OR shift (a shift ID), account_points
RESPONSE
On success, an id attribute will provide the identifier for the new
accountPoints record.
ATTESTATION OBJECT
attestation objects have the following attributes:
ID
Unique identifier (UUID) for this attestation. Automatically generated with
attestation.create.
ATTESTATION_TYPE_ID
ID for the related attestationType object. Required.
ACCOUNT
The account identifier for this attestation. Either account or external_account
is required.
EXTERNAL_ACCOUNT
The external account identifier for this attestation. Either account or
external_account is required.
ACTIVE
Boolean for whether this attestation is active. Default is the auto_activation
setting of the attestationType.
VALID
Boolean for whether this attestation is valid, based on whether it meets the
requirements of the attestationType (for example, if name_setting is required in
the type, and name is NULL in the attestation, the attestation is invalid). An
invalid attestation will not be used for shift conflict checking.
NAME
Name of the attestation object (255-character string). Optional (depending on
attestationType settings).
START_DATE
Date at which this attestation starts; null if attestation extends indefinitely
into the past. Optional (depending on attestationType settings).
END_DATE
Date at which this attestation ends; null if attestation extends indefinitely
into the future. Optional (depending on attestationType settings).
TIMEZONE
An IANA timezone name, e.g. America/Los_Angeles. See IANA Time Zone Database for
more information. Default is the timezone of the account, or if not set, the
site.
DOCUMENT
Boolean for whether this attestation has an attached document.
Additionally, there is a special kind of attestation objects called an
"exemption" record, used for when an account is exempt from that
attestationType. It is created/deleted with separate methods (attestation.exempt
and attestation.unexempt), and never modified.
Exemption attestation objects have the following attributes:
ID
Unique identifier (UUID) for this attestation. Automatically generated with
attestation.create.
ACCOUNT
The account identifier for this attestation. Either account or external_account
is required.
EXTERNAL_ACCOUNT
The external account identifier for this attestation. Either account or
external_account is required.
EXEMPT
Boolean for whether this attestation is an exemption record.
ATTESTATIONTYPE OBJECT
attestationType objects have the following attributes:
ID
Unique identifier (UUID) for this attestation. Automatically generated with
attestationType.create.
NAME
Name of the attestation type (255-character string). Must be unique. Required.
ENABLED
Boolean for whether this attestation type is enabled. Default is true.
HOLD_ACCOUNT
Boolean for whether accounts with this attestation type will be put on hold on
when the account falls into an "expired" state (i.e., it has attestations of
this type that have expired, and currently has no active attestations of this
type). Used only with advanced onboarding. Default is false.
AUTO_ACTIVATION
Boolean for whether a new attestation record defaults to active. Default is
true.
NAME_REQUIRED
START_DATE_REQUIRED
END_DATE_REQUIRED
DOCUMENT_REQUIRED
Setting for whether the attestation field is required for an attestation of this
type. When one of these settings is changed, the attestations of that type are
not modified, though whether they are valid may change. optional: in the API and
UI, but not required to be valid. required: in the API and UI, and required to
be valid. unused: not in the API or UI, and not required to be valid. One of
optional, required, unused. Default is optional.
EXAMPLE 1: If an attestation has a start_date and then the attestation type's
start_date_required is set to unused, the record will be treated as though its
start_date is blank, though the stored start_date will not change.
EXAMPLE 2: If start_date_required is then changed to optional or required, the
stored start_date will be used.
EXAMPLE 3: If the stored start_date is blank and start_date_required is changed
from optional or unused to required, the attestation will no longer be valid.
ATTESTATIONTYPE.LIST
> Request example:
{
"select" : {
"workgroup" : "226084"
}
}
> Response example:
{
"id" : "1",
"jsonrpc" : "2.0",
"result" : {
"attestationTypes" : [
{
"auto_activation" : false,
"document_required" : "optional",
"enabled" : true,
"end_date_required" : "optional",
"hold_account" : false,
"id" : "01234567-890a-bcde-f012-3456789abcde",
"name" : "Contract",
"name_required" : "optional",
"permissions" : "{}",
"start_date_required" : "optional"
},
{
"auto_activation" : false,
"document_required" : "optional",
"enabled" : true,
"end_date_required" : "optional",
"hold_account" : false,
"id" : "12345678-90ab-cdef-0123-456789abcdef",
"name" : "Certifications",
"name_required" : "optional",
"permissions" : "{}",
"start_date_required" : "optional"
}
]
},
"seconds" : "0.089939"
}
Try it!
Returns attestation type records for the org.
REQUIRED PARAMETERS
* select - An object specifying selection criteria for this request. Allowed
criteria are:
* workgroup (team)
RESPONSE
On success, the selected attestationType records will be returned as an array in
the "attestationTypes" key.
AVAILABILITY OBJECT
availability objects have the following attributes:
ID
Unique identifier for this availability.
ACCOUNT
Account identifier for this availability.
EXTERNAL_ACCOUNT
The external account identifier for this object.
NOTE: This field is only used or returned when external ids are enabled for the
site.
BUSY
false if the availability record indicates availability; true if it indicates
unavailability.
START_DATE
Date at which this availability starts; null if availability extends
indefinitely into the past.
END_DATE
Date at which this availability ends; null if availability extends indefinitely
into the future.
START_TIME
Start time for each date of this availability, in RFC 3339 partial time format
(e.g. "13:00:00"), or null if the availability extends from the beginning of the
day.
note: It is not possible to specify the seconds for start_time. This value
should always be set to: "00"
END_TIME
End time for each date of this availability, in RFC 3339 partial time format
(e.g. "13:00:00"), or null if the availability extends to the end of the day.
note: It is not possible to specify the seconds for end_time. This value should
always be set to: "00"
WORKGROUP
Workgroup identifier for this availability or null if no workgroup
SUNDAY
MONDAY
TUESDAY
WEDNESDAY
THURSDAY
FRIDAY
SATURDAY
true for all days of the week (within the date range, if specified) to which
this availability applies.
AVAILABILITY.APPROVE
Try it!
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
Try it!
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" : {}
}
Try it!
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
}
}
}
}
Try it!
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
}
]
}
}
Try it!
Get a summarized list of data for a given date range.
Required parameters:
START_DATE
END_DATE
Optional parameters:
WORKGROUPS
Selects only the included workgroups, if and only if array contains elements
INCLUDE_SHIFTS
Include shift information. If not defined, this property is set to true
SHIFTS
Additional configuration for what shift information to display. Options are as
follows:
COVERAGE_TYPE
Coverage type array with possible values of `mine`, `available`, `confirmed`,
`signup_list`, and `no_pick_up`. If not specified, all of these types are
included in the response.
INCLUDE_TIMEOFF
Include time off information. If not defined, this property is set to true
TIMEOFFREQUESTS
Additional configuration for what time off information to display. Options are
as follows:
STATUS
Accepts any valid timeOffRequest status
MEMBER
Only show data relevant to the specified member. Accepts the internal Shiftboard
Member ID (small integer).
EXTERNAL_MEMBER
Only show data relevant to the specified member. Accepts an external Member ID
(only if site is configured to use external IDs).
INCLUDE_TRADEBOARD
Include tradeboard information. If not defined, this property is set to true.
TRADEBOARD
Additional configuration for what tradeboard information to display. The only
option is:
TRADE_COMPLETE
Accepts Tradeboard's trade_complete
Response: On success, an array of summaries will be returned.
On error, one of the following error codes may be returned:
* Missing start_date
* Missing end_date
* Invalid exists value
* Invalid exists criteria
CLIENT OBJECT
client objects have the following attributes:
ID
A unique identifier for this client.
NAME
The name of this client. Maximum length 128 characters.
BUSINESS_NAME
Business name. Maximum length 100 characters.
ADDRESS
Address line (e.g. "123 Main St"). Maximum length 100 characters.
ADDRESS_SECOND
Second address line. Maximum length 100 characters.
CITY
City. Maximum length 100 characters.
STATE
Abbreviation or full name of state/province/subdivision. Maximum length 64
characters.
ZIP
Postal code. Maximum length 12 characters.
COUNTRY
Country. Maximum length 24 characters.
CONTACT_FIRST_NAME
First name of contact person. Maximum length 100 characters.
CONTACT_LAST_NAME
Last name of contact person. Maximum length 100 characters.
CONTACT_PHONE
Phone number of contact person. Maximum length 100 characters.
CONTACT_EMAIL
Email address of contact person. Maximum length 255 characters.
Notes
SPECIAL_INSTRUCTIONS
CLIENT.CREATE
> Request example:
{
"workgroup" : "226072",
"name" : "client 887"
}
> Response example:
{
"seconds" : "0.391969",
"jsonrpc" : "2.0",
"id" : "3",
"result" : {
"id" : "988"
}
}
> Request example with "exists_ok" set:
{
"workgroup" : "226072",
"name" : "client 887",
"exists_ok": true
}
> Response example when client didn't already exist:
{
"seconds" : "0.391969",
"jsonrpc" : "2.0",
"id" : "3",
"result" : {
"id" : "988",
"new": true
}
}
> Response example when client already existed:
{
"seconds" : "0.391969",
"jsonrpc" : "2.0",
"id" : "3",
"result" : {
"id" : "988",
"new": false
}
}
Try it!
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
Try it!
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"
}
}
Try it!
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"
}
]
}
}
Try it!
Returns information about clients. Uses pagination.
Optional parameters:
SELECT
An object specifying selection criteria for this request. Allowed criteria are:
CLIENT
A single client identifier or array of client identifiers.
SEARCH
A generic search string; select clients containing this string in their name.
WORKGROUP
The response results clients attribute will be an array of the current page of
clients. Each element of the array may have the following attributes:
ID
A unique identifier for this client.
NAME
The name of this client.
CLIENT.UPDATE
> Request example:
{
"special_instructions" : "test special instructions",
"contact_phone" : "5555551212",
"contact_last_name" : "test",
"country" : "USA",
"contact_first_name" : "client",
"state" : "WA",
"city" : "testmetro",
"zip" : 90210,
"notes" : "test note",
"contact_email" : "test@example.com",
"address_second" : "apt 1 test",
"address" : "123 test st",
"id" : "988",
"business_name" : "test"
}
> Response example:
{
"seconds" : "0.04165",
"jsonrpc" : "2.0",
"id" : "6",
"result" : {}
}
Try it!
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
Try it!
> 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"
}
}
Try it!
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
Try it!
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"
}
}
Try it!
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"
}
]
}
}
Try it!
Returns information about departments. Uses pagination.
Optional parameters:
SELECT
An object specifying selection criteria for this request. Allowed criteria are:
DEPARTMENT
A single department identifier or array of department identifiers.
SEARCH
A generic search string; select departments containing this string in their
name.
WORKGROUP
Single workgroup to filter results to be returned.
NOTE: If the call is made on behalf of a manager, the caller must also specify
the boolean value exclude_site to limit the results to only the workgroup
specified.
SHOW_ONLY_WORKGROUP_LISTABLES
Only return results for the workgroup.
EXCLUDE_SITE
Boolean; if a manager of the team, don't include departments associated with the
site itself with those for the team.
SITEWIDE
Boolean; query for all departments across all workgroups that the user has
access to. Enabled by default for manager accounts.
The response results departments attribute will be an array of the current page
of departments. Each element of the array may have the following attributes:
ID
A unique identifier for this department.
NAME
The name of this department.
DESCRIPTION
Description of the department
DEPARTMENT.UPDATE
> Request example:
{
"workgroup" : "226086",
"name" : "Test Department 949",
"id" : "949"
}
> Response example:
{
"seconds" : "0.116093",
"jsonrpc" : "2.0",
"id" : "56",
"result" : {}
}
Try it!
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",
}
}
Try it!
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"
}
]
}
}
Try it!
Returns information about direct managers. Uses pagination.
Optional parameters: select object with a direct_manager attribute identifying a
single direct manager or array of direct managers to be returned.
E.g.{select:{direct_manager:12345}}
The response results direct_managers attribute will be an array of the current
page of direct managers. Each element of the array may have the following
attributes:
Optional parameters:
SELECT
An object specifying selection criteria for this request. Allowed criteria are:
DIRECT_MANAGER
A single direct_manager identifier or array of direct_manager identifiers.
SEARCH
A generic search string; select direct_managers containing this string in their
name.
WORKGROUP
Single workgroup to filter results to be returned.
NOTE: If the call is made on behalf of a manager, the caller must also specify
the boolean value exclude_site to limit the results to only the workgroup
specified.
SHOW_ONLY_WORKGROUP_LISTABLES
Only return results for the workgroup.
EXCLUDE_SITE
Boolean; if a manager of the team, don't include direct_managers associated with
the site itself with those for the team.
SITEWIDE
Boolean; query for all direct_managers across all workgroups that the user has
access to. Enabled by default for manager accounts.
The response results direct_managers attribute will be an array of the current
page of direct_managers. Each element of the array may have the following
attributes:
ID
A unique identifier for this direct manager.
NAME
The name of this direct manager.
ACCOUNT
The Shiftboard id of the direct manager account
EXTERNAL_ACCOUNT
The external id of the direct manager account
NOTE: The external_account identifier will only be returned when the site is
configured to use external identifiers.
LOCATION OBJECT
location objects have the following attributes:
ID
A unique identifier for this location.
NAME
The name of this location. Maximum length 96 characters.
DESCRIPTION
A description of this location. Maximum length 255 characters.
ADDRESS
Address line (e.g. "123 Main St"). Maximum length 100 characters.
ADDRESS_SECOND
Second address line. Maximum length 100 characters.
CITY
City. Maximum length 100 characters.
STATE
Abbreviation or full name of state/province/subdivision. Maximum length 64
characters.
ZIP
Postal code. Maximum length 12 characters.
COUNTRY
Country. Maximum length 24 characters.
CONTACT_FIRST_NAME
First name of contact person. Maximum length 100 characters.
CONTACT_LAST_NAME
Last name of contact person. Maximum length 100 characters.
CONTACT_PHONE
Phone number of contact person. Maximum length 100 characters.
CONTACT_EMAIL
Email address of contact person. Maximum length 255 characters.
NOTES
SPECIAL_INSTRUCTIONS
LATLON
Optional latitude/longitude for more precise map location, e.g.
"34.015137,-118.791438".
DERIVED_LATLON
Latitude/longitude as calculated by the system, when possible; not updateable.
GEOFENCE_RADIUS
Allowed geofence radius for clocking in to shifts with this location, in meters;
only the following values are allowed: "-1" (no restriction), "10", "25", "50",
"100", "250", or null to use the site setting value.
GEOFENCE_ALLOW_IVR
Boolean; allow clocking in to shifts with this location via IVR, even when
geofencing is enforced and a geofence radius is set.
LOCATION.CREATE
> Request example:
{
"workgroup" : "226092",
"zip" : 90210,
"name" : "Test Location 0.287588880766943",
"description": "A test location named with a random floating-point identifier"
}
> Response example:
{
"seconds" : "1.616022",
"jsonrpc" : "2.0",
"id" : "15",
"result" : {
"id" : "29120"
}
}
Try it!
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" : {}
}
Try it!
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
}
}
}
}
Try it!
Returns information about locations. Uses pagination.
Optional parameters:
SELECT
An object specifying selection criteria for this request. Allowed criteria are:
LOCATION
A single location identifier or array of location identifiers.
SEARCH
A generic search string; select locations containing this string in their name.
DEPARTMENT
Single department or array of departments to be returned.
WORKGROUP
Single workgroup to filter results to be returned.
NOTE: If the call is made on behalf of a manager, the caller must also specify
the boolean value exclude_site to limit the results to only the workgroup
specified.
SHOW_ONLY_WORKGROUP_LISTABLES
Only return results for the workgroup.
EXCLUDE_SITE
Boolean; if a manager of the team, don't include 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" : {}
}
Try it!
Updates a location object.
Required parameter: id. Any other location object attributes may be specified.
Response: On success, empty results will be returned.
MANAGERNOTE OBJECT
MANAGERNOTE: BASIC ATTRIBUTES
ID
A unique identifier for this managerNote.
ACCOUNT
Identifier of the account to which this managerNote is assigned.
ACTIVITY_DATE
The date of the manager note activity
ADMIN_ONLY
Boolean; indicates this managerNote is accessible only to site administrators
CREATED_BY
The account identifier of the account that created the manager note record
CREATION_DATE
The date and UTC time the manager note record was created
LAST_UPDATED
Date and UTC time managerNote was updated
CUSTOM_BOOLEAN_[NUMBER]
Boolean; If enabled in the application settings, the value of the custom boolean
associated with the manager note record
CUSTOM_DROPDOWN_[NUMBER]
If enabled in the application settings, the value of the custom dropdown
selected associated with the manager note record
CUSTOM_TEXTAREA_[NUMBER]
If enabled in the application settings, the value of the custom textarea
associated with the manager note record
NOTE_TYPE
The selected note type of the manager note record or null if no type
NOTES
The notes associated with the manager note record
SCORE
The score associated with the manager note record
SHIFT
The shift associated with the manager note record or null if no shift
UPDATED_BY
The site user who last updated the manager note record
WORKGROUP
The workgroup associated with the manager note record
Not all fields will be configured to be used for all organizations or set for
all managerNote.
MANAGERNOTE.CUSTOMFIELDS
> Request example:
{}
> Response example:
{
"custom_fields" : [
{
"label" : "ImaBoolean",
"name" : "custom_boolean_1",
"type" : "boolean"
},
{
"label" : "ImaDropdown",
"name" : "custom_dropdown_3",
"type" : "dropdown",
"values" : [
"a",
"b",
"c"
]
},
{
"label" : "ImaTextarea",
"name" : "custom_textarea_2",
"type" : "textarea"
}
]
}
Try it!
Returns information about configured manager notes custom fields.
Parameters: none
MANAGERNOTE.GET
> Request example:
{
"select" : {
"start_date" : "2019-01-01",
"end_date" : "2019-01-01",
},
"user_actions" : true
}
> Response example:
{
"manager_note": {
"account": "1",
"activity_date": null,
"admin_only": false,
"created_by": "1",
"creation_date": "2019-01-01 18:27:36",
"custom_boolean_1": true,
"custom_dropdown_1": "first option",
"custom_textarea_1": "text found in the text area",
"id": "11111",
"last_updated": "2019-01-01 18:27:36",
"note_type": "1234",
"notes": "These are some notes",
"org_id": "1",
"score": "11",
"shift": "12345",
"updated_by": "1",
"user_actions": {
"delete": true,
"edit": true
},
"workgroup": "999999"
},
"referenced_objects": {
"account": [
{
"id": "1",
"name": "User Account Name"
}
],
"custom_dropdown": [
{
"name": "custom_dropdown_1",
"values": [
"first option",
"second option",
]
}
],
"note_type": [
{
"id": "1234",
"name": "Note Type Selected",
"org_id": "1"
}
],
"score": [
"11 - Excellent"
],
"workgroup": [
{
"id": "999999",
"name": "Workgroup Name"
}
]
}
}
Try it!
Returns information about a manager note
Parameters:
ID
Required. id of the manager note for which to return information.
USER_ACTIONS
Boolean; if specified and true, a user_actions object will be returned with
attributes indicating what actions may be presented to the user to perform on
this manager note.
MANAGERNOTE.LIST
> Request example:
{
"select" : {
"start_date" : "2019-01-01",
"end_date" : "2019-01-01",
},
"user_actions" : true
}
> Response example:
{
"count": "2",
"manager_notes": [
{
"account": "2",
"activity_date": null,
"admin_only": false,
"created_by": "1",
"creation_date": "2019-01-01 18:27:36",
"id": "12345",
"note_type": "7317",
"notes": "These are some notes",
"score": "11",
"shift": null,
"updated_by": null,
"user_actions": {
"delete": true,
"edit": true
},
"workgroup": "9999"
},
{
"account": "7",
"activity_date": null,
"admin_only": false,
"created_by": "1",
"creation_date": "2019-01-01 12:27:09",
"id": "685471",
"note_type": "1",
"notes": "These are some notes",
"score": "8",
"shift": null,
"updated_by": null,
"user_actions": {
"delete": false,
"edit": false
},
"workgroup": "1111"
}
],
"page": {
"this": {
"batch": 10,
"start": 1
}
},
"referenced_objects": {
"account": [
{
"id": "2",
"name": "Account Name"
},
{
"id": "7",
"name": "Account Name"
}
],
"note_type": [
{
"id": "1",
"name": "Note type",
"org_id": "11111"
}
],
"score": [
"11 - Excellent",
"8 - Good"
],
"workgroup": [
{
"id": "9999",
"name": "Workgroup Name"
},
{
"id": "1111",
"name": "Workgroup Name"
}
]
}
}
Try it!
Returns information about manager notes. Uses pagination.
Optional parameters:
USER_ACTIONS
Boolean; if specified and true, a user_actions object will be returned with
attributes indicating what actions may be presented to the user for each manager
note returned.
SELECT
An object specifying selection criteria for this request.
WORKGROUP
Workgroup identifier; filter results by workgroup
ACCOUNT
Account identifier; filter results by account
ADMIN_ONLY
Boolean; Only return notes that are or are not accessible only to the site
administrator
START_DATE
Creation start date; if included, end_date is required. Filter results to those
notes created in the specified date range.
END_DATE
Creation end date; if included, start_date is required. Filter results to those
notes created in the specified date range.
ACTIVITY_START_DATE
Activity start date; if included, activity_end_date is required. Filter results
to those notes with activity in the specified date range.
ACTIVITY_START_DATE
Activity end date; if included, activity_start_date is required. Filter results
to those notes with activity in the specified date range.
SHIFT
Shift identifier; filter results by shift
NOTE_TYPE
Note type identifier; filter results by note type
NO_ACTIVITY
Boolean; limit results to those manager notes that have had no activity
MANAGERNOTE.CREATE
> Request example:
{
"account": 1,
"score": 10,
"admin_only": true,
"notes": "Notes to be read by admin only",
"shift": 12345
}
> Response example:
{
"id": 123456789
}
Try it!
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:
{}
Try it!
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:
{}
Try it!
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"
}
]
}
Try it!
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
}
Try it!
Creates a new manager note type.
Note: This method is only accessible to site administrators.
REQUIRED PARAMETERS
* name - A unique name is required
MANAGERNOTETYPE.DELETE
> Request example:
{
"id": 12345
}
> Response example:
{}
Try it!
Delete a new manager note type.
Note: This method is only accessible to site administrators.
REQUIRED PARAMETERS
* id
MANAGERNOTETYPE.UPDATE
> Request example:
{
"id": 12345,
"name": "Updated Manager Note Type Name"
}
> Response example:
{}
Try it!
Updates a new manager note type.
Note: This method is only accessible to site administrators.
REQUIRED PARAMETERS
* id
* name - A unique name is required
MEMBERSHIP OBJECT
membership objects have the following attributes:
ID
Pseudo-id (workgroup-member) for callers that need a fixed ID string.
MEMBER
The account identifier for this membership.
EXTERNAL_ACCOUNT
The external account identifier for this object.
NOTE: This field is only used or returned when external ids are enabled for the
site.
WORKGROUP
The workgroup identifier for this membership.
LEVEL
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" : {}
}
Try it!
Creates new workgroup/account memberships.
Required parameters:
MEMBER
A single account identifier or an array of identifiers of accounts for which to
create memberships for each specified workgroup.
NOTE: If you are calling this method with the external_member parameter, member
is not required.
EXTERNAL_MEMBER
A single external account identifier or an array of external identifiers of
accounts for which to create memberships for each specified workgroup.
NOTE: If you are calling this method with the member parameter, external_member
is not required, and will be ignored.
WORKGROUP
A single workgroup identifier or an array of identifiers of workgroups for which
to create memberships for each specified account.
LEVEL
User level for which to create memberships.
TIER
Optional; tier at which to create memberships if membership tiers are enabled.
No more than 10,000 memberships may be specified in one request.
If one or more of the specified memberships already exist, the remaining
memberships (if any) will be created and no error will be returned. Existing
user levels will remain unchanged.
Response: On success, empty results will be returned.
MEMBERSHIP.DELETE
> Request example:
{
"workgroup" : "226094",
"member" : 950
}
> Response example:
{
"seconds" : "0.055246",
"jsonrpc" : "2.0",
"id" : "37",
"result" : {}
}
Try it!
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
}
}
}
}
Try it!
Returns information about workgroup/account memberships. Uses pagination. Uses
select criteria.
Required parameters:
SELECT
An object specifying selection criteria for this request. Either member or
workgroup must be specified. The available criteria include:
MEMBER
A single account identifier or an array of account identifiers indicating
accounts for whom to return memberships.
NOTE: If you are calling this method with the external_member parameter, member
is not required.
EXCLUDE_WORKGROUP
A single workgroup identifier, or an array of workgroup identifiers. Any
accounts returned must not belong to these workgroups.
INCLUDE_WORKGROUP
A single workgroup identifier. Any accounts returned must belong to this
workgroup.
EXTERNAL_MEMBER
A single external account identifier or an array of external account identifiers
indicating accounts for whom to return memberships.
NOTE: If you are calling this method with the external_member parameter, member
is not required.
WORKGROUP
A single workgroup identifier or an array of workgroup identifiers indicating
workgroup for which to return memberships.
LEVEL
User level of memberships to return.
TIER
Tier or array of tiers of memberships to return.
ORG_HOLD
Boolean; if specified and true, indicates that accounts on hold should be
included in the returned results.
ORG_PENDING
Boolean; if specified and true, indicates that accounts with pending status
should be included in the returned results.
REFERENCED_OBJECTS
Boolean, defaults to true. Indicates that, in addition to the memberships
attribute, the results should include a referenced_objects attribute giving
information about the accounts and workgroups referred to by the returned
memberships.
The response results memberships attribute will be an array of the current page
of memberships. Each element of the array will be a membership object.
If requested, the response results referenced_objects attribute will be an
object containing one or more object type names as attributes; for each object
type the value will be an array of those instances of that type of object which
are referred to in the memberships results, with only selected minimal
attributes provided:
ACCOUNT
id, first_name, last_name, screen_name, and email attributes are provided.
WORKGROUP
id and name attributes are provided.
MEMBERSHIP.LISTEXCLUDED
> Request example:
{
"workgroup" : [
2,
1171
]
}
> Response example:
{
"seconds" : "0.035573",
"jsonrpc" : "2.0",
"id" : "",
"result" : {
"count" : 2,
"members" : [
{
"member" : "2",
"profile_type_id" : "1"
},
{
"member" : "3",
"profile_type_id" : "1"
}
],
"referenced_objects" : {
"account" : [
{
"email" : "pjones@example.com",
"external_id" : "42648",
"id" : "2",
"first_name" : "Paul",
"last_name" : "Jones",
"screen_name" : "Paul Jones"
},
{
"email" : "susana@example.com",
"external_id" : "46037",
"id" : "3",
"first_name" : "Susan",
"last_name" : "Adams",
"screen_name" : "Susan Adams"
}
]
},
"page" : {
"next" : {
"batch" : 2,
"start" : 3
},
"this" : {
"batch" : 2,
"start" : 1
}
}
}
}
Try it!
Returns information about accounts that are not members of the given workgoups.
Uses pagination. Uses select criteria.
Required parameters:
REFERENCED_OBJECTS
Boolean, defaults to true. Indicates that, in addition to the memberships
attribute, the results should include a referenced_objects attribute giving
information about the accounts referred to.
The response results members attribute will be an array of the current page of
accounts. Each element of the array will be a member object.
If requested, the response results referenced_objects attribute will be an
object containing one or more object type names as attributes; for each object
type the value will be an array of those instances of that type of object which
are referred to in the members results, with only selected minimal attributes
provided:
ACCOUNT
id, first_name, last_name, screen_name, and email attributes are provided.
MEMBERSHIP.TIERLIST
> Request example:
{
}
> Response example:
{
"seconds" : "0.017018",
"jsonrpc" : "2.0",
"id" : "3",
"result" : {
"tiers": {
"10" : "Platinum",
"7" : "Copper",
"8" : "Silver",
"9" : "Gold"
}
}
}
Try it!
Shows membership tiers that are enabled.
Response: An object with tier identifiers ("1" through "10") as attributes and
the corresponding labels for those tiers as values.
MEMBERSHIP.UPDATE
> Request example:
{
"workgroup" : 132994,
"level" : 4,
"member" : 946
}
> Response example:
{
"seconds" : "0.068018",
"jsonrpc" : "2.0",
"id" : "3",
"result" : {}
}
Try it!
Updates user levels for workgroup/account memberships.
Required parameters:
MEMBER
A single account identifier or an array of identifiers of accounts for which to
update memberships for each specified workgroup.
NOTE: If you are calling this method with the external_member parameter, member
is not required.
EXTERNAL_MEMBER
A single external account identifier or an array of external identifiers of
accounts for which to update memberships for each specified workgroup.
NOTE: If you are calling this method with the member parameter, external_member
is not required.
WORKGROUP
A single workgroup identifier or an array of identifiers of workgroups for which
to update memberships for each specified account. Currently, only a single
workgroup may be specified.
LEVEL
User level to which to update memberships.
TIER
Optional; tier to which to update memberships if membership tiers are enabled.
If one or more of the specified memberships doesn't exist, the remaining
memberships (if any) will be updated and no error will be returned.
Response: On success, empty results will be returned.
MESSAGE OBJECT
MESSAGE.BROADCAST
> Request example:
{
"message" : "everyone get out of the building now",
"subject" : "read this when you have time",
"sender" : {
"name" : "Your Boss",
"email" : "your.boss@example.com"
},
"cc" : true,
"sms" : true,
"workgroups" : ["1", "2"],
"location" : "3",
"client" : "4",
"department" : "5",
"role" : "6",
"reference_id" : "my event id",
"profile_type" : "7",
"tier" : "8",
"level" : ["level"],
"score" : {
"no_score" : true,
"value" : "10",
"cmp" : ">="
},
"org_hold" : false,
"org_pending" : 2,
"restrict_delivery" : {
"type" : "with_assignment",
"start_date" : "2018-07-01T00:00:00",
"end_date" : "2018-08-01T00:00:00",
"dates" : ["2018-08-02","2018-08-03"]
},
"link_account" : true,
"link_referrals" : true,
"link_schedule" : true,
"login_info" : true,
"personalize" : true,
"zip" : {
"zip_code" : "98101",
"range" : "50"
}
}
> Response example:
{
"id" : "1",
"jsonrpc" : "2.0",
"result": {
"sent": [
{
"account": "My User",
"email": "my.user@example.com",
"id": "8"
},
{
"account": "Your User",
"email": "your.user@example.com",
"id": "92"
}
],
"sent_count": 2,
"warning": [
{
"message": "Message could not be sent to addresses marked as undeliverable",
"unsent": [
{
"account": "Some User",
"email": "some.user@example.com",
"id": "234"
}
],
"unsent_count": 1
}
]
},
"seconds" : "0.089939"
}
Try it!
Sends a broadcast message. Only site admins can send messages to everyone.
Managers can send messages to the workgroups they manage; coordinators can do
the same, if the site is set to allow it.
REQUIRED PARAMETERS
* subject - text string of the message subject
* level - array of strings for what level of accounts to send to. For site
messages: member, team_mgr, site_admin; For workgroup messages: member,
coordinator, manager (ignored for coordinators)
* workgroups - array of workgroup IDs to send to (required unless site admin)
OPTIONAL PARAMETERS
* return_sent_accounts - the number of accounts to return a success for in
result.sent; if this limit is exceeded, no results are returned (default 0,
no results)
* return_unsent_accounts - the number of accounts to return warnings for in
result.warning.emails; if this limit is exceeded, no warnings are returned
(default 0, no results)
* message - plain text message
* sender - object describing the sender of the message
* email - email address of the sender (default: email address of the sending
account)
* name - name of the sender (default: none)
* cc - boolean to send copy back to sending account (default: false)
* sms - boolean to also send message via SMS (default: false)
* link_account - boolean to include the account link in the message (default
false)
* link_referrals - boolean to include the referral link in the message (default
false)
* link_schedule - boolean to include the schedule link in the message (default
false)
* login_info - boolean to include the login info in the message (default false)
* personalize - boolean to personalize the message (default false)
OPTIONAL FILTERS
Filters further resrict which accounts to send the message to. Defaults are no
additional restrictions.
* tier - an exact team tier (must match the account's tier for one or more of
the specified workgroups) (numeric value)
* profile_type - the profile of the accounts to send to
* org_hold - boolean whether to send users on admin hold (default false)
* org_pending - an onboarding status (may only be specified if org_hold is
false)
* score - object describing the score of the accounts to send to
* value - the score value
* cmp - a string for the comparison operator, one of: >= (or better;
default), <= (or worse), == (exactly)
* no_score - also include accounts with no score
* zip - object of ZIP code restrictions
* zip_code - ZIP code to restrict to
* range - distance in miles from the ZIP code (default: 0)
* restrict_delivery - object describing who to further restrict delivery to. It
has a type, and then other restrictions, including date ranges for the type,
etc.
* Example: if without_assignment is selected, with a start_date of
2018-08-01, end_date of 2018-08-07, and location of 1001, then only
accounts who were not assigned a shift for that location, between those
dates, will be sent the message.
* NOTES
* options relating to shifts specifically only apply to a type of
with_assignment, without_assignment, and without_acknowledgment
* signed_on and not_signed_on only apply to org messages, not workgroup
messages
* no options apply to a type of everyone
* start_date and end_date must both be set for start_date, end_date, dates,
or start_time to be used
* type - string of one of the following values
* everyone - all matching accounts (default)
* with_assignment - if the account was assigned a shift
* without_assignment - if the account was not assigned a shift
* signed_on - if the account was signed on
* not_signed_on - if the account was not signed on
* without_acknowledgment - if the account did not acknowledge a shift
* start_date - a date at or after to restrict the type (signed on, didn't
sign on, had assignment, didn't have assignment, or didn't acknolwedge, at
or after this datetime)
* end_date - a date at or before to restrict the type
* dates - array of additional arbitrary dates for restricting
* start_time - the time the shift started (in HH:MM:SS format)
* location - the location ID for the shift
* client - the client ID for the shift
* department - the department ID for the shift
* role - the role ID for the shift
* reference_id - the reference ID for the shift
RESPONSE
On success, include the list of addresses sent to in the sent key, and a list of
warning objects, if any addresses could not be sent to.
MESSAGE.DIRECT
> Request example:
{
"message" : "everyone get out of the building now",
"subject" : "read this when you have time",
"account" : [1, 23, 45, 72],
"sms" : true,
"urgent" : true
}
> Response example:
{
"id" : "1",
"jsonrpc" : "2.0",
"result": {
"sent": [
{
"account": "Bri Lum",
"email": "364@servola.org",
"email_sent": "1",
"id": "364",
"sms_sent": ""
},
{
"account": "Charlie Watts",
"email": "2834156@servola.org",
"email_sent": "1",
"id": "2834156",
"sms_sent": "1"
}
],
"sent_count": 2,
"warning": [
{
"message": "Message could not be sent to addresses marked as undeliverable",
"unsent": [
{
"account": "Andrew Allison",
"email": "3953240@ishifts.com",
"email_sent": "",
"id": "3953240",
"sms_sent": ""
},
{
"account": "Bri Lum",
"email": "364@servola.org",
"email_sent": "1",
"id": "364",
"sms_sent": ""
}
],
"unsent_count": 2
},
{
"message": "Not Authorized to send email to account",
"unsent": [
{
"account": "Paul Allison",
"email": "2834193@servola.org",
"id": "2834193"
}
],
"unsent_count": 1
}
]
},
"seconds" : "0.03719"
}
Try it!
Sends a direct message. Only site admins can send messages to everyone. Managers
can send messages to members of the workgroups they manage; coordinators can do
the same, if the site is set to allow it, members can can only send messages to
primary contact of their workgroup and to contact for the site.
REQUIRED PARAMETERS
One of account and external_account is required * account - the account
(shiftboard_id) to direct message or an array of account identifiers
NOTE: If you are calling this method with the account parameter,
external_account will be ignored (if included).
* external_account - the external_account (external_id) to direct message or an
array of external account identifiers
OPTIONAL PARAMETERS
* subject - text string of the message subject
* message - plain text message
* urgent - boolean to mark message as urgent (default: false)
* sms - boolean to also send message via SMS if site configured (default:
false)
RESPONSE
On success, include the list of addresses sent to in the sent key, and a list of
warning objects, if any addresses could not be sent to or if sender is not
authorized to send to account. The section warning can have two sub-sections,
one for messages that was not fully sent out due to either a bad email address
or missing sms number. The other section contains account that user is not
authorized to message.
Note that account "Bri Lum" is included in both section 'sent' and in 'warning'
for messages marked as undeliverable. The reason is that the request was to
email and sms but in this case no sms was sent out. See the two status
indicators "sms_sent" and "email_sent"
NEWS OBJECT
NEWS.GET
> Request example:
{}
> Response example:
{
"seconds" : "0.065741",
"jsonrpc" : "2.0",
"id" : "7",
"result" : {
"news" : {
"member" : "Member news goes here",
"team" : {
"Example" : {
"news" : "This is the news section for my Workgroup"
}
},
"manager" : "Manager news goes here"
}
}
}
Try it!
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
}
}
Try it!
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" : {}
}
Try it!
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" : {}
}
Try it!
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
Try it!
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
Try it!
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" : ""
}
}
Try it!
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" : ""
}
]
}
}
Try it!
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
Try it!
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"
}
]
}
}
Try it!
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"
}
]
}
}
Try it!
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"
]
}
]
}
}
Try it!
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" : {}
}
Try it!
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",
}
]
}
]
}
}
Try it!
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
}
}
Try it!
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
Try it!
> 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"
}
}
Try it!
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
Try it!
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"
}
}
Try it!
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" : {}
}
Try it!
Enables or disables roles for a member of a workgroup that uses restricted
roles.
EXTERNAL_ACCOUNT
external account ID to be updated, if this organization uses external IDs.
ACCOUNT
account to be updated
WORKGROUP
workgroup the member belongs to
ROLE
One or more ids of roles that are associated with the given workgroup.
ENABLE
false if the specified roles shoud be disabled for this member; otherwise the
specified roles will be enabled.
ROLE.LIST
> Request example:
{
"select" : {
"role" : "2281"
}
}
> Response example:
{
"seconds" : "0.115639",
"jsonrpc" : "2.0",
"id" : "4",
"result" : {
"roles" : [
{
"name" : "role 813",
"id" : "2281"
}
],
"count" : "1",
"page" : {
"this" : {
"batch" : 25,
"start" : 1
}
}
}
}
Try it!
Returns information about roles. Uses pagination.
Optional parameters:
SELECT
An object specifying selection criteria for this request. Allowed criteria are:
ROLE
A single role identifier or array of role identifiers.
SEARCH
A generic search string; select roles containing this string in their name.
WORKGROUP
Single workgroup to filter results to be returned.
NOTE: If the call is made on behalf of a manager, the caller must also specify
the boolean value exclude_site to limit the results to only the workgroup
specified.
SHOW_ONLY_WORKGROUP_LISTABLES
Only return results for the workgroup.
EXCLUDE_SITE
Boolean; if a manager of the team, don't include roles associated with the site
itself with those for the team.
SITEWIDE
Boolean; query for all roles across all workgroups that the user has access to.
Enabled by default for manager accounts.
The response results roles attribute will be an array of the current page of
roles. Each element of the array may have the following attributes:
ID
A unique identifier for this role.
NAME
The name of this role.
ROLE.UPDATE
> Request example:
{
"workgroup" : "226086",
"name" : "Test Role 2282",
"id" : "2282"
}
> Response example:
{
"seconds" : "0.141744",
"jsonrpc" : "2.0",
"id" : "52",
"result" : {}
}
Try it!
Updates a role object.
Required parameter: id. Any other role object attributes may be specified.
Response: On success, empty results will be returned.
SHIFT OBJECT
SHIFT: BASIC ATTRIBUTES
ID
A unique identifier for this shift.
COUNT
The number of positions represented by this shift record.
QTY
The total number of positions represented by this and associated records.
START_DATE
The date or date and time on which this shift begins. For an all-day shift, this
is date in RFC 3339 full date format (e.g. "2009-04-01"). Otherwise, this is a
datetime (e.g. "2009-04-01T13:00:00").
END_DATE
The date and time on which this shift ends, (e.g. "2009-04-01T17:00:00"). Not
specified for all-day or open-ended shifts.
dur_hrs Integer; shift duration in hours. Required when creating a shift with a
use_time value of 2. Likewise this value will only be returned when querying for
shifts whose use_time value is equal to 2.
dur_mins Integer; shift duration in minutes. Required when creating a shift with
a use_time value of 2. Likewise this value will only be returned when querying
for shifts whose use_time value is equal to 2.
TIMEZONE
The timezone for which the shift is scheduled.
WORKGROUP
The shift's workgroup.
SUBJECT
The shift's subject. Maximum length 100 characters.
LOCATION
The location id for the shift, if specified.
ROLE
The role id for the shift, if specified.
CLIENT
The client id for the shift, if specified.
DEPARTMENT
The department id for the shift, if specified.
COVERED
true if the shift is covered.
PUBLISHED
true if the shift is published.
URGENT
true if the shift is critical to have covered.
COVERING_MEMBER
If the shift is covered by a member, the id of the member's account.
EXTERNAL_COVERING_MEMBER
If the shift is covered by a member, the external id of the member's account.
USE_TIME (DEPRECATED)
Integer; shift type identifier. Valid use_time values are in the range of 1-5.
1: shift/coverage block 2: start time/duration 3: start/end time 4: open
ended/tbd 5: anytime
TIME_BLOCK
Integer; time block identifier. Required when creating a shift with a use_time
value of 1. Likewise this value will only be returned when querying for shifts
whose use_time value is equal to 1.
SHIFT: EXTENDED ATTRIBUTES
DETAILS
Additional details about the shift.
NO_PICK_UP
Boolean
SIGNUP_LIST
Boolean
NO_TRADE
Boolean
REFERENCE_ID
WORK_STATUS_TYPE
The workStatusType id for the shift, if specified.
LINKTITLE
LINKURL
ROOM_FLOOR
ZIPCODE
PAY_RATE
BASE_RATE
NO_CREDIT
Boolean
EXTRA_CREDIT
ABSENT_REASON
Integer
ARRIVE_LATE_DATETIME
Datetime
ARRIVE_LATE_REASON
Integer
ARRIVE_LATE_REASON_LABEL
String
LEAVE_EARLY_DATETIME
Datetime
LEAVE_EARLY_REASON
Integer
LEAVE_EARLY_REASON_LABEL
String
CUSTOM_TEXT_1
CUSTOM_TEXT_2
CUSTOM_TEXT_3
CUSTOM_MULTIPICK
Array of custom_multipick identifiers for the shift
ACKNOWLEDGED
Boolean; shift has been acknowledged or declined (declined if
acknowledge_decline_reason is not null).
ACKNOWLEDGED_AT
Date/time of acknowledgement or most recent modification to the acknowledgement.
ACKNOWLEDGE_DECLINE_REASON
Decline reason identifier; present only if declined.
ACKNOWLEDGED_NOTES
RESOURCE
Array of resource identifiers for this shift
CUSTOM_DROPDOWN_1
CUSTOM_DROPDOWN_2
CUSTOM_DROPDOWN_3
CUSTOM_DROPDOWN_4
CUSTOM_DROPDOWN_5
CUSTOM_DROPDOWN_6
CUSTOM_DROPDOWN_7
CUSTOM_DROPDOWN_8
CUSTOM_DROPDOWN_9
CUSTOM_DROPDOWN_10
CUSTOM_DROPDOWN_11
CUSTOM_DROPDOWN_12
CUSTOM_DROPDOWN_13
CUSTOM_DROPDOWN_14
CUSTOM_DROPDOWN_15
CUSTOM_TEXTAREA
CREATED
UTC time shift was created
STATUS_UPDATED
UTC time shift was published, unpublished, assigned, confirmed, or unconfirmed
UPDATED
UTC time shift was otherwise updated
BREAKS
Array of breaks for the shift; each break has the following attributes:
NAME
START_TIME
The time in which a shift break starts, in RFC 3339 full date format (e.g.
"2009-04-01").
DISPLAY_TIME
DURATION_MINUTES
PAID
Boolean.
IS_A_TRADE
Boolean; true if this shift has been offered for trade by the covering member.
Not all fields will be configured to be used for all organizations or set for
all shifts.
ABSENT_REASON - INTEGER
ARRIVE_LATE_REASON - INTEGER
LEAVE_EARLY_REASON - INTEGER
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"
}
}
Try it!
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"
}
}
Try it!
Assign a shift. Can also publish the shift and/or mark the shift as
acknowledged.
REQUIRED PARAMETER
ID
ID of the shift to be assigned.
COVERING_MEMBER OR EXTERNAL_COVERING_MEMBER
ID of member to whom the shift is to be assigned.
OPTIONAL PARAMETERS
PUBLISH
set to true to publish the shift
ACKNOWLEDGE
set to true to acknowledge shift
NO_NOTIFY
set to true to disable notification
ASSIGNABILITY_CHECKS
set to false to disable processing of Assignability parameters
ASSIGNABILITY PARAMETERS
To use assignability checks, the assignability_checks parameter must be true or
not specified; additionally, the following options may be available, based on
enabled features:
conflicts_ok - boolean
daily_overtime_ok - boolean
weekly_overtime_ok - boolean
timeoff_ok - boolean
consecutive_days - boolean
short_turnaround - boolean
ignore_attestation_types - boolean
attestation_type - array of attestationTypeId
ignore_role - boolean
SHIFT.BULKDELETE
Delete multiple shifts with a single call. This method processes bulk deletes
asynchronously, meaning the caller will be returned a success message
immediately (assuming valid parameters were sent), and the processing of these
shift delete operations will happen out-of-band. Once all shift deletions have
completed, a report will be emailed to the API caller. This report will detail
the number of successes, failures, and provide details about why a failure
occurred.
> Request example:
{
"shifts" : [2753501, 2753502],
}
> Response example:
{
"seconds" : "0.178901",
"jsonrpc" : "2.0",
"id" : "43",
"result" : {
"message": "Bulk delete has been started. You will receive an email with results."
}
}
Try it!
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.
Try it!
Deletes a shift record.
Required parameter: id.
Optional Parameters:
notify_on_delete Boolean; if the shift is assigned, notify covering member upon
deletion of the shift.
notify_message Custom text to be included when notifying shift owner upon
deletion of shift.
SHIFT.BULKUPLOAD
Prepare the system to ingest and process a spreadsheet file containing one or
more shift records. Upon executing this method, the caller will receive a unique
identifier and unique upload URL that is valid for the next 10 minutes. The
identifier can be used in conjunction with shift.bulkUploadStatus to poll the
current status of the bulk upload operation.
In order to upload a file to the URL specified, the file should be POSTed with
the content-type header matching the file type for the file being uploaded. If a
file is POSTed with a content-type header that does not match the file type
being uploaded to the server, an error will occur and the file will NOT be
processed.
Valid file types are xls, xlsx, and csv.
VALID CONTENT-TYPE HEADERS AND FILE ASSOCIATIONS
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"
}
Try it!
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.
Try it!
> Request example:
{}
> Response example:
{
"bulk_upload_settings": {
"add_org_custom_multipick": true,
"add_org_custom_multipick_2": false,
"add_org_member": true,
"add_org_venue": true,
"add_team": false,
"add_time_block": false,
"auto_conflicts_ok": false,
"auto_is_available": true,
"auto_timeoff_ok": false,
"by_seniority": false,
"conflicts_ok": false,
"include_holds": true,
"is_available": false,
"notify": true,
"past_dates": false,
"seniority_required": false,
"single_shift_per_day": true,
"timeoff_ok": false,
"use_acct_org_id_off": false
}
}
REQUIRED PARAMETERS
None
OPTIONAL PARAMETERS
None
CONFIGURATION SETTINGS
Where items do not already exist setting|Description| --|-- add_team|Create New
Teams add_venue|Create New Locations add_role|Create New Roles add_client|Create
New Clients add_department|Create New Departments add_custom_multipick|Create
New MP Labels add_custom_multipick_2|Create New Custom Multipick
add_resource|Create New Resources add_time_block|Create New Shift/Coverage
Blocks
Where associations do not already exist setting|Description| --|--
add_org_venue|Add Locations/Maps to Teams add_org_role|Add Roles to Teams
add_org_client|Authorize Clients to Teams add_org_department|Authorize
Departments to Teams add_org_custom_multipick|Authorize MP Labels to Teams
add_org_custom_multipick_2|Authorize Custom Multipick to Teams
add_org_resource|Authorize Resources to Teams add_org_time_block|Add Shift
Blocks to Teams
When making assignments setting|Description| --|-- conflicts_ok|Allow Conflicts
is_available|Listed in Available
timeoff_ok|Ignore approved Time Off
include_holds|Assign to members in hold/inactive status add_org_member|Add
necessary Team memberships - (you must be an authorized manager)
When using auto-assignments setting|Description| --|-- by_seniority|Honor
Seniority
seniority_required|Skipping members without Seniority auto_conflicts_ok|Allow
Conflicts
auto_is_available|Listed in Available
auto_timeoff_ok|Ignore approved Time Off
single_shift_per_day|Restrict members to a single shift per day
Load Past Coverage setting|Description| --|-- past_dates|Allow expired/past
dates
Send Notifications setting|Description| --|-- notify|For assigned/auto-assigned
positions
SHIFT.BULKUPLOADGETTEMPLATES
Retrieve a list of URLS that identify site specific or general spreadhseet
templates for bulk upload operations. These templates can be used for proper
formatting required for the system to ingest spreadsheets uploaded to a
shift.bulkUpload generated URL.
Try it!
> 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.
Try it!
> 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.
Try it!
> 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,
"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
ignore_role - boolean
SHIFT.CONFIRM
This method is used by anyone to pick up a shift for themselves. By default, all
conflict checking that is enabled for the site and is applicable to pick-up
shifts is applied (this cannot be changed), and the shift will be acknowledged
(this cannot be changed).
> Request example:
{
"id" : 2753501
}
> Response example:
{
"seconds" : "0.443989",
"jsonrpc" : "2.0",
"id" : "2",
"result" : {
"message" : "You have accepted this position:\n\nWednesday, May 20, 2015, 9:55am to 11:55am\nFront Desk"
}
}
Try it!
Confirms a shift.
REQUIRED PARAMETER
id: ID of the shift to be assigned.
OPTIONAL PARAMETERS
covering_member or external_covering_member: Assign the specified user to the
shift (rather than assigning the current user). Only available to workgroup
managers.
ASSIGNABILITY PARAMETERS
To use assignability checks, the assignability_checks parameter must be true;
then, the following options may be available, based on enabled features:
is_available - boolean
by_seniority - boolean
seniority_required - boolean
single_shift_per_day - boolean
conflicts_ok - boolean
daily_overtime_ok - boolean
weekly_overtime_ok - boolean
timeoff_ok - boolean
consecutive_days - boolean
short_turnaround - boolean
ignore_attestation_types - boolean
attestation_type - array of attestationTypeId
ignore_role - boolean
RESPONSE
On success, a message attribute will provide a brief notification message. If
the shift had a count > 1, a new shift object will have been created and the id
of the new shift will also be returned.
SHIFT.CREATE
> Request example:
{
"workgroup" : "226085",
"department" : "949",
"location" : "29118",
"start_date" : "2010-09-17T12:00:00",
"role" : "2282"
}
> Response example:
{
"seconds" : "1.007354",
"jsonrpc" : "2.0",
"id" : "57",
"result" : {
"id" : 2753502
}
}
Try it!
Creates a new shift record.
PARAMETERS
Most attributes of a shift object except id may be specified. Minimally,
workgroup and start_date parameters must be specified. timezone will default to
the organization's timezone. location will default to the workgroup's default
location, if set. external_covering_member/covering_member are mutually
exclusive, and may only be specified if the shift is covered. If either is
specified as an array, single positions of the shift will be assigned to the
indicated members. covered may only be true if the shift is published. Start and
end dates may only fall on even five minute times. Either count or qty may be
specified and both will be set for the new shift, defaulting to 1; if both are
specified, they must be equal. count must be 1 for a covered shift.
OPTIONAL PARAMETERS
notify_on_create Boolean; send a notification message to the covering member for
this shift.
notify_message Additional text to include in notification message.
REPEATING SHIFT PARAMETERS
It is possible to use this method to create a series of repeating (repeating)
shifts. In order to do so, some additional parameters are required:
REPEATING_SHIFT
Boolean; specifies the caller is creating a series of repeating shifts.
REPEATING_SHIFT_TYPE
Type of repeating shift.
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
ignore_role - boolean
DELAYED PUBLICATION PARAMETERS
Depending on enabled site features, a shift can be scheduled for publishing some
date and time in the future, with optionally different datetimes per tier. NB:
When setting any of the delayed publication dates, all of them must be set;
previous values will be ignored.
For tiers, the higher tiers (10 is highest) have to be the same as, or earlier
than, the lower tiers (1 is lowest), or an error will be returned. Setting a
lower tier and leaving higher tiers empty will set the empty, higher tiers to
the same value as the closest lower tier.
All of the dates are set in datetime format (e.g. "2009-04-01T13:00:00Z"), in
UTC. They can also be set to the string now, instead of a datetime.
To publish immediately to a single tier, merely that tier to now.
Setting the shift's published value from true to false, or false to true,
removes all publication dates.
tier1_publish_date_utc..tier10_publish_date_utc - datetime
The individual datetimes for each tier. Only tiers supported for the
organization are shown. If tier support is not enabled, none are shown. If a
value is set to null, the shift will not be published to members at that tier.
publish_date_utc - datetime
The earliest publish datetime of the shift (if tiers used, the earliest of those
datetimes). If set, publish_date_utc will override and blank out all of the tier
publish datetimes.
publish_level - integer (read-only)
The current publish level of the shift. For example, if tier6_publish_date_utc
is in the past, and tier5_publish_date_utc is in the future, then publish_level
will be 6.
RESPONSE
On success, an id attribute will provide the identifier for the new shift. When
creating a series of repeating shifts, the id returned will be an array of
identifiers, one id for each of the shifts created in the series.
SHIFT.CUSTOMDROPDOWNLIST
> Request example:
{}
> Response example:
{
"custom_listable_1": {
"25013": "Listable 1 Value A",
"25014": "Listable 1 Value B"
},
"custom_listable_2": {
"25015": "Listable 2 Value A",
"25016": "Listable 2 Value B",
"25017": "Listable 2 Value C"
},
"custom_listable_3": {
"25018": "Listable 3 Value A",
"25019": "Listable 3 Value B",
"25020": "Listable 3 Value C",
"25021": "Listable 3 Value D"
}
}
Try it!
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": []
}
Try it!
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
Try it!
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" : ""
}
}
}
Try it!
Returns information about a coverage shift.
Parameters:
ID
Required. id of the shift for which to return information.
EXTENDED
Boolean; if not specified or true or user_actions is true, the results returned
will be an extended set of attributes; otherwise a basic set of attributes will
be returned for each shift.
USER_ACTIONS
Boolean; if specified and true, a user_actions object will be returned with
attributes indicating what actions (e.g. cover, uncover, assign, delete,
acknowledge) may be presented to the user.
ABSENT - BOOLEAN, ATTENDANCE FEATURE AVAILABLE FOR THIS SHIFT
ABSENT_REASONS - LIST OF 0 OR MORE REASON OBJECTS; KEYS ARE ID (INT), REASON
(TEXT), SELECTED (BOOLEAN), AND ACCOUNT_POINTS (FLOAT)
ARRIVE_LATE - BOOLEAN, ALLOWED TO SET ARRIVE_LATE_REASON FOR THIS SHIFT
ARRIVE_LATE_MAX_ADJUST - INT, MAXIMUM NUMBER OF MINUTES FROM THE START TIME THAT
A SHIFT MAY BE MARKED LATE
ARRIVE_LATE_REMOVE - BOOLEAN, WHETHER OR NOT THE USER CAN REMOVE THE ARRIVE LATE
REASON/DATETIME (THEY MAY STILL BE ABLE TO CREATE OR EDIT, DEPENDING ON VALUES
OF ARRIVE_LATE AND ARRIVE_LATE_REASONS)
ARRIVE_LATE_REASONS - SAME AS ABSENT_REASONS
ASSIGN - CAN ASSIGN SHIFT
CHANGE - CAN MODIFY SHIFT
CHANGE_CUSTOM_TEXT_N - CAN MODIFY THE NUMBERED CUSTOM TEXT FIELD OF THE SHIFT
COVER - CAN COVER SHIFT
CREATE_NOTE - CAN CREATE MANAGER NOTE FOR SHIFT
DELETE - CAN DELETE SHIFT
LEAVE_EARLY - BOOLEAN, ALLOWED TO SET LEAVE_EARLY FOR THIS SHIFT
LEAVE_EARLY_MAX_ADJUST - INT, MAXIMUM NUMBER OF MINUTES FROM THE END TIME THAT A
SHIFT MAY BE MARKED EARLY
LEAVE_EARLY_REMOVE - BOOLEAN, WHETHER OR NOT THE USER CAN REMOVE THE ARRIVE LATE
REASON/DATETIME (THEY MAY STILL BE ABLE TO CREATE OR EDIT, DEPENDING ON VALUES
OF LEAVE_EARLY AND LEAVE_EARLY_REASONS)
LEAVE_EARLY_REASONS - SAME AS ABSENT_REASONS
PUBLISH - CAN PUBLISH SHIFT
REASSIGN - CAN REASSIGN SHIFT
TIMECLOCK - CAN CLOCK IN TO SHIFT
UNCOVER - CAN UNASSIGN SHIFT
UNPUBLISH - CAN UNPUBLISH SHIFT
VIEW_CUSTOM_TEXT_N - CAN VIEW THE NUMBERED CUSTOM TEXT FIELD OF THE SHIFT
DISPLAY_TIME
Boolean; if specified and true, the returned shift will include other attributes
giving a string presentation of when the shift is scheduled.
DENORMALIZE
denormalize is deprecated; where possible, the results referenced_objects
attribute should be used instead.
Boolean; if specified and true, all identifiers (except the shift id itself) in
the returned shift object will be replaced with corresponding names, etc.
suitable for display, and the following attributes may be added:
LOCATION_DETAILS
An object providing one or more of the following attributes, when available:
zipcode, address, city, state, country, latitude, longitude.
DISPLAY_DATE
The start date of the shift, formatted for display (including weekday name).
DISPLAY_ADJ_END_TIME
The end time of the shift, formatted for display, adjusted for late/early.
DISPLAY_ADJ_START_TIME
The start time of the shift, formatted for display, adjusted for late/early.
DISPLAY_END_TIME
The end time of the shift, formatted for display.
DISPLAY_START_TIME
The start time of the shift, formatted for display.
DISPLAY_TIME
The time range of the shift, formatted for display.
LOCAL_ARRIVE_LATE_DATETIME
The (possibly TZ-adjusted) datetime that the member arrived late
LOCAL_END_DATE
The (possibly TZ-adjusted) end datetime of the shift
LOCAL_LEAVE_EARLY_DATETIME
The (possibly TZ-adjusted) datetime that the member left early
LOCAL_START_DATE
The (possibly TZ-adjusted) start datetime of the shift
LOCAL_TIMEZONE
The timezone the local times are adjusted for. When updating
arrive_late_datetime or leave_early_datetime (using the starting values from
local_start_date / local_end_date), also pass local_timezone to ensure the API
can convert the time to the correct timezone (optionally use a local_timezone of
GMT to submit the values in GMT).
REFERENCED_OBJECTS
Boolean, defaults to true unless denormalize is true. Indicates that, in
addition to the shift attribute, the results should include a referenced_objects
attribute giving information about objects referred to by the returned shift.
The response results shift attribute will be the selected shift object.
If user_actions were requested, a user\_actions attribute will also be returned.
If requested, the response results referenced_objects attribute will be an
object containing one or more object type names as attributes; for each object
type the value will be an array of those instances of that type of object which
are referred to in the shift results, with only selected minimal attributes
provided:
ACCOUNT
id, first_name, last_name, and screen_name attributes are provided.
CLIENT
id and name attributes are provided.
DEPARTMENT
id and name attributes are provided.
LOCATION
id and name attributes are provided.
ROLE
id and name attributes are provided.
TIMEZONE
name and iana_timezone attributes are provided.
workStatusType
id and name attributes are provided.
WORKGROUP
id and name attributes are provided.
acknowledgeDeclineReason
id and label attributes are provided.
IMAGE
Boolean; if specified and true, the results returned will include an image_url
attribute giving a url to the shift's covering_member's user image or null if no
image is available.
CUSTOM_MULTIPICK
id and name attributes are provided.
CUSTOM_DROPDOWN_1
id and name attributes are provided.
CUSTOM_DROPDOWN_2
id and name attributes are provided.
CUSTOM_DROPDOWN_3
id and name attributes are provided.
CUSTOM_DROPDOWN_4
id and name attributes are provided.
CUSTOM_DROPDOWN_5
id and name attributes are provided.
CUSTOM_DROPDOWN_6
id and name attributes are provided.
CUSTOM_DROPDOWN_7
id and name attributes are provided.
CUSTOM_DROPDOWN_8
id and name attributes are provided.
CUSTOM_DROPDOWN_9
id and name attributes are provided.
CUSTOM_DROPDOWN_10
id and name attributes are provided.
CUSTOM_DROPDOWN_11
id and name attributes are provided.
CUSTOM_DROPDOWN_12
id and name attributes are provided.
CUSTOM_DROPDOWN_13
id and name attributes are provided.
CUSTOM_DROPDOWN_14
id and name attributes are provided.
CUSTOM_DROPDOWN_15
id and name attributes are provided.
RESOURCE
id, name, and label attributes are provided.
SHIFT.GETASSIGNMENTLIST
> Request example:
{
"workgroup" : 12345,
"shift" : {
"id" : 123456789
}
}
> Response example:
{
"seconds" : "0.058344",
"jsonrpc" : "2.0",
"id" : "67",
"result" : {
"unassignable" : {
"5" : "John Smith - Has Conflicts (My Team)"
},
"assignable" : {
"1" : "Bob Doe",
"2" : "Jane Doe"
},
"assignable_order" : [ "2", "1" ],
"unassignable_order" : [ "5" ]
}
}
Try it!
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.
IGNORE_ROLE
Boolean; default false; ignore role restrictions.
MIN_LEVEL
Default 1, maximum level to exclude (e.g. 3 to exclude non-manager, 2 to exclude
members).
MAX_LEVEL
Maximum level to include (e.g. 2 to exclude coordinators/managers).
PHRASE
Match in first name, last name, fullname
COVERAGE_SIGNUP_LIST_EID
Exclude members already signed up for this eid (start_date must also be
specified).
ACCOUNTS
List of accounts to limit results to.
EXCLUDE_ACCOUNTS
List of accounts to exclude from results to.
PROFILE_TYPE
Only members with this profile type.
EXTENDED_FILTER
> Request example with extended_filter specified:
{
"workgroup" : 12345,
"shift" : {
"id" : 123456789
},
"profile_type": 1,
"extended_filter": { "emergency_contact": "Joe Blow" }
}
Specification to filter on profile options (profile_type must be specified). A
complete list of valid options can be found by calling the
profileConfiguration.list method. The relevant fields are profile\_type and
form\_name.
RANGE
Range of accounts in miles from venue zipcode.
MIN_SCORE
Minimum score.
NO_SCORE
Include members with no score (min_score must be specified).
BY_SENIORITY
Order by those with seniority by seniority date or rank, then with seniority and
no date/rank, then no seniority (random within those). The order can be found in
the assignable_order and unassignable_order arrays in the response.
RANDOMIZE
Return results in random order.
MANDATORY_DAYS_OFF
Mandatory days off settings (hash).
TIER
The user's tier.
TIER_GE
The user's minimum tier.
LANG
The user's language (or if user has not set one, the site's default).
CONSECUTIVE_DAYS
Allow shifts on N consecutive days if beta feature is enabled (boolean).
SHORT_TURNAROUND
Allow shifts that have a short (N hours) turnaround if beta feature is enabled
(boolean).
IGNORE_ATTESTATION_TYPES
Array of attestationType IDs to ignore.
SHIFT.GETOFFEREDTRADE
> Request example:
{
"id" : "56789012",
"extended" : true
}
> Response example:
{
"seconds" : "0.128193",
"jsonrpc" : "2.0",
"id" : "15",
"result" : {
"referenced_objects" : {
"workgroup" : [
{
"name" : "Help Desk",
"id" : "412345"
}
],
"department" : [
{
"name" : "Distribution",
"label" : "Distribution",
"id" : "9942"
}
],
"timezone" : [
{
"name" : "Pacific Time (US/Can) (GMT-08:00)",
"iana_timezone" : "America/Los_Angeles"
}
],
"location" : [
{
"name" : "Training / Meetings",
"id" : "92580"
}
],
"shift" : [
{
"display_time" : "1pm to 2pm",
"department" : "9942",
"reference_id" : "",
"linkurl" : "",
"work_status_type" : "5",
"start_date" : "2014-01-29T13:00:00",
"signup_list" : false,
"id" : "56789012",
"count" : "1",
"timezone" : "Pacific Time (US/Can) (GMT-08:00)",
"display_date" : "January 29, 2014",
"location" : "92580",
"subject" : "",
"covering_member" : "47",
"urgent" : false,
"zipcode" : "94132",
"qty" : "1",
"details" : "details!",
"workgroup" : "412345",
"published" : true,
"no_credit" : false,
"end_date" : "2014-01-29T14:00:00",
"covered" : true,
"no_pick_up" : false,
"no_trade" : false,
"room_floor" : "room/floor",
"linktitle" : ""
}
],
"account" : [
{
"id" : "39",
"screen_name" : null,
"last_name" : "Foster",
"first_name" : "Joanie"
},
{
"seniority_order" : "19999-12-31 23:59:59",
"id" : "47",
"profile_type" : "3",
"screen_name" : "Stan Wilson",
"last_name" : "Wilson",
"first_name" : "Stan"
}
],
"workStatusType" : [
{
"name" : "Salary/Exempt",
"id" : "5"
}
]
},
"tradeboard" : {
"trade_completed" : "2014-01-21T20:40:38Z",
"shift" : "56789012",
"notes" : "Need to see the dentist; please take this trade",
"id" : "12345",
"traded_to" : "47",
"traded_by" : "39",
"trade_complete" : true
}
}
}
Try it!
Returns information about a tradeboard posting for a coverage shift.
Parameters:
ID
Required. id of the shift for which to return information.
EXTENDED
Boolean; if specified and true, the results returned will include an extended
set of attributes; otherwise a basic set of attributes will be returned for each
tradeboard posting.
REFERENCED_OBJECTS
Boolean, defaults to true. Indicates that, in addition to the tradeboard
attribute, the results should include a referenced_objects attribute giving
information about objects referred to by the returned tradeboard posting.
The response results tradeboard attribute will be the selected tradeboard
object.
If requested, the response results referenced_objects attribute will be an
object containing one or more object type names as attributes; for each object
type the value will be an array of those instances of that type of object which
are referred to in the tradeboard results or in its associated shift, with only
selected minimal attributes provided:
ACCOUNT
id, first_name, last_name, and screen_name attributes are provided.
NOTE: external_id will also be returned in the results if external ids are
enabled for the site.
CLIENT
id and name attributes are provided.
DEPARTMENT
id and name attributes are provided.
LOCATION
id and name attributes are provided.
ROLE
id and name attributes are provided.
SHIFT
All basic shift attributes will be provided. If the extended parameter is true,
extended shift attributes will also be provided. Additionally, display_date and
display_time attributes contain formatted strings describing the shift's start
and end time.
TIMEZONE
name and iana_timezone attributes are provided.
workStatusType
id and name attributes are provided.
WORKGROUP
id and name attributes are provided.
SHIFT.LIST
> Request example:
{
"select" : {
"workgroup" : "226084"
}
}
> Response example:
{
"seconds" : "0.081433",
"jsonrpc" : "2.0",
"id" : "44",
"result" : {
"shifts" : [
{
"count" : "1",
"timezone" : "Greenwich Mean Time : Dublin, Lisbon, London (GMT)",
"subject" : "updated",
"qty" : "1",
"workgroup" : "226084",
"published" : true,
"covered" : true,
"end_date" : "2010-09-17T14:30:00",
"id" : "2753501",
"start_date" : "2010-09-17T14:00:00"
}
],
"count" : "1",
"page" : {
"this" : {
"batch" : 25,
"start" : 1
}
}
}
}
Try it!
Returns information about coverage shifts. Uses pagination. Uses select
criteria.
Optional parameters:
EXTENDED
Boolean; if specified and true or user_actions is true, the results returned
will include an extended set of attributes; otherwise a basic set of attributes
will be returned for each shift.
REFERENCED_OBJECTS
Boolean, defaults to true. Indicates that, in addition to the shifts attribute,
the results should include a referenced_objects attribute giving information
about objects referred to by the returned shifts.
DISPLAY_TIME
Boolean; if specified and true, the results returned will include a display_time
attribute giving a string presentation of when the shift is scheduled.
AGGREGATION_MODE
If specified, aggregated results are returned. Options are:
SIMILAR
Shifts with the same start_date, end_date, timezone, workgroup, covering_member,
covered, published, location, role, and urgent attributes are aggregated.
SIMILAR_SUBJECT
Shifts with the same start_date, end_date, timezone, subject, covering_member,
covered, published, location, role, and urgent attributes are aggregated.
DATE
Shifts with the same start_date, workgroup, covered, published, and urgent
attributes are aggregated.
DATE_SUBJECT
Shifts with the same start_date, subject, covered, published, and urgent
attributes are aggregated.
Each result element will have an aggregate_count attribute indicating how many
elements were aggregated. count and qty will be summed for the aggregated
elements; other fields that are not aggregated over will be omitted from results
that aggregate more than one element.
IMAGE
Boolean; if specified and true, the results returned will include an image_url
attribute giving a url to the shift's covering_member's user image or null if no
image is available.
IMAGE_EXPIRATION
Specifies the valid lifetime of the returned URL in seconds; default 300,
maximum 604800 (1 week).
TIMECLOCK_STATUS
Boolean; if specified and true, the results returned will include a clocked_in
attribute indicating that the shift's covering_member is currently clocked in
(though not necessarily for this shift) and a can_clock_in_out attribute
indicating whether there is authorization to clock that covering member in or
out.
NO_LOCATION
Boolean; if specified and true, the results returned will include shifts that do
not have an assigned location (in addition to the locations specified in
select), false excludes shifts without locations.
DIRECT_MANAGER_ACCOUNT
Account ID; if specified, shifts will be filtered by the account ID of the
manager of members to whom the shifts are assigned
EXTERNAL_DIRECT_MANAGER_ACCOUNT
External Account ID; if specified, shifts will be filtered by the external
account ID of the manager of members to whom the shifts are assigned
SHARED
Boolean; if specified and true, the results returned will also include shifts
that are covered and published from workgroups that are shared to the account.
USER_ACTIONS
Boolean; if specified and true, a user_actions object will be returned with
attributes indicating what actions (e.g. cover, uncover, assign, delete,
acknowledge) may be presented to the user.
LABELS
Boolean; if specified and true, displayable labels are returned for many id
attributes. E.g. in addition to "role":"123", "role_label":"Bartender" will be
returned.
SELECT
> Select shifts which start between January 1st, 2018 and January 7th, 2018
> (inclusive), are published, and have not been filled.
{
select: {
start_date: "2018-01-01",
end_date: "2018-01-07",
published: true,
covered: false
}
}
An object specifying selection criteria for this request. Note that start_date
and end_date will have default values if not specified. The available criteria
include:
START_DATE
The earliest date of coverage to select, in RFC 3339 full date format (e.g.
"2009-04-01"). Defaults to today.
END_DATE
The latest date of coverage to select, in RFC 3339 full date format. Defaults to
7 days after the start_date.
DISPLAY_START_DATE
The earliest date of coverage to select, in RFC 3339 full date format (e.g.
"2009-04-01"). This should be used instead of start_date when selecting shifts
that include workers across multiple timezones.
DISPLAY_END_DATE
The latest date of coverage to select, in RFC 3339 full date format. This should
be used instead of end_date when selecting shifts that include workers across
multiple timezones.
PUBLISHED
If specified, true requests only published shifts, false requests only
unpublished shifts.
COVERED
If specified, true requests only covered shifts, false requests only uncovered
shifts.
URGENT
If specified, true requests only urgent shifts, false requests only non-urgent
shifts.
NO_PICK_UP
If specified, true requests only "No Pick-Up" shifts, false requests only
non-"No Pick-Up" shifts.
SIGNUP_LIST
If specified, true requests only Signup List shifts, false requests only
non-Signup List shifts.
LOCATION
If specified, requests only shifts with the given locations (either a single
location id or an array of ids). Use 0 for shifts with no location.
ROLE
If specified, requests only shifts with the given roles (either a single role id
or an array of ids). Use 0 for shifts with no role.
CLIENT
If specified, and the site is configured to use client for schedule items,
requests only shifts with the given roles (either a single client id or an array
of ids). Use 0 for shifts with no client.
DEPARTMENT
If specified, and the site is configured to use department for schedule items,
requests only shifts with the given departments (either a single department id
or an array of ids). Use 0 for shifts with no department.
START_TIME
If specified, requests only shifts with the given starting times (either a
single time or an array of times), in RFC 3339 partial time format (e.g.
"13:00:00").
WORKGROUP
If specified, requests only shifts for the given workgroups. May be a single
workgroup or an array of workgroups.
SCOPE
If specified, a value of 'my_calendar' requests shifts normally shown to a user
on the calendar, that is, shifts for workgroups for which the user is a
coordinator or manager, shifts covered by the user, or approved, open shifts for
workgroups for which the user is a member. A value of 'siteadmin' requests all
shifts for the entire site and is only allowed for site administrators. A value
of 'managed_workgroups' requests shifts for the workgroups managed by the user
and is only allowed for workgroup managers. A value of 'report' is like
'siteadmin' for site administrators and like 'managed_workgroups' for others.
'siteadmin' is the default for site administrators while 'my_calendar' is the
default for all others.
REFERENCE_ID
If specified, requests only shifts with the given reference IDs (case
insensitive) (either a single reference ID or an array of reference IDs).
SUBJECT
If specified, only shifts with the matching subject (subject or body of the
shift) will be selected.
KEYWORDS
If specified, only select shifts with the keywords given as an array or a single
string (which is treated as whitespace separated keywords unless 'exact'
matching). keywords parameter works together with parameter 'match'.
MATCH
String, defaults to 'any'. Works together with 'keywords' parameter. Recognizes
three values: 'any', 'all' and 'exact'. If 'any' is specified, it will match if
any word from 'subject' parameter appears in either 'subject' or in 'details' of
the shift. If 'all' is specified, it will match if all words from 'subject'
parameter appears in either 'subject' or all words appear in 'details' of the
shift. If 'exact' is specified, it will match if a keyword is an exact match
with 'subject' parameter and the entirety of the 'subject' field or exact match
with the entirety of the 'details' field of the shift.
COVERING_MEMBER
If specified, requests only shifts covered by the workgroup members. May be a
single account id or an array.
NOTE: If you are calling this method with the external_covering_member
parameter, covering_member will be ignored, and is not required.
EXTERNAL_COVERING_MEMBER
If specified, requests only shifts covered by the workgroup members. May be a
single account id or an array.
NOTE: If you are calling this method with the covering_member parameter,
external_covering_member will be ignored, and is not required.
EXCLUDE_COVERING_MEMBER
If specified, excludes shifts covered by the workgroup members. May be a single
account id or an array.
ONLY_DELETED_WORKGROUPS
If specified and true, only shifts for deleted workgroups will be selected; if
specified and false, shifts for both deleted and non-deleted workgroups will be
selected. Otherwise (the default), only shifts for non-deleted workgroups will
be selected.
PROFILE_TYPE
If specified, only shifts with covering members with this profile type
identifier will be selected.
ACKNOWLEDGED
If specified and true, only shifts that have been acknowledged (including being
declined) will be selected.
CUSTOM_MULTIPICK, CUSTOM_MULTIPICK_2,3,...
If specified, only shifts with the given custom multipick identifier (and
possibly other custom multipick identifiers) will be selected.
RESOURCE
If specified, only shifts with the given resource identifier (and possibly other
resource identifiers) will be selected.
ATTENDEE_FILLED
If specified and false, only shifts for which additional attendees may be added
will be selected; if specified and true, only shifts which have attendees but
for which no additional attendees may be added will be selected.
ABSENT
If specified and true, only shifts that have been marked "Absent" will be
selected; if specified and false, only shifts that have not been marked "Absent"
will be selected.
ARRIVE_LATE
If specified and true, only shifts that have been marked "Arrive Late" will be
selected; if specified and false, only shifts that have not been marked "Arrive
Late" will be selected.
LEAVE_EARLY
If specified and true, only shifts that have been marked "Leave Early" will be
selected; if specified and false, only shifts that have not been marked "Leave
Early" will be selected.
ATTENDANCE
An enumerated string (or array of them) of absent, arrive_late, or leave_early.
Shifts matching any of the supplied strings will be returned. An empty array
will select only shifts that match none of absent, arrive_late, or leave_early.
WORKGROUP_OR_COVERING
If true, select shifts where the workgroup OR covering_member filter applies.
Otherwise, select shifts for which both filters (if specified) apply.
CUSTOM_DROPDOWN_1,2,3,...
If specified, only shifts with the given custom dropdown identifiers will be
selected. May be a single identifier or an array of identifiers.
CUSTOM_DROPDOWN_4
If specified, only shifts with the given custom_dropdown_4 identifiers will be
selected. May be a single identifier or an array of identifiers.
CUSTOM_DROPDOWN_5
If specified, only shifts with the given custom_dropdown_5 identifiers will be
selected. May be a single identifier or an array of identifiers.
CUSTOM_DROPDOWN_6
If specified, only shifts with the given custom_dropdown_6 identifiers will be
selected. May be a single identifier or an array of identifiers.
CUSTOM_DROPDOWN_7
If specified, only shifts with the given custom_dropdown_7 identifiers will be
selected. May be a single identifier or an array of identifiers.
CUSTOM_DROPDOWN_8
If specified, only shifts with the given custom_dropdown_8 identifiers will be
selected. May be a single identifier or an array of identifiers.
CUSTOM_DROPDOWN_9
If specified, only shifts with the given custom_dropdown_9 identifiers will be
selected. May be a single identifier or an array of identifiers.
CUSTOM_DROPDOWN_10
If specified, only shifts with the given custom_dropdown_10 identifiers will be
selected. May be a single identifier or an array of identifiers.
CUSTOM_DROPDOWN_11
If specified, only shifts with the given custom_dropdown_11 identifiers will be
selected. May be a single identifier or an array of identifiers.
CUSTOM_DROPDOWN_12
If specified, only shifts with the given custom_dropdown_12 identifiers will be
selected. May be a single identifier or an array of identifiers.
CUSTOM_DROPDOWN_13
If specified, only shifts with the given custom_dropdown_13 identifiers will be
selected. May be a single identifier or an array of identifiers.
CUSTOM_DROPDOWN_14
If specified, only shifts with the given custom_dropdown_14 identifiers will be
selected. May be a single identifier or an array of identifiers.
CUSTOM_DROPDOWN_15
If specified, only shifts with the given custom_dropdown_15 identifiers will be
selected. May be a single identifier or an array of identifiers.
COVERAGE_TYPE
One of or an array of the following (if an array, any shifts that meet at least
one of the criteria are selected):
MINE
Select only shifts published and assigned to the current user.
CONFIRMED
Select only shifts published and assigned to someone other than the current
user.
AVAILABLE
Select only shifts published and not assigned.
ROOM_FLOOR
If specified, only shifts with the given room_floor (case insensitive) will be
selected. May be a single value or an array of values.
CUSTOM_TEXT_1,2,3,...
If specified, only shifts with the given custom text value (case insensitive)
will be selected. May be a single value or an array of values. Ignored unless
the user is a site administrator or, if the custom text field is readable by
managers, you have specified a scope of report or managed_workgroups (see scope
above) and the user is a manager.
START_TIME_FROM, START_TIME_THROUGH
Times in RFC 3339 partial-time format (e.g. "12:34:00"). Must be an even minute.
If specified, only shifts with a start_time in the given range will be selected.
If start_time_from is greater than start_time_through, shifts with a start_time
on or after start_time_from OR on or before start_time_through will be selected.
END_TIME_FROM, END_TIME_THROUGH
Times in RFC 3339 partial-time format (e.g. "12:34:00"). Must be an even minute.
If specified, only shifts with a end_time in the given range will be selected.
If end_time_from is greater than end_time_through, shifts with a end_time on or
after end_time_from OR on or before end_time_through will be selected.
DISPLAY_START_TIME_FROM, DISPLAY_START_TIME_THROUGH
Like start_time_from and start_time_through, except that it will filter using
the display time.
DISPLAY_END_TIME_FROM, DISPLAY_END_TIME_THROUGH
Like end_time_from and end_time_through, except that it will filter using the
display time.
ORG_HOLD
True if only assigned shifts with an assignee in hold status should be returned.
False if only assigned shifts with an assignee not in hold status should be
returned.
ORG_PENDING
Return assigned shifts where the assignee has this onboarding status.
The response results shifts attribute will be an array of the current page of
selected shifts. Each element of the array will be an shift object containing
basic or basic and extended shift fields.
If requested, the response results referenced_objects attribute will be an
object containing one or more object type names as attributes; for each object
type the value will be an array of those instances of that type of object which
are referred to in the shifts results, with only selected minimal attributes
provided:
ACCOUNT
id, first_name, last_name, and screen_name attributes are provided.
CLIENT
id and name attributes are provided.
DEPARTMENT
id and name attributes are provided.
LOCATION
id and name attributes are provided.
ROLE
id and name attributes are provided.
TIMEZONE
name and iana_timezone attributes are provided.
workStatusType
id and name attributes are provided.
WORKGROUP
id and name attributes are provided.
ACKNOWLEDGE_DECLINE_REASON
id and label attributes are provided.
CUSTOM_MULTIPICK
id and name attributes are provided.
CUSTOM_DROPDOWN_1
id and name attributes are provided.
CUSTOM_DROPDOWN_2
id and name attributes are provided.
CUSTOM_DROPDOWN_3
id and name attributes are provided.
CUSTOM_DROPDOWN_4
id and name attributes are provided.
CUSTOM_DROPDOWN_5
id and name attributes are provided.
CUSTOM_DROPDOWN_6
id and name attributes are provided.
CUSTOM_DROPDOWN_7
id and name attributes are provided.
CUSTOM_DROPDOWN_8
id and name attributes are provided.
CUSTOM_DROPDOWN_9
id and name attributes are provided.
CUSTOM_DROPDOWN_10
id and name attributes are provided.
CUSTOM_DROPDOWN_11
id and name attributes are provided.
CUSTOM_DROPDOWN_12
id and name attributes are provided.
CUSTOM_DROPDOWN_13
id and name attributes are provided.
CUSTOM_DROPDOWN_14
id and name attributes are provided.
CUSTOM_DROPDOWN_15
id and name attributes are provided.
RESOURCE
id, name, and label attributes are provided.
SHIFT.LISTUPDATED
> Request example:
{
"select" : {
"updated_since" : 1284656001
}
}
> Response example:
{
"seconds" : "0.056182",
"jsonrpc" : "2.0",
"id" : "36",
"result" : {
"shifts" : [
{
"count" : "1",
"timezone" : "Pacific Time (US/Can) (GMT-08:00)",
"subject" : "updated",
"qty" : "1",
"published" : false,
"workgroup" : "226082",
"covered" : false,
"start_date" : "2010-09-17T12:00:00",
"id" : "2753500"
}
],
"count" : "1",
"page" : {
"this" : {
"batch" : 25,
"start" : 1
}
}
}
}
Try it!
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
}
}
Try it!
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
Try it!
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
Try it!
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
Try it!
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
}
]
}
}
Try it!
This method is experimental and subject to change.
Returns summary information about selected shifts.
Parameters:
SELECT
Selection criteria. For defaults and allowed criteria, refer to shift.list.
AGGREGATE
Shift attribute name or array of names by which to summarize; defaults to
start_date. Currently supported values: start_date.
AUTO_AGGREGATE
Boolean; options, if specified and true, the returned result will be grouped by
Start Date and either Workgroup or Subject depending on the Application setting
for Schedules/Calenders "Display by Subject(Not Workgroup)". If setting is Yes,
result is grouped by Start Date and Subject, if set to No, the result is grouped
by Start Date and Workgroup.
Difference between aggreate for Workgroup and Subject. When the Application
setting for Schedules/Calenders "Display by Subject(Not Workgroup)" is No, the
aggregate is for a Start Date and Workgroup, the Label contain the Workgroup
Name, and there is also a field to indicate the id for the workgroup, called
"workgroup". When the Application setting is Yes, the aggregate is for Start
Date and Subject, the Label will be the Subject or the special value "Misc."
This special value is used when the subject is missing. Also, there is an extra
field called "label_orig", this contains the real subject, this means, the true
value for Subject and it is be the empty string.
See the example
> Request example: ```JSON { "auto_aggregate": true, "exists": { "available": {
> "covered": false, "published": true }, "confirmed": { "acknowledged": true,
> "covered": true, "published": true }, "unacknowledged": { "acknowledged":
> false, "covered": true, "published": true }, "unpublished": { "published":
> false }, "unpublished_available": { "covered": false, "published": false },
> "unpublished_confirmed": { "covered": true, "published": false } },
> "include_count": true, "select": { "display_end_date": "2020-04-03",
> "display_start_date": "2020-02-29" } }
> Response example:
```JSON
{
"referenced_objects": {},
"summary": [
{
"key": "2020-03-01",
"value": [
{
"available": 0,
"confirmed": 0,
"date": "2020-03-01",
"label": "CMT",
"unacknowledged": 1,
"unpublished": 0,
"unpublished_available": 0,
"unpublished_confirmed": 0,
"workgroup": "2834160"
}
]
},
{
"key": "2020-03-17",
"value": [
{
"available": 2,
"confirmed": 1,
"date": "2020-03-17",
"label": "CNA",
"unacknowledged": 1,
"unpublished": 3,
"unpublished_available": 1,
"unpublished_confirmed": 2,
"workgroup": "2834161"
},
{
"available": 0,
"confirmed": 1,
"date": "2020-03-17",
"label": "Home Health Aides",
"unacknowledged": 0,
"unpublished": 1,
"unpublished_available": 1,
"unpublished_confirmed": 0,
"workgroup": "2834157"
},
{
"available": 0,
"confirmed": 1,
"date": "2020-03-17",
"label": "RN",
"unacknowledged": 0,
"unpublished": 0,
"unpublished_available": 0,
"unpublished_confirmed": 0,
"workgroup": "2834158"
}
]
},
{
"key": "2020-03-26",
"value": [
{
"available": 1,
"confirmed": 0,
"date": "2020-03-26",
"label": "CMT",
"unacknowledged": 0,
"unpublished": 1,
"unpublished_available": 1,
"unpublished_confirmed": 0,
"workgroup": "2834160"
},
{
"available": 0,
"confirmed": 0,
"date": "2020-03-26",
"label": "Home Health Aides",
"unacknowledged": 1,
"unpublished": 1,
"unpublished_available": 1,
"unpublished_confirmed": 0,
"workgroup": "2834157"
}
]
}
]
}
EXISTS
Object with arbitrarily named attributes with selection criteria objects as
values.
SHARED
Boolean; if specified and true, the results returned will also include shifts
that are covered and published from workgroups that are shared to the account.
INCLUDE_COUNT
Boolean; if specified and true, the results returned will also include the
totals for each attribute returned.
REFERENCED_OBJECTS
Boolean, defaults to true. For future use. Indicates that, in addition to the
summary attribute, the results should include a referenced_objects attribute
giving information about objects referred to by the returned summary data.
The response results summary attribute will provide an array containing an
element for each distinct set of values found of the specified aggregate
attributes. Each element will be an object with an attribute for each of the
specified aggregate attributes giving the value found, and additional attributes
for each named set of additional criteria specified in exists giving a Boolean
value to indicate whether shifts with those additional criteria were found with
the given aggregate attribute values.
SHIFT.UNCONFIRM
> Request example:
{
"id" : 2753501
}
> Response example:
{
"seconds" : "0.123864",
"jsonrpc" : "2.0",
"id" : "46",
"result" : {}
}
Try it!
Confirms a shift.
Required parameter: id.
Response: On success, empty results will be returned. Note that if the shift had
a quantity, the particular shift that was unconfirmed may have been merged with
other unconfirmed shifts and deleted.
SHIFT.UPDATE
This method is for changing details about a shift. When assigning a shift no
conflict checking of that assignment will be done unless explicitly enabled via
the assignability_checks and conflicts_ok parameters. Furthermore, by default
the assignment will not be acknowledged nor published. To acknowledge the
assignment see the shift.acknowledge or shift.assign methods. To publish a
shift, set the published parameter to true.
> Request example:
{
"count" : 1,
"timezone" : "Greenwich Mean Time : Dublin, Lisbon, London (GMT)",
"subject" : "updated",
"qty" : 1,
"published" : true,
"workgroup" : "226084",
"end_date" : "2010-09-17T14:30:00",
"covered" : true,
"start_date" : "2010-09-17T14:00:00",
"id" : 2753501
}
> Response example:
{
"seconds" : "0.178901",
"jsonrpc" : "2.0",
"id" : "43",
"result" : {}
}
Try it!
Updates a shift object.
REQUIRED PARAMETER
id. Most other shift object attributes may be specified.
OPTIONAL PARAMETERS
notify Boolean; notify covering member upon update, or notify the workgroup on
publishing an uncovered shift.
The count of a shift is the number of positions available for that specific
shift, whereas the qty is the total positions for all related shifts. Counts may
not be directly modified: to increase or decrease available counts, modify the
qty field, which will update the qty for all related shifts, increasing or
decreasing the count only for the related uncovered shift. Therefore, qty cannot
be decreased below the total count for all related covered shifts. If qty is set
to the total count for all related covered shifts, the uncovered shift, now with
count 0, is deleted.
If covering_member is specified as an array, single positions of the shift will
be assigned to the indicated members.
To set absent_reason, no_credit must also be set to true (even if already true).
To set arrive_late_reason or leave_early_reason, arrive_late_datetime and
leave_early_datetime must also be set.
Setting arrive_late_reason or leave_early_reason will un-set absent_reason /
no_credit; similarly, setting the latter will un-set the former.
arrive_late_reason and leave_early_reason can be set together, but if either is
set in the same update call as absent_reason / no_credit, the system will return
an error.
ASSIGNABILITY PARAMETERS
To use assignability checks, the assignability_checks parameter must be true;
then, the following options may be available, based on enabled features:
is_available - boolean
by_seniority - boolean
seniority_required - boolean
single_shift_per_day - boolean
conflicts_ok - boolean
daily_overtime_ok - boolean
weekly_overtime_ok - boolean
timeoff_ok - boolean
consecutive_days - boolean
short_turnaround - boolean
ignore_attestation_types - boolean
attestation_type - array of attestationTypeId
ignore_role - boolean
RESPONSE
On success, if the shift was updated, empty results will be returned. If the
shift had a count > 1 and the update was only applied to a portion of the count,
a new shift object will have been created and the id of the new shift will be
returned. If qty is modified on a covered shift, the id of the modified
uncovered shift will be returned.
SHIFT.WHOSON
> Request example:
{}
> Response example:
{
"count": "1",
"page": {
"this": {
"batch": 10,
"start": 1
}
},
"referenced_objects": {
"account": [
{
"first_name": "First",
"id": "1",
"last_name": "Last",
"screen_name": "First Last",
"seniority_order": "12014-09-12 08:57:52"
}
],
"location": [
{
"id": "1234",
"name": "API Test Site"
}
],
"timezone": [
{
"name": "Pacific Time (US/Can) (GMT-08:00)",
"iana_timezone": "America/Los_Angeles"
}
],
"workgroup": [
{
"id": "11111",
"name": "CNA"
}
]
},
"shifts": [
{
"client": null,
"count": "1",
"covered": true,
"covering_member": "9",
"department": null,
"display_time": "Anytime",
"id": "123456",
"location": "1234",
"name": "",
"published": true,
"qty": "1",
"role": null,
"start_date": "2019-01-01",
"subject": "",
"timezone": "Pacific Time (US/Can) (GMT-08:00)",
"urgent": false,
"use_time": "5",
"workgroup": "11111"
}
]
}
Returns information about coverage shifts currently underway. Uses #pagination.
Optional parameters
EXTENDED
Boolean; if specified and true, the results returned will include an extended
set of attributes; otherwise a basic set of attributes will be returned for each
shift.
REFERENCED_OBJECTS
Boolean, defaults to true. Indicates that, in addition to the shifts attribute,
the results should include a referenced_objects attribute giving information
about objects referred to by the returned shifts.
IMAGE
Boolean; if specified and true, the results returned will include an image_url
attribute giving a url to the shift's covering_member's user image or null if no
image is available.
IMAGE_EXPIRATION
Specifies the valid lifetime of the returned URL in seconds; default 300,
maximum 604800 (1 week).
TIMECLOCK_STATUS
Boolean; if specified and true, the results returned will include a clocked_in
attribute indicating that the shift's covering_member is currently clocked in
(though not necessarily for this shift) and a can_clock_in_out attribute
indicating whether there is authorization to clock that covering member in or
out.
The response results "shifts" attribute will be an array of the current page of
shifts. Each element of the array will be an shift object containing basic or
basic and extended shift fields and a "display_time" attribute giving a string
presentation of when the shift is scheduled.
If requested, the response results "referenced_objects" attribute will be an
object containing one or more object type names as attributes; for each object
type the value will be an array of those instances of that type of object which
are referred to in the "shifts" results, with only selected minimal attributes
provided:
ACCOUNT
id, first_name, last_name, and screen_name attributes are provided.
CLIENT
id and name attributes are provided.
DEPARTMENT
id and name attributes are provided.
LOCATION
id and name attributes are provided.
ROLE
id and name attributes are provided.
TIMEZONE
name and iana_timezone attributes are provided.
WORKSTATUSTYPE
id and name attributes are provided.
WORKGROUP
id and name attributes are provided.
SELECT
An object specifying selection criteria for this request
NOT_CLOCKED_IN
Boolean, if specified and true, the result will be filter to only return workers
who has not clocked.
SYSTEM OBJECT
SYSTEM.ECHO
> Request example:
{
"false" : false,
"true" : true,
"null" : null
}
> Response example:
{
"seconds" : "0.040819",
"jsonrpc" : "2.0",
"id" : "3",
"result" : {
"false" : false,
"true" : true,
"null" : null
}
}
Try it!
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" : {}
}
Try it!
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.
Try it!
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
}
}
Try it!
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"
}
}
Try it!
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
}
]
}
Try it!
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
}
}
Try it!
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
}
}
Try it!
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" : {}
}
Try it!
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
}
]
}
}
Try it!
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
}
}
Try it!
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" : {}
}
Try it!
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
}
}
Try it!
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" : {}
}
Try it!
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
PAID
Boolean; indicates whether this time off is paid or unpaid
CATEGORY
Category for this time off request, or null if the request has no category.
TIMEOFFREQUEST: EXTENDED ATTRIBUTES
DETAILS
Additional details for this request
ADMIN_NOTES
(site administrators only)
STATUS_REASON
Reason for approval or denial of request
LAST_STATUS_UPDATE
Datetime of last status update for this request
STATUS_UPDATE_BY
account that last updated this request's status
TIMEOFFREQUEST.APPROVE
Try it!
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
Try it!
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
Try it!
Deletes a timeOffRequest record.
Required parameter: id.
Response: On success, empty results will be returned.
TIMEOFFREQUEST.DENY
Try it!
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
Try it!
Returns information about a timeOffRequest.
Parameters:
ID
Required. id of the timeOffRequest for which to return information.
EXTENDED
Boolean; if specified and false, the results returned will be a basic set of
attributes; otherwise an extended set of attributes will be returned for each
timeOffRequest.
USER_ACTIONS
Boolean; if specified and true, a user_actions object will be returned with
attributes indicating what actions (e.g. delete, update) may be presented to the
user.
REFERENCED_OBJECTS
Boolean, defaults to true. Indicates that, in addition to the timeOffRequest
attribute, the results should include a referenced_objects attribute giving
information about objects referred to by the returned time off request.
DISPLAY_TIME
Boolean; if specified and true, the results returned will include a display_time
attribute giving a string presentation of what time range the time off is
requested.
The response results "timeOffRequest" attribute will be the selected
timeOffRequest object.
If user_actions were requested, a user_actions attribute will also be returned.
If requested, the response results referenced_objects attribute will be an
object containing one or more object type names as attributes; for each object
type the value will be an array of those instances of that type of object which
are referred to in the "timeOffRequest" results, with only selected minimal
attributes provided:
ACCOUNT
id, first_name, last_name, and screen_name attributes are provided.
NOTE: external_id will also be returned in the results if external ids are
enabled for the site.
id, first_name, last_name, and screen_name attributes are provided.
TIMEZONE
name and iana_timezone attributes are provided.
WORKGROUP
id and name attributes are provided.
TIMEOFFREQUEST.LIST
Try it!
Returns information about timeOffRequests. Uses pagination. Uses select
criteria.
Optional parameters:
EXTENDED
Boolean; if specified and true, the results returned will include an extended
set of attributes; otherwise a basic set of attributes will be returned for each
timeOffRequest.
USER_ACTIONS
Boolean; if specified and true, a user_actions object will be returned for each
timeOffRequest with attributes indicating what actions (e.g. delete, update,
approve) may be presented to the user.
REFERENCED_OBJECTS
Boolean, defaults to true. Indicates that, in addition to the timeOffRequests
attribute, the results should include a referenced_objects attribute giving
information about objects referred to by the returned time off request.
DISPLAY_TIME
Boolean; if specified and true, the results returned will include a display_time
attribute giving a string presentation of what time range the time off is
requested.
SELECT
An object specifying selection criteria for this request. Note that start_date
and end_date will have default values if not specified. The available criteria
include:
START_DATE
The earliest date of coverage to select, in RFC 3339 full date format (e.g.
"2009-04-01"). Defaults to today.
END_DATE
The latest date of coverage to select, in RFC 3339 full date format. Defaults to
7 days after the start_date.
PROFILE_TYPE
If specified, requests only timeOffRequests for accounts having one of the
specified profile_type(s). The specified value is the profile_type_id or array
of profile_type_id(s) for the account requesting the timeoff.
STATUS
If specified, requests only timeOffRequests with the status.
MEMBER
If specified, requests only timeOffRequests for the given account.
The response results "timeOffRequests" attribute will be an array of the current
page of selected timeOffRequests. Each element of the array will be an
timeOffRequest object containing basic or basic and extended timeOffRequest
fields.
If requested, the response results referenced_objects attribute will be an
object containing one or more object type names as attributes; for each object
type the value will be an array of those instances of that type of object which
are referred to in the "timeOffRequest" results, with only selected minimal
attributes provided:
NOTE: If you are calling this method with the external_member parameter, member
is not required.
EXTERNAL_MEMBER
If specified, requests only timeOffRequests for the given account.
NOTE: If you are calling this method with the member parameter, external_member
is not required, and will be ignored.
ACCOUNT
id, first_name, last_name, and screen_name attributes are provided.
TIMEZONE
name and iana_timezone attributes are provided.
WORKGROUP
id and name attributes are provided.
SORT
If specified, the name of a preconfigured sort criteria. There are three valid
values that can be used: creation_date, start_date and name.
creation_date sorts by creation_date in descending order so the most recent
request are listed first. If a day contains multiple time off requests, the day
is further sorted by start_time, end_date and end_time.
start_date sorts by start_date in descending order (most future day to past). If
a day contain multiple time off requests then these are further sorted by
start_time, then by end_date in descending order then end_time
name sorts by last_name then first_name. If a person has multiple time off
request then these are further sorted by start_date in descenting order and then
start_time
TIMEOFFREQUEST.UPDATE
Try it!
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
Try it!
> 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
Try it!
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" : {}
}
Try it!
Deletes a timecard record.
Required parameter: id.
Response: On success, empty results will be returned.
TIMECARD.EXPORTTRAXPAYROLL
Try it!
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
Try it!
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
Try it!
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
Try it!
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
Try it!
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"
}
}
Try it!
Returns information about timecard related custom dropdown list objects.
Required Parameter: none
Optional Parameters: none
Response: On success, an object will be returned containing all timecard custom
drop down listables that have been created, and are enabled for the site.
TIMECARD.SHIFTLIST
> Request example:
{
"member" : "1"
}
> Response example:
{
"seconds" : "2.811506",
"jsonrpc" : "2.0",
"id" : "21",
"result" : {
"referenced_objects": {
"workgroup": {
"123456": "My Team"
}
},
"shifts": [
{
"agent": "12345",
"approved": "1",
"client": null,
"count": "1",
"covered": true,
"department": null,
"display_time": "7am - 11:10am",
"dur_hrs": "4",
"dur_mins": "10",
"end_date": "2018-02-06T11:10:00",
"id": "1234567890",
"name": "",
"qty": "1",
"role": "0",
"start_date": "2018-02-06T07:00:00",
"subject": "",
"timezone": "Pacific Time (US/Can) (GMT-08:00)",
"urgent": false,
"use_time": "2",
"venue": "0",
"workgroup": "123456"
}
]
}
}
Try it!
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
}
}
Try it!
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
}
}
Try it!
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
Try it!
Returns information about a timeclock object.
Parameters:
ID
Required. id of the timeclock object for which to return information.
EXTENDED
Boolean; if specified and false, the results returned will be a basic set of
attributes; otherwise an extended set of attributes will be returned for each
timeclock.
REFERENCED_OBJECTS
Boolean, defaults to true. Indicates that, in addition to the timeclock
attribute, the results should include a referenced_objects attribute giving
information about objects referred to by the returned timeclock.
The response results timeclock attribute will be the selected timeclock object.
If requested, the response results referenced_objects attribute will be an
object containing one or more object type names as attributes; for each object
type the value will be an array of those instances of that type of object which
are referred to in the timeclocks results, with only selected minimal attributes
provided:
ACCOUNT
id, first_name, last_name, and screen_name attributes are provided.
NOTE: external_id will also be returned in the results if external ids are
enabled for the site
TIMEZONE
name and iana_timezone attributes are provided.
WORKGROUP
id and name attributes are provided.
TIMECLOCK.LIST
Try it!
Returns information about timeclock objects. Uses pagination. Uses select
criteria.
Optional parameters:
EXTENDED
Boolean; if specified and true, the results returned will include an extended
set of attributes; otherwise a basic set of attributes will be returned for each
timeclock object.
REFERENCED_OBJECTS
Boolean, defaults to true. Indicates that, in addition to the timeclocks
attribute, the results should include a referenced_objects attribute giving
information about objects referred to by the returned timeclock objects.
SELECT
An object specifying selection criteria for this request. Note that start_date
and end_date will have default values if not specified. The available criteria
include:
START_DATE
Earliest clock in date to select
END_DATE
Latest clock in date to select
CLOCKED_OUT
Boolean; true to include only already clocked out timeclock records, false to
include only not yet clocked out timeclock records. Omit to include all records.
WORKGROUP
Single workgroup identifier or array of workgroup identifiers to report
ACCOUNT
Single account identifier or array of account identifiers to report
NOTE: If you are calling this method with the account parameter,
external_account is not required, and will be ignored.
EXTERNAL_ACCOUNT
Single external account identifier or array of external account identifiers to
report
NOTE: If you are calling this method with the account parameter,
external_account is not required, and will be ignored.
The response results timeclocks attribute will be an array of the current page
of selected timeclock objects. Each element of the array will be an timeclock
object containing basic or basic and extended timeclock fields.
If requested, the response results referenced_objects attribute will be an
object containing one or more object type names as attributes; for each object
type the value will be an array of those instances of that type of object which
are referred to in the timeclocks results, with only selected minimal attributes
provided:
ACCOUNT
id, first_name, last_name, and screen_name attributes are provided.
TIMEZONE
name and iana_timezone attributes are provided.
WORKGROUP
id and name attributes are provided.
TIMECLOCK.REPORT
> Request example:
{
"format" : "xls",
"report_type" : "total_hour",
"select" : {
"start_date" : "2012-10-01"
}
}
> Response example:
{
"seconds" : "2.811506",
"jsonrpc" : "2.0",
"id" : "21",
"result" : {
"url" : "https://www.shiftboard.com/servola/fetch.cgi?ss=14;type=report;key=5085a260feff2760;signature=kRMtQqcLl0SULDYifhdg3OH4uIU;format=excel"
}
}
Try it!
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
}
}
Try it!
Reports clocked in/out status of an account.
Parameters:
ACCOUNT
Optional, defaults to current user
NOTE: If you are calling this method with the account parameter,
external_account is not required, and will be ignored.
EXTERNAL_ACCOUNT
Optional, defaults to current user
NOTE: If you are calling this method with the account parameter,
external_account is not required, and will be ignored.
LATITUDE
Optional, latitude of clock in. If specified, longitude and location_accuracy
must also be specified.
LONGITUDE
Optional, longitude of clock in. If specified, latitude and location_accuracy
must also be specified.
LOCATION_ACCURACY
Optional, meters of 68% confidence of latitude/longitude. If specified, latitude
and longitude must also be specified.
Response: On success, returns basic timeclock attributes. If the account is
clocked in, they will reflect that timeclock object; otherwise, timeclock
attributes other than account will be null.
If not clocked in and shifts can be associated to timeclock entries, an
additional boolean shift_required attribute will be present and indicate whether
an associated shift is required and a shifts_available attribute will provide an
array of possible shifts to associate (with those shifts most likely to be
intended first), each element of the array providing the following attributes:
CATEGORY
A string with the value current, next, or previous, indicating whether the shift
is scheduled for now, in the future, or in the past.
SHIFT
The shift identifier to specify when clocking in.
WORKGROUP
The workgroup identifier to specify when clocking in.
DESCRIPTION
A string describing when and for what team the shift is scheduled.
TIMEZONE
The timezone of the shift.
Additionally, if latitude/longitude/location_accuracy are specified, each
element of the array will provide the following 3 attributes:
GEOFENCE_RADIUS
The allowed geofence radius in meters, or null if there is no restriction.
DISTANCE_OUTSIDE
The distance in meters of the user's location outside the allowed geofence, or 0
if the user is not outside.
GEOFENCE_TIMECLOCK_ALLOWED
If the shift requires the member to be within the geofenced area, this boolean
is false if the member is outside the area (that is, geofence_status is
inaccurate, or outside).
GEOFENCE_STATUS
A string describing the user's position with respect to the geofence. One of:
NO_RESTRICTION
There is no geofence restriction for this shift.
UNKNOWN_LOCATION
There is no latitude/longitude known for this shift
INACCURATE
The location provided is not accurate enough.
INSIDE
The user is within the geofence.
INSIDE_EDGE
The user's location is within the geofence, but the circle of accuracy extends
outside it.
OUTSIDE_EDGE
The user's location is outside the geofence, but the circle of accuracy extends
inside it.
OUTSIDE
The user is outside the geofence.
The shifts_available array entries will be sorted as follows:
* First sort by category: current, followed by next, then previous
* If current, sort by "most recently started," then "longest shift"
* If next, sort by "next to start," then "longest shift"
* If previous, sort by "most recently ended," then "longest shift"
The response will provide an additional org_level attribute, indicating the
account's level in the organization (2, 3, or 4), as well as screen_name,
first_name, and last_name account attributes.
TIMECLOCK.WHOSON
Returns information about timeclock entries currently clocked in. Uses
pagination.
Optional parameters:
EXTENDED
Boolean; if specified and true, the results returned will include an extended
set of attributes; otherwise a basic set of attributes will be returned for each
timeclock entry.
REFERENCED_OBJECTS
Boolean, defaults to true. Indicates that, in addition to the timeclocks
attribute, the results should include a referenced_objects attribute giving
information about objects referred to by the returned timeclock entries.
IMAGE
Boolean; if specified and true, the results returned will include an image_url
attribute giving a url to the timeclock's account's user image or null if no
image is available.
IMAGE_EXPIRATION
Specifies the valid lifetime of the returned URL in seconds; default 300,
maximum 604800 (1 week).
The response results "timeclocks" attribute will be an array of the current page
of timeclock entries. Each element of the array will be a timeclock object
containing basic or basic and extended timeclock fields. Additionally, a
can_clockout boolean attribute will be returned indicating whether the api user
is authorized to clock out this timeclock entry.
If requested, the response results "referenced_objects" attribute will be an
object containing one or more object type names as attributes; for each object
type the value will be an array of those instances of that type of object which
are referred to in the "timeclocks" results, with only selected minimal
attributes provided:
ACCOUNT
id, first_name, last_name, and screen_name attributes are provided.
TIMEZONE
name and iana_timezone attributes are provided.
TIMEZONE OBJECT
timezone objects have the following minimal attributes:
NAME
A unique displayable name used to identify this timezone. Currently, one of the
following strings:
* "International Date Line West (GMT-12:00)"
* "Midway Island, Samoa (GMT-11:00)"
* "Hawaii (GMT-10:00)"
* "Alaska (GMT-09:00)"
* "Pacific Time (US/Can) (GMT-08:00)"
* "Arizona (GMT-07:00)"
* "Mountain Time (US/Can) (GMT-07:00)"
* "Chihuahua, La Paz, Mazatlan (GMT-07:00)"
* "Saskatchewan (GMT-06:00)"
* "Central Time (US/Can) (GMT-06:00)"
* "Guadalajara, Mexico City, Monterrey (GMT-06:00)"
* "Indiana (East) (GMT-05:00)"
* "Bogota, Lima, Quito (GMT-05:00)"
* "Eastern Time (US/Can) (GMT-05:00)"
* "Caracas, La Paz (GMT-04:30)"
* "Atlantic Time (Can) (GMT-04:00)"
* "Santiago (GMT-04:00)"
* "Newfoundland (GMT-03:30)"
* "Buenos Aires, Georgetown (GMT-03:00)"
* "Mid-Atlantic (GMT-02:00)"
* "Cape Verde Is. (GMT-01:00)"
* "Azores (GMT-01:00)"
* "Casablanca, Monrovia (GMT)"
* "Greenwich Mean Time : Dublin, Lisbon, London (GMT)"
* "Brussels, Copenhagen, Madrid, Paris (GMT+01:00)"
* "Belgrade, Bratislava, Budapest, Prague (GMT+01:00)"
* "Amsterdam, Berlin, Bern, Rome, Vienna (GMT+01:00)"
* "Sarajevo, Skopje, Warsaw, Zagreb (GMT+01:00)"
* "Harare, Pretoria (GMT+02:00)"
* "Cairo (GMT+02:00)"
* "Jerusalem (GMT+02:00)"
* "Athens, Beirut, Istanbul, Minsk (GMT+02:00)"
* "Bucharest (GMT+02:00)"
* "Helsinki, Kyiv, Riga, Sofia, Vilnius (GMT+02:00)"
* "Nairobi (GMT+03:00)"
* "Kuwait, Riyadh (GMT+03:00)"
* "Moscow, St. Petersburg, Volgograd (GMT+03:00)"
* "Baghdad (GMT+03:00)"
* "Tehran (GMT+03:30)"
* "Abu Dhabi, Muscat (GMT+04:00)"
* "Baku, Tbilisi, Yerevan (GMT+04:00)"
* "Kabul (GMT+04:30)"
* "Islamabad, Karachi, Tashkent (GMT+05:00)"
* "Chennai, Kolkata, Mumbai, New Delhi (GMT+05:30)"
* "Kathmandu (GMT+05:45)"
* "Astana, Dhaka (GMT+06:00)"
* "Almaty, Novosibirsk (GMT+06:00)"
* "Rangoon (GMT+06:30)"
* "Bangkok, Hanoi, Jakarta (GMT+07:00)"
* "Krasnoyarsk (GMT+07:00)"
* "Beijing, Chongqing, Hong Kong, Urumqi (GMT+08:00)"
* "Kuala Lumpur, Singapore (GMT+08:00)"
* "Taipei (GMT+08:00)"
* "Perth (GMT+08:00)"
* "Irkutsk, Ulaan Bataar (GMT+08:00)"
* "Seoul (GMT+09:00)"
* "Osaka, Sapporo, Tokyo (GMT+09:00)"
* "Yakutsk (GMT+09:00)"
* "Darwin (GMT+09:30)"
* "Adelaide (GMT+09:30)"
* "Brisbane (GMT+10:00)"
* "Guam, Port Moresby (GMT+10:00)"
* "Vladivostok (GMT+10:00)"
* "Hobart (GMT+10:00)"
* "Canberra, Melbourne, Sydney (GMT+10:00)"
* "Magadan, Solomon Is., New Caledonia (GMT+11:00)"
* "Fiji, Kamchatka, Marshall Is. (GMT+12:00)"
* "Auckland, Wellington (GMT+12:00)"
* "Nuku'alofa (GMT+13:00)"
IANA_TIMEZONE
The IANA timezone name for this timezone (e.g. America/Los_Angeles).
timezone objects have the following additional basic attributes:
STANDARD_OFFSET
The offset from UTC when DST is not being observed (e.g. -08:00).
ABBREVIATIONS
The standard abbreviation(s) for this timezone (e.g. PST/PDT).
TIMEZONE.GET
Try it!
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
Try it!
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" : {}
}
Try it!
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
}
}
Try it!
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" : {}
}
Try it!
Deletes a tradeboard posting.
Required parameter: id.
Response: On success, empty results will be returned.
TRADEBOARD.GET
> Request example:
{
"id" : "123456",
"extended" : true
}
> Response example:
{
"seconds" : "0.128193",
"jsonrpc" : "2.0",
"id" : "15",
"result" : {
"referenced_objects" : {
"workgroup" : [
{
"name" : "Help Desk",
"id" : "412345"
}
],
"department" : [
{
"name" : "Distribution",
"label" : "Distribution",
"id" : "9942"
}
],
"timezone" : [
{
"name" : "Pacific Time (US/Can) (GMT-08:00)",
"iana_timezone" : "America/Los_Angeles"
}
],
"location" : [
{
"name" : "Training / Meetings",
"id" : "92580"
}
],
"shift" : [
{
"display_time" : "1pm to 2pm",
"department" : "9942",
"reference_id" : "",
"linkurl" : "",
"work_status_type" : "5",
"start_date" : "2014-01-29T13:00:00",
"signup_list" : false,
"id" : "56789012",
"count" : "1",
"timezone" : "Pacific Time (US/Can) (GMT-08:00)",
"display_date" : "January 29, 2014",
"location" : "92580",
"subject" : "",
"covering_member" : "47",
"urgent" : false,
"zipcode" : "94132",
"qty" : "1",
"details" : "details!",
"workgroup" : "412345",
"published" : true,
"no_credit" : false,
"end_date" : "2014-01-29T14:00:00",
"covered" : true,
"no_pick_up" : false,
"no_trade" : false,
"room_floor" : "room/floor",
"linktitle" : ""
}
],
"account" : [
{
"id" : "39",
"screen_name" : null,
"last_name" : "Foster",
"first_name" : "Joanie"
},
{
"seniority_order" : "19999-12-31 23:59:59",
"id" : "47",
"profile_type" : "3",
"screen_name" : "Stan Wilson",
"last_name" : "Wilson",
"first_name" : "Stan"
}
],
"workStatusType" : [
{
"name" : "Salary/Exempt",
"id" : "5"
}
]
},
"tradeboard" : {
"trade_completed" : "2014-01-21T20:40:38Z",
"shift" : "56789012",
"notes" : "Need to see the dentist; please take this trade",
"id" : "123456",
"traded_to" : "47",
"traded_by" : "39",
"trade_complete" : true
}
}
}
Try it!
Returns information about a tradeboard posting.
Parameters:
ID
Required. id of the tradeboard posting for which to return information.
EXTENDED
Boolean; if specified and true, the results returned will include an extended
set of attributes; otherwise a basic set of attributes will be returned for each
tradeboard posting.
REFERENCED_OBJECTS
Boolean, defaults to true. Indicates that, in addition to the tradeboard
attribute, the results should include a referenced_objects attribute giving
information about objects referred to by the returned tradeboard posting.
The response results tradeboard attribute will be the selected tradeboard
object.
If requested, the response results referenced_objects attribute will be an
object containing one or more object type names as attributes; for each object
type the value will be an array of those instances of that type of object which
are referred to in the tradeboard results or in its associated shift, with only
selected minimal attributes provided:
ACCOUNT
id, first_name, last_name, and screen_name attributes are provided.
NOTE: external_id will also be returned in the results if external ids are
enabled for the site.
CLIENT
id and name attributes are provided.
DEPARTMENT
id and name attributes are provided.
LOCATION
id and name attributes are provided.
ROLE
id and name attributes are provided.
SHIFT
All basic shift attributes will be provided. If the extended parameter is true,
extended shift attributes will also be provided. Additionally, display_date and
display_time attributes contain formatted strings describing the shift's start
and end time.
TIMEZONE
name and iana_timezone attributes are provided.
workStatusType
id and name attributes are provided.
WORKGROUP
id and name attributes are provided.
TRADEBOARD.LIST
> Request example:
{
"select" : {
"end_date" : "2014-07-18",
"start_date" : "2014-07-12"
}
}
> Response example:
{
"seconds" : "0.087686",
"jsonrpc" : "2.0",
"id" : "3",
"result" : {
"referenced_objects" : {
"workgroup" : [
{
"name" : "Floor Staff",
"id" : "226093"
}
],
"account" : [
{
"id" : "20",
"screen_name" : "Johnny Smith",
"last_name" : "John",
"first_name" : "Smith"
}
],
"shift" : [
{
"workgroup" : "226093",
"display_time" : "10am to 11am",
"display_date" : "July 13, 2014",
"id" : "25687871"
}
]
},
"tradeboard" : [
{
"shift" : "25687871",
"id" : "1123",
"trade_complete" : false,
"traded_by" : "20",
"traded_to" : null
}
],
"count" : "1",
"page" : {
"this" : {
"batch" : 10,
"start" : 1
}
}
}
}
Try it!
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" : {}
}
Try it!
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
Try it!
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
Try it!
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
Try it!
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
Try it!
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
Try it!
Returns information about workStatusTypes. Uses pagination.
Parameters: None
The response results "workStatusTypes" attribute will be an array of the current
page of selected workStatusTypes. Each element of the array will be an
workStatusType object containing basic workStatusType attributes.
WORKGROUP OBJECT
WORKGROUP: BASIC ATTRIBUTES
ID
A unique identifier for this workgroup.
NAME
The name of this workgroup.
ZIP
The postal code for this workgroup.
CODE
The nickname or code for this workgroup.
CONTACT_ACCOUNT
The account identifier of the primary contact for this workgroup.
EXTERNAL_CONTACT_ACCOUNT
The external account identifier of the primary contact for this workgroup. This
field is optional, and should be used instead of contact_account if your site is
configured to support external identifiers and you wish to key off of the
external id instead.
Extended workgroup objects may also have these attributes:
ORG_DEFAULT
Boolean; true if new organization accounts by default get membership in this
workgroup.
DESCRIPTION
Workgroup description shown to current members.
AUTO_ADD
Boolean; true if members may add themselves to this workgroup; false if add
requests require manager approval.
VIEW_PUBLIC
Boolean; true if recruiting new members within the organization.
VIEW_PUBLIC_NON_ORG
Boolean; true if recruiting new members from outside the organization.
PUBLIC_EMAIL
Email address to include in recruiting information.
PUBLIC_PHONE
Phone number to include in recruiting information.
PUBLIC_CODE
Summary description of workgroup to include in recruiting information.
PUBLIC_INFO
Long description of workgroup to include in recruiting information.
SELF_REMOVE
Boolean; true if members can remove themselves from membership in this
workgroup.
ALLOW_READONLY
An integer corresponding to the various possible values for sharing:
* 0: none
* 1: share with this workgroup
* 2: share with specified groups
* 3: share with all workgroup for the site
(This value cannot be set directly, see allow_shared)
ALLOW_SHARED
Boolean; true shifts for this workgroup are shown in the shared schedule view
(depending on the value of allow_readonly: "allow_readonly":0 means
"allow_shared":false, and other values of allow_readonly are
"allow_shared":true).
To set this, either set a boolean, or an integer, corresponding to
allow_readonly.
ALLOW_SHARED_GROUPS
An object of workgroups (ID => name) to share with (if "allow_readonly":2).
To set this, use a comma-separated string of workgroup IDs. Can only be set with
workgroup.update, not workgroup.create.
SHOW_CONFIRMED
Boolean; true if the count of covered shifts by date for this workgroup is
visible to all workgroup members.
MEMBER_ADD_SHIFT
Boolean; true if workgroup members are allowed to add their own covered shifts
to the schedule.
SHOW_OPEN
Boolean; true if the count of open shifts by date for this workgroup is shown to
all workgroup members.
CANCEL_PERIOD
Number of days prior to a shift within which a workgroup member may cancel.
ALLOWED_CONFLICT_MINS
Number of minutes of overlap between shifts with the same location and workgroup
to consider not a conflict.
TIMEZONE
LOCATION
Default location identifier for this workgroup's shifts.
URL
Workgroup website.
ADDRESS
Mailing address address line.
CITY
Mailing address city.
STATE
Full name of mailing address state/province/subdivision.
COUNTRY
Full name of mailing address country.
OFFICE_PHONE
MOBILE_PHONE
OTHER_PHONE
FAX
PAGER
(Not all attributes will be provided to all users.)
LEVEL
User level within the workgroup.
* 2 - member
* 3 - coordinator
* 4 - manager
WORKGROUP.CREATE_CLIENTS
Try it!
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" : {}
}
Try it!
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" : {}
}
Try it!
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" : {}
}
Try it!
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"
}
}
Try it!
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" : {}
}
Try it!
Deletes a workgroup record.
WORKGROUP.DELETECLIENTS
> Request example:
{
"client" : "988",
"workgroup" : "226072"
}
> Response example:
{
"seconds" : "0.056321",
"jsonrpc" : "2.0",
"id" : "10",
"result" : {}
}
Try it!
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" : {}
}
Try it!
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" : {}
}
Try it!
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" : {}
}
Try it!
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": ""
}
}
Try it!
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"
}
]
}
}
Try it!
Returns information about workgroups. Uses pagination. Uses select criteria.
Optional parameters:
SELECT
An object specifying selection criteria for this request. May specify selected
workgroup object attributes and values to select. The following additional
criteria may be specified:
DELETED
true if deleted workgroups should be returned.
SEARCH
A generic search string; select workgroups containing this string in name or
code.
EXTENDED
Boolean; if specified and true, the results returned will include an extended
set of attributes; otherwise a basic set of attributes will be returned for each
workgroup.
LEVEL
Filter workgroups based on the caller's membership level. The filter is a lower
limit; any workgroups the caller has access to and is the specified level and
above, will be returned.
SHARED
Boolean; if specified and true, the results returned will also include
workgroups that are shared to the account.
REFERENCED_OBJECTS
Boolean, defaults to true. Indicates that, in addition to the workgroups
attribute, the results should include a referenced_objects attribute giving
information about objects referred to by the returned workgroups.
The response results workgroups attribute will be an array of the current page
of selected workgroups. Each element of the array will be a workgroup object
containing basic or basic and extended workgroup fields.
If requested, the response results referenced_objects attribute will be an
object containing one or more object type names as attributes; for each object
type the value will be an array of those instances of that type of object which
are referred to in the workgroups results, with only selected minimal attributes
provided:
ACCOUNT
id, first_name, last_name, and screen_name attributes are provided.
WORKGROUP.LISTJOINABLE
For sites that allow for internal team recruitment, this method will list all
public workgroups that are accepting new members from within the site. Only
workgroups that the requesting member is not already a member of will be
returned.
> Request example:
{}
> Response example:
{ "id" : "1", "jsonrpc" : "2.0", "result" : { "count" : "2", "page" : { "this" : { "batch" : "20", "start" : 1 } }, "workgroups" : [ { "code" : "", "contact_account" : "88810", "id" : "23041", "level" : 1, "name" : "First Joinable Workgroup", "user_actions" : { "delete" : false, "edit" : false, "view" : false, "view_members" : false }, "zip" : "98765" }, { "code" : "", "contact_account" : "88810", "id" : "23052", "level" : 1, "name" : "Second Joinable Workgroup", "user_actions" : { "delete" : false, "edit" : false, "view" : false, "view_members" : false }, "zip" : "98765" } ] }, "seconds" : 0.090942 }
Try it!
Returns information about workgroups. Uses pagination. Uses select criteria.
WORKGROUP.LISTCLIENTS
> Request example:
{
"select" : {
"workgroup" : "226072"
}
}
> Response example:
{
"seconds" : "0.040039",
"jsonrpc" : "2.0",
"id" : "9",
"result" : {
"count" : "1",
"page" : {
"this" : {
"batch" : 25,
"start" : 1
}
},
"workgroup_clients" : [
{
"client" : "988",
"workgroup" : "226072"
}
]
}
}
Try it!
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"
}
]
}
}
Try it!
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"
}
]
}
}
Try it!
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}}}}
Try it!
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:
RESTRICTED_ROLES
Boolean, defaults to false. If true and the caller is a site administrator, each
workgroup_roles element will also include an account attribute giving an array
of account ids of accounts with the role enabled for the workgroup.
SELECT
An object specifying selection criteria for this request. The available criteria
include:
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" : {}
}
Try it!
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" : {}
}
Try it!
Updates a workgroup record.
Required parameter: id. Any other workgroup object attributes may be specified.
Response: On success, empty results will be returned.
JSON Example PHP Code