đ Tanda API v2
API Endpoint
https://my.tanda.coGetting Started
Welcome to the Tanda API! This documentation steps you through authenticating to the API, as well as the various endpoints and methods supported.
Not sure where to start? Check out the quick start guide, or browse some code samples on GitHub.
Thereâs two ways to connect to the API. Use Authorization Code if youâre making an add-on for other Tanda users to use. Use Password if youâre building an integration just for your own account.
Authentication (Authorization Code)
Use Authorization Code authentication if youâre making an add-on for other Tanda customers to use. For example, if you are building an integration that connects your custom reporting platform to Tanda data, youâll probably want to let lots of Tanda customers use it. This is the approach for you.
First, you should create a new account for your app. Do this by signing up for a new account from the Tanda homepage, then reach out to your Tanda account manager (or developers@tanda.co) and ask for the account to be set up as a developer account.
Once you have a dedicated account, you can get an application ID, secret, and redirect URI. You can get all of these from the applications page. With those details, follow these steps to authenticate a user using the Authorization Code authentication flow.
The Authorization Code approach uses the OAuth 2 authorization code grant type. If you arenât familiar with it, this is a good, practical introduction.
https://my.tanda.co/api/oauth/authorize?scope=SCOPE1+SCOPE2&client_id=YOUR_APPLICATION_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code
1. Redirect the user to the authorize endpoint
Allow users on your website to authenticate themselves with Tanda by redirecting them to the following URL. Where APPLICATION_ID
and REDIRECT_URI
are the values specific to your app, and the scope parameter is the relevant Tanda OAuth2 scopes your want access to (more information: Scopes).
2. Catch the request to your redirect URI
The Tanda server will then redirect the request back to your redirect URI, with a request code in the URL parameters. So if your redirect URI is https://mysite.com/callback
then the request will be made to https://mysite.com/callback?code=AUTHORIZATION_CODE
.
For local testing, as the browser gets redirected to the URI, it is possible to set it to a local address (i.e. http://localhost:3000/callback
) to allow you to test your OAuth web app before deploying your code.
curl https://my.tanda.co/api/oauth/token -X POST -H "Cache-Control: no-cache" \
-F "client_id=YOUR_APPLICATION_ID" \
-F "client_secret=YOUR_SECRET" \
-F "code=AUTHORIZATION_CODE" \
-F "redirect_uri=YOUR_REDIRECT_URI" \
-F "grant_type=authorization_code"
3. Make a POST request to the token endpoint
Now that youâve got your authorization code, you can finally make the POST
request to get your access token (donât worry, this is the last step).
From your server/application make a POST
request to https://my.tanda.co/api/oauth/token
.
The response should look something like this:
{
"access_token": "6833b9ecaa84ce420da3cafaa43124d241cb28b5287b72d131f6b38bcb64cd91",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "ddeb6480f06247e3635826dd5e3875ece6f64a27044516731a914897431ab446",
"scope": "me",
"created_at": 1457304578
}
expires_in
is in seconds, so your token will last 2 hours. To learn how to refresh your token, see Refreshing your Token.
Refreshing your Token
curl https://my.tanda.co/api/oauth/token -X POST -H "Cache-Control: no-cache" \
-F "client_id=YOUR_APPLICATION_ID" \
-F "client_secret=YOUR_SECRET" \
-F "refresh_token=REFRESH_TOKEN" \
-F "redirect_uri=YOUR_REDIRECT_URI" \
-F "grant_type=refresh_token"
If you got your token using the Authorization Code authentication flow, and it expires, then using the the refresh_token
you got above, you are able to refresh it by making a POST
request to https://my.tanda.co/api/oauth/token
.
The response should look something like this:
{
"access_token": "ddeb6480f06247e3635826dd5e3875ece6f64a27044516731a914897431ab446",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "d0692903972ff6559ec5f0e3165cabd5b87f47e3613431ad53805b5397268206",
"scope": "me",
"created_at": 1457311778
}
You can now go on using this new access token for another 2 hours.
If your applicationâs access is revoked by the user, then you will need to run through the authentication process again to obtain a new access token.
Although the tokens only last for 2 hours, you can refresh your token as many times as you want. The refresh token has no expiry but can only be used once.
Authentication (Password)
Use Password authentication if youâre building an integration just for your own account. For example, if youâre building an integration for a specific customer - either as an in-house developer or as a consultant - this is the the approach for you.
If youâre using the API for a single account, the Password authentication flow is an easier way to get set up. You can authenticate via the command line using your Tanda login details, or you can just set up an access token through the Tanda API management page.
Access tokens generated using Password authentication never expire, but can be revoked from the API management page.
1. Make a POST request to the token endpoint
curl https://my.tanda.co/api/oauth/token -X POST -H "Cache-Control: no-cache" \
-F "username=USER_EMAIL" \
-F "password=USER_PASSWORD" \
-F "scope=SCOPE1 SCOPE2" \
-F "grant_type=password"
From your server/application make a POST
request to https://my.tanda.co/api/oauth/token
with the userâs email and password.
The response should look something like this:
{
"access_token": "6833b9ecaa84ce420da3cafaa43124d241cb28b5287b72d131f6b38bcb64cd91",
"token_type": "bearer",
"scope": "me",
"created_at": 1457304578
}
Password authenticated tokens have no expiry. They can also be created and revoked from the access tokens page.
Making Requests
Once either of the above authentication methods have been completed, youâll have an access token (in the case of Authorization Code authentication, the token will only last for 2 hours).
Your access token will look something like this: 6833b9ecaa84ce420da3cafaa43124d241cb28b5287b72d131f6b38bcb64cd91
.
From here on out all requests you make to the Tanda v2 API must include the token in the header like so:
curl --header "Authorization: bearer 6833b9ecaa84ce420da3cafaa43124d241cb28b5287b72d131f6b38bcb64cd91" \
https://my.tanda.co/api/v2/users/me
Authorization: bearer 6833b9ecaa84ce420da3cafaa43124d241cb28b5287b72d131f6b38bcb64cd91
See the right hand sidebar for an example of a request that gets information about the user that just authenticated.
Invalid Subscriptions
If you receive a 402
response status with this message:
Your account is locked out for billing purposes, and cannot use the API!
This indicates that the customerâs account does not have a valid credit card or other billing method set, and their free trial has ended. Therefore they will not be able to access some components of Tanda either through the website or the API.
You can query the current user endpoint to check if a user has a valid subscription.
Rate Limiting
If you reach the rate limit, youâll get the following 429
response:
Headers
X-RateLimit-Limit: 200
X-RateLimit-RateLimited: true
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1461211225
Body
{
"error": "API rate limit exceeded!"
}
Requests to the API are rate limited to 200 requests, per 1 minute for each requester.
A requester is defined through the following workflow:
- Is the request using a Password Access Token?
- Yes? Then the requester is the current user (meaning all requests made though any of my password tokens are counted together).
- No? The the requester is the combination of the OAuth app and current user.
When making requests to the API, the following headers will be added to the response:
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 52
X-RateLimit-Reset: 1461211225
-
X-RateLimit-Limit
is the your rate limit -
X-RateLimit-Remaining
is the remaining number of requests you can make before you will be rate limited -
X-RateLimit-Reset
is when the rate limit will be reset
If have reached the rate limit, then an additional header will be present:
X-RateLimit-RateLimited: true
Hereâs an example to make things a little clearer:
-
I have multiple Password Access Tokens with different scopes,
token_1
,token_2
. -
I have an OAuth app, which is used by
user_1
,user_2
and myself. -
user_2
has also created an OAuth app which I am using.
This is the maximum number of requests that can be made in a single minute:
-
199 requests with
token_1
-
1 request with
token_2
(I have 200 requests/min for all my Password Access Tokens) -
200 requests on my behalf through
user_2
's OAuth app -
200 requests on my behalf through my OAuth app
-
200 requests on
user_1
's behalf through my OAuth app -
200 requests on
user_2
's behalf through my OAuth app
In summary the distinct requesters in this example are:
-
Me through my Password Access Tokens
-
Me through
user_2
's OAuth app -
Me through my OAuth app
-
user_1
through my OAuth app -
user_2
through my OAuth app
Caching
curl --header "If-None-Match: 17f1542065ae37d0963a608fd632b4615a288ceb" --header "Authorization: bearer 6833b9ecaa84ce420da3cafaa43124d241cb28b5287b72d131f6b38bcb64cd91" \
https://my.tanda.co/api/v2/users/me
The Tanda API supports the If-None-Match
HTTP header. All API responses will include an ETag
response header. You can use the value of this header in future requests to the same endpoint by passing it to the If-None-Match
request header. If the content the API would return has not changed, you will get back a 304
Not Modified response.
The right sidebar has an example of an ETag being included in a request. For more information about ETags and If-None-Match, see Mozillaâs guide.
Scopes
In both the Authorization Code and Password authentication methods, you are required to include a scope
parameter. Here is a complete list of the scopes in the Tanda API, additionally, in this documentation each endpoint specifies which scope/s it requires.
Scope | Endpoints | Description |
---|---|---|
me |
Users, Shift Reminders | Access information about the current user |
roster |
Rosters, Schedules, Schedule Swap Plans, Custom Events | Manage roster, schedule information, shift swaps and custom events |
timesheet |
Timesheets, Shifts | Manage timesheet and shift information |
department |
Locations, Teams (Departments), Shift Details, Custom Events | Manage location, department (team), and shift detail information |
user |
Users, Award Tags, Clock Ins | Manage personal information about your employees (without wages) |
cost |
Users, Timesheets, Shifts, Rosters, Schedules, WageComparisons | Mange information about your employeeâs wage, and see costs for timesheets and rosters |
leave |
Leave Requests, Leave Balances | Manage leave requests and balances |
unavailability |
Unavailability | Manage unavailability |
datastream |
Data Streams, Data Stream Joins, Store Stats | Manage your data streams and store stats |
device |
Devices, Clock Ins | Manage timeclock information, and read clock ins for devices |
qualifications |
Qualifications | Manage qualifications |
settings |
Settings, Award Templates | Manage account settings and award related configuration |
organisation |
Organisations | View & create client organisations |
sms |
SMS | Send SMS |
personal |
Personal Details | Manage your personal details (without Bank Details, TFN, etc) |
financial |
Personal Details, Users | Access financial data about your employees (Bank Details, TFN, etc) |
platform |
Platform | Get platform data |
Not only will you need the relevant scopes to access the endpoints, but also the correct system permissions in Tanda. For more information see each endpoint group.
By selecting only the bare minimum scopes that your application needs, users will feel more comfortable authorizing your application.
For example: If you had all scopes selected but your application simply collects information about users (using the User endpoint, and user
scope) people will question why your application needs to have access to timesheet data (timesheet
scope) and will be less likely to approve it.
Dates and Times
All dates in the Tanda API are rendered in YYYY-MM-DD format. Any request you make must use YYYY-MM-DD format for all dates.
All times in the Tanda API are rendered as Unix time, this is to avoid confusion as there can be users with different timezones in the same organisation. A userâs timezone can be retrieved from the both the User endpoint and the Current User endpoint. Any request you make must use Unix time for all times.
Our user guide has more information on working with unix times through the API.
Update Timestamps
As well as the fields listed in the API examples below, every API response will also include an updated_at
timestamp. This represents the last time that an object was updated. Like all other times returned by the API, it will be formatted as a Unix timestamp.
Many GET endpoints support an updated_after
querystring parameter. Use this to filter results API-side by the updated_at
field. Some endpoints also support a show_costs
parameter, and return a last_costed_at
field. If you pass both show_costs
and updated_after
, we will compare to both the updated_at
and last_costed_at
field when filtering.
An example may illustrate this better. Say you have a shift, and at 10am you change its start time. Then, at 11am, costing details for the shiftâs employee are changed, which causes the cost of the shift to update. The shiftâs updated_at
will be 10am, while its last_costed_at
will be 11am. If you make a call to the shift GET endpoint with updated_after
of 10:30am, the shift will not be returned. But if you include the show_costs
parameter when making the call, the shift will be returned since it was last costed after 10:30am.
Audit Trails
Every change made in Tanda through the API is logged and added to the in-Tanda audit trail. By default, changes will be marked as being made by âAPI v2â, with the user ID that corresponds to the authenticated user. If youâre building an integration that requires more fine tuned auditing (for example, a token is shared by multiple users, but youâre able to identify which user is responsible for a particular action), you can customise the user ID and audit trail name that are displayed. Please contact developers@tanda.co and we can help you set this up.
Code Samples
We have a repository of code samples available on GitHub. Hereâs some guides you might find helpful:
General ¶
Current User ¶
Headers
Content-Type: application/json
Body
{
"id": 123456,
"name": "Lenny Leonard",
"email": "lenny.leonard@springfieldpowerplant.com",
"photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
"time_zone": "Australia/Brisbane",
"utc_offset": 36000,
"organisation": "Moe's Tavern",
"organisation_id": 126546,
"locale": "en-US",
"country": "United States",
"permissions": [
"employee",
"manager"
],
"valid_subscription": true,
"user_ids": [
1,
2,
123456
],
"organisations": [
{
"name": "Moe's Tavern",
"id": 1,
"user_id": 1,
"locale": "en-US",
"country": "United States"
},
{
"name": "Bob's Burgers",
"id": 2,
"user_id": 1,
"locale": "en-US",
"country": "United States"
},
{
"name": "Dave's Doors",
"id": 3,
"user_id": 123456,
"locale": "en-AU",
"country": "Australia"
}
],
"updated_at": 1478650040
}
Get Current UserGET/api/v2/users/me
Gets information about the current user (i.e. the user that has been authenticated).
The following fields are returned:
-
id
- the userâs unique ID. -
name
- the userâs name. -
email
- the userâs email. -
photo
- if present, a link to a photo of the user. -
time_zone
- the name of the time zone the user is in - uses zone names from the IANA Time Zone Database. See our user guide for more on using times with the Tanda API. -
utc_offset
- the UTC offset for the current user, this can be used as a compliment to the time zone name. See our user guide for more on using times with the Tanda API. -
organisation
- the name of the currently authenticated organisation. A user can belong to one or more organisations. Unless otherwise specified on the individual endpoint, only data from this organisation will be returned by any API calls using the current access token. -
organisation_id
- the ID of the currently authenticated organisation. A user can belong to one or more organisations. Unless otherwise specified on the individual endpoint, only data from this organisation will be returned by any API calls using the current access token. -
locale
- the locale of the user. -
country
- the country the userâs organisation is based in. -
permissions
- The userâs privilege levels in the system, from the set of['organisation_admin', 'payroll_officer', 'roster_manager', 'manager', 'employee', 'partner']
. -
valid_subscription
- If true, the user will be able to access other API endpoints. -
user_ids
- User IDs associated with this user. This array will contain more than one item if the user has multiple profiles. If you want to get all data relating to a person across all their workplaces, use these. If you need to restrict your API call to a specific user, you can use theX-User-Id
header and one of these IDs. -
organisations
- Organisations at which this user has profiles, based onuser_ids
. If your application needs to deal with people who may work at more than one Tanda organisation, you should use this. If you need to restrict your API call to a specific organisation, you can use theX-Organisation-Id
header and one of these IDs. Note that a user may have multiple profiles within the same organisation.
This method requires the me
scope (see Scopes for more information).
Rosters ¶
Rosters are the container for scheduled shifts, each roster runs for 1 week and contains Schedules. For actual times worked, please see Timesheets or Shifts.
Rosters are not created directly. Instead a roster will be created when creating through the Schedules endpoint.
No special Tanda permissions are required to use the roster endpoint.
Roster ¶
Headers
Content-Type: application/json
Body
{
"id": 70074,
"schedules": [
{
"date": "2016-03-02",
"schedules": [
{
"id": 31337157,
"roster_id": 70074,
"user_id": 123456,
"start": 1456902000,
"finish": 1456916400,
"breaks": [
{
"start": 1456909200,
"finish": 1456911000
}
],
"automatic_break_length": 30,
"department_id": 111,
"shift_detail_id": 36,
"cost": 20.19,
"last_published_at": 1457002800,
"acceptance_status: `not_accepted`": "Hello, world!",
"record_id": 532432,
"needs_acceptance": true
}
]
}
],
"start": "2016-02-29",
"finish": "2016-03-07",
"cost": 1200.2,
"meta": {
"page": 1,
"page_size": 100,
"total": 53360,
"total_pages": 534
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the roster"
},
"schedules": {
"type": "array",
"description": "The roster broken down by days"
},
"start": {
"type": "string",
"description": "The date of the first day of the roster"
},
"finish": {
"type": "string",
"description": "The date of the last day of the roster"
},
"cost": {
"type": "number",
"description": "The total cost of the roster, if `show_costs=true` parameter is set"
},
"meta": {
"type": "object",
"properties": {
"page": {
"type": "number",
"description": "The page number of data when DailyScheduleData is paginated."
},
"page_size": {
"type": "number",
"description": "The number of records per page when DailyScheduleData is paginated."
},
"total": {
"type": "number",
"description": "The total number of records in a query when DailyScheduleData is paginated."
},
"total_pages": {
"type": "number",
"description": "The total number of pages in a paginated query when DailyScheduleData is paginated."
}
},
"description": "The pagination metadata, if `page` and `page_size` parameters are set"
}
},
"required": [
"id",
"schedules",
"start",
"finish"
]
}
Get RosterGET/api/v2/rosters/{id}{?show_costs}
Get a roster by id.
This method requires the roster
scope (see Scopes for more information).
If you are using show_costs=true
, the cost
scope is also required.
- id
number
(required) Example: 70074The id of the roster
- show_costs
boolean
(optional) Example: trueWhether to show the costs for the roster (defaults to false)
Current Roster ¶
Headers
Content-Type: application/json
Body
{
"id": 70074,
"schedules": [
{
"date": "2016-03-02",
"schedules": [
{
"id": 31337157,
"roster_id": 70074,
"user_id": 123456,
"start": 1456902000,
"finish": 1456916400,
"breaks": [
{
"start": 1456909200,
"finish": 1456911000
}
],
"automatic_break_length": 30,
"department_id": 111,
"shift_detail_id": 36,
"cost": 20.19,
"last_published_at": 1457002800,
"acceptance_status: `not_accepted`": "Hello, world!",
"record_id": 532432,
"needs_acceptance": true
}
]
}
],
"start": "2016-02-29",
"finish": "2016-03-07",
"cost": 1200.2,
"meta": {
"page": 1,
"page_size": 100,
"total": 53360,
"total_pages": 534
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the roster"
},
"schedules": {
"type": "array",
"description": "The roster broken down by days"
},
"start": {
"type": "string",
"description": "The date of the first day of the roster"
},
"finish": {
"type": "string",
"description": "The date of the last day of the roster"
},
"cost": {
"type": "number",
"description": "The total cost of the roster, if `show_costs=true` parameter is set"
},
"meta": {
"type": "object",
"properties": {
"page": {
"type": "number",
"description": "The page number of data when DailyScheduleData is paginated."
},
"page_size": {
"type": "number",
"description": "The number of records per page when DailyScheduleData is paginated."
},
"total": {
"type": "number",
"description": "The total number of records in a query when DailyScheduleData is paginated."
},
"total_pages": {
"type": "number",
"description": "The total number of pages in a paginated query when DailyScheduleData is paginated."
}
},
"description": "The pagination metadata, if `page` and `page_size` parameters are set"
}
},
"required": [
"id",
"schedules",
"start",
"finish"
]
}
Get the Current RosterGET/api/v2/rosters/current{?show_costs}
Get the current roster.
This method requires the roster
scope (see Scopes for more information).
If you are using show_costs=true
, the cost
scope is also required.
- show_costs
boolean
(required) Example: trueWhether to show the costs for the roster (defaults to false)
Roster that Contains Date ¶
Headers
Content-Type: application/json
Body
{
"id": 70074,
"schedules": [
{
"date": "2016-03-02",
"schedules": [
{
"id": 31337157,
"roster_id": 70074,
"user_id": 123456,
"start": 1456902000,
"finish": 1456916400,
"breaks": [
{
"start": 1456909200,
"finish": 1456911000
}
],
"automatic_break_length": 30,
"department_id": 111,
"shift_detail_id": 36,
"cost": 20.19,
"last_published_at": 1457002800,
"acceptance_status: `not_accepted`": "Hello, world!",
"record_id": 532432,
"needs_acceptance": true
}
]
}
],
"start": "2016-02-29",
"finish": "2016-03-07",
"cost": 1200.2,
"meta": {
"page": 1,
"page_size": 100,
"total": 53360,
"total_pages": 534
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the roster"
},
"schedules": {
"type": "array",
"description": "The roster broken down by days"
},
"start": {
"type": "string",
"description": "The date of the first day of the roster"
},
"finish": {
"type": "string",
"description": "The date of the last day of the roster"
},
"cost": {
"type": "number",
"description": "The total cost of the roster, if `show_costs=true` parameter is set"
},
"meta": {
"type": "object",
"properties": {
"page": {
"type": "number",
"description": "The page number of data when DailyScheduleData is paginated."
},
"page_size": {
"type": "number",
"description": "The number of records per page when DailyScheduleData is paginated."
},
"total": {
"type": "number",
"description": "The total number of records in a query when DailyScheduleData is paginated."
},
"total_pages": {
"type": "number",
"description": "The total number of pages in a paginated query when DailyScheduleData is paginated."
}
},
"description": "The pagination metadata, if `page` and `page_size` parameters are set"
}
},
"required": [
"id",
"schedules",
"start",
"finish"
]
}
Headers
Content-Type: application/json
Get Roster that Contains DateGET/api/v2/rosters/on/{date}{?show_costs}
Get the roster that contains a date, will return a 204
response if there is no roster.
This method requires the roster
scope (see Scopes for more information).
If you are using show_costs=true
, the cost
scope is also required.
- date
string
(required) Example: 2016-03-02The date thatâs contained in the roster you are looking for.
- show_costs
boolean
(optional) Example: trueWhether to show the costs for the roster (defaults to false)
- page
number
(optional) Example: 1The page number for your nested schedule list
- page_size
number
(optional) Example: 50The number of nested schedules retrieved per page. Maximum 100 per page.
Sales Targets ¶
Headers
Content-Type: application/json
Body
{
"target": "1234.56",
"created_at": 1519621685,
"updated_at": 1519621685,
"user_entered": true
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "Value of the sales target. null if there is no roster for the given date."
},
"created_at": {
"type": [
"number",
"null"
],
"description": "When the user-entered sales target was first created, if there is one. Otherwise null."
},
"updated_at": {
"type": [
"number",
"null"
],
"description": "When the user-entered sales target was last updated, if there is one. Otherwise null."
},
"user_entered": {
"type": "boolean",
"description": "Whether or not the default projection was overridden with a user-entered value."
}
},
"required": [
"created_at",
"updated_at",
"user_entered"
]
}
Get Sales TargetGET/api/v2/rosters/sales_targets/{type}/{date}
Get the sales target for a given roster with no filter.
This method requires the roster
scope (see Scopes for more information).
- type
string
(required)There are two possible values:
day
andweek
.- date
string
(required) Example: 2018-02-26A date within the roster you are looking for.
Sales Targets for Team (Department) ¶
Headers
Content-Type: application/json
Body
{
"target": "1234.56",
"created_at": 1519621685,
"updated_at": 1519621685,
"user_entered": true
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "Value of the sales target. null if there is no roster for the given date."
},
"created_at": {
"type": [
"number",
"null"
],
"description": "When the user-entered sales target was first created, if there is one. Otherwise null."
},
"updated_at": {
"type": [
"number",
"null"
],
"description": "When the user-entered sales target was last updated, if there is one. Otherwise null."
},
"user_entered": {
"type": "boolean",
"description": "Whether or not the default projection was overridden with a user-entered value."
}
},
"required": [
"created_at",
"updated_at",
"user_entered"
]
}
Get Target for TeamGET/api/v2/rosters/sales_targets/{type}/{date}{?department_id}
Get the sales target for a given roster filtered to a team.
You must either be an Admin or General Manager, or have read access to the team you are requesting.
This method requires the roster
scope (see Scopes for more information).
- type
string
(required)There are two possible values:
day
andweek
.- date
string
(required) Example: 2018-02-26A date within the roster you are looking for.
- department_id
number
(optional) Example: 123The ID of a team to filter the roster to.
Sales Targets for Location ¶
Headers
Content-Type: application/json
Body
{
"target": "1234.56",
"created_at": 1519621685,
"updated_at": 1519621685,
"user_entered": true
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "Value of the sales target. null if there is no roster for the given date."
},
"created_at": {
"type": [
"number",
"null"
],
"description": "When the user-entered sales target was first created, if there is one. Otherwise null."
},
"updated_at": {
"type": [
"number",
"null"
],
"description": "When the user-entered sales target was last updated, if there is one. Otherwise null."
},
"user_entered": {
"type": "boolean",
"description": "Whether or not the default projection was overridden with a user-entered value."
}
},
"required": [
"created_at",
"updated_at",
"user_entered"
]
}
Get Target for LocationGET/api/v2/rosters/sales_targets/{type}/{date}{?location_id}
Get the sales target for a given roster filtered to a location.
You must either be an Admin or General Manager, or have read access to the location you are requesting.
This method requires the roster
scope (see Scopes for more information).
- type
string
(required)There are two possible values:
day
andweek
.- date
string
(required) Example: 2018-02-26A date within the roster you are looking for.
- location_id
number
(optional) Example: 456The ID of a location to filter the roster to.
Schedules ¶
Schedules represent planned shifts for a user and are contained in a Roster, for actual times worked please see Timesheets or Shifts.
No special Tanda permissions are required to view schedules, however only the schedules that would be visible through the UI are visible through the API.
To create or change schedules, the user must be a team manager, roster manager, or admin. In the case of the team manager, the shift must be for someone in the userâs managed teams.
Employees can only see published schedules. Specifying ids of unpublished schedules, or using the published_only
flag will not change this.
Looking to just get the roster for an individual employee? Check out our user guide for a workflow.
Schedules ¶
Headers
Content-Type: application/json
Body
[
{
"id": 31337157,
"roster_id": 70074,
"user_id": 123456,
"start": 1456902000,
"finish": 1456916400,
"breaks": [
{
"start": 1456909200,
"finish": 1456911000
}
],
"automatic_break_length": 30,
"department_id": 111,
"shift_detail_id": 36,
"cost": 20.19,
"last_published_at": 1457002800,
"acceptance_status: `not_accepted`": "Hello, world!",
"record_id": 532432,
"needs_acceptance": true
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get SchedulesGET/api/v2/schedules{?ids,show_costs,include_names,include_colleagues,platform}
Get multiple schedules by id.
This method requires the roster
scope (see Scopes for more information).
If you are using show_costs=true
or show_award_interpretation=true
, the cost
scope is also required.
- ids
string
(required) Example: 1,2,31337157Comma separated list of schedule ids
- show_costs
boolean
(optional) Example: trueWhether to show the costs for the schedule (defaults to false).
- show_award_interpretation
boolean
(optional) Example: trueWhether to show costs breakdown for the schedule (defaults to false).
- include_names
boolean
(optional) Example: falseIf true, the department name and shift detail name (not just ID) will be included in the response. Defaults to false.
- include_colleagues
boolean
(optional) Example: falseIf true, shifts for colleagues will be returned. If false, only shifts for the current user will be returned. Defaults to false.
- platform
boolean
(optional) Example: falseIf true, Platform data will be returned (defaults to false).
- updated_after
number
(optional) Example: 1451570400Time filter to find recently created or modified schedules
- published_only
boolean
(optional) Example: falseOnly retrieve schedules that have been published. Useful for managers to see only published schedules, where they would usually see any schedule. Defaults to false.
- show_vacant_only
boolean
(optional) Example: falseOnly retrieve schedules that are vacant. Defaults to false.
Headers
Content-Type: application/json
Body
[
{
"id": 31337157,
"roster_id": 70074,
"user_id": 123456,
"start": 1456902000,
"finish": 1456916400,
"breaks": [
{
"start": 1456909200,
"finish": 1456911000
}
],
"automatic_break_length": 30,
"department_id": 111,
"shift_detail_id": 36,
"cost": 20.19,
"last_published_at": 1457002800,
"acceptance_status: `not_accepted`": "Hello, world!",
"record_id": 532432,
"needs_acceptance": true
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get Schedules by UserGET/api/v2/schedules{?user_ids,from,to,show_costs,include_names}
Get multiple schedules by user IDs, from, and to date. From and to date are required, while user IDs are optional. If no user IDs are provided, all visible schedules (based on the current userâs permission levels) will be returned.
This method requires the roster
scope (see Scopes for more information).
If you are using show_costs=true
, the cost
scope is also required, and you must have access to see wages for all user IDs provided.
- user_ids
string
(required) Example: 1,2,123456Comma separated list of user ids. You can pass user IDs from multiple different organisations, for example if you want to get all schedules for a particular person across companies.
- from
string
(required) Example: 2016-03-02From date to lookup schedules in. If provided, from and to can be at most 7 days apart.
- to
string
(required) Example: 2016-03-02To date to lookup schedules in. If provided, from and to can be at most 7 days apart.
- show_costs
boolean
(optional) Example: trueWhether to show the costs for the schedule (defaults to false).
- show_award_interpretation
boolean
(optional) Example: trueWhether to show costs breakdown for the schedule (defaults to false).
- include_names
boolean
(optional) Example: falseIf true, the department name and shift detail name (not just ID) will be included in the response. Defaults to false.
- updated_after
number
(optional) Example: 1451570400Time filter to find recently created or modified schedules
Headers
Content-Type: application/json
Body
{
"user_id": 123456,
"start": 1456903800,
"finish": 1456911000,
"department_id": 111,
"automatic_break_length": 30
}
Headers
Content-Type: application/json
Body
{
"id": 31337158,
"roster_id": 70074,
"user_id": 123456,
"start": 1456903800,
"finish": 1456911000,
"breaks": [],
"automatic_break_length": 30,
"department_id": 111,
"shift_detail_id": null,
"last_published_at": null,
"last_acknowledged_at": null,
"acceptance_status": "not_accepted"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the schedule"
},
"roster_id": {
"type": "number",
"description": "The id of the roster"
},
"user_id": {
"type": "number",
"description": "The id of the user who is assigned the schedule"
},
"start": {
"type": "number",
"description": "The start of the schedule"
},
"finish": {
"type": "number",
"description": "The end of the schedule"
},
"breaks": {
"type": "array",
"description": "The breaks taken in the schedule"
},
"automatic_break_length": {
"type": "number",
"description": "Length of automatic break in minutes"
},
"department_id": {
"type": "number",
"description": "The department (team) id for the schedule"
},
"shift_detail_id": {
"type": "number",
"description": "The shift detail id for the schedule"
},
"cost": {
"type": "number",
"description": "The cost of the schedule, if `show_costs=true` parameter is set"
},
"last_published_at": {
"type": "number",
"description": "When the schedule was last published to its given employee"
},
"acceptance_status: `not_accepted`": {
"type": "string",
"description": "The current status of the schedule"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
},
"needs_acceptance": {
"type": "boolean",
"description": "Has the schedule been accepted by the employee?"
}
},
"required": [
"id",
"roster_id"
]
}
Headers
Content-Type: application/json
Body
{
"start": 1456903800
}
Headers
Content-Type: application/json
Body
{
"id": 31337158,
"roster_id": 70074,
"user_id": null,
"start": 1456903800,
"finish": null,
"breaks": [],
"automatic_break_length": null,
"department_id": null,
"shift_detail_id": null,
"last_published_at": null,
"last_acknowledged_at": null,
"acceptance_status": "not_accepted"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the schedule"
},
"roster_id": {
"type": "number",
"description": "The id of the roster"
},
"user_id": {
"type": "number",
"description": "The id of the user who is assigned the schedule"
},
"start": {
"type": "number",
"description": "The start of the schedule"
},
"finish": {
"type": "number",
"description": "The end of the schedule"
},
"breaks": {
"type": "array",
"description": "The breaks taken in the schedule"
},
"automatic_break_length": {
"type": "number",
"description": "Length of automatic break in minutes"
},
"department_id": {
"type": "number",
"description": "The department (team) id for the schedule"
},
"shift_detail_id": {
"type": "number",
"description": "The shift detail id for the schedule"
},
"cost": {
"type": "number",
"description": "The cost of the schedule, if `show_costs=true` parameter is set"
},
"last_published_at": {
"type": "number",
"description": "When the schedule was last published to its given employee"
},
"acceptance_status: `not_accepted`": {
"type": "string",
"description": "The current status of the schedule"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
},
"needs_acceptance": {
"type": "boolean",
"description": "Has the schedule been accepted by the employee?"
}
},
"required": [
"id",
"roster_id"
]
}
Schedule ¶
Headers
Content-Type: application/json
Body
{
"id": 31337157,
"roster_id": 70074,
"user_id": 123456,
"start": 1456902000,
"finish": 1456916400,
"breaks": [
{
"start": 1456909200,
"finish": 1456911000
}
],
"automatic_break_length": 30,
"department_id": 111,
"shift_detail_id": 36,
"cost": 20.19,
"last_published_at": 1457002800,
"acceptance_status: `not_accepted`": "Hello, world!",
"record_id": 532432,
"needs_acceptance": true
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the schedule"
},
"roster_id": {
"type": "number",
"description": "The id of the roster"
},
"user_id": {
"type": "number",
"description": "The id of the user who is assigned the schedule"
},
"start": {
"type": "number",
"description": "The start of the schedule"
},
"finish": {
"type": "number",
"description": "The end of the schedule"
},
"breaks": {
"type": "array",
"description": "The breaks taken in the schedule"
},
"automatic_break_length": {
"type": "number",
"description": "Length of automatic break in minutes"
},
"department_id": {
"type": "number",
"description": "The department (team) id for the schedule"
},
"shift_detail_id": {
"type": "number",
"description": "The shift detail id for the schedule"
},
"cost": {
"type": "number",
"description": "The cost of the schedule, if `show_costs=true` parameter is set"
},
"last_published_at": {
"type": "number",
"description": "When the schedule was last published to its given employee"
},
"acceptance_status: `not_accepted`": {
"type": "string",
"description": "The current status of the schedule"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
},
"needs_acceptance": {
"type": "boolean",
"description": "Has the schedule been accepted by the employee?"
}
},
"required": [
"id",
"roster_id"
]
}
Get ScheduleGET/api/v2/schedules/{id}{?show_costs,include_names,platform}
Get a schedule by id.
If you are not able to see the schedule through the UI then you will not be able to see it through the API.
This method requires the roster
scope (see Scopes for more information).
If you are using show_costs=true
, the cost
scope is also required.
- id
number
(required) Example: 31337157The id of the schedule
- show_costs
boolean
(optional) Example: trueWhether to show the costs for the schedule (defaults to false)
- show_award_interpretation
boolean
(optional) Example: trueWhether to show costs breakdown for the schedule (defaults to false).
- include_names
boolean
(optional) Example: falseIf true, the department name and shift detail name (not just ID) will be included in the response. Defaults to false.
- platform
boolean
(optional) Example: falseIf true, Platform data will be returned (defaults to false).
Headers
Content-Type: application/json
Body
{
"start": 1456898400,
"breaks": [
{
"start": 1456903800,
"finish": 1456905600
},
{
"start": 1456909200,
"finish": 1456911000
}
],
"automatic_break_length": null,
"department_id": null
}
Headers
Content-Type: application/json
Body
{
"id": 31337157,
"roster_id": 70074,
"user_id": 123456,
"start": 1456898400,
"finish": 1456916400,
"breaks": [
{
"start": 1456903800,
"finish": 1456905600,
"paid": false
},
{
"start": 1456909200,
"finish": 1456911000,
"paid": false
}
],
"automatic_break_length": null,
"department_id": null,
"shift_detail_id": null,
"last_published_at": null,
"last_acknowledged_at": null,
"acceptance_status": "not_accepted"
}
Headers
Content-Type: application/json
Body
{
"user_id": nil
}
Headers
Content-Type: application/json
Body
{
"id": 31337157,
"roster_id": 70074,
"user_id": null,
"start": 1456902000,
"finish": 1456916400,
"breaks": [
{
"start": 1456909200,
"finish": 1456911000,
"paid": false
}
],
"department_id": 111,
"shift_detail_id": null,
"last_published_at": null,
"last_acknowledged_at": null,
"acceptance_status": "not_accepted"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the schedule"
},
"roster_id": {
"type": "number",
"description": "The id of the roster"
},
"user_id": {
"type": "number",
"description": "The id of the user who is assigned the schedule"
},
"start": {
"type": "number",
"description": "The start of the schedule"
},
"finish": {
"type": "number",
"description": "The end of the schedule"
},
"breaks": {
"type": "array",
"description": "The breaks taken in the schedule"
},
"automatic_break_length": {
"type": "number",
"description": "Length of automatic break in minutes"
},
"department_id": {
"type": "number",
"description": "The department (team) id for the schedule"
},
"shift_detail_id": {
"type": "number",
"description": "The shift detail id for the schedule"
},
"cost": {
"type": "number",
"description": "The cost of the schedule, if `show_costs=true` parameter is set"
},
"last_published_at": {
"type": "number",
"description": "When the schedule was last published to its given employee"
},
"acceptance_status: `not_accepted`": {
"type": "string",
"description": "The current status of the schedule"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
},
"needs_acceptance": {
"type": "boolean",
"description": "Has the schedule been accepted by the employee?"
}
},
"required": [
"id",
"roster_id"
]
}
Headers
Content-Type: application/json
Body
{
"automatic_break_length": 25,
"breaks": null
}
Headers
Content-Type: application/json
Body
{
"id": 31337157,
"roster_id": 70074,
"user_id": 123456,
"start": 1456902000,
"finish": 1456916400,
"breaks": [],
"automatic_break_length": 25,
"department_id": 111,
"shift_detail_id": null,
"last_published_at": null,
"last_acknowledged_at": null,
"acceptance_status": "not_accepted"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the schedule"
},
"roster_id": {
"type": "number",
"description": "The id of the roster"
},
"user_id": {
"type": "number",
"description": "The id of the user who is assigned the schedule"
},
"start": {
"type": "number",
"description": "The start of the schedule"
},
"finish": {
"type": "number",
"description": "The end of the schedule"
},
"breaks": {
"type": "array",
"description": "The breaks taken in the schedule"
},
"automatic_break_length": {
"type": "number",
"description": "Length of automatic break in minutes"
},
"department_id": {
"type": "number",
"description": "The department (team) id for the schedule"
},
"shift_detail_id": {
"type": "number",
"description": "The shift detail id for the schedule"
},
"cost": {
"type": "number",
"description": "The cost of the schedule, if `show_costs=true` parameter is set"
},
"last_published_at": {
"type": "number",
"description": "When the schedule was last published to its given employee"
},
"acceptance_status: `not_accepted`": {
"type": "string",
"description": "The current status of the schedule"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
},
"needs_acceptance": {
"type": "boolean",
"description": "Has the schedule been accepted by the employee?"
}
},
"required": [
"id",
"roster_id"
]
}
Update SchedulePUT/api/v2/schedules/{id}
Only one of breaks
and automatic_break_length
can be set to non-null values. If automatic_break_length
or breaks
is already set, you will not be able to change the other unless the set field is cleared (can be done in the same request by setting the currently set field to null
).
This method requires the roster
scope (see Scopes for more information).
- id
number
(required) Example: 31337157The id of the schedule
Headers
Content-Type: application/json
Schedule Versions ¶
Headers
Content-Type: application/json
Body
[
{
"version_id": 123456,
"time": 1459209907,
"event": "update",
"author": {
"id": 123456,
"name": "API v2"
},
"item_id": 1235435,
"item_type": "\"Schedule\"",
"changes": [
{
"field": "start",
"previous": 1456898400,
"updated": 1456902000
},
{
"field": "finish",
"previous": 1456912800,
"updated": 1456916400
}
]
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get Schedule VersionsGET/api/v2/schedules/{id}/versions
If you are not able to see the schedule through the UI then you will not be able to see it through the API.
This method requires the roster
scope (see Scopes for more information).
- id
number
(required) Example: 31337157The id of the schedule
- updated_after
number
(optional) Example: 1451570400Time filter to find recently created or modified schedule versions
Timesheets ¶
Timesheets are the container for actual shifts worked, a timesheet can be for a period of 1 or 2 weeks depending on how the organisation pays their staff. Each timesheet contains many Shifts. For rostered times, please see Rosters or Schedules.
Timesheets are not created directly. Instead a timesheet will be created when creating through the Shifts endpoint.
Regular employees can only see their own timesheets, roster managers and admins can see all timesheets, and department managers can only see timesheets for staff that they manage.
All methods require the timesheet
scope (see Scopes for more information).
Exporting Timesheets
You can download a timesheet in an export format to be imported into a payroll system by providing the export_format
URI parameter. This works with any of the timesheet endpoints.
For example, making a call to /api/v2/timesheets/7007?export_format=myob
will return a MYOB-compatible export of the timesheet, and /api/v2/timesheets/on/2016-03-02?export_format=myob
will return a MYOB-compatible export of all timesheets for that date range.
By default all timesheets will be returned. Provide the approved_only
parameter to limit your export to approved timesheets (this is the default behaviour in the Tanda UI). For example, /api/v2/timesheets/7007?export_format=myob&approved_only=true
.
The content-type of these responses will not be application/json
as they are for other API calls - it will depend on the export format requested, but will generally be text/plain
or text/csv
.
Timesheets will have their status set to exported when accessed through this endpoint. If you donât want this to happen, include the skip_status_update
parameter - eg. /api/v2/timesheets/7007?export_format=myob&skip_status_update=true
. Alternatively, use the update timesheeet endpoint to reset their status.
Current Timesheets ¶
Headers
Content-Type: application/json
Body
[
{
"id": 7007,
"user_id": 123456,
"start": "2016-02-29",
"finish": "2016-03-14",
"status": "approved",
"shifts": [
{
"id": 1337,
"timesheet_id": 7007,
"user_id": 123456,
"date": "2016-03-02",
"start": 1456902118,
"break_start": 1456908143,
"break_finish": 1456909812,
"break_length": 27,
"breaks": [
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27,
"paid": false,
"selected_automatic_break_id": 73647
}
],
"finish": 1456916286,
"status": "PENDING",
"allowances": [
{
"id": 456789,
"name": "Hazardous Environment Allowance",
"value": 0.5,
"cost": 1.75
}
],
"tag": "Head Technician",
"tag_id": 65421,
"cost": 20.1,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"department_id": 808,
"metadata": "My special metadata",
"leave_request_id": 333,
"record_id": 532432,
"approved_by": 123455,
"approved_at": "1456988518",
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
],
"cost": 102.15,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get Current TimesheetsGET/api/v2/timesheets/current{?show_costs,show_award_interpretation}
If you are using show_costs=true
or show_award_interpretation=true
, the cost
scope is required.
- show_costs
boolean
(optional) Example: trueWhether to show the costs for the timesheet (defaults to false)
- show_award_interpretation
boolean
(optional) Example: trueWhether to show award interpretation for the timesheet (defaults to false)
- show_notes
boolean
(optional) Example: trueWhether to show notes for the timesheet (defaults to false). Note that notes can exist at the timesheet level or the shift level, and these can be found through
notes
arrays on the respective objects.- updated_after
number
(optional) Example: 1451570400Time filter to find recently created or modified timesheets
- report_location_id
number
(optional) Example: 111The ID of a location for which to filter timesheets to. If provided, only returns timesheets if the timesheetâs userâs default team (
report_department_id
) is set, and it is a team within this location.- export_format
string
(optional) Example: myobThe format in which timesheet data should be exported. See the Exporting Timesheets section above for more information.
- skip_status_update
boolean
(optional) Example: trueIf
true
, timesheets will not have their status set toexported
as part of the export. Default isfalse
. Only used ifexport_format
is provided.- approved_only
boolean
(optional) Example: trueIf
true
, only approved timesheets will be returned. Default isfalse
.
Timesheets on Date ¶
Headers
Content-Type: application/json
Body
[
{
"id": 7007,
"user_id": 123456,
"start": "2016-02-29",
"finish": "2016-03-14",
"status": "approved",
"shifts": [
{
"id": 1337,
"timesheet_id": 7007,
"user_id": 123456,
"date": "2016-03-02",
"start": 1456902118,
"break_start": 1456908143,
"break_finish": 1456909812,
"break_length": 27,
"breaks": [
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27,
"paid": false,
"selected_automatic_break_id": 73647
}
],
"finish": 1456916286,
"status": "PENDING",
"allowances": [
{
"id": 456789,
"name": "Hazardous Environment Allowance",
"value": 0.5,
"cost": 1.75
}
],
"tag": "Head Technician",
"tag_id": 65421,
"cost": 20.1,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"department_id": 808,
"metadata": "My special metadata",
"leave_request_id": 333,
"record_id": 532432,
"approved_by": 123455,
"approved_at": "1456988518",
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
],
"cost": 102.15,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get Timesheets on DateGET/api/v2/timesheets/on/{date}{?show_costs,show_award_interpretation}
If you are using show_costs=true
or show_award_interpretation=true
, the cost
scope is required.
- date
date
(required) Example: 2016-03-02The date included in the timesheet to find
- show_costs
boolean
(optional) Example: trueWhether to show the costs for the timesheet (defaults to false)
- show_award_interpretation
boolean
(optional) Example: trueWhether to show award interpretation for the timesheet (defaults to false)
- updated_after
number
(optional) Example: 1451570400Time filter to find recently created or modified timesheets
- report_location_id
number
(optional) Example: 111The ID of a location for which to filter timesheets to. If provided, only returns timesheets if the timesheetâs userâs default team (
report_department_id
) is set, and it is a team within this location.- export_format
string
(optional) Example: myobThe format in which timesheet data should be exported. See the Exporting Timesheets section above for more information.
- skip_status_update
boolean
(optional) Example: trueIf
true
, timesheets will not have their status set toexported
as part of the export. Default isfalse
. Only used ifexport_format
is provided.- approved_only
boolean
(optional) Example: trueIf
true
, only approved timesheets will be returned. Default isfalse
.- page
number
(optional) Example: 1The page number for your timesheet list
- page_size
number
(optional) Example: 50The number of timesheets retrieved per page. The maximum is 100 timesheets per request.
Current Timesheet for User ¶
Headers
Content-Type: application/json
Body
{
"id": 7007,
"user_id": 123456,
"start": "2016-02-29",
"finish": "2016-03-14",
"status": "approved",
"shifts": [
{
"id": 1337,
"timesheet_id": 7007,
"user_id": 123456,
"date": "2016-03-02",
"start": 1456902118,
"break_start": 1456908143,
"break_finish": 1456909812,
"break_length": 27,
"breaks": [
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27,
"paid": false,
"selected_automatic_break_id": 73647
}
],
"finish": 1456916286,
"status": "PENDING",
"allowances": [
{
"id": 456789,
"name": "Hazardous Environment Allowance",
"value": 0.5,
"cost": 1.75
}
],
"tag": "Head Technician",
"tag_id": 65421,
"cost": 20.1,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"department_id": 808,
"metadata": "My special metadata",
"leave_request_id": 333,
"record_id": 532432,
"approved_by": 123455,
"approved_at": "1456988518",
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
],
"cost": 102.15,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the timesheet"
},
"user_id": {
"type": "number",
"description": "The id of the user who worked the shift"
},
"start": {
"type": "string",
"description": "The start date of the timesheet"
},
"finish": {
"type": "string",
"description": "The end date of the timesheet"
},
"status": {
"type": "string",
"description": "One of `pending`, `approved`, `exported`"
},
"shifts": {
"type": "array",
"description": "The shifts on the timesheet"
},
"cost": {
"type": "number",
"description": "The total cost of the timesheet, if `show_costs=true` parameter is set"
},
"award_interpretation": {
"type": "array",
"description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
},
"notes": {
"type": "array",
"description": "Notes on the timesheet"
}
},
"required": [
"id",
"user_id",
"start",
"finish",
"status",
"shifts"
]
}
Get Current Timesheet for UserGET/api/v2/timesheets/for/{user_id}/current{?show_costs,show_award_interpretation}
If you are using show_costs=true
or show_award_interpretation=true
, the cost
scope is required.
- user_id
number
(required) Example: 123456The userâs id,
me
can also be used to reference the current user- show_costs
boolean
(optional) Example: trueWhether to show the costs for the timesheet (defaults to false)
- show_award_interpretation
boolean
(optional) Example: trueWhether to show award interpretation for the timesheet (defaults to false)
- approved_only
boolean
(optional) Example: trueIf
true
, only approved timesheets will be returned. Default isfalse
.
Timesheet for User on Date ¶
Headers
Content-Type: application/json
Body
{
"id": 7007,
"user_id": 123456,
"start": "2016-02-29",
"finish": "2016-03-14",
"status": "approved",
"shifts": [
{
"id": 1337,
"timesheet_id": 7007,
"user_id": 123456,
"date": "2016-03-02",
"start": 1456902118,
"break_start": 1456908143,
"break_finish": 1456909812,
"break_length": 27,
"breaks": [
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27,
"paid": false,
"selected_automatic_break_id": 73647
}
],
"finish": 1456916286,
"status": "PENDING",
"allowances": [
{
"id": 456789,
"name": "Hazardous Environment Allowance",
"value": 0.5,
"cost": 1.75
}
],
"tag": "Head Technician",
"tag_id": 65421,
"cost": 20.1,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"department_id": 808,
"metadata": "My special metadata",
"leave_request_id": 333,
"record_id": 532432,
"approved_by": 123455,
"approved_at": "1456988518",
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
],
"cost": 102.15,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the timesheet"
},
"user_id": {
"type": "number",
"description": "The id of the user who worked the shift"
},
"start": {
"type": "string",
"description": "The start date of the timesheet"
},
"finish": {
"type": "string",
"description": "The end date of the timesheet"
},
"status": {
"type": "string",
"description": "One of `pending`, `approved`, `exported`"
},
"shifts": {
"type": "array",
"description": "The shifts on the timesheet"
},
"cost": {
"type": "number",
"description": "The total cost of the timesheet, if `show_costs=true` parameter is set"
},
"award_interpretation": {
"type": "array",
"description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
},
"notes": {
"type": "array",
"description": "Notes on the timesheet"
}
},
"required": [
"id",
"user_id",
"start",
"finish",
"status",
"shifts"
]
}
Get Timesheet for User on DateGET/api/v2/timesheets/for/{user_id}/on/{date}{?show_costs,show_award_interpretation}
If you are using show_costs=true
or show_award_interpretation=true
, the cost
scope is required.
- user_id
number
(required) Example: 123456The userâs id,
me
can also be used to reference the current user- date
date
(required) Example: 2016-03-02The date included in the timesheet to find
- show_costs
boolean
(optional) Example: trueWhether to show the costs for the timesheet (defaults to false)
- show_award_interpretation
boolean
(optional) Example: trueWhether to show award interpretation for the timesheet (defaults to false)
- approved_only
boolean
(optional) Example: trueIf
true
, only approved timesheets will be returned. Default isfalse
.
Timesheet ¶
Headers
Content-Type: application/json
Body
{
"id": 7007,
"user_id": 123456,
"start": "2016-02-29",
"finish": "2016-03-14",
"status": "approved",
"shifts": [
{
"id": 1337,
"timesheet_id": 7007,
"user_id": 123456,
"date": "2016-03-02",
"start": 1456902118,
"break_start": 1456908143,
"break_finish": 1456909812,
"break_length": 27,
"breaks": [
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27,
"paid": false,
"selected_automatic_break_id": 73647
}
],
"finish": 1456916286,
"status": "PENDING",
"allowances": [
{
"id": 456789,
"name": "Hazardous Environment Allowance",
"value": 0.5,
"cost": 1.75
}
],
"tag": "Head Technician",
"tag_id": 65421,
"cost": 20.1,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"department_id": 808,
"metadata": "My special metadata",
"leave_request_id": 333,
"record_id": 532432,
"approved_by": 123455,
"approved_at": "1456988518",
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
],
"cost": 102.15,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the timesheet"
},
"user_id": {
"type": "number",
"description": "The id of the user who worked the shift"
},
"start": {
"type": "string",
"description": "The start date of the timesheet"
},
"finish": {
"type": "string",
"description": "The end date of the timesheet"
},
"status": {
"type": "string",
"description": "One of `pending`, `approved`, `exported`"
},
"shifts": {
"type": "array",
"description": "The shifts on the timesheet"
},
"cost": {
"type": "number",
"description": "The total cost of the timesheet, if `show_costs=true` parameter is set"
},
"award_interpretation": {
"type": "array",
"description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
},
"notes": {
"type": "array",
"description": "Notes on the timesheet"
}
},
"required": [
"id",
"user_id",
"start",
"finish",
"status",
"shifts"
]
}
Get TimesheetGET/api/v2/timesheets/{id}{?show_costs,show_award_interpretation}
If you are using show_costs=true
or show_award_interpretation=true
, the cost
scope is required.
- id
number
(required) Example: 7007The id of the timesheet
- show_costs
boolean
(optional) Example: trueWhether to show the costs for the timesheet (defaults to false)
- show_award_interpretation
boolean
(optional) Example: trueWhether to show award interpretation for the timesheet (defaults to false)
- show_notes
boolean
(optional) Example: trueWhether to show notes for the timesheet (defaults to false)
- approved_only
boolean
(optional) Example: trueIf
true
, only approved timesheets will be returned. Default isfalse
.
Headers
Content-Type: application/json
Body
{
"status": "pending"
}
Headers
Content-Type: application/json
Body
{
"id": 7007,
"user_id": 123456,
"start": "2016-02-29",
"finish": "2016-03-14",
"status": "exported",
"shifts": [
{
"id": 1337,
"timesheet_id": 7007,
"user_id": 123456,
"date": "2016-03-02",
"start": 1456902118,
"break_start": 1456908143,
"break_finish": 1456909812,
"break_length": 27,
"breaks": [
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27,
"paid": false,
"selected_automatic_break_id": 73647
}
],
"finish": 1456916286,
"status": "PENDING",
"allowances": [
{
"id": 456789,
"name": "Hazardous Environment Allowance",
"value": 0.5,
"cost": 1.75
}
],
"tag": "Head Technician",
"tag_id": 65421,
"cost": 20.1,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"department_id": 808,
"metadata": "My special metadata",
"leave_request_id": 333,
"record_id": 532432,
"approved_by": 123455,
"approved_at": "1456988518",
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
],
"cost": 102.15,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the timesheet"
},
"user_id": {
"type": "number",
"description": "The id of the user who worked the shift"
},
"start": {
"type": "string",
"description": "The start date of the timesheet"
},
"finish": {
"type": "string",
"description": "The end date of the timesheet"
},
"status": {
"type": "string",
"description": "One of `pending`, `approved`, `exported`"
},
"shifts": {
"type": "array",
"description": "The shifts on the timesheet"
},
"cost": {
"type": "number",
"description": "The total cost of the timesheet, if `show_costs=true` parameter is set"
},
"award_interpretation": {
"type": "array",
"description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
},
"notes": {
"type": "array",
"description": "Notes on the timesheet"
}
},
"required": [
"id",
"user_id",
"start",
"finish",
"status",
"shifts"
]
}
Update TimesheetPUT/api/v2/timesheets/{id}
Use this endpoint to change a timesheetâs status. Three values are accepted: pending
, approved
, or exported
.
If a timesheet is exported it cannot be edited and its costs are locked. If you are exporting data out of timesheets through the API to be costed externally, you should mark those timesheets as exported at that time.
- id
number
(required) Example: 7007The id of the timesheet
Shifts ¶
Shifts represent actual times worked for a user and are contained in a Timesheet. For rostered times, please see Rosters or Schedules.
A user can see all the shifts on each timesheet that they can see. Shifts can be created, updated and deleted by staff if they have the ability to see their own timesheets (a system setting). All shifts can be created, updated and deleted by roster managers and admins, and department managers can create, update and delete shifts for staff that they manage.
Shifts ¶
Headers
Content-Type: application/json
Body
[
{
"id": 1337,
"timesheet_id": 7007,
"user_id": 123456,
"date": "2016-03-02",
"start": 1456902118,
"break_start": 1456908143,
"break_finish": 1456909812,
"break_length": 27,
"breaks": [
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27,
"paid": false,
"selected_automatic_break_id": 73647
}
],
"finish": 1456916286,
"status": "PENDING",
"allowances": [
{
"id": 456789,
"name": "Hazardous Environment Allowance",
"value": 0.5,
"cost": 1.75
}
],
"tag": "Head Technician",
"tag_id": 65421,
"cost": 20.1,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"department_id": 808,
"metadata": "My special metadata",
"leave_request_id": 333,
"record_id": 532432,
"approved_by": 123455,
"approved_at": "1456988518",
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get ShiftsGET/api/v2/shifts{?ids,user_ids,from,to,show_costs,show_award_interpretation,report_location_id,platform}
Get multiple shifts by IDs, user IDs, or from/to dates. You need to provide at least one of these parameters (ids
, user_ids
, or from
+ to
). If you provide more than one, or any of the other parameters below, only shifts that meet all criteria will be returned.
This method requires the timesheet
scope (see Scopes for more information).
If you are using show_costs=true
or show_award_interpretation=true
, the cost
scope is also required.
- ids
string
(optional) Example: 1,2,1337Comma separated list of shift IDs
- user_ids
string
(optional) Example: 1,2,123456Comma separated list of user IDs
- from
string
(optional) Example: 2016-03-02From date to lookup shifts in
- to
string
(optional) Example: 2016-03-02To date to lookup shifts in
- show_costs
boolean
(optional) Example: trueWhether to show the costs for the shift (defaults to false)
- show_award_interpretation
boolean
(optional) Example: trueWhether to show award interpretation for the shifts (defaults to false)
- show_associated_tag
boolean
(optional) Example: trueWhether to show the associated tag for the shifts (defaults to false)
- show_notes
boolean
(optional) Example: trueWhether to show notes for the shifts (defaults to false)
- report_location_id
number
(optional) Example: 111The ID of a location for which to filter shifts to. If provided, only returns shifts if the shiftsâs userâs default team (
report_department_id
) is set, and it is a team within this location. Note that it is possible for a shiftâs userâs default location to be different to the location at which a shift was worked. This parameter always filters based on the user. For example if a user can work at locations A and B, they default to A, but work at B, a call withreport_location_id=A
will return that userâs shifts worked at location B.- platform
boolean
(optional) Example: falseIf true, Platform data will be returned (defaults to false).
- page
number
(optional) Example: 1The page number for your shifts list
- page_size
number
(optional) Example: 50The number of shifts retrieved per page. The maximum is 100 shifts per request.
- updated_after
number
(optional) Example: 1451570400Time filter to find recently created or modified shifts
Headers
Content-Type: application/json
Body
{
"user_id": 123456,
"date": "2016-03-12",
"start": 1457741040,
"finish": 1457762640,
"department_id": 808,
"metadata": "My special metadata"
}
Headers
Content-Type: application/json
Body
{
"id": 9665,
"timesheet_id": 7007,
"user_id": 123456,
"date": "2016-03-12",
"start": 1457741040,
"break_start": null,
"break_finish": null,
"break_length": null,
"finish": 1457762640,
"status": "PENDING",
"allowances": [],
"tag": null,
"tag_id": null,
"department_id": 808,
"department_export_name": "abc123",
"metadata": "My special metadata",
"leave_request_id": null
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the shift"
},
"timesheet_id": {
"type": "number",
"description": "The id of the timesheet that the shift belongs on"
},
"user_id": {
"type": "number",
"description": "The id of the user who worked the shift"
},
"date": {
"type": "string",
"description": "The date the shift was worked"
},
"start": {
"type": "number",
"description": "The start of the shift"
},
"break_start": {
"type": "number",
"description": "The start of the break"
},
"break_finish": {
"type": "number",
"description": "The end of the break"
},
"break_length": {
"type": "number",
"description": "The length of the break in minutes (NOTE: this can be different to `(break_finish - break_start) / 60`, see Shifts section)"
},
"finish": {
"type": "number",
"description": "The end of the shift"
},
"status": {
"type": "string",
"description": "One of `PENDING`, `APPROVED`"
},
"allowances": {
"type": "array",
"description": "The allowances that apply to the shift"
},
"tag": {
"type": "string",
"description": "The name of the tag on the shift (can use `tag_id` instead)"
},
"tag_id": {
"type": "number",
"description": "The id of the tag on the shift (can use `tag` instead)"
},
"department_id": {
"type": "number",
"description": "The ID for the team this shift was worked in"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
}
},
"required": [
"id",
"timesheet_id",
"user_id",
"date",
"status",
"allowances"
]
}
Headers
Content-Type: application/json
Body
{
"user_id": 123456,
"date": "2016-03-12",
"start": 1457741040,
"finish": 1457762640,
"break_start": 1457751660,
"break_finish": 1457753280,
"metadata": "My special metadata"
}
Headers
Content-Type: application/json
Body
{
"id": 9665,
"timesheet_id": 7007,
"user_id": 123456,
"date": "2016-03-12",
"start": 1457741040,
"break_start": 1457751660,
"break_finish": 1457753280,
"break_length": 27,
"finish": 1457762640,
"status": "PENDING",
"allowances": [],
"tag": "Head Technician",
"tag_id": 65421,
"department_id": 808,
"record_id": 532432,
"metadata": "My special metadata"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the shift"
},
"timesheet_id": {
"type": "number",
"description": "The id of the timesheet that the shift belongs on"
},
"user_id": {
"type": "number",
"description": "The id of the user who worked the shift"
},
"date": {
"type": "string",
"description": "The date the shift was worked"
},
"start": {
"type": "number",
"description": "The start of the shift"
},
"break_start": {
"type": "number",
"description": "The start of the break"
},
"break_finish": {
"type": "number",
"description": "The end of the break"
},
"break_length": {
"type": "number",
"description": "The length of the break in minutes (NOTE: this can be different to `(break_finish - break_start) / 60`, see Shifts section)"
},
"finish": {
"type": "number",
"description": "The end of the shift"
},
"status": {
"type": "string",
"description": "One of `PENDING`, `APPROVED`"
},
"allowances": {
"description": "The allowances that apply to the shift"
},
"tag": {
"type": "string",
"description": "The name of the tag on the shift (can use `tag_id` instead)"
},
"tag_id": {
"type": "number",
"description": "The id of the tag on the shift (can use `tag` instead)"
},
"department_id": {
"type": "number",
"description": "The ID for the team this shift was worked in"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
},
"metadata": {
"type": "string"
}
},
"required": [
"id",
"timesheet_id",
"user_id",
"date",
"status",
"allowances"
]
}
Headers
Content-Type: application/json
Body
{
"user_id": 123456,
"date": "2016-03-12",
"start": 1457741040,
"finish": 1457762640,
"status": "APPROVED",
"tag": null
}
Headers
Content-Type: application/json
Body
{
"id": 9665,
"timesheet_id": 7007,
"user_id": 123456,
"start": 1457741040,
"break_start": null,
"break_finish": null,
"break_length": null,
"finish": 1457762640,
"status": "APPROVED",
"allowances": [],
"tag": null,
"tag_id": null,
"metadata": null,
"leave_request_id": null
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the shift"
},
"timesheet_id": {
"type": "number",
"description": "The id of the timesheet that the shift belongs on"
},
"user_id": {
"type": "number",
"description": "The id of the user who worked the shift"
},
"date": {
"type": "string",
"description": "The date the shift was worked"
},
"start": {
"type": "number",
"description": "The start of the shift"
},
"break_start": {
"type": "number",
"description": "The start of the break"
},
"break_finish": {
"type": "number",
"description": "The end of the break"
},
"break_length": {
"type": "number",
"description": "The length of the break in minutes (NOTE: this can be different to `(break_finish - break_start) / 60`, see Shifts section)"
},
"finish": {
"type": "number",
"description": "The end of the shift"
},
"status": {
"type": "string",
"description": "One of `PENDING`, `APPROVED`"
},
"allowances": {
"type": "array",
"description": "The allowances that apply to the shift"
},
"tag": {
"type": "string",
"description": "The name of the tag on the shift (can use `tag_id` instead)"
},
"tag_id": {
"type": "number",
"description": "The id of the tag on the shift (can use `tag` instead)"
},
"department_id": {
"type": "number",
"description": "The ID for the team this shift was worked in"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
}
},
"required": [
"id",
"timesheet_id",
"user_id",
"date",
"status",
"allowances"
]
}
Headers
Content-Type: application/json
Body
{
"user_id": 123456,
"date": "2016-03-12",
"start": 1457741040,
"finish": 1457762640,
"allowances": [
{
"id": 987654,
"value": 1
}
]
}
Headers
Content-Type: application/json
Body
{
"id": 9665,
"timesheet_id": 7007,
"user_id": 123456,
"date": "2016-03-12",
"start": 1457741040,
"break_start": null,
"break_finish": null,
"break_length": null,
"finish": 1457762640,
"status": "PENDING",
"allowances": [
{
"id": 987654,
"value": 1
}
],
"tag": null,
"tag_id": null,
"metadata": null,
"leave_request_id": null
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the shift"
},
"timesheet_id": {
"type": "number",
"description": "The id of the timesheet that the shift belongs on"
},
"user_id": {
"type": "number",
"description": "The id of the user who worked the shift"
},
"date": {
"type": "string",
"description": "The date the shift was worked"
},
"start": {
"type": "number",
"description": "The start of the shift"
},
"break_start": {
"type": "number",
"description": "The start of the break"
},
"break_finish": {
"type": "number",
"description": "The end of the break"
},
"break_length": {
"type": "number",
"description": "The length of the break in minutes (NOTE: this can be different to `(break_finish - break_start) / 60`, see Shifts section)"
},
"finish": {
"type": "number",
"description": "The end of the shift"
},
"status": {
"type": "string",
"description": "One of `PENDING`, `APPROVED`"
},
"allowances": {
"type": "array",
"description": "The allowances that apply to the shift"
},
"tag": {
"type": "string",
"description": "The name of the tag on the shift (can use `tag_id` instead)"
},
"tag_id": {
"type": "number",
"description": "The id of the tag on the shift (can use `tag` instead)"
},
"department_id": {
"type": "number",
"description": "The ID for the team this shift was worked in"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
}
},
"required": [
"id",
"timesheet_id",
"user_id",
"date",
"status",
"allowances"
]
}
Create ShiftPOST/api/v2/shifts
Create a shift for a user, with specified times, on a specified date.
This will create a timesheet for the user for the given pay period, if one doesnât exist already. The shift object that is returned will have both an id
(to use for Shift lookups) and a timesheet_id
(for Timesheet lookups).
When a shift is created, the times provided for the start
, finish
, break_start
, and break_finish
keys will be rounded to the nearest minute. To avoid potentially confusing, you can round them before passing them to the API.
This method requires the timesheet
scope (see Scopes for more information).
Shift ¶
Headers
Content-Type: application/json
Body
{
"id": 1337,
"timesheet_id": 7007,
"user_id": 123456,
"date": "2016-03-02",
"start": 1456902118,
"break_start": 1456908143,
"break_finish": 1456909812,
"break_length": 27,
"breaks": [
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27,
"paid": false,
"selected_automatic_break_id": 73647
}
],
"finish": 1456916286,
"status": "PENDING",
"allowances": [
{
"id": 456789,
"name": "Hazardous Environment Allowance",
"value": 0.5,
"cost": 1.75
}
],
"tag": "Head Technician",
"tag_id": 65421,
"cost": 20.1,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"department_id": 808,
"metadata": "My special metadata",
"leave_request_id": 333,
"record_id": 532432,
"approved_by": 123455,
"approved_at": "1456988518",
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the shift"
},
"timesheet_id": {
"type": "number",
"description": "The id of the timesheet that the shift belongs on"
},
"user_id": {
"type": "number",
"description": "The id of the user who worked the shift"
},
"date": {
"type": "string",
"description": "The date the shift was worked"
},
"start": {
"type": "number",
"description": "The start of the shift"
},
"break_start": {
"type": "number",
"description": "The start of the break"
},
"break_finish": {
"type": "number",
"description": "The end of the break"
},
"break_length": {
"type": "number",
"description": "The length of the break in minutes (NOTE: this can be different to `(break_start - break_finish) / 60`, see Shifts section)"
},
"breaks": {
"type": "array",
"description": "The shift's breaks"
},
"finish": {
"type": "number",
"description": "The end of the shift"
},
"status": {
"type": "string",
"description": "One of `PENDING`, `APPROVED`"
},
"allowances": {
"type": "array",
"description": "The allowances that apply to the shift"
},
"tag": {
"type": "string",
"description": "The name of the tag on the shift (can use `tag_id` instead)"
},
"tag_id": {
"type": "number",
"description": "The id of the tag on the shift (can use `tag` instead)"
},
"cost": {
"type": "number",
"description": "The cost of the shift, if `show_costs=true` parameter is set"
},
"award_interpretation": {
"type": "array",
"description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
},
"department_id": {
"type": "number",
"description": "The ID for the team this shift was worked in"
},
"metadata": {
"type": "string",
"description": "Custom string field that holds up to 500 characters"
},
"leave_request_id": {
"type": "number",
"description": "The ID for the leave request, if leave was taken, otherwise null."
},
"record_id": {
"type": "number",
"description": "The record ID, for use with Platform endpoints"
},
"approved_by": {
"type": "number",
"description": "The ID of the user that approved the shift"
},
"approved_at": {
"type": "string",
"description": "The time the shift was approved"
},
"notes": {
"type": "array",
"description": "Notes on the shift"
}
},
"required": [
"id",
"timesheet_id",
"user_id",
"date",
"status",
"allowances"
]
}
Get ShiftGET/api/v2/shifts/{id}{?show_costs,show_award_interpretation,platform}
Get a shift by id.
This method requires the timesheet
scope (see Scopes for more information).
If you are using show_costs=true
or show_award_interpretation=true
, the cost
scope is also required.
- id
number
(required) Example: 1337The id of the shift
- show_costs
boolean
(optional) Example: trueWhether to show the costs for the shift (defaults to false)
- show_award_interpretation
boolean
(optional) Example: trueWhether to show award interpretation for the shift (defaults to false)
- show_associated_tag
boolean
(optional) Example: trueWhether to show the associated tag for the shifts (defaults to false)
- show_notes
boolean
(optional) Example: trueWhether to show notes for the shift (defaults to false)
- show_export_name
boolean
(optional) Example: trueWhether to show the departmentâs export code that the employee worked on the shift (defaults to false)
- platform
boolean
(optional) Example: falseIf true, Platform data will be returned (defaults to false).
Headers
Content-Type: application/json
Body
{
"status": "APPROVED"
}
Headers
Content-Type: application/json
Body
{
"id": 1337,
"timesheet_id": 7007,
"user_id": 123456,
"date": "2016-03-02",
"start": 1456902118,
"break_start": 1456908143,
"break_finish": 1456909812,
"break_length": 27,
"breaks": [
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27,
"paid": false,
"selected_automatic_break_id": 73647
}
],
"finish": 1456916286,
"status": "APPROVED",
"allowances": [
{
"id": 456789,
"name": "Hazardous Environment Allowance",
"value": 0.5,
"cost": 1.75
}
],
"tag": "Head Technician",
"tag_id": 65421,
"cost": 20.1,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"department_id": 808,
"metadata": "My special metadata",
"leave_request_id": 333,
"record_id": 532432,
"approved_by": 123455,
"approved_at": "1456988518",
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the shift"
},
"timesheet_id": {
"type": "number",
"description": "The id of the timesheet that the shift belongs on"
},
"user_id": {
"type": "number",
"description": "The id of the user who worked the shift"
},
"date": {
"type": "string",
"description": "The date the shift was worked"
},
"start": {
"type": "number",
"description": "The start of the shift"
},
"break_start": {
"type": "number",
"description": "The start of the break"
},
"break_finish": {
"type": "number",
"description": "The end of the break"
},
"break_length": {
"type": "number",
"description": "The length of the break in minutes (NOTE: this can be different to `(break_start - break_finish) / 60`, see Shifts section)"
},
"breaks": {
"type": "array",
"description": "The shift's breaks"
},
"finish": {
"type": "number",
"description": "The end of the shift"
},
"status": {
"type": "string",
"description": "One of `PENDING`, `APPROVED`"
},
"allowances": {
"type": "array",
"description": "The allowances that apply to the shift"
},
"tag": {
"type": "string",
"description": "The name of the tag on the shift (can use `tag_id` instead)"
},
"tag_id": {
"type": "number",
"description": "The id of the tag on the shift (can use `tag` instead)"
},
"cost": {
"type": "number",
"description": "The cost of the shift, if `show_costs=true` parameter is set"
},
"award_interpretation": {
"type": "array",
"description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
},
"department_id": {
"type": "number",
"description": "The ID for the team this shift was worked in"
},
"metadata": {
"type": "string",
"description": "Custom string field that holds up to 500 characters"
},
"leave_request_id": {
"type": "number",
"description": "The ID for the leave request, if leave was taken, otherwise null."
},
"record_id": {
"type": "number",
"description": "The record ID, for use with Platform endpoints"
},
"approved_by": {
"type": "number",
"description": "The ID of the user that approved the shift"
},
"approved_at": {
"type": "string",
"description": "The time the shift was approved"
},
"notes": {
"type": "array",
"description": "Notes on the shift"
}
},
"required": [
"id",
"timesheet_id",
"user_id",
"date",
"status",
"allowances"
]
}
Headers
Content-Type: application/json
Body
{
"start": 1456901518,
"finish": 1456916886
}
Headers
Content-Type: application/json
Body
{
"id": 1337,
"timesheet_id": 7007,
"user_id": 123456,
"date": "2016-03-02",
"start": 1456901518,
"break_start": 1456908143,
"break_finish": 1456909812,
"break_length": 27,
"breaks": [
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27,
"paid": false,
"selected_automatic_break_id": 73647
}
],
"finish": 1456916886,
"status": "PENDING",
"allowances": [
{
"id": 456789,
"name": "Hazardous Environment Allowance",
"value": 0.5,
"cost": 1.75
}
],
"tag": "Head Technician",
"tag_id": 65421,
"cost": 20.1,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"department_id": 808,
"metadata": "My special metadata",
"leave_request_id": 333,
"record_id": 532432,
"approved_by": 123455,
"approved_at": "1456988518",
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the shift"
},
"timesheet_id": {
"type": "number",
"description": "The id of the timesheet that the shift belongs on"
},
"user_id": {
"type": "number",
"description": "The id of the user who worked the shift"
},
"date": {
"type": "string",
"description": "The date the shift was worked"
},
"start": {
"type": "number",
"description": "The start of the shift"
},
"break_start": {
"type": "number",
"description": "The start of the break"
},
"break_finish": {
"type": "number",
"description": "The end of the break"
},
"break_length": {
"type": "number",
"description": "The length of the break in minutes (NOTE: this can be different to `(break_start - break_finish) / 60`, see Shifts section)"
},
"breaks": {
"type": "array",
"description": "The shift's breaks"
},
"finish": {
"type": "number",
"description": "The end of the shift"
},
"status": {
"type": "string",
"description": "One of `PENDING`, `APPROVED`"
},
"allowances": {
"type": "array",
"description": "The allowances that apply to the shift"
},
"tag": {
"type": "string",
"description": "The name of the tag on the shift (can use `tag_id` instead)"
},
"tag_id": {
"type": "number",
"description": "The id of the tag on the shift (can use `tag` instead)"
},
"cost": {
"type": "number",
"description": "The cost of the shift, if `show_costs=true` parameter is set"
},
"award_interpretation": {
"type": "array",
"description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
},
"department_id": {
"type": "number",
"description": "The ID for the team this shift was worked in"
},
"metadata": {
"type": "string",
"description": "Custom string field that holds up to 500 characters"
},
"leave_request_id": {
"type": "number",
"description": "The ID for the leave request, if leave was taken, otherwise null."
},
"record_id": {
"type": "number",
"description": "The record ID, for use with Platform endpoints"
},
"approved_by": {
"type": "number",
"description": "The ID of the user that approved the shift"
},
"approved_at": {
"type": "string",
"description": "The time the shift was approved"
},
"notes": {
"type": "array",
"description": "Notes on the shift"
}
},
"required": [
"id",
"timesheet_id",
"user_id",
"date",
"status",
"allowances"
]
}
Headers
Content-Type: application/json
Body
{
"date": "2016-03-03",
"start": 1456987918,
"finish": 1457003286,
"break_start": 1456994543,
"break_finish": 1456996212
}
Headers
Content-Type: application/json
Body
{
"id": 1337,
"timesheet_id": 7007,
"user_id": 123456,
"date": "2016-03-03",
"start": 1456987918,
"break_start": 1456994543,
"break_finish": 1456996212,
"break_length": 27,
"breaks": [
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27,
"paid": false,
"selected_automatic_break_id": 73647
}
],
"finish": 1457003286,
"status": "PENDING",
"allowances": [
{
"id": 456789,
"name": "Hazardous Environment Allowance",
"value": 0.5,
"cost": 1.75
}
],
"tag": "Head Technician",
"tag_id": 65421,
"cost": 20.1,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"department_id": 808,
"metadata": "My special metadata",
"leave_request_id": 333,
"record_id": 532432,
"approved_by": 123455,
"approved_at": "1456988518",
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the shift"
},
"timesheet_id": {
"type": "number",
"description": "The id of the timesheet that the shift belongs on"
},
"user_id": {
"type": "number",
"description": "The id of the user who worked the shift"
},
"date": {
"type": "string",
"description": "The date the shift was worked"
},
"start": {
"type": "number",
"description": "The start of the shift"
},
"break_start": {
"type": "number",
"description": "The start of the break"
},
"break_finish": {
"type": "number",
"description": "The end of the break"
},
"break_length": {
"type": "number",
"description": "The length of the break in minutes (NOTE: this can be different to `(break_start - break_finish) / 60`, see Shifts section)"
},
"breaks": {
"type": "array",
"description": "The shift's breaks"
},
"finish": {
"type": "number",
"description": "The end of the shift"
},
"status": {
"type": "string",
"description": "One of `PENDING`, `APPROVED`"
},
"allowances": {
"type": "array",
"description": "The allowances that apply to the shift"
},
"tag": {
"type": "string",
"description": "The name of the tag on the shift (can use `tag_id` instead)"
},
"tag_id": {
"type": "number",
"description": "The id of the tag on the shift (can use `tag` instead)"
},
"cost": {
"type": "number",
"description": "The cost of the shift, if `show_costs=true` parameter is set"
},
"award_interpretation": {
"type": "array",
"description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
},
"department_id": {
"type": "number",
"description": "The ID for the team this shift was worked in"
},
"metadata": {
"type": "string",
"description": "Custom string field that holds up to 500 characters"
},
"leave_request_id": {
"type": "number",
"description": "The ID for the leave request, if leave was taken, otherwise null."
},
"record_id": {
"type": "number",
"description": "The record ID, for use with Platform endpoints"
},
"approved_by": {
"type": "number",
"description": "The ID of the user that approved the shift"
},
"approved_at": {
"type": "string",
"description": "The time the shift was approved"
},
"notes": {
"type": "array",
"description": "Notes on the shift"
}
},
"required": [
"id",
"timesheet_id",
"user_id",
"date",
"status",
"allowances"
]
}
Headers
Content-Type: application/json
Body
{
"allowances": [
{
"id": 987654,
"value": 1
}
]
}
Headers
Content-Type: application/json
Body
{
"id": 1337,
"timesheet_id": 7007,
"user_id": 123456,
"date": "2016-03-02",
"start": 1456902118,
"break_start": 1456908143,
"break_finish": 1456909812,
"break_length": 27,
"breaks": [
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27,
"paid": false,
"selected_automatic_break_id": 73647
}
],
"finish": 1456916286,
"status": "PENDING",
"allowances": [
{
"id": 987654,
"value": 1
},
{
"id": 456789,
"value": 0.5,
"cost": 1.75
}
],
"tag": "Head Technician",
"tag_id": 65421,
"cost": 20.1,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "LOAD",
"pay_class": "P1",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"department_id": 808,
"metadata": "My special metadata",
"leave_request_id": 333,
"record_id": 532432,
"approved_by": 123455,
"approved_at": "1456988518",
"notes": [
{
"body": "Goals were kicked this shift đȘ",
"author": "Mike Richards"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the shift"
},
"timesheet_id": {
"type": "number",
"description": "The id of the timesheet that the shift belongs on"
},
"user_id": {
"type": "number",
"description": "The id of the user who worked the shift"
},
"date": {
"type": "string",
"description": "The date the shift was worked"
},
"start": {
"type": "number",
"description": "The start of the shift"
},
"break_start": {
"type": "number",
"description": "The start of the break"
},
"break_finish": {
"type": "number",
"description": "The end of the break"
},
"break_length": {
"type": "number",
"description": "The length of the break in minutes (NOTE: this can be different to `(break_start - break_finish) / 60`, see Shifts section)"
},
"breaks": {
"type": "array",
"description": "The shift's breaks"
},
"finish": {
"type": "number",
"description": "The end of the shift"
},
"status": {
"type": "string",
"description": "One of `PENDING`, `APPROVED`"
},
"allowances": {
"type": "array",
"description": "The allowances that apply to the shift"
},
"tag": {
"type": "string",
"description": "The name of the tag on the shift (can use `tag_id` instead)"
},
"tag_id": {
"type": "number",
"description": "The id of the tag on the shift (can use `tag` instead)"
},
"cost": {
"type": "number",
"description": "The cost of the shift, if `show_costs=true` parameter is set"
},
"award_interpretation": {
"type": "array",
"description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
},
"department_id": {
"type": "number",
"description": "The ID for the team this shift was worked in"
},
"metadata": {
"type": "string",
"description": "Custom string field that holds up to 500 characters"
},
"leave_request_id": {
"type": "number",
"description": "The ID for the leave request, if leave was taken, otherwise null."
},
"record_id": {
"type": "number",
"description": "The record ID, for use with Platform endpoints"
},
"approved_by": {
"type": "number",
"description": "The ID of the user that approved the shift"
},
"approved_at": {
"type": "string",
"description": "The time the shift was approved"
},
"notes": {
"type": "array",
"description": "Notes on the shift"
}
},
"required": [
"id",
"timesheet_id",
"user_id",
"date",
"status",
"allowances"
]
}
Update ShiftPUT/api/v2/shifts/{id}
When a shift is updated, the times provided for the start
and finish
keys will be rounded to the nearest minute. To avoid potentially confusing, you can round them before passing them to the API.
After the parent timesheet to which a shift is attached has been exported, you can no longer update the shift.
This method requires the timesheet
scope (see Scopes for more information).
- id
number
(required) Example: 1337The id of the shift
Headers
Content-Type: application/json
Active Status ¶
Headers
Content-Type: application/json
Body
[
{
"user_id": 123456,
"shift_id": 1337,
"status": "clocked_in"
},
{
"user_id": 123457,
"shift_id": 1338,
"status": "on_break"
}
]
Get Active ShiftsGET/api/v2/shifts/active
Gets a list of shifts that are taking place now. For each shift, returns the user ID, the shift ID, and the shiftâs current status, which could be either clocked_in
or on_break
. Shifts are returned if they have a start time and no finish time.
This method requires the timesheet
scopes (see Scopes for more information).
Shift's Applicable Allowances ¶
Headers
Content-Type: application/json
Body
[
{
"id": 456789,
"name": "Hazardous Environment Allowance",
"export_name": "HE Allowance",
"current_value": 0.5
},
{
"id": 987654,
"name": "Meal Allowance"
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get Shift's Applicable AllowancesGET/api/v2/shifts/{id}/applicable_allowances
Our user guide has more information on working with allowances through the API.
Get list of manually applied allowances that can apply to a shift, along with the current amount currently applied to the given shift.
The allowance IDs returned will be the same for all shifts within the organisation, but the values may differ from shift to shift.
Allowances that are configured to apply automatically will not be returned by this endpoint. They will update automatically every time a shift is saved.
This method requires the timesheet
scope (see Scopes for more information).
- id
number
(required) Example: 1337The id of the shift
Shift Versions ¶
Headers
Content-Type: application/json
Body
[
{
"version_id": 123456,
"time": 1459209907,
"event": "update",
"author": {
"id": 123456,
"name": "API v2"
},
"item_id": 1235435,
"item_type": "\"Shift\"",
"changes": [
{
"field": "finish",
"previous": 1456916286,
"updated": 1456916300
},
{
"field": "status",
"previous": "PENDING",
"updated": "APPROVED"
}
]
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get Shift VersionsGET/api/v2/shifts/{id}/versions
This method requires the timesheet
scope (see Scopes for more information).
- id
number
(required) Example: 1337The id of the shift
- updated_after
number
(optional) Example: 1451570400Time filter to find recently created or modified shift versions
Headers
Content-Type: application/json
Body
[
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27,
"paid": false,
"selected_automatic_break_id": 73647
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get Shift's BreaksGET/api/v2/shifts/{shift_id}/breaks
- shift_id
number
(required) Example: 1337The id of the shift
Headers
Content-Type: application/json
Body
{
"start": 1456908143,
"finish": 1456909812,
}
Headers
Content-Type: application/json
Body
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27,
"paid": false,
"selected_automatic_break_id": 73647
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the break"
},
"shift_id": {
"type": "number",
"description": "The id of the break's shift"
},
"start": {
"type": "number",
"description": "The start of the break"
},
"finish": {
"type": "number",
"description": "The end of the break"
},
"length": {
"type": "number",
"description": "The length of the break in minutes (NOTE: this can be different to `(break_start - break_finish) / 60`, see Shifts section)"
},
"paid": {
"type": "boolean",
"description": "Whether the break is a paid break"
},
"selected_automatic_break_id": {
"type": "number",
"description": "The id of the automatic break rule chosen to correspond to this shift break by the employee when they clocked in"
}
},
"required": [
"id",
"shift_id"
]
}
Headers
Content-Type: application/json
Body
{
"length": 45,
}
Headers
Content-Type: application/json
Body
{
"id": 42,
"shift_id": 1337,
"start": null,
"finish": null,
"length": 45,
"paid": false,
}
Headers
Content-Type: application/json
Body
{
"paid": true,
}
Headers
Content-Type: application/json
Body
{
"id": 42,
"shift_id": 1337,
"start": null,
"finish": null,
"length": 45,
"paid": true,
}
Create Shift BreakPOST/api/v2/shifts/{shift_id}/breaks
- shift_id
number
(required) Example: 1337The id of the shift
Headers
Content-Type: application/json
Body
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27,
"paid": false,
"selected_automatic_break_id": 73647
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the break"
},
"shift_id": {
"type": "number",
"description": "The id of the break's shift"
},
"start": {
"type": "number",
"description": "The start of the break"
},
"finish": {
"type": "number",
"description": "The end of the break"
},
"length": {
"type": "number",
"description": "The length of the break in minutes (NOTE: this can be different to `(break_start - break_finish) / 60`, see Shifts section)"
},
"paid": {
"type": "boolean",
"description": "Whether the break is a paid break"
},
"selected_automatic_break_id": {
"type": "number",
"description": "The id of the automatic break rule chosen to correspond to this shift break by the employee when they clocked in"
}
},
"required": [
"id",
"shift_id"
]
}
Get Shift BreakGET/api/v2/shifts/{shift_id}/breaks/{break_id}
- shift_id
number
(required) Example: 1337The id of the shift
- break_id
number
(required) Example: 42The id of the break
Headers
Content-Type: application/json
Body
{
"start": 1456908143
}
Headers
Content-Type: application/json
Body
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27,
"paid": false,
"selected_automatic_break_id": 73647
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the break"
},
"shift_id": {
"type": "number",
"description": "The id of the break's shift"
},
"start": {
"type": "number",
"description": "The start of the break"
},
"finish": {
"type": "number",
"description": "The end of the break"
},
"length": {
"type": "number",
"description": "The length of the break in minutes (NOTE: this can be different to `(break_start - break_finish) / 60`, see Shifts section)"
},
"paid": {
"type": "boolean",
"description": "Whether the break is a paid break"
},
"selected_automatic_break_id": {
"type": "number",
"description": "The id of the automatic break rule chosen to correspond to this shift break by the employee when they clocked in"
}
},
"required": [
"id",
"shift_id"
]
}
Update Shift BreakPUT/api/v2/shifts/{shift_id}/breaks/{break_id}
When a break is updated, the times provided for the start
and finish
keys will be rounded to the nearest minute. To avoid potentially confusing, you can round them before passing them to the API.
- shift_id
number
(required) Example: 1337The id of the shift
- break_id
number
(required) Example: 42The id of the break
Shift Break Versions ¶
Headers
Content-Type: application/json
Body
[
{
"version_id": 123456,
"time": 1459209907,
"event": "update",
"author": {
"id": 123456,
"name": "API v2"
},
"item_id": 1235435,
"item_type": "\"ShiftBreak\"",
"changes": [
{
"field": "break_finish",
"previous": 1456916286,
"updated": 1456916300
}
]
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get Shift Break VersionsGET/api/v2/shifts/breaks/{break_id}/versions
This method requires the timesheet
scope (see Scopes for more information).
- id
number
(required) Example: 1337The id of the shift
- break_id
number
(required) Example: 42The id of the break
- updated_after
number
(optional) Example: 1451570400Time filter to find recently created or modified shift break versions
Shift Limits ¶
Body
[
{
"id": 1337,
"timesheet_id": 7007,
"user_id": 123456,
"date": "2016-03-02",
"start": 1456902118,
"break_start": 1456908143,
"break_finish": 1456909812,
"break_length": 27,
"breaks": [
{
"id": 42,
"shift_id": 1337,
"start": 1456908143,
"finish": 1456909812,
"length": 27
}
],
"finish": 1456916286,
"status": "PENDING",
"allowances": [
{
"id": 456789,
"name": "Hazardous Environment Allowance",
"value": 0.5,
"cost": 1.75
}
],
"tag": "Head Technician",
"tag_id": 65421,
"cost": 20.1,
"award_interpretation": [
{
"units": 6.45,
"date": "2016-02-29",
"export_name": "ORD 1x",
"secondary_export_name": "PEN10",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"department_id": 808,
"department_export_name": "abc123",
"metadata": "My special metadata",
"leave_request_id": 333
},
{
"id": 9956,
"timesheet_id": 14090,
"user_id": 123456,
"date": "2019-01-17",
"start": 1547685971,
"break_start": 1547695971,
"break_finish": 1547697971,
"break_length": 27,
"breaks": [
{
"id": 42,
"shift_id": 1337,
"start": 1547695971,
"finish": 1547697971,
"length": 27
}
],
"finish": 1547697971,
"status": "PENDING",
"allowances": [
{
"id": 456789,
"name": "Hazardous Environment Allowance",
"value": 0.5,
"cost": 1.75
}
],
"tag": "Head Technician",
"tag_id": 65421,
"cost": 20.1,
"award_interpretation": [
{
"units": 6.45,
"date": "2019-01-17",
"export_name": "ORD 1x",
"ordinary_hours": true,
"cost": 16.125,
"from": 1456902000,
"to": 1456916400
}
],
"department_id": 808,
"department_export_name": "abc123"
"metadata": "My special metadata",
"leave_request_id": 7889,
}
]
Get Shift LimitsGET/api/v2/shifts/limits?user_ids=123456,987654
This method requires the timesheet
scope (see Scopes for more information).
Gets the first and last shifts (based on start date/time) out of all shifts owned by the given users.
- user_ids
string
(required) Example: 123456,987654Comma separated list of user IDs
Staff (Users) ¶
There are no special system permissions to see information about the current user /users/me
. However, to CRUD users in the organisation, the user will need to be a payroll officer, department manager, roster manager, or admin.
User List ¶
Headers
Content-Type: application/json
Body
[
{
"id": 123456,
"name": "Lenny Leonard",
"date_of_birth": "1955-05-12",
"employment_start_date": "1989-12-17",
"employee_id": "LL1",
"passcode": "0456",
"platform_role_ids": [
18,
19,
22
],
"department_ids": [
111
],
"preferred_hours": 20,
"award": {
"name": "Fast Food Industry",
"identifier": "MA000003",
"note": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_organisation_id` field instead."
},
"award_template_id": 990,
"award_template_organisation_id": 5624432,
"award_tag_ids": [
3816
],
"report_department_id": 111,
"managed_department_ids": [
222
],
"active": true,
"email": "lenny.leonard@springfieldpowerplant.com",
"photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
"phone": "0404 123 123",
"normalised_phone": "+61404123123",
"salary": 1234.12,
"hourly_rate": 32.47,
"time_zone": "Australia/Brisbane",
"utc_offset": 36000,
"part_time_fixed_hours": 20,
"expected_hours_in_pay_period": 38,
"days_overtime_averaged_over": 7,
"overtime_calculated_over_period_start": "2016-09-12",
"super_fund": {
"id": 1234,
"fund_name": "FUND NAME",
"product_name": "FUND PRODUCT",
"smsf": false,
"abn": 123456789
},
"super_fund_membership": {
"super_contribution_type": "arpa",
"trustee_director": false,
"member_number": "123ACB",
"employer_action_date": "2000-01-01T09:30:00+10:00",
"occupational_rating": "A1",
"super_fund_id": 1234,
"employer_preferred": 0,
"employer_default": 1,
"employer_generic": 2
},
"bank_details": {
"bsb": 60111,
"account_number": 12345678,
"account_name": 0
},
"address": {
"street_line_one": "742 Evergreen Terrace",
"street_line_two": "Hello, world!",
"city": "Springfield",
"state": "Oregon",
"country": "United States of America",
"postcode": "97475"
},
"tax_declaration": {
"previous_family_name": "Smith",
"tax_free_threshold": true,
"senior_tax_offset": false,
"zone_overseas_carer": false,
"student_loan": true,
"financial_supplement_debt": true,
"tax_code": true,
"employment_basis: full_time": "Hello, world!",
"tax_file_number": "123 456 789",
"uk_tax_year_status": "first_job / had_previous_job / second_job",
"uk_student_loan_plan": "plan_1 / plan_2 / both"
},
"onboarding_status": "not_applicable, pending, invited, in_progress, completed, invitation_failed",
"qualifications": [
{
"id": 12345,
"qualification_id": 1234,
"enabled": true,
"license_number": "ABC123",
"expires": "2012-10-20",
"in_training": false
}
],
"regular_hours": {
"start_date": "2021-01-01",
"schedules": {
"week": 1,
"day": "Monday",
"start": "09:00",
"end": "17:00",
"breaks": "12:00",
"department_id": 1234
}
},
"minimum_base_hours": 20,
"created_at": 1430715548,
"record_id": 532432,
"next_pay_group_id": 53242,
"last_synced_mobile_app": 1430715548,
"automatic_break_rule_set_id": 1430715548
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get UsersGET/api/v2/users{?show_wages}
Gets information about all visible users.
This method requires the user
scope (see Scopes for more information).
If you are using show_wages=true
, the cost
scope is also required.
If you want to see financial data, youâll need the financial
scope.
If your account contains more than 50 Qualifications, per-user qualification data will not be returned by default. Include the show_qualifications=true
option to include it in the response.
- show_wages
boolean
(optional) Example: trueWhether to show the userâs wage (defaults to false)
- show_qualifications
boolean
(optional) Example: trueShould the response include qualifications for each user
- show_regular_hours
boolean
(optional) Example: trueShould the response include regular hours for each user
- show_inactive
boolean
(optional) Example: falseInclude inactive staff in your response
- updated_after
number
(optional) Example: 1451570400Time filter to find recently created or modified users
- location_id
number
(optional) Example: 111The ID of a location for which to filter users to. If provided, only returns userâs that belong to a department assigned to that location.
- report_location_id
number
(optional) Example: 111The ID of a location for which to filter users to. If provided, only returns users if the userâs default team (
report_department_id
) is set, and it is a department, within this location.- role_types
number
(optional) Example: employeeThe role type for which to filter users by. This can be a list of role types, separated by a comma (ie.
"manager,employee"
).- platform_role_ids
string
(optional) Example: 111The ID of a role for which to filter users by. This can be a list of ids, separated by a comma (ie.
"111,222,333"
).- employee_id
string
(optional) Example: "CC123"Employee ID to filter by.
- platform
boolean
(optional) Example: falseIf true, Platform data will be returned (defaults to false).
- page
number
(optional) Example: 1The page number for your user list
- page_size
number
(optional) Example: 50The number of users retrieved per page. Maximum 100 per page.
Headers
Content-Type: application/json
Body
{
"name": "Carlton Carlson Jr.",
"employee_id": "CC123",
"passcode": "6789",
"phone": "+61408123654",
"date_of_birth": "1956-09-25",
"employment_start_date": "1986-09-24",
"email": "carl.carlson@springfieldpowerplant.com",
"report_department_id": 111,
"preferred_hours": 22,
"award_template_organisation_id": 5324324,
"award_tag_ids": [
3816
],
"department_ids": [
111
],
"managed_department_ids": [
111
],
"platform_role_ids": [
3816,
3817
],
"yearly_salary": 40000,
"enable_login": true
}
Headers
Content-Type: application/json
Body
{
"id": 12345678,
"name": "Carlton Carlson Jr.",
"date_of_birth": "1956-09-25",
"employment_start_date": "1986-09-24",
"employment_end_date": null,
"employee_id": "CC123",
"passcode": "6789",
"platform_role_ids": [
3816,
3817
],
"department_ids": [
111
],
"preferred_hours": 22,
"award_template_organisation_id": 5324324,
"award_tag_ids": [
3816
],
"report_department_id": 111,
"managed_department_ids": [
111
],
"active": true,
"enable_login": true,
"can_see_costs": true,
"email": "carl.carlson@springfieldpowerplant.com",
"photo": null,
"phone": "+61408123654",
"normalised_phone": "+61408123654",
"time_zone": "Australia/Brisbane",
"utc_offset": 36000,
"created_at": 1459476813,
"part_time_fixed_hours": 0.0,
"expected_hours_in_pay_period": null,
"days_overtime_averaged_over": 7,
"overtime_calculated_over_period_start": "2016-11-14",
"super_fund_membership": null,
"super_fund": null,
"bank_details": null,
"tax_declaration": null,
"onboarding_status": "not_applicable",
"qualifications": [],
"regular_hours": {
"start_date": "2021-01-01",
"schedules": [
{
"week": 1,
"day": "Monday",
"start": "09:00",
"end": "17:00",
"department_id": 1234,
"breaks": "12:00-13:00"
}
]
}
"updated_at": 1562272900
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the user"
},
"name": {
"type": "string",
"description": "The user's name"
},
"date_of_birth": {
"type": "string",
"description": "The user's date of birth"
},
"employment_start_date": {
"type": "string",
"description": "The user's employment start date"
},
"employee_id": {
"type": "string",
"description": "The user's employee id, used for external systems"
},
"passcode": {
"type": "string",
"description": "The user's system passcode (used for clocking in and out)"
},
"platform_role_ids": {
"type": "array",
"description": "IDs of the user's roles (see Access & Roles)"
},
"department_ids": {
"type": "array",
"description": "The department (team) ids that the user is a member of"
},
"preferred_hours": {
"type": "number",
"description": "The preferred number of hours to be rostered each week"
},
"award": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the award"
},
"identifier": {
"type": "string",
"description": "The award's identifier (will be the award code for all modern awards)"
},
"note": {
"type": "string",
"description": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_id` field instead."
}
},
"required": [
"name"
],
"description": "Information about the user's award, null if user isn't on award"
},
"award_template_id": {
"type": "number",
"description": "The ID of the award template thte user is on"
},
"award_tag_ids": {
"type": "array",
"description": "The award tag ids that apply to the user"
},
"report_department_id": {
"type": "number",
"description": "The user's default team"
},
"managed_department_ids": {
"type": "array",
"description": "The department ids that this user manages"
},
"active": {
"type": "boolean",
"description": "Whether the user is active in the system"
},
"email": {
"type": "string",
"description": "The user's email"
},
"photo": {
"type": "string",
"description": "An avatar for the user"
},
"phone": {
"type": "string",
"description": "Phone number for the user"
},
"normalised_phone": {
"type": "string",
"description": "Phone number for user with international dialing code"
},
"time_zone": {
"type": "string",
"description": "The user's time zone"
},
"utc_offset": {
"type": "number",
"description": "The user's time zone's UTC offset"
},
"oauth_provider": {
"type": "string",
"description": "If oAuth login enabled, login provider"
},
"oauth_uid": {
"type": "string",
"description": "If oAuth login enabled, login UID"
},
"part_time_fixed_hours": {
"type": "number",
"description": "readonly: for part time staff, can be used to configure when overtime starts to apply"
},
"expected_hours_in_pay_period": {
"type": "number",
"description": "readonly: for salaried staff, defines expected number of hours worked per pay period"
},
"days_overtime_averaged_over": {
"type": "number",
"description": "readonly: date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run"
},
"overtime_calculated_over_period_start": {
"type": "string",
"description": "readonly: date from which overtime averaging periods should commence"
},
"created_at": {
"type": "number",
"description": "When the user's Tanda profile was created"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
}
},
"required": [
"id",
"name",
"passcode",
"platform_role_ids",
"department_ids",
"preferred_hours",
"award_tag_ids",
"active",
"utc_offset",
"created_at"
]
}
Headers
Content-Type: application/json
Body
{
"name": "Carlton Carlson Jr."
}
Headers
Content-Type: application/json
Body
{
"id": 12345678,
"name": "Carlton Carlson Jr.",
"date_of_birth": null,
"employment_start_date": null,
"employment_end_date": null,
"employee_id": null,
"passcode": null,
"platform_role_ids": [
3816
],
"department_ids": [],
"preferred_hours": 22,
"award_template_id": null,
"award_tag_ids": [],
"report_department_id": null,
"managed_department_ids": [],
"active": true,
"enable_login": true,
"can_see_costs": true,
"email": null,
"photo": null,
"phone": null,
"normalised_phone": null,
"time_zone": "Australia/Brisbane",
"utc_offset": 36000,
"created_at": 1459476813,
"part_time_fixed_hours": 0,
"expected_hours_in_pay_period": null,
"days_overtime_averaged_over": 7,
"overtime_calculated_over_period_start": "2016-11-14",
"super_fund_membership": null,
"super_fund": null,
"bank_details": null,
"tax_declaration": null,
"onboarding_status": "not_applicable",
"qualifications": [],
"updated_at": 1562272900
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the user"
},
"name": {
"type": "string",
"description": "The user's name"
},
"date_of_birth": {
"type": "string",
"description": "The user's date of birth"
},
"employment_start_date": {
"type": "string",
"description": "The user's employment start date"
},
"employee_id": {
"type": "string",
"description": "The user's employee id, used for external systems"
},
"passcode": {
"type": "string",
"description": "The user's system passcode (used for clocking in and out)"
},
"platform_role_ids": {
"type": "array",
"description": "IDs of the user's roles (see Access & Roles)"
},
"department_ids": {
"type": "array",
"description": "The department (team) ids that the user is a member of"
},
"preferred_hours": {
"type": "number",
"description": "The preferred number of hours to be rostered each week"
},
"award": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the award"
},
"identifier": {
"type": "string",
"description": "The award's identifier (will be the award code for all modern awards)"
},
"note": {
"type": "string",
"description": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_id` field instead."
}
},
"required": [
"name"
],
"description": "Information about the user's award, null if user isn't on award"
},
"award_template_id": {
"type": "number",
"description": "The ID of the award template thte user is on"
},
"award_tag_ids": {
"type": "array",
"description": "The award tag ids that apply to the user"
},
"report_department_id": {
"type": "number",
"description": "The user's default team"
},
"managed_department_ids": {
"type": "array",
"description": "The department ids that this user manages"
},
"active": {
"type": "boolean",
"description": "Whether the user is active in the system"
},
"email": {
"type": "string",
"description": "The user's email"
},
"photo": {
"type": "string",
"description": "An avatar for the user"
},
"phone": {
"type": "string",
"description": "Phone number for the user"
},
"normalised_phone": {
"type": "string",
"description": "Phone number for user with international dialing code"
},
"time_zone": {
"type": "string",
"description": "The user's time zone"
},
"utc_offset": {
"type": "number",
"description": "The user's time zone's UTC offset"
},
"oauth_provider": {
"type": "string",
"description": "If oAuth login enabled, login provider"
},
"oauth_uid": {
"type": "string",
"description": "If oAuth login enabled, login UID"
},
"part_time_fixed_hours": {
"type": "number",
"description": "readonly: for part time staff, can be used to configure when overtime starts to apply"
},
"expected_hours_in_pay_period": {
"type": "number",
"description": "readonly: for salaried staff, defines expected number of hours worked per pay period"
},
"days_overtime_averaged_over": {
"type": "number",
"description": "readonly: date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run"
},
"overtime_calculated_over_period_start": {
"type": "string",
"description": "readonly: date from which overtime averaging periods should commence"
},
"created_at": {
"type": "number",
"description": "When the user's Tanda profile was created"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
}
},
"required": [
"id",
"name",
"passcode",
"platform_role_ids",
"department_ids",
"preferred_hours",
"award_tag_ids",
"active",
"utc_offset",
"created_at"
]
}
Headers
Content-Type: application/json
Body
{
"name": "Steve Barnett",
"regular_hours": {
"start_date": "2021-01-01",
"schedules": [
{
"week": 1,
"day": "Monday",
"start": "09:00",
"end": "17:00",
"department_id": 1234,
"breaks": "12:00-13:00"
},
{
"week": 2,
"day": "Tuesday",
"start": "10:00",
"end": "20:00",
"department_id": 4321,
"breaks": "12:00-13:00"
}
]
}
}
Headers
Content-Type: application/json
Body
{
"id": 12345678,
"name": "Steve Barnett",
"date_of_birth": null,
"employment_start_date": null,
"employment_end_date": null,
"employee_id": null,
"passcode": null,
"platform_role_ids": [
3816
],
"department_ids": [],
"preferred_hours": 22,
"award_template_id": null,
"award_tag_ids": [],
"report_department_id": null,
"managed_department_ids": [],
"active": true,
"enable_login": true,
"can_see_costs": true,
"email": null,
"photo": null,
"phone": null,
"normalised_phone": null,
"time_zone": "Australia/Brisbane",
"utc_offset": 36000,
"created_at": 1459476813,
"part_time_fixed_hours": 0,
"expected_hours_in_pay_period": null,
"days_overtime_averaged_over": 7,
"overtime_calculated_over_period_start": "2016-11-14",
"super_fund_membership": null,
"super_fund": null,
"bank_details": null,
"tax_declaration": null,
"onboarding_status": "not_applicable",
"qualifications": [],
"regular_hours": {
"start_date": "2021-01-01",
"schedules": [
{
"week": 1,
"day": "Monday",
"start": "09:00",
"end": "17:00",
"department_id": 1234,
"breaks": "12:00-13:00"
},
{
"week": 2,
"day": "Tuesday",
"start": "10:00",
"end": "20:00",
"department_id": 4321,
"breaks": "12:00-13:00"
}
]
},
"updated_at": 1562272900
}
Create UserPOST/api/v2/users
Only the name
field is required to create a user.
To create a manager, you should provide the IDs of Teams they manage in the managed_department_ids
field.
The Tanda API currently requires email addresses to be unique within an organisation when creating a user. However, there is no guarantee that this restriction will exist in the future. If you are creating users via the API you should first GET
a list of users and validate that the user youâre creating doesnât already exist - do not depend on the API to validate this for you.
To skip email validation when creating a user, use skip_validation=true
.
This method requires the user
scope (see Scopes for more information).
If you plan to assign wage information you will need the cost
scope. This includes the employee_id
field.
To set financial information, you will need the financial
scope.
- skip_validation
boolean
(optional) Example: trueSkipâs checking if an employee already exists with this email address (defaults to false)
Inactive User List ¶
Headers
Content-Type: application/json
Body
[
{
"id": 1234567,
"name": "Homer Simpson",
"date_of_birth": null,
"employment_start_date": null,
"employment_end_date": "2019-06-01",
"employee_id": "HS98",
"passcode": "1230",
"department_ids": [
111
],
"preferred_hours": 22,
"award_template_id": 58,
"award_tag_ids": [],
"report_department_id": 111,
"managed_department_ids": [],
"active": false,
"enable_login": true,
"can_see_costs": true,
"email": "homer.simpson@springfieldpowerplant.com",
"photo": "http://vignette2.wikia.nocookie.net/simpsons/images/b/bd/Homer_Simpson.png",
"phone": "+61404123456",
"normalised_phone": "+61404123456",
"time_zone": "Australia/Brisbane",
"utc_offset": 36000,
"created_at": 1430715549,
"part_time_fixed_hours": 0,
"expected_hours_in_pay_period": null,
"days_overtime_averaged_over": 7,
"overtime_calculated_over_period_start": "2016-11-14",
"super_fund_membership": null,
"super_fund": null,
"bank_details": null,
"tax_declaration": null,
"onboarding_status": "not_applicable",
"qualifications": [],
"updated_at": 1562272900
}
]
Get Inactive UsersGET/api/v2/users/inactive
This method requires the user
scope (see Scopes for more information).
- updated_after
number
(optional) Example: 1451570400Time filter to find recently created or modified users
- report_location_id
number
(optional) Example: 111The ID of a location for which to filter users to. If provided, only returns users if the userâs default team (
report_department_id
) is set, and it is a team within this location.
User ¶
Headers
Content-Type: application/json
Body
{
"id": 123456,
"name": "Lenny Leonard",
"date_of_birth": "1955-05-12",
"employment_start_date": "1989-12-17",
"employee_id": "LL1",
"passcode": "0456",
"platform_role_ids": [
18,
19,
22
],
"department_ids": [
111
],
"preferred_hours": 20,
"award": {
"name": "Fast Food Industry",
"identifier": "MA000003",
"note": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_organisation_id` field instead."
},
"award_template_id": 990,
"award_template_organisation_id": 5624432,
"award_tag_ids": [
3816
],
"report_department_id": 111,
"managed_department_ids": [
222
],
"active": true,
"email": "lenny.leonard@springfieldpowerplant.com",
"photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
"phone": "0404 123 123",
"normalised_phone": "+61404123123",
"salary": 1234.12,
"hourly_rate": 32.47,
"time_zone": "Australia/Brisbane",
"utc_offset": 36000,
"part_time_fixed_hours": 20,
"expected_hours_in_pay_period": 38,
"days_overtime_averaged_over": 7,
"overtime_calculated_over_period_start": "2016-09-12",
"super_fund": {
"id": 1234,
"fund_name": "FUND NAME",
"product_name": "FUND PRODUCT",
"smsf": false,
"abn": 123456789
},
"super_fund_membership": {
"super_contribution_type": "arpa",
"trustee_director": false,
"member_number": "123ACB",
"employer_action_date": "2000-01-01T09:30:00+10:00",
"occupational_rating": "A1",
"super_fund_id": 1234,
"employer_preferred": 0,
"employer_default": 1,
"employer_generic": 2
},
"bank_details": {
"bsb": 60111,
"account_number": 12345678,
"account_name": 0
},
"address": {
"street_line_one": "742 Evergreen Terrace",
"street_line_two": "Hello, world!",
"city": "Springfield",
"state": "Oregon",
"country": "United States of America",
"postcode": "97475"
},
"tax_declaration": {
"previous_family_name": "Smith",
"tax_free_threshold": true,
"senior_tax_offset": false,
"zone_overseas_carer": false,
"student_loan": true,
"financial_supplement_debt": true,
"tax_code": true,
"employment_basis: full_time": "Hello, world!",
"tax_file_number": "123 456 789",
"uk_tax_year_status": "first_job / had_previous_job / second_job",
"uk_student_loan_plan": "plan_1 / plan_2 / both"
},
"onboarding_status": "not_applicable, pending, invited, in_progress, completed, invitation_failed",
"qualifications": [
{
"id": 12345,
"qualification_id": 1234,
"enabled": true,
"license_number": "ABC123",
"expires": "2012-10-20",
"in_training": false
}
],
"regular_hours": {
"start_date": "2021-01-01",
"schedules": {
"week": 1,
"day": "Monday",
"start": "09:00",
"end": "17:00",
"breaks": "12:00",
"department_id": 1234
}
},
"minimum_base_hours": 20,
"created_at": 1430715548,
"record_id": 532432,
"next_pay_group_id": 53242,
"last_synced_mobile_app": 1430715548,
"automatic_break_rule_set_id": 1430715548
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the user"
},
"name": {
"type": "string",
"description": "The user's name"
},
"date_of_birth": {
"type": "string",
"description": "The user's date of birth"
},
"employment_start_date": {
"type": "string",
"description": "The user's employment start date"
},
"employee_id": {
"type": "string",
"description": "The user's employee id, used for external systems"
},
"passcode": {
"type": "string",
"description": "The user's system passcode (used for clocking in and out)"
},
"platform_role_ids": {
"type": "array",
"description": "IDs of the user's roles (see Access & Roles)"
},
"department_ids": {
"type": "array",
"description": "The department (team) ids that the user is a member of"
},
"preferred_hours": {
"type": "number",
"description": "The preferred number of hours to be rostered each week"
},
"award": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the award"
},
"identifier": {
"type": "string",
"description": "The award's identifier (will be the award code for all modern awards)"
},
"note": {
"type": "string",
"description": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_organisation_id` field instead."
}
},
"required": [
"name"
],
"description": "Information about the user's award, null if user isn't on award"
},
"award_template_id": {
"type": "number",
"description": "The ID of the award template the user is on"
},
"award_template_organisation_id": {
"type": "number",
"description": "The internal ID of the award template the user is on"
},
"award_tag_ids": {
"type": "array",
"description": "The award tag ids that apply to the user"
},
"report_department_id": {
"type": "number",
"description": "The user's default team"
},
"managed_department_ids": {
"type": "array",
"description": "The department ids that this user manages"
},
"active": {
"type": "boolean",
"description": "Whether the user is active in the system"
},
"email": {
"type": "string",
"description": "The user's email"
},
"photo": {
"type": "string",
"description": "An avatar for the user"
},
"phone": {
"type": "string",
"description": "Phone number for the user"
},
"normalised_phone": {
"type": "string",
"description": "Phone number for user with international dialing code"
},
"salary": {
"type": "number",
"description": "The weekly salary of the user, if `show_wages=true` parameter is set"
},
"hourly_rate": {
"type": "number",
"description": "The hourly rate of the user, if `show_wages=true` parameter is set, will not show if the salary exists"
},
"time_zone": {
"type": "string",
"description": "The user's time zone"
},
"utc_offset": {
"type": "number",
"description": "The user's time zone's UTC offset"
},
"part_time_fixed_hours": {
"type": "number",
"description": "For part time staff, can be used to configure when overtime starts to apply"
},
"expected_hours_in_pay_period": {
"type": "number",
"description": "readonly: for salaried staff, defines expected number of hours worked per pay period"
},
"days_overtime_averaged_over": {
"type": "number",
"description": "date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run"
},
"overtime_calculated_over_period_start": {
"type": "string",
"description": "date from which overtime averaging periods should commence"
},
"super_fund": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "the unique ID of the employees fund"
},
"fund_name": {
"type": "string",
"description": "the name of the fund"
},
"product_name": {
"type": "string",
"description": "the name of the fund product"
},
"smsf": {
"type": "boolean",
"description": "is the fund a self managed fund"
},
"abn": {
"type": "number",
"description": "the number of the fund"
}
},
"description": "information about the employees super fund"
},
"super_fund_membership": {
"type": "object",
"properties": {
"super_contribution_type": {
"type": "string",
"description": "the type of the employees super contribution"
},
"trustee_director": {
"type": "boolean",
"description": "is the employees super fund directed by a trustee?"
},
"member_number": {
"type": "string",
"description": "the membership number of the employees super fund"
},
"employer_action_date": {
"type": "string",
"description": "the action date of the super fund by the employer"
},
"occupational_rating": {
"type": "string",
"description": "the occupational rating of the employees super fund"
},
"super_fund_id": {
"type": "number",
"description": "the record ID of the employees super fund"
},
"employer_preferred": {
"type": "number",
"description": "indication of an employers preferred super fund"
},
"employer_default": {
"type": "number",
"description": "indication of an employers default super fund"
},
"employer_generic": {
"type": "number",
"description": "indication of an employers generic super fund"
}
},
"required": [
"super_fund_id",
"employer_preferred",
"employer_default",
"employer_generic"
],
"description": "information about the employees super fund membership"
},
"bank_details": {
"type": "object",
"properties": {
"bsb": {
"type": "number",
"description": "the bsb number of the employees bank account"
},
"account_number": {
"type": "number",
"description": "the account number of the employees bank account"
},
"account_name": {
"type": "number",
"description": "the account name of the employees bank account"
}
},
"required": [
"bsb",
"account_number",
"account_name"
],
"description": "the bank details of the employee"
},
"address": {
"type": "object",
"properties": {
"street_line_one": {
"type": "string"
},
"street_line_two": {
"type": [
"string",
"null"
],
"description": "Apartment, Suite, etc"
},
"city": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"country": {
"type": "string"
},
"postcode": {
"type": [
"string",
"null"
]
}
},
"required": [
"street_line_two"
]
},
"tax_declaration": {
"type": "object",
"properties": {
"previous_family_name": {
"type": "string",
"description": "the previous family name of the employee"
},
"tax_free_threshold": {
"type": "boolean",
"description": "is the employee under the tax free threshold?"
},
"senior_tax_offset": {
"type": "boolean",
"description": "can the employee claim a senior tax offset?"
},
"zone_overseas_carer": {
"type": "boolean",
"description": "can the employee claim a zone or overseas tax offset?"
},
"student_loan": {
"type": "boolean",
"description": "does the employee have a student loan?"
},
"financial_supplement_debt": {
"type": "boolean",
"description": "does the employee have a financial supplement debt?"
},
"tax_code": {
"type": "boolean",
"description": "the employees code for tax services"
},
"employment_basis: full_time": {
"type": "string",
"description": "the employment type the employee has specified on their TFN declaration (full_time, part_time, casual, labour_hire, super_or_annuity)"
},
"tax_file_number": {
"type": "string",
"description": "The tax file number for the user. This property only exists when using the `financial` scope is in use."
},
"uk_tax_year_status": {
"type": "string",
"description": "(uk residents) the stage of the employees career"
},
"uk_student_loan_plan": {
"type": "string",
"description": "(uk residents) the tax scheme for the employee"
}
},
"description": "the tax declaration information of the employee"
},
"onboarding_status": {
"type": "string",
"description": "the status of the employee onboarding progress"
},
"qualifications": {
"type": "array",
"description": "Information about qualifications the user holds, if Qualifications are enabled"
},
"regular_hours": {
"type": "object",
"properties": {
"start_date": {
"type": "string",
"description": "the anchor date of the regular hours"
},
"schedules": {
"type": "object",
"properties": {
"week": {
"type": "number",
"description": "which week does the schedule fall in"
},
"day": {
"type": "string",
"description": "what day is the schedule for"
},
"start": {
"type": "string",
"description": "what time does the schedule start"
},
"end": {
"type": "string",
"description": "what time does the schedule finish"
},
"breaks": {
"type": "string",
"description": "13:00 (string) - what breaks apply to this schedule"
},
"department_id": {
"type": "number",
"description": "the id of the department the schedule is for"
}
},
"required": [
"week",
"day",
"start",
"end"
],
"description": "information about the schedules that make up the regular hours of work"
}
},
"required": [
"start_date"
],
"description": "information about the employees regular hours of work"
},
"minimum_base_hours": {
"type": "number",
"description": "minimum required hours for this employee"
},
"created_at": {
"type": "number",
"description": "When the user's Tanda profile was created"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
},
"next_pay_group_id": {
"type": "number",
"description": "the ID for the pay group of the user's next timesheet"
},
"last_synced_mobile_app": {
"type": "number",
"description": "Read only: when the user last opened the mobile app."
},
"automatic_break_rule_set_id": {
"type": "number",
"description": "Read only: the ID for the user's automatic break rule set."
}
},
"required": [
"id",
"name",
"passcode",
"platform_role_ids",
"department_ids",
"preferred_hours",
"award_tag_ids",
"active",
"utc_offset",
"created_at"
]
}
Get UserGET/api/v2/users/{id}{?show_wages}
Gets information about a user.
This method requires the user
scope (see Scopes for more information).
If you are using show_wages=true
, the cost
scope is also required.
- id
number
(required) Example: 123456The id of the user
- show_wages
boolean
(optional) Example: trueWhether to show the userâs wage (defaults to false)
- show_regular_hours
boolean
(optional) Example: trueWhether to show the userâs regular hours (defaults to false)
- platform
boolean
(optional) Example: falseIf true, Platform data will be returned (defaults to false)
Headers
Content-Type: application/json
Body
{
"name": "Lenford Leonard",
"employee_id": "Lenford",
"passcode": "0123",
"phone": "0404123122",
"date_of_birth": "1990-12-12",
"employment_start_date": "2016-03-01",
"email": "some_email@test.com",
"hourly_rate": 12.34,
"enable_login": true,
"qualifications": [
{
"qualification_id": 2345,
"enabled": true,
"license_number": "BCD234",
"expires": "2012-11-21",
"in_training": false,
"file_id": "2d4ab757-637c-4be2-b2d6-5f89ae211ba4"
}
]
}
Headers
Content-Type: application/json
Body
{
"id": 123456,
"name": "Lenford Leonard",
"date_of_birth": "1990-12-12",
"employment_start_date": "2016-03-01",
"employee_id": "Lenford",
"passcode": "0123",
"platform_role_ids": [
18,
19,
22
],
"department_ids": [
111
],
"preferred_hours": 20,
"award": {
"name": "Fast Food Industry",
"identifier": "MA000003",
"note": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_organisation_id` field instead."
},
"award_template_id": 990,
"award_template_organisation_id": 5624432,
"award_tag_ids": [
3816
],
"report_department_id": 111,
"managed_department_ids": [
222
],
"active": true,
"email": "some_email@test.com",
"photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
"phone": "0404123122",
"normalised_phone": "+61404123122",
"salary": 1234.12,
"hourly_rate": 12.34,
"time_zone": "Australia/Brisbane",
"utc_offset": 36000,
"part_time_fixed_hours": 20,
"expected_hours_in_pay_period": 38,
"days_overtime_averaged_over": 7,
"overtime_calculated_over_period_start": "2016-09-12",
"super_fund": {
"id": 1234,
"fund_name": "FUND NAME",
"product_name": "FUND PRODUCT",
"smsf": false,
"abn": 123456789
},
"super_fund_membership": {
"super_contribution_type": "arpa",
"trustee_director": false,
"member_number": "123ACB",
"employer_action_date": "2000-01-01T09:30:00+10:00",
"occupational_rating": "A1",
"super_fund_id": 1234,
"employer_preferred": 0,
"employer_default": 1,
"employer_generic": 2
},
"bank_details": {
"bsb": 60111,
"account_number": 12345678,
"account_name": 0
},
"address": {
"street_line_one": "742 Evergreen Terrace",
"street_line_two": null,
"city": "Springfield",
"state": "Oregon",
"country": "United States of America",
"postcode": "97475"
},
"tax_declaration": {
"previous_family_name": "Smith",
"tax_free_threshold": true,
"senior_tax_offset": false,
"zone_overseas_carer": false,
"student_loan": true,
"financial_supplement_debt": true,
"tax_code": true,
"employment_basis: full_time": "",
"tax_file_number": "123 456 789",
"uk_tax_year_status": "first_job / had_previous_job / second_job",
"uk_student_loan_plan": "plan_1 / plan_2 / both"
},
"onboarding_status": "not_applicable, pending, invited, in_progress, completed, invitation_failed",
"qualifications": "[{}]",
"regular_hours": {
"start_date": "2021-01-01",
"schedules": {
"week": 1,
"day": "Monday",
"start": "09:00",
"end": "17:00",
"breaks": "12:00",
"department_id": 1234
}
},
"minimum_base_hours": 20,
"created_at": 1430715548,
"record_id": 532432,
"next_pay_group_id": 53242,
"last_synced_mobile_app": 1430715548,
"automatic_break_rule_set_id": 1430715548,
"enable_login": true
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the user"
},
"name": {
"type": "string",
"description": "The user's name"
},
"date_of_birth": {
"type": "string",
"description": "The user's date of birth"
},
"employment_start_date": {
"type": "string",
"description": "The user's employment start date"
},
"employee_id": {
"type": "string",
"description": "The user's employee id, used for external systems"
},
"passcode": {
"type": "string",
"description": "The user's system passcode (used for clocking in and out)"
},
"platform_role_ids": {
"type": "array",
"description": "IDs of the user's roles (see Access & Roles)"
},
"department_ids": {
"type": "array",
"description": "The department (team) ids that the user is a member of"
},
"preferred_hours": {
"type": "number",
"description": "The preferred number of hours to be rostered each week"
},
"award": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the award"
},
"identifier": {
"type": "string",
"description": "The award's identifier (will be the award code for all modern awards)"
},
"note": {
"type": "string",
"description": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_organisation_id` field instead."
}
},
"required": [
"name"
],
"description": "Information about the user's award, null if user isn't on award"
},
"award_template_id": {
"type": "number",
"description": "The ID of the award template the user is on"
},
"award_template_organisation_id": {
"type": "number",
"description": "The internal ID of the award template the user is on"
},
"award_tag_ids": {
"type": "array",
"description": "The award tag ids that apply to the user"
},
"report_department_id": {
"type": "number",
"description": "The user's default team"
},
"managed_department_ids": {
"type": "array",
"description": "The department ids that this user manages"
},
"active": {
"type": "boolean",
"description": "Whether the user is active in the system"
},
"email": {
"type": "string",
"description": "The user's email"
},
"photo": {
"type": "string",
"description": "An avatar for the user"
},
"phone": {
"type": "string",
"description": "Phone number for the user"
},
"normalised_phone": {
"type": "string",
"description": "Phone number for user with international dialing code"
},
"salary": {
"type": "number",
"description": "The weekly salary of the user, if `show_wages=true` parameter is set"
},
"hourly_rate": {
"type": "number",
"description": "The hourly rate of the user, if `show_wages=true` parameter is set, will not show if the salary exists"
},
"time_zone": {
"type": "string",
"description": "The user's time zone"
},
"utc_offset": {
"type": "number",
"description": "The user's time zone's UTC offset"
},
"part_time_fixed_hours": {
"type": "number",
"description": "For part time staff, can be used to configure when overtime starts to apply"
},
"expected_hours_in_pay_period": {
"type": "number",
"description": "readonly: for salaried staff, defines expected number of hours worked per pay period"
},
"days_overtime_averaged_over": {
"type": "number",
"description": "date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run"
},
"overtime_calculated_over_period_start": {
"type": "string",
"description": "date from which overtime averaging periods should commence"
},
"super_fund": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "the unique ID of the employees fund"
},
"fund_name": {
"type": "string",
"description": "the name of the fund"
},
"product_name": {
"type": "string",
"description": "the name of the fund product"
},
"smsf": {
"type": "boolean",
"description": "is the fund a self managed fund"
},
"abn": {
"type": "number",
"description": "the number of the fund"
}
},
"description": "information about the employees super fund"
},
"super_fund_membership": {
"type": "object",
"properties": {
"super_contribution_type": {
"type": "string",
"description": "the type of the employees super contribution"
},
"trustee_director": {
"type": "boolean",
"description": "is the employees super fund directed by a trustee?"
},
"member_number": {
"type": "string",
"description": "the membership number of the employees super fund"
},
"employer_action_date": {
"type": "string",
"description": "the action date of the super fund by the employer"
},
"occupational_rating": {
"type": "string",
"description": "the occupational rating of the employees super fund"
},
"super_fund_id": {
"type": "number",
"description": "the record ID of the employees super fund"
},
"employer_preferred": {
"type": "number",
"description": "indication of an employers preferred super fund"
},
"employer_default": {
"type": "number",
"description": "indication of an employers default super fund"
},
"employer_generic": {
"type": "number",
"description": "indication of an employers generic super fund"
}
},
"required": [
"super_fund_id",
"employer_preferred",
"employer_default",
"employer_generic"
],
"description": "information about the employees super fund membership"
},
"bank_details": {
"type": "object",
"properties": {
"bsb": {
"type": "number",
"description": "the bsb number of the employees bank account"
},
"account_number": {
"type": "number",
"description": "the account number of the employees bank account"
},
"account_name": {
"type": "number",
"description": "the account name of the employees bank account"
}
},
"required": [
"bsb",
"account_number",
"account_name"
],
"description": "the bank details of the employee"
},
"address": {
"type": "object",
"properties": {
"street_line_one": {
"type": "string"
},
"street_line_two": {
"type": [
"string",
"null"
],
"description": "Apartment, Suite, etc"
},
"city": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"country": {
"type": "string"
},
"postcode": {
"type": [
"string",
"null"
]
}
},
"required": [
"street_line_two"
]
},
"tax_declaration": {
"type": "object",
"properties": {
"previous_family_name": {
"type": "string",
"description": "the previous family name of the employee"
},
"tax_free_threshold": {
"type": "boolean",
"description": "is the employee under the tax free threshold?"
},
"senior_tax_offset": {
"type": "boolean",
"description": "can the employee claim a senior tax offset?"
},
"zone_overseas_carer": {
"type": "boolean",
"description": "can the employee claim a zone or overseas tax offset?"
},
"student_loan": {
"type": "boolean",
"description": "does the employee have a student loan?"
},
"financial_supplement_debt": {
"type": "boolean",
"description": "does the employee have a financial supplement debt?"
},
"tax_code": {
"type": "boolean",
"description": "the employees code for tax services"
},
"employment_basis: full_time": {
"type": "string",
"description": "the employment type the employee has specified on their TFN declaration (full_time, part_time, casual, labour_hire, super_or_annuity)"
},
"tax_file_number": {
"type": "string",
"description": "The tax file number for the user. This property only exists when using the `financial` scope is in use."
},
"uk_tax_year_status": {
"type": "string",
"description": "(uk residents) the stage of the employees career"
},
"uk_student_loan_plan": {
"type": "string",
"description": "(uk residents) the tax scheme for the employee"
}
},
"description": "the tax declaration information of the employee"
},
"onboarding_status": {
"type": "string",
"description": "the status of the employee onboarding progress"
},
"qualifications": {
"type": "string",
"description": "Information about qualifications the user holds, if Qualifications are enabled"
},
"regular_hours": {
"type": "object",
"properties": {
"start_date": {
"type": "string",
"description": "the anchor date of the regular hours"
},
"schedules": {
"type": "object",
"properties": {
"week": {
"type": "number",
"description": "which week does the schedule fall in"
},
"day": {
"type": "string",
"description": "what day is the schedule for"
},
"start": {
"type": "string",
"description": "what time does the schedule start"
},
"end": {
"type": "string",
"description": "what time does the schedule finish"
},
"breaks": {
"type": "string",
"description": "13:00 (string) - what breaks apply to this schedule"
},
"department_id": {
"type": "number",
"description": "the id of the department the schedule is for"
}
},
"required": [
"week",
"day",
"start",
"end"
],
"description": "information about the schedules that make up the regular hours of work"
}
},
"required": [
"start_date"
],
"description": "information about the employees regular hours of work"
},
"minimum_base_hours": {
"type": "number",
"description": "minimum required hours for this employee"
},
"created_at": {
"type": "number",
"description": "When the user's Tanda profile was created"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
},
"next_pay_group_id": {
"type": "number",
"description": "the ID for the pay group of the user's next timesheet"
},
"last_synced_mobile_app": {
"type": "number",
"description": "Read only: when the user last opened the mobile app."
},
"automatic_break_rule_set_id": {
"type": "number",
"description": "Read only: the ID for the user's automatic break rule set."
},
"enable_login": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"passcode",
"platform_role_ids",
"department_ids",
"preferred_hours",
"award_tag_ids",
"active",
"utc_offset",
"created_at"
]
}
Headers
Content-Type: application/json
Body
{
"active": false
}
Headers
Content-Type: application/json
Body
{
"id": 123456,
"name": "Lenny Leonard",
"date_of_birth": "1955-05-12",
"employment_start_date": "1989-12-17",
"employee_id": "LL1",
"passcode": "01234568975461",
"platform_role_ids": [
18,
19,
22
],
"department_ids": [
111
],
"preferred_hours": 20,
"award": {
"name": "Fast Food Industry",
"identifier": "MA000003",
"note": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_organisation_id` field instead."
},
"award_template_id": 990,
"award_template_organisation_id": 5624432,
"award_tag_ids": [
3816
],
"report_department_id": 111,
"managed_department_ids": [
222
],
"active": false,
"email": "lenny.leonard@springfieldpowerplant.com",
"photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
"phone": "0404 123 123",
"normalised_phone": "+61404123123",
"salary": 1234.12,
"hourly_rate": 32.47,
"time_zone": "Australia/Brisbane",
"utc_offset": 36000,
"part_time_fixed_hours": 20,
"expected_hours_in_pay_period": 38,
"days_overtime_averaged_over": 7,
"overtime_calculated_over_period_start": "2016-09-12",
"super_fund": {
"id": 1234,
"fund_name": "FUND NAME",
"product_name": "FUND PRODUCT",
"smsf": false,
"abn": 123456789
},
"super_fund_membership": {
"super_contribution_type": "arpa",
"trustee_director": false,
"member_number": "123ACB",
"employer_action_date": "2000-01-01T09:30:00+10:00",
"occupational_rating": "A1",
"super_fund_id": 1234,
"employer_preferred": 0,
"employer_default": 1,
"employer_generic": 2
},
"bank_details": {
"bsb": 60111,
"account_number": 12345678,
"account_name": 0
},
"address": {
"street_line_one": "742 Evergreen Terrace",
"street_line_two": null,
"city": "Springfield",
"state": "Oregon",
"country": "United States of America",
"postcode": "97475"
},
"tax_declaration": {
"previous_family_name": "Smith",
"tax_free_threshold": true,
"senior_tax_offset": false,
"zone_overseas_carer": false,
"student_loan": true,
"financial_supplement_debt": true,
"tax_code": true,
"employment_basis: full_time": "",
"tax_file_number": "123 456 789",
"uk_tax_year_status": "first_job / had_previous_job / second_job",
"uk_student_loan_plan": "plan_1 / plan_2 / both"
},
"onboarding_status": "not_applicable, pending, invited, in_progress, completed, invitation_failed",
"qualifications": [
{
"id": 12345,
"qualification_id": 1234,
"enabled": true,
"license_number": "ABC123",
"expires": "2012-10-20",
"in_training": false
}
],
"regular_hours": {
"start_date": "2021-01-01",
"schedules": {
"week": 1,
"day": "Monday",
"start": "09:00",
"end": "17:00",
"breaks": "12:00",
"department_id": 1234
}
},
"minimum_base_hours": 20,
"created_at": 1430715548,
"record_id": 532432,
"next_pay_group_id": 53242,
"last_synced_mobile_app": 1430715548,
"automatic_break_rule_set_id": 1430715548
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the user"
},
"name": {
"type": "string",
"description": "The user's name"
},
"date_of_birth": {
"type": "string",
"description": "The user's date of birth"
},
"employment_start_date": {
"type": "string",
"description": "The user's employment start date"
},
"employee_id": {
"type": "string",
"description": "The user's employee id, used for external systems"
},
"passcode": {
"type": "string",
"description": "The user's system passcode (used for clocking in and out)"
},
"platform_role_ids": {
"type": "array",
"description": "IDs of the user's roles (see Access & Roles)"
},
"department_ids": {
"type": "array",
"description": "The department (team) ids that the user is a member of"
},
"preferred_hours": {
"type": "number",
"description": "The preferred number of hours to be rostered each week"
},
"award": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the award"
},
"identifier": {
"type": "string",
"description": "The award's identifier (will be the award code for all modern awards)"
},
"note": {
"type": "string",
"description": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_organisation_id` field instead."
}
},
"required": [
"name"
],
"description": "Information about the user's award, null if user isn't on award"
},
"award_template_id": {
"type": "number",
"description": "The ID of the award template the user is on"
},
"award_template_organisation_id": {
"type": "number",
"description": "The internal ID of the award template the user is on"
},
"award_tag_ids": {
"type": "array",
"description": "The award tag ids that apply to the user"
},
"report_department_id": {
"type": "number",
"description": "The user's default team"
},
"managed_department_ids": {
"type": "array",
"description": "The department ids that this user manages"
},
"active": {
"type": "boolean",
"description": "Whether the user is active in the system"
},
"email": {
"type": "string",
"description": "The user's email"
},
"photo": {
"type": "string",
"description": "An avatar for the user"
},
"phone": {
"type": "string",
"description": "Phone number for the user"
},
"normalised_phone": {
"type": "string",
"description": "Phone number for user with international dialing code"
},
"salary": {
"type": "number",
"description": "The weekly salary of the user, if `show_wages=true` parameter is set"
},
"hourly_rate": {
"type": "number",
"description": "The hourly rate of the user, if `show_wages=true` parameter is set, will not show if the salary exists"
},
"time_zone": {
"type": "string",
"description": "The user's time zone"
},
"utc_offset": {
"type": "number",
"description": "The user's time zone's UTC offset"
},
"part_time_fixed_hours": {
"type": "number",
"description": "For part time staff, can be used to configure when overtime starts to apply"
},
"expected_hours_in_pay_period": {
"type": "number",
"description": "readonly: for salaried staff, defines expected number of hours worked per pay period"
},
"days_overtime_averaged_over": {
"type": "number",
"description": "date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run"
},
"overtime_calculated_over_period_start": {
"type": "string",
"description": "date from which overtime averaging periods should commence"
},
"super_fund": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "the unique ID of the employees fund"
},
"fund_name": {
"type": "string",
"description": "the name of the fund"
},
"product_name": {
"type": "string",
"description": "the name of the fund product"
},
"smsf": {
"type": "boolean",
"description": "is the fund a self managed fund"
},
"abn": {
"type": "number",
"description": "the number of the fund"
}
},
"description": "information about the employees super fund"
},
"super_fund_membership": {
"type": "object",
"properties": {
"super_contribution_type": {
"type": "string",
"description": "the type of the employees super contribution"
},
"trustee_director": {
"type": "boolean",
"description": "is the employees super fund directed by a trustee?"
},
"member_number": {
"type": "string",
"description": "the membership number of the employees super fund"
},
"employer_action_date": {
"type": "string",
"description": "the action date of the super fund by the employer"
},
"occupational_rating": {
"type": "string",
"description": "the occupational rating of the employees super fund"
},
"super_fund_id": {
"type": "number",
"description": "the record ID of the employees super fund"
},
"employer_preferred": {
"type": "number",
"description": "indication of an employers preferred super fund"
},
"employer_default": {
"type": "number",
"description": "indication of an employers default super fund"
},
"employer_generic": {
"type": "number",
"description": "indication of an employers generic super fund"
}
},
"required": [
"super_fund_id",
"employer_preferred",
"employer_default",
"employer_generic"
],
"description": "information about the employees super fund membership"
},
"bank_details": {
"type": "object",
"properties": {
"bsb": {
"type": "number",
"description": "the bsb number of the employees bank account"
},
"account_number": {
"type": "number",
"description": "the account number of the employees bank account"
},
"account_name": {
"type": "number",
"description": "the account name of the employees bank account"
}
},
"required": [
"bsb",
"account_number",
"account_name"
],
"description": "the bank details of the employee"
},
"address": {
"type": "object",
"properties": {
"street_line_one": {
"type": "string"
},
"street_line_two": {
"type": [
"string",
"null"
],
"description": "Apartment, Suite, etc"
},
"city": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"country": {
"type": "string"
},
"postcode": {
"type": [
"string",
"null"
]
}
},
"required": [
"street_line_two"
]
},
"tax_declaration": {
"type": "object",
"properties": {
"previous_family_name": {
"type": "string",
"description": "the previous family name of the employee"
},
"tax_free_threshold": {
"type": "boolean",
"description": "is the employee under the tax free threshold?"
},
"senior_tax_offset": {
"type": "boolean",
"description": "can the employee claim a senior tax offset?"
},
"zone_overseas_carer": {
"type": "boolean",
"description": "can the employee claim a zone or overseas tax offset?"
},
"student_loan": {
"type": "boolean",
"description": "does the employee have a student loan?"
},
"financial_supplement_debt": {
"type": "boolean",
"description": "does the employee have a financial supplement debt?"
},
"tax_code": {
"type": "boolean",
"description": "the employees code for tax services"
},
"employment_basis: full_time": {
"type": "string",
"description": "the employment type the employee has specified on their TFN declaration (full_time, part_time, casual, labour_hire, super_or_annuity)"
},
"tax_file_number": {
"type": "string",
"description": "The tax file number for the user. This property only exists when using the `financial` scope is in use."
},
"uk_tax_year_status": {
"type": "string",
"description": "(uk residents) the stage of the employees career"
},
"uk_student_loan_plan": {
"type": "string",
"description": "(uk residents) the tax scheme for the employee"
}
},
"description": "the tax declaration information of the employee"
},
"onboarding_status": {
"type": "string",
"description": "the status of the employee onboarding progress"
},
"qualifications": {
"type": "array",
"description": "Information about qualifications the user holds, if Qualifications are enabled"
},
"regular_hours": {
"type": "object",
"properties": {
"start_date": {
"type": "string",
"description": "the anchor date of the regular hours"
},
"schedules": {
"type": "object",
"properties": {
"week": {
"type": "number",
"description": "which week does the schedule fall in"
},
"day": {
"type": "string",
"description": "what day is the schedule for"
},
"start": {
"type": "string",
"description": "what time does the schedule start"
},
"end": {
"type": "string",
"description": "what time does the schedule finish"
},
"breaks": {
"type": "string",
"description": "13:00 (string) - what breaks apply to this schedule"
},
"department_id": {
"type": "number",
"description": "the id of the department the schedule is for"
}
},
"required": [
"week",
"day",
"start",
"end"
],
"description": "information about the schedules that make up the regular hours of work"
}
},
"required": [
"start_date"
],
"description": "information about the employees regular hours of work"
},
"minimum_base_hours": {
"type": "number",
"description": "minimum required hours for this employee"
},
"created_at": {
"type": "number",
"description": "When the user's Tanda profile was created"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
},
"next_pay_group_id": {
"type": "number",
"description": "the ID for the pay group of the user's next timesheet"
},
"last_synced_mobile_app": {
"type": "number",
"description": "Read only: when the user last opened the mobile app."
},
"automatic_break_rule_set_id": {
"type": "number",
"description": "Read only: the ID for the user's automatic break rule set."
}
},
"required": [
"id",
"name",
"passcode",
"platform_role_ids",
"department_ids",
"preferred_hours",
"award_tag_ids",
"active",
"utc_offset",
"created_at"
]
}
Headers
Content-Type: application/json
Body
{
"department_ids": null
}
Headers
Content-Type: application/json
Body
{
"id": 123456,
"name": "Lenny Leonard",
"date_of_birth": "1955-05-12",
"employment_start_date": "1989-12-17",
"employment_end_date": "2019-06-01",
"employee_id": "LL1",
"passcode": "0456",
"department_ids": [],
"preferred_hours": 20,
"award_template_id": 990,
"award_tag_ids": [
3816
],
"report_department_id": 111,
"managed_department_ids": [
222
],
"active": true,
"enable_login": true,
"can_see_costs": true,
"email": "lenny.leonard@springfieldpowerplant.com",
"photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
"phone": "0404 123 123",
"normalised_phone": "+61404123123",
"salary": 1234.12,
"hourly_rate": 32.47,
"time_zone": "Australia/Brisbane",
"utc_offset": 36000,
"created_at": 1430715548
"part_time_fixed_hours": 20,
"expected_hours_in_pay_period": 38,
"days_overtime_averaged_over": 7,
"overtime_calculated_over_period_start": "2016-09-12",
"super_fund_membership": null,
"super_fund": null,
"bank_details": null,
"tax_declaration": null,
"qualifications": [],
"updated_at": 1562272900
}
Headers
Content-Type: application/json
Body
{
"regular_hours": {
"start_date": "2021-01-01",
"schedules": [
{
"week": 1,
"day": "Monday",
"start": "09:00",
"end": "17:00",
"department_id": 1234,
"breaks": "12:00-13:00"
}
]
}
}
Headers
Content-Type: application/json
Body
{
"id": 123456,
"name": "Lenny Leonard",
"date_of_birth": "1955-05-12",
"employment_start_date": "1989-12-17",
"employment_end_date": "2019-06-01",
"employee_id": "LL1",
"passcode": "0456",
"department_ids": [],
"preferred_hours": 20,
"award_template_id": 990,
"award_tag_ids": [
3816
],
"report_department_id": 111,
"managed_department_ids": [
222
],
"active": true,
"enable_login": true,
"can_see_costs": true,
"email": "lenny.leonard@springfieldpowerplant.com",
"photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
"phone": "0404 123 123",
"normalised_phone": "+61404123123",
"salary": 1234.12,
"hourly_rate": 32.47,
"time_zone": "Australia/Brisbane",
"utc_offset": 36000,
"created_at": 1430715548
"part_time_fixed_hours": 20,
"expected_hours_in_pay_period": 38,
"days_overtime_averaged_over": 7,
"overtime_calculated_over_period_start": "2016-09-12",
"super_fund_membership": null,
"super_fund": null,
"bank_details": null,
"tax_declaration": null,
"qualifications": [],
"regular_hours": {
"start_date": "2021-01-01",
"schedules": [
{
"week": 1,
"day": "Monday",
"start": "09:00",
"end": "17:00",
"department_id": 1234,
"breaks": "12:00-13:00"
}
]
},
"updated_at": 1562272900
}
Update UserPUT/api/v2/users/{id}
This method requires the user
scope (see Scopes for more information).
If you plan to update wage information you will need the cost
scope. This includes the employee_id
field.
To set financial information, you will need the financial
scope.
Notes
-
To skip email validation when creating a user, use
skip_validation=true
. -
The UUID for uploading a file_id to a qualification can be found at the create temporary file endpoint.
-
If you are attempting to remove a userâs
department_id
s ormanaged_department_id
s, you should passnull
as part of your API call. There is an example in the sidebar. -
The API currently requires email addresses to be unique within an organisation. However, there is no guarantee that this restriction will exist in the future. If you are updating a userâs email via the API you should first
GET
a list of users and validate that the email youâre setting isnât already in use - do not depend on the API to validate this for you. -
Itâs not possible to remove a userâs passcode. If you pass
null
as a value for it, the userâs passcode will be regenerated. -
Updating a Tax File Number requires the
financial
scope. Valid values for a Tax File Number are 8 or 9 numeric characters, or an exemption:exempt_underage
|exempt_applied
|exempt_allowance
|exempt_blank
(TFN intentionally withheld). Only the current user can view their TFN via the API; that is, you can POST/PUT a TFN but cannot read it except for your own user record. If you POST/PUT an invalid TFN youâll get a validation error.
- id
number
(required) Example: 123456The id of the user
- skip_validation
boolean
(optional) Example: trueSkipâs checking if an employee already exists with this email address
Headers
Content-Type: application/json
Body
{
"id": 123456,
"name": "Lenny Leonard",
"date_of_birth": "1955-05-12",
"employment_start_date": "1989-12-17",
"employee_id": "LL1",
"passcode": "01234568975461",
"platform_role_ids": [
18,
19,
22
],
"department_ids": [
111
],
"preferred_hours": 20,
"award": {
"name": "Fast Food Industry",
"identifier": "MA000003",
"note": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_organisation_id` field instead."
},
"award_template_id": 990,
"award_template_organisation_id": 5624432,
"award_tag_ids": [
3816
],
"report_department_id": 111,
"managed_department_ids": [
222
],
"active": false,
"email": "lenny.leonard@springfieldpowerplant.com",
"photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
"phone": "0404 123 123",
"normalised_phone": "+61404123123",
"salary": 1234.12,
"hourly_rate": 32.47,
"time_zone": "Australia/Brisbane",
"utc_offset": 36000,
"part_time_fixed_hours": 20,
"expected_hours_in_pay_period": 38,
"days_overtime_averaged_over": 7,
"overtime_calculated_over_period_start": "2016-09-12",
"super_fund": {
"id": 1234,
"fund_name": "FUND NAME",
"product_name": "FUND PRODUCT",
"smsf": false,
"abn": 123456789
},
"super_fund_membership": {
"super_contribution_type": "arpa",
"trustee_director": false,
"member_number": "123ACB",
"employer_action_date": "2000-01-01T09:30:00+10:00",
"occupational_rating": "A1",
"super_fund_id": 1234,
"employer_preferred": 0,
"employer_default": 1,
"employer_generic": 2
},
"bank_details": {
"bsb": 60111,
"account_number": 12345678,
"account_name": 0
},
"address": {
"street_line_one": "742 Evergreen Terrace",
"street_line_two": null,
"city": "Springfield",
"state": "Oregon",
"country": "United States of America",
"postcode": "97475"
},
"tax_declaration": {
"previous_family_name": "Smith",
"tax_free_threshold": true,
"senior_tax_offset": false,
"zone_overseas_carer": false,
"student_loan": true,
"financial_supplement_debt": true,
"tax_code": true,
"employment_basis: full_time": "",
"tax_file_number": "123 456 789",
"uk_tax_year_status": "first_job / had_previous_job / second_job",
"uk_student_loan_plan": "plan_1 / plan_2 / both"
},
"onboarding_status": "not_applicable, pending, invited, in_progress, completed, invitation_failed",
"qualifications": [
{
"id": 12345,
"qualification_id": 1234,
"enabled": true,
"license_number": "ABC123",
"expires": "2012-10-20",
"in_training": false
}
],
"regular_hours": {
"start_date": "2021-01-01",
"schedules": {
"week": 1,
"day": "Monday",
"start": "09:00",
"end": "17:00",
"breaks": "12:00",
"department_id": 1234
}
},
"minimum_base_hours": 20,
"created_at": 1430715548,
"record_id": 532432,
"next_pay_group_id": 53242,
"last_synced_mobile_app": 1430715548,
"automatic_break_rule_set_id": 1430715548
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the user"
},
"name": {
"type": "string",
"description": "The user's name"
},
"date_of_birth": {
"type": "string",
"description": "The user's date of birth"
},
"employment_start_date": {
"type": "string",
"description": "The user's employment start date"
},
"employee_id": {
"type": "string",
"description": "The user's employee id, used for external systems"
},
"passcode": {
"type": "string",
"description": "The user's system passcode (used for clocking in and out)"
},
"platform_role_ids": {
"type": "array",
"description": "IDs of the user's roles (see Access & Roles)"
},
"department_ids": {
"type": "array",
"description": "The department (team) ids that the user is a member of"
},
"preferred_hours": {
"type": "number",
"description": "The preferred number of hours to be rostered each week"
},
"award": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the award"
},
"identifier": {
"type": "string",
"description": "The award's identifier (will be the award code for all modern awards)"
},
"note": {
"type": "string",
"description": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_organisation_id` field instead."
}
},
"required": [
"name"
],
"description": "Information about the user's award, null if user isn't on award"
},
"award_template_id": {
"type": "number",
"description": "The ID of the award template the user is on"
},
"award_template_organisation_id": {
"type": "number",
"description": "The internal ID of the award template the user is on"
},
"award_tag_ids": {
"type": "array",
"description": "The award tag ids that apply to the user"
},
"report_department_id": {
"type": "number",
"description": "The user's default team"
},
"managed_department_ids": {
"type": "array",
"description": "The department ids that this user manages"
},
"active": {
"type": "boolean",
"description": "Whether the user is active in the system"
},
"email": {
"type": "string",
"description": "The user's email"
},
"photo": {
"type": "string",
"description": "An avatar for the user"
},
"phone": {
"type": "string",
"description": "Phone number for the user"
},
"normalised_phone": {
"type": "string",
"description": "Phone number for user with international dialing code"
},
"salary": {
"type": "number",
"description": "The weekly salary of the user, if `show_wages=true` parameter is set"
},
"hourly_rate": {
"type": "number",
"description": "The hourly rate of the user, if `show_wages=true` parameter is set, will not show if the salary exists"
},
"time_zone": {
"type": "string",
"description": "The user's time zone"
},
"utc_offset": {
"type": "number",
"description": "The user's time zone's UTC offset"
},
"part_time_fixed_hours": {
"type": "number",
"description": "For part time staff, can be used to configure when overtime starts to apply"
},
"expected_hours_in_pay_period": {
"type": "number",
"description": "readonly: for salaried staff, defines expected number of hours worked per pay period"
},
"days_overtime_averaged_over": {
"type": "number",
"description": "date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run"
},
"overtime_calculated_over_period_start": {
"type": "string",
"description": "date from which overtime averaging periods should commence"
},
"super_fund": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "the unique ID of the employees fund"
},
"fund_name": {
"type": "string",
"description": "the name of the fund"
},
"product_name": {
"type": "string",
"description": "the name of the fund product"
},
"smsf": {
"type": "boolean",
"description": "is the fund a self managed fund"
},
"abn": {
"type": "number",
"description": "the number of the fund"
}
},
"description": "information about the employees super fund"
},
"super_fund_membership": {
"type": "object",
"properties": {
"super_contribution_type": {
"type": "string",
"description": "the type of the employees super contribution"
},
"trustee_director": {
"type": "boolean",
"description": "is the employees super fund directed by a trustee?"
},
"member_number": {
"type": "string",
"description": "the membership number of the employees super fund"
},
"employer_action_date": {
"type": "string",
"description": "the action date of the super fund by the employer"
},
"occupational_rating": {
"type": "string",
"description": "the occupational rating of the employees super fund"
},
"super_fund_id": {
"type": "number",
"description": "the record ID of the employees super fund"
},
"employer_preferred": {
"type": "number",
"description": "indication of an employers preferred super fund"
},
"employer_default": {
"type": "number",
"description": "indication of an employers default super fund"
},
"employer_generic": {
"type": "number",
"description": "indication of an employers generic super fund"
}
},
"required": [
"super_fund_id",
"employer_preferred",
"employer_default",
"employer_generic"
],
"description": "information about the employees super fund membership"
},
"bank_details": {
"type": "object",
"properties": {
"bsb": {
"type": "number",
"description": "the bsb number of the employees bank account"
},
"account_number": {
"type": "number",
"description": "the account number of the employees bank account"
},
"account_name": {
"type": "number",
"description": "the account name of the employees bank account"
}
},
"required": [
"bsb",
"account_number",
"account_name"
],
"description": "the bank details of the employee"
},
"address": {
"type": "object",
"properties": {
"street_line_one": {
"type": "string"
},
"street_line_two": {
"type": [
"string",
"null"
],
"description": "Apartment, Suite, etc"
},
"city": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"country": {
"type": "string"
},
"postcode": {
"type": [
"string",
"null"
]
}
},
"required": [
"street_line_two"
]
},
"tax_declaration": {
"type": "object",
"properties": {
"previous_family_name": {
"type": "string",
"description": "the previous family name of the employee"
},
"tax_free_threshold": {
"type": "boolean",
"description": "is the employee under the tax free threshold?"
},
"senior_tax_offset": {
"type": "boolean",
"description": "can the employee claim a senior tax offset?"
},
"zone_overseas_carer": {
"type": "boolean",
"description": "can the employee claim a zone or overseas tax offset?"
},
"student_loan": {
"type": "boolean",
"description": "does the employee have a student loan?"
},
"financial_supplement_debt": {
"type": "boolean",
"description": "does the employee have a financial supplement debt?"
},
"tax_code": {
"type": "boolean",
"description": "the employees code for tax services"
},
"employment_basis: full_time": {
"type": "string",
"description": "the employment type the employee has specified on their TFN declaration (full_time, part_time, casual, labour_hire, super_or_annuity)"
},
"tax_file_number": {
"type": "string",
"description": "The tax file number for the user. This property only exists when using the `financial` scope is in use."
},
"uk_tax_year_status": {
"type": "string",
"description": "(uk residents) the stage of the employees career"
},
"uk_student_loan_plan": {
"type": "string",
"description": "(uk residents) the tax scheme for the employee"
}
},
"description": "the tax declaration information of the employee"
},
"onboarding_status": {
"type": "string",
"description": "the status of the employee onboarding progress"
},
"qualifications": {
"type": "array",
"description": "Information about qualifications the user holds, if Qualifications are enabled"
},
"regular_hours": {
"type": "object",
"properties": {
"start_date": {
"type": "string",
"description": "the anchor date of the regular hours"
},
"schedules": {
"type": "object",
"properties": {
"week": {
"type": "number",
"description": "which week does the schedule fall in"
},
"day": {
"type": "string",
"description": "what day is the schedule for"
},
"start": {
"type": "string",
"description": "what time does the schedule start"
},
"end": {
"type": "string",
"description": "what time does the schedule finish"
},
"breaks": {
"type": "string",
"description": "13:00 (string) - what breaks apply to this schedule"
},
"department_id": {
"type": "number",
"description": "the id of the department the schedule is for"
}
},
"required": [
"week",
"day",
"start",
"end"
],
"description": "information about the schedules that make up the regular hours of work"
}
},
"required": [
"start_date"
],
"description": "information about the employees regular hours of work"
},
"minimum_base_hours": {
"type": "number",
"description": "minimum required hours for this employee"
},
"created_at": {
"type": "number",
"description": "When the user's Tanda profile was created"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
},
"next_pay_group_id": {
"type": "number",
"description": "the ID for the pay group of the user's next timesheet"
},
"last_synced_mobile_app": {
"type": "number",
"description": "Read only: when the user last opened the mobile app."
},
"automatic_break_rule_set_id": {
"type": "number",
"description": "Read only: the ID for the user's automatic break rule set."
}
},
"required": [
"id",
"name",
"passcode",
"platform_role_ids",
"department_ids",
"preferred_hours",
"award_tag_ids",
"active",
"utc_offset",
"created_at"
]
}
Delete UserDELETE/api/v2/users/{id}
This endpoint will just mark the user as inactive and return the user, this effectively does the same as the deactivate user request above.
This method requires the user
scope (see Scopes for more information).
- id
number
(required) Example: 654321The id of the user
Invite Users ¶
Headers
Content-Type: application/json
Invite UserPOST/api/v2/users/{id}/invite
This endpoint takes a user ID and sends that user an email invite to use Tanda.
This method requires the user
scope (see Scopes for more information).
It also requires the following prerequisites to work
-
User must exist
-
You must be able to manage the User
-
The User must have an email and it must be valid
-
The User must not have already signed up
-
The User must not already have a valid invitation
Failure to meet these pre reqs will result in a returned 400
, 403
or 404
.
Otherwise a 201 CREATED
will be returned
- id
number
(required) Example: 654321The id of the user
Invite New Users for Onboarding ¶
Headers
Content-Type: application/json
Body
{
"name": "Eddard Sheppard",
"email": "carl.carlson@springfieldpowerplant.com",
"phone": "+61408123654",
"custom_message": "Welcome to the company!"
}
Headers
Content-Type: application/json
Invite User for OnboardingPOST/api/v2/users/onboarding
If you are using Tandaâs employee onboarding, you can use this endpoint to automatically invite new staff to be onboarded. It takes a name and email, and optionally a phone number and custom message, and sends the employee a link to a form where they can add their details.
Invite Existing User for Onboarding ¶
Headers
Content-Type: application/json
Invite Existing User for OnboardingPOST/api/v2/users/{id}/onboard
If you have created a new user with the Create User
endpoint and are using Tandaâs employee onboarding, you can use this endpoint to trigger the onboarding process for the new user.
This endpoint is intended only for brand new users created from the Create User
endpoint.
If the user has already been invited to Tanda you cannot use this endpoint.
- id
number
(required) Example: 123456The id of the user
Clocked In Users ¶
Headers
Content-Type: application/json
Body
[
{
"user_id": 123456,
"shift_id": 1337
}
]
Get Clocked In UsersGET/api/v2/users/clocked_in
This endpoint is deprecated. You should use /shifts/active instead.
Gets a list of staff who are currently at work. Essentially this looks for valid shifts that have a start time but no end time. The shiftâs ID is also returned.
This method requires the user
and timesheet
scopes (see Scopes for more information).
- updated_after
number
(optional) Example: 1451570400Time filter to find recently created or modified users
User Versions ¶
Headers
Content-Type: application/json
Body
[
{
"version_id": 123456,
"time": 1459209907,
"event": "update",
"author": {
"id": 123456,
"name": "API v2"
},
"item_id": 1235435,
"item_type": "\"User\"",
"changes": [
{
"field": "name",
"previous": "Lenny L Leonard",
"updated": "Lenny Leonard"
},
{
"field": "preferred_hours",
"previous": 28,
"updated": 20
}
]
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Alternate Rates ¶
Alternate Rates are user level assigned hourly rates based on team.
Note: employment_contract_id
is an optional param for all Alternate Rate endpoints.
If no employment_contract_id
is included, the endpoint will refrence the latest employment contract.
These endpoint actions require Allow Additional Rates
to be enabled under your organisationâs feature management settings.
Headers
Content-Type: application/json
Body
{
"alternate_rates": [
{
"department_id": "123456",
"hourly_rate": "20.01"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"alternate_rates": {
"type": "array"
}
}
}
Headers
Content-Type: application/json
Body
{
"id": 123456,
"employment_contract_id": 987654,
"alternate_rates": [
{"department_id": 987654, "hourly_rate": 20.01},
{"department_id": 987653, "hourly_rate": 7.99},
{"department_id": 987652, "hourly_rate": 8},
]
}
Headers
Content-Type: application/json
Body
{
"alternate_rates": [
{
"department_id": "123456",
"hourly_rate": "20.01"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"alternate_rates": {
"type": "array"
}
}
}
Update Alternate RatesPUT/api/v2/users/{id}/alternate_rates
To Create and update a userâs alternate rate(s) data, include the userâs id
and alternate_rates
array.
Note: Alternate rates can only be assigned to teams that are scope to the user. Also only one alternate rate can be assigned per team and the rate must be different from the userâs base hourly rate.
This method requires the user
scope (see Scopes for more information).
Successfully using this endpoint will overwrite all existing alternate rates for the user.
- id
number
(required) Example: 123456The ID of an user
- employment_contract_id
number
(optional) Example: 162456The ID of an userâs employment contract
- alternate_rates
array
(required)- object
object
(required) Example: {"department_id": 987654, "hourly_rate": 20.01}department_id: (required, number) - The ID of a department/team the user works in hourly_rate: (required, number) - The hourly rate this user will be paid for working in this team
Headers
Content-Type: application/json
Body
{
"message": "Successfully deleted all alternate rates"
}
Delete Alternate RatesDELETE/api/v2/users/{id}/alternate_rates
This method requires the user
scope (see Scopes for more information).
This method will delete ALL alternate rates for the user.
- id
number
(required) Example: 162456The ID of an user
- employment_contract_id
number
(optional) Example: 162456The ID of an userâs employment contract
Employee Pay Fields ¶
There are no special system permissions required.
To access most of these endpoints, you will need the cost scope for your api token.
The user the token is generated for must also have custom permissions edit_wages
on for the staff members they wish to edit pay fields for.
Employee Payfields ¶
Headers
Content-Type: application/json
Body
[
{
"id": 12345,
"reason_for_change": "Pay Fields Update Jan 2022",
"from_date": "1970-1-1",
"to_date": "1970-1-1",
"hourly_rate": 0,
"yearly_salary": 60000,
"user_id": 12345,
"award_template_organisation_id": 12345
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get Payfields For All UsersGET/api/v2/user_pay_fields
Retrieves all pay field objects belonging to the users of the organisation. This endpoint can be paginated.
This method requires the cost
scope (see Scopes for more information).
- page
number
(optional) Example: 1The page number for your pay fields list
- page_size
number
(optional) Example: 50The number of pay field objects retrieved per page. The maximum is 100 per page.
Get Payfields By Known ID ¶
Headers
Content-Type: application/json
Body
{
"id": 12345,
"reason_for_change": "Pay Fields Update Jan 2022",
"from_date": "1970-1-1",
"to_date": "1970-1-1",
"hourly_rate": 0,
"yearly_salary": 60000,
"user_id": 12345,
"award_template_organisation_id": 12345
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the payfield"
},
"reason_for_change": {
"type": "string",
"description": "The name of a pay field change, usually specifying the reason."
},
"from_date": {
"type": "string",
"description": "The effective date that the grouping of payfields applies after"
},
"to_date": {
"type": "string",
"description": "The effective date that the grouping of payfields applies until"
},
"hourly_rate": {
"type": "number",
"description": "Hourly rate of the employee for the effective date"
},
"yearly_salary": {
"type": "number",
"description": "Yearly Salary of the employee for the effective date"
},
"user_id": {
"type": "number",
"description": "The id of the user these payfields apply to"
},
"award_template_organisation_id": {
"type": "number",
"description": "The id of the award template organisation that is attached to this user"
}
}
}
Employee Payfields By User ¶
Headers
Content-Type: application/json
Body
[
{
"id": 12345,
"reason_for_change": "Pay Fields Update Jan 2022",
"from_date": "1970-1-1",
"to_date": "1970-1-1",
"hourly_rate": 0,
"yearly_salary": 60000,
"user_id": 12345,
"award_template_organisation_id": 12345
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get Payfields By UserGET/api/v2/user_pay_fields/user/{user_id}
This endpoint takes a user ID and returns an array of all the users pay field objects.
This method requires the cost
scope (see Scopes for more information).
It also requires the following prerequisites to work
- User must exist
Failure to meet these pre reqs will result in a returned 400
, 403
or 404
.
Otherwise an array of UserPayFieldData
will be returned
- user_id
number
(required) Example: 654321The id of the user
Verify Employee Payfields By User ¶
Headers
Content-Type: application/json
Body
[
{
"id": 12345,
"from": {
"date": "2022-01-01",
"valid": true
},
"to": {
"date": "2023-01-01",
"valid": true
},
"errors": [
"Something is wrong",
"Something else is wrong"
]
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Verify Payfields By UserGET/api/v2/user_pay_fields/user/{user_id}/verify
This endpoint conducts a check on a specific userâs pay field records. The check will ensure correct sequence of dates, and return any errors that might be evident.
This method requires the cost
scope (see Scopes for more information).
- user_id
number
(required) Example: 654321The id of the user
Updating Pay Fields ¶
Headers
Content-Type: application/json
Body
{
"id": 54321,
"user_id": 654321,
"from_date": "1970-1-1",
"to_date": "2020-1-1",
"hourly_rate": 0,
"award_tags": "Casual,Level 1",
"yearly_salary": 60000,
"award_template_organisation_id": 12345
}
Headers
Content-Type: application/json
Body
{
"id": 12345,
"reason_for_change": "Pay Fields Update Jan 2022",
"from_date": "1970-1-1",
"to_date": "1970-1-1",
"hourly_rate": 0,
"yearly_salary": 60000,
"user_id": 12345,
"award_template_organisation_id": 12345
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the payfield"
},
"reason_for_change": {
"type": "string",
"description": "The name of a pay field change, usually specifying the reason."
},
"from_date": {
"type": "string",
"description": "The effective date that the grouping of payfields applies after"
},
"to_date": {
"type": "string",
"description": "The effective date that the grouping of payfields applies until"
},
"hourly_rate": {
"type": "number",
"description": "Hourly rate of the employee for the effective date"
},
"yearly_salary": {
"type": "number",
"description": "Yearly Salary of the employee for the effective date"
},
"user_id": {
"type": "number",
"description": "The id of the user these payfields apply to"
},
"award_template_organisation_id": {
"type": "number",
"description": "The id of the award template organisation that is attached to this user"
}
}
}
Update PayfieldPUT/api/v2/user_pay_fields/{id}
Update a specific param for a single payfield entry.
This method requires a id
to be given.
This method requires the cost
scope (see Scopes for more information).
You do not have to provide every pay field in the request body.
The ones you do provide will form the new value of the updated pay field object.
The only limitation to updating behaviour is - you cannot update a userâs first pay field objectâs from_date
.
You can identify which pay field object is the first by itâs from date. This should be represented as start
.
- id
number
(required) Example: 54321The ID of payfield entry.
Creating Pay Fields ¶
Headers
Content-Type: application/json
Body
{
"user_id": 654321,
"from_date": "1970-1-1",
"to_date": "2020-1-1",
"hourly_rate": 0,
"award_tags": "Casual,Level 1",
"yearly_salary": 60000,
"award_template_organisation_id": 12345
}
Headers
Content-Type: application/json
Body
{
"id": 12345,
"reason_for_change": "Pay Fields Update Jan 2022",
"from_date": "1970-1-1",
"to_date": "1970-1-1",
"hourly_rate": 0,
"yearly_salary": 60000,
"user_id": 12345,
"award_template_organisation_id": 12345
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the payfield"
},
"reason_for_change": {
"type": "string",
"description": "The name of a pay field change, usually specifying the reason."
},
"from_date": {
"type": "string",
"description": "The effective date that the grouping of payfields applies after"
},
"to_date": {
"type": "string",
"description": "The effective date that the grouping of payfields applies until"
},
"hourly_rate": {
"type": "number",
"description": "Hourly rate of the employee for the effective date"
},
"yearly_salary": {
"type": "number",
"description": "Yearly Salary of the employee for the effective date"
},
"user_id": {
"type": "number",
"description": "The id of the user these payfields apply to"
},
"award_template_organisation_id": {
"type": "number",
"description": "The id of the award template organisation that is attached to this user"
}
}
}
Create PayfieldPOST/api/v2/user_pay_fields
user_id
and from_date
are all that are required in the request body to create a new payfield entry.
If no to_date
is provided as a parameter, this payfield record will apply forever.
Managing Multiple Pay Fields ¶
Headers
Content-Type: application/json
Body
{
"pay_fields": [
{
"id": 654321,
"regular_hours": "Pay Increase Jan 2022",
"from_date": "2020-1-1",
"to_date": "2021-1-1",
"hourly_rate": 0,
"award_tags": "Casual,Level 1",
"yearly_salary": 60000,
"award_template_organisation_id": 12345
}
]
}
Headers
Content-Type: application/json
Body
[
{
"id": 12345,
"reason_for_change": "Pay Fields Update Jan 2022",
"from_date": "1970-1-1",
"to_date": "1970-1-1",
"hourly_rate": 0,
"yearly_salary": 60000,
"user_id": 12345,
"award_template_organisation_id": 12345
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Create & Update Multiple Pay Fields For A UserPOST/api/v2/user_pay_fields/{user_id}
This endpoint can be used through a POST request to manage a specific userâs pay field objects in bulk.
This method requires a user_id
to be given.
This method requires the cost
scope (see Scopes for more information).
You do not have to provide every pay field in the request body. The ones you do provide will form the new value of the updated pay field object.
The only limitation to updating behaviour is - you cannot update a userâs first pay field objectâs from_date
.
You can identify which pay field object is the first by itâs from date. This should be represented as start
.
If you provide an id
to a pay field object in the array, the request will look for the existing record and update the corresponding fields.
You must provide a valid id
in doing so. The whole request will fail there is a non-existent pay field id
.
If you do not provide an id
to a pay field object in the array, the request will create a new pay field record for the user.
It will create the record with the provided fields.
- user_id
number
(required) Example: 654321The ID of the user
Deleting Pay Fields ¶
Headers
Content-Type: application/json
Body
{
"id": 54321
}
Headers
Content-Type: application/json
Delete Payfield By IdDELETE/api/v2/user_pay_fields/{id}
Delete a specific payfield entry.
This method requires a id
to be given.
You cannot remove the earliest payfield record; There should ALWAYS be a single payfield record. If this isnât the case, costing and award interpretation will not work as intended.
This method requires the cost
scope (see Scopes for more information).
- id
number
(required) Example: 54321The ID of payfield entry.
Locations ¶
Admins and general managers can CRUD locations. Team managers can read locations which contain teams they manage.
Location List ¶
Headers
Content-Type: application/json
Body
[
{
"id": 111,
"name": "Springfield",
"short_name": "S",
"latitude": -27.459687,
"longitude": 153.032108,
"address": "Springfield Powerplant Reactors",
"time_zone": "Australia/Brisbane",
"utc_offset": 36000,
"public_holiday_regions": [
"au",
"au_qld"
],
"specific_holiday_dates": [
{
"date": "2016-08-08",
"from": 8,
"to": 17
}
],
"business_day_cutoff": 5,
"bunsiness_hours": [
{
"weekday": 0,
"start": "8:30",
"finish": "17:00"
}
],
"record_id": 532432
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get LocationsGET/api/v2/locations{?updated_after,platform,show_business_hours}
This method requires the department
scope (see Scopes for more information).
For business hours data, weekday â0â is Sunday, â1â is Monday, with the rest following that order till â6â which ends on Saturday.
- updated_after
number
(optional) Example: 1451570400Time filter to find recently created or modified locations
- platform
boolean
(optional) Example: falseIf true, Platform data will be returned (defaults to false).
- show_business_hours
boolean
(optional) Example: falseIf true, business hours will be returned (defaults to false).
Headers
Content-Type: application/json
Body
{
"name": "Springfield",
"short_name": "S",
"latitude": -27.467004,
"longitude": 153.025453,
"address": "Springfield Powerplant Logistics Centre",
"public_holiday_regions": [
"au"
],
"specific_holiday_dates": [
{
"date": "2016-03-14"
},
{
"date": "2016-08-08",
"from": 12,
"to": 17
}
]
}
Headers
Content-Type: application/json
Body
{
"id": 801,
"name": "Springfield",
"short_name": "S",
"latitude": -27.467004,
"longitude": 153.025453,
"address": "Springfield Powerplant Logistics Centre",
"time_zone": null,
"organisation_id": 12,
"public_holiday_regions": [
"au"
],
"specific_holiday_dates": [
{
"date": "2016-03-14"
},
{
"date": "2016-08-08",
"from": 12,
"to": 17
}
],
"business_day_cutoff": 0
}
Headers
Content-Type: application/json
Body
{
"name": "Springfield"
}
Headers
Content-Type: application/json
Body
{
"id": 801,
"name": "Springfield",
"short_name": null,
"latitude": null,
"longitude": null,
"address": null,
"time_zone": null,
"organisation_id": 12,
"public_holiday_regions": [],
"specific_holiday_dates": [],
"business_day_cutoff": 0
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the location"
},
"name": {
"type": "string",
"description": "The name of the location"
},
"short_name": {
"type": "string",
"description": "The abbreviated form of the location's name"
},
"latitude": {
"type": "number",
"description": "The latitude of the location"
},
"longitude": {
"type": "number",
"description": "The longitude of the location"
},
"address": {
"type": "string",
"description": "Address of the location"
},
"time_zone": {
"type": "string",
"description": "The location's time zone"
},
"utc_offset": {
"type": "number",
"description": "The location's time zone's UTC offset"
},
"public_holiday_regions": {
"type": "array",
"description": "Public holiday regions (see Locations section for list of options)"
},
"specific_holiday_dates": {
"type": "array",
"description": "The dates and times of specific holidays for the location"
},
"business_day_cutoff": {
"type": "number",
"description": "The hour of the day before which data should be treated as being part of the previous day. eg 5 indicates that data from before 5am is part of the previous business day."
},
"bunsiness_hours": {
"type": "array",
"description": "The business hours of the location"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
}
},
"required": [
"id",
"name",
"time_zone",
"utc_offset"
]
}
Create LocationPOST/api/v2/locations
Use this endpoint to create a Location object. Location objects should have addresses, but the field is not mandatory - you can create a Location with just a name (though it will not be as useful).
If an address
is provided, latitude
and longitude
are also required.
This method requires the department
scope (see Scopes for more information).
Location ¶
Headers
Content-Type: application/json
Body
{
"id": 111,
"name": "Springfield",
"short_name": "S",
"latitude": -27.459687,
"longitude": 153.032108,
"address": "Springfield Powerplant Reactors",
"time_zone": "Australia/Brisbane",
"utc_offset": 36000,
"public_holiday_regions": [
"au",
"au_qld"
],
"specific_holiday_dates": [
{
"date": "2016-08-08",
"from": 8,
"to": 17
}
],
"business_day_cutoff": 5,
"bunsiness_hours": [
{
"weekday": 0,
"start": "8:30",
"finish": "17:00"
}
],
"record_id": 532432
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the location"
},
"name": {
"type": "string",
"description": "The name of the location"
},
"short_name": {
"type": "string",
"description": "The abbreviated form of the location's name"
},
"latitude": {
"type": "number",
"description": "The latitude of the location"
},
"longitude": {
"type": "number",
"description": "The longitude of the location"
},
"address": {
"type": "string",
"description": "Address of the location"
},
"time_zone": {
"type": "string",
"description": "The location's time zone"
},
"utc_offset": {
"type": "number",
"description": "The location's time zone's UTC offset"
},
"public_holiday_regions": {
"type": "array",
"description": "Public holiday regions (see Locations section for list of options)"
},
"specific_holiday_dates": {
"type": "array",
"description": "The dates and times of specific holidays for the location"
},
"business_day_cutoff": {
"type": "number",
"description": "The hour of the day before which data should be treated as being part of the previous day. eg 5 indicates that data from before 5am is part of the previous business day."
},
"bunsiness_hours": {
"type": "array",
"description": "The business hours of the location"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
}
},
"required": [
"id",
"name",
"time_zone",
"utc_offset"
]
}
Headers
Content-Type: application/json
Body
{
"name": "Shelbyville",
"short_name": "S",
"latitude": -27.467004,
"longitude": 153.025453
}
Headers
Content-Type: application/json
Body
{
"id": 111,
"name": "Shelbyville",
"short_name": "S",
"latitude": -27.459687,
"longitude": 153.032108,
"address": "Springfield Powerplant Reactors",
"time_zone": "Australia/Brisbane",
"utc_offset": 36000,
"public_holiday_regions": [
"au",
"au_qld"
],
"specific_holiday_dates": [
{
"date": "2016-08-08",
"from": 8,
"to": 17
}
],
"business_day_cutoff": 5,
"bunsiness_hours": [
{
"weekday": 0,
"start": "8:30",
"finish": "17:00"
}
],
"record_id": 532432
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the location"
},
"name": {
"type": "string",
"description": "The name of the location"
},
"short_name": {
"type": "string",
"description": "The abbreviated form of the location's name"
},
"latitude": {
"type": "number",
"description": "The latitude of the location"
},
"longitude": {
"type": "number",
"description": "The longitude of the location"
},
"address": {
"type": "string",
"description": "Address of the location"
},
"time_zone": {
"type": "string",
"description": "The location's time zone"
},
"utc_offset": {
"type": "number",
"description": "The location's time zone's UTC offset"
},
"public_holiday_regions": {
"type": "array",
"description": "Public holiday regions (see Locations section for list of options)"
},
"specific_holiday_dates": {
"type": "array",
"description": "The dates and times of specific holidays for the location"
},
"business_day_cutoff": {
"type": "number",
"description": "The hour of the day before which data should be treated as being part of the previous day. eg 5 indicates that data from before 5am is part of the previous business day."
},
"bunsiness_hours": {
"type": "array",
"description": "The business hours of the location"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
}
},
"required": [
"id",
"name",
"time_zone",
"utc_offset"
]
}
Headers
Content-Type: application/json
Body
{
"business_hours": [
{ "weekday": 0, "start": "08:30", "finish": "17:00" },
{ "weekday": 1, "start": "6am", "finish": "2pm" },
{ "weekday": 1, "start": "3pm", "finish": "8pm" },
{ "weekday": 2, "start": "11:30", "finish": "11:45pm" },
]
}
Headers
Content-Type: application/json
Body
{
"id": 111,
"name": "Springfield",
"short_name": "S",
"latitude": -27.459687,
"longitude": 153.032108,
"address": "Springfield Powerplant Reactors",
"time_zone": "Australia/Brisbane",
"utc_offset": 36000,
"public_holiday_regions": [
"au",
"au_qld"
],
"specific_holiday_dates": [
{
"date": "2016-08-08",
"from": 8,
"to": 17
}
],
"business_day_cutoff": 5,
"bunsiness_hours": [
{
"weekday": 0,
"start": "08:30",
"finish": "17:00"
},
{
"weekday": 1,
"start": "06:00",
"finish": "14:00"
},
{
"weekday": 1,
"start": "15:00",
"finish": "20:00"
},
{
"weekday": 2,
"start": "11:30",
"finish": "23:45"
}
],
"record_id": 532432
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the location"
},
"name": {
"type": "string",
"description": "The name of the location"
},
"short_name": {
"type": "string",
"description": "The abbreviated form of the location's name"
},
"latitude": {
"type": "number",
"description": "The latitude of the location"
},
"longitude": {
"type": "number",
"description": "The longitude of the location"
},
"address": {
"type": "string",
"description": "Address of the location"
},
"time_zone": {
"type": "string",
"description": "The location's time zone"
},
"utc_offset": {
"type": "number",
"description": "The location's time zone's UTC offset"
},
"public_holiday_regions": {
"type": "array",
"description": "Public holiday regions (see Locations section for list of options)"
},
"specific_holiday_dates": {
"type": "array",
"description": "The dates and times of specific holidays for the location"
},
"business_day_cutoff": {
"type": "number",
"description": "The hour of the day before which data should be treated as being part of the previous day. eg 5 indicates that data from before 5am is part of the previous business day."
},
"bunsiness_hours": {
"type": "array",
"description": "The business hours of the location"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
}
},
"required": [
"id",
"name",
"time_zone",
"utc_offset"
]
}
Update LocationPUT/api/v2/locations/{id}
This method requires the department
scope (see Scopes for more information).
Updating a locationâs business hours
For business hours data, weekday â0â is Sunday, â1â is Monday, with the rest following that order till â6â which ends on Saturday. Setting a config for a certain weekday through the API will override any existing business hours for that weekday, the rest of the week will stay the same. You can update multiple days at the same time with one request.
- id
number
(required) Example: 111The id of the location
Headers
Content-Type: application/json
Location Versions ¶
Headers
Content-Type: application/json
Body
[
{
"version_id": 123456,
"time": 1459209907,
"event": "update",
"author": {
"id": 123456,
"name": "API v2"
},
"item_id": 1235435,
"item_type": "\"Location\"",
"changes": [
{
"field": "name",
"previous": "Spring field",
"updated": "Springfield"
},
{
"field": "longitude",
"previous": 153.032108,
"updated": 100.500169
}
]
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get Location VersionsGET/api/v2/locations/{id}/versions
This method requires the department
scope (see Scopes for more information).
- id
number
(required) Example: 111The id of the location
- updated_after
number
(optional) Example: 1451570400Time filter to find recently created or modified location versions
Teams (Departments) ¶
Departments are often referred to as Teams inside Tanda. Teams belong to a Location.
Department managers can read and update information about the departments they manage. Admins can CRUD departments. Employees can read the departments that they belong to, with a subset of fields (see below)
The department group / team group Feature needs to be enabled before you can access this field. The assisting teams Feature needs to be enabled before you can access this field.
Team List ¶
Body
[
{
"id": 808,
"location_id": 111,
"name": "Waiters",
"export_name": "WGB",
"colour": "#FBB829",
"staff": [
1,
2,
123456
],
"managers": [
4,
5
],
"associated_tags": [
"Level 2",
"Level 3 HD"
],
"qualifications": [
1234,
4321
],
"assisting_team_ids": [
1234,
4321
],
"team_group": "Front of House",
"record_id": 532432
}
]
Schema
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the team"
},
"location_id": {
"type": "number",
"description": "The id of the team's location"
},
"name": {
"type": "string",
"description": "The name of the team"
},
"export_name": {
"type": "string",
"description": "30 (string) - The payroll export name of the team (if different to the name)"
},
"colour": {
"type": "string",
"description": "The team's colour"
},
"staff": {
"type": "array",
"items": {
"type": "number"
},
"description": "The user ids of the staff in the team"
},
"managers": {
"type": "array",
"items": {
"type": "number"
},
"description": "The user ids of the managers of the team"
},
"associated_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags automatically assigned to shifts worked in this team"
},
"qualifications": {
"type": "array",
"items": {
"type": "number"
},
"description": "The required qualifications to work in this team"
},
"assisting_team_ids": {
"type": "array",
"items": {
"type": "number"
},
"description": "The teams that will count toward this team's requirements on the roster"
},
"team_group": {
"type": "string",
"description": "A group of teams for rostering or reporting"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
}
},
"required": [
"id",
"location_id",
"name"
]
},
"$schema": "http://json-schema.org/draft-04/schema#"
}
Headers
Content-Type: application/json
Body
[
{
"id": 608,
"name": "Waiters",
"location_id": 111,
"colour": "#FBB830"
}
]
Get TeamsGET/api/v2/departments
This method requires the department
scope (see Scopes for more information).
- updated_after
number
(optional) Example: 1451570400Time filter to find recently created or modified teams
- platform
boolean
(optional) Example: falseIf true, Platform data will be returned (defaults to false).
- page
number
(optional) Example: 1The page number for your teams list
- page_size
number
(optional) Example: 50The number of teams retrieved per page. The maximum is 100 teams per page.
Headers
Content-Type: application/json
Body
{
"name": "Waiters",
"location_id": 111,
"export_name": "WGB-32",
"colour": "#FBB830",
"team_group": "Front of House"
}
Headers
Content-Type: application/json
Body
{
"id": 809,
"location_id": "111",
"name": "Waiters",
"export_name": "WGB",
"colour": "#FBB830",
"staff": [],
"managers": [],
"associated_tags": [
"Level 2",
"Level 3 HD"
],
"qualifications": [
1234,
4321
],
"assisting_team_ids": [],
"team_group": "Front of House",
"record_id": 532432
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the team"
},
"location_id": {
"type": "string",
"description": "The id of the team's location"
},
"name": {
"type": "string",
"description": "The name of the team"
},
"export_name": {
"type": "string",
"description": "32"
},
"colour": {
"type": "string",
"description": "The team's colour"
},
"staff": {
"description": "The user ids of the staff in the team"
},
"managers": {
"description": "The user ids of the managers of the team"
},
"associated_tags": {
"type": "array",
"description": "Tags automatically assigned to shifts worked in this team"
},
"qualifications": {
"type": "array",
"description": "The required qualifications to work in this team"
},
"assisting_team_ids": {
"description": "The teams that will count toward this team's requirements on the roster"
},
"team_group": {
"type": "string",
"description": "A group of teams for rostering or reporting"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
}
},
"required": [
"id",
"location_id",
"name"
]
}
Headers
Content-Type: application/json
Body
{
"name": "Waiters",
"location_id": "111",
}
Headers
Content-Type: application/json
Body
{
"id": 809,
"location_id": 111,
"name": "Waiters",
"export_name": null,
"colour": null,
"staff": [],
"managers": []
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the team"
},
"location_id": {
"type": "number",
"description": "The id of the team's location"
},
"name": {
"type": "string",
"description": "The name of the team"
},
"export_name": {
"type": "string",
"description": "30 (string) - The payroll export name of the team (if different to the name)"
},
"colour": {
"type": "string",
"description": "The team's colour"
},
"staff": {
"type": "array",
"description": "The user ids of the staff in the team"
},
"managers": {
"type": "array",
"description": "The user ids of the managers of the team"
},
"associated_tags": {
"type": "array",
"description": "Tags automatically assigned to shifts worked in this team"
},
"qualifications": {
"type": "array",
"description": "The required qualifications to work in this team"
},
"assisting_team_ids": {
"type": "array",
"description": "The teams that will count toward this team's requirements on the roster"
},
"team_group": {
"type": "string",
"description": "A group of teams for rostering or reporting"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
}
},
"required": [
"id",
"location_id",
"name"
]
}
Team ¶
Headers
Content-Type: application/json
Body
{
"id": 808,
"location_id": 111,
"name": "Waiters",
"export_name": "WGB",
"colour": "#FBB829",
"staff": [
1,
2,
123456
],
"managers": [
4,
5
],
"associated_tags": [
"Level 2",
"Level 3 HD"
],
"qualifications": [
1234,
4321
],
"assisting_team_ids": [
1234,
4321
],
"team_group": "Front of House",
"record_id": 532432
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the team"
},
"location_id": {
"type": "number",
"description": "The id of the team's location"
},
"name": {
"type": "string",
"description": "The name of the team"
},
"export_name": {
"type": "string",
"description": "30 (string) - The payroll export name of the team (if different to the name)"
},
"colour": {
"type": "string",
"description": "The team's colour"
},
"staff": {
"type": "array",
"description": "The user ids of the staff in the team"
},
"managers": {
"type": "array",
"description": "The user ids of the managers of the team"
},
"associated_tags": {
"type": "array",
"description": "Tags automatically assigned to shifts worked in this team"
},
"qualifications": {
"type": "array",
"description": "The required qualifications to work in this team"
},
"assisting_team_ids": {
"type": "array",
"description": "The teams that will count toward this team's requirements on the roster"
},
"team_group": {
"type": "string",
"description": "A group of teams for rostering or reporting"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
}
},
"required": [
"id",
"location_id",
"name"
]
}
Headers
Content-Type: application/json
Body
{
"name": "Kitchen Staff"
}
Headers
Content-Type: application/json
Body
{
"id": 808,
"location_id": 111,
"name": "Kitchen Staff",
"export_name": "WGB",
"colour": "#FBB829",
"staff": [
1,
2,
123456
],
"managers": [
4,
5
],
"associated_tags": [
"Level 2",
"Level 3 HD"
],
"qualifications": [
1234,
4321
],
"assisting_team_ids": [
1234,
4321
],
"team_group": "Front of House",
"record_id": 532432
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the team"
},
"location_id": {
"type": "number",
"description": "The id of the team's location"
},
"name": {
"type": "string",
"description": "The name of the team"
},
"export_name": {
"type": "string",
"description": "30 (string) - The payroll export name of the team (if different to the name)"
},
"colour": {
"type": "string",
"description": "The team's colour"
},
"staff": {
"type": "array",
"description": "The user ids of the staff in the team"
},
"managers": {
"type": "array",
"description": "The user ids of the managers of the team"
},
"associated_tags": {
"type": "array",
"description": "Tags automatically assigned to shifts worked in this team"
},
"qualifications": {
"type": "array",
"description": "The required qualifications to work in this team"
},
"assisting_team_ids": {
"type": "array",
"description": "The teams that will count toward this team's requirements on the roster"
},
"team_group": {
"type": "string",
"description": "A group of teams for rostering or reporting"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
}
},
"required": [
"id",
"location_id",
"name"
]
}
Headers
Content-Type: application/json
Body
{
"user_ids": [
1111,
2222,
3333
],
"manager_ids": [
4444,
5555
]
}
Headers
Content-Type: application/json
Body
{
"id": 808,
"location_id": 111,
"name": "Waiters",
"export_name": "WGB",
"colour": "#FBB829",
"staff": [
"1111",
"2222",
"3333"
],
"managers": [
"4444",
"5555"
],
"associated_tags": [
"Level 2",
"Level 3 HD"
],
"qualifications": [
1234,
4321
],
"assisting_team_ids": [
1234,
4321
],
"team_group": "Front of House",
"record_id": 532432
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the team"
},
"location_id": {
"type": "number",
"description": "The id of the team's location"
},
"name": {
"type": "string",
"description": "The name of the team"
},
"export_name": {
"type": "string",
"description": "30 (string) - The payroll export name of the team (if different to the name)"
},
"colour": {
"type": "string",
"description": "The team's colour"
},
"staff": {
"type": "array",
"description": "The user ids of the staff in the team"
},
"managers": {
"type": "array",
"description": "The user ids of the managers of the team"
},
"associated_tags": {
"type": "array",
"description": "Tags automatically assigned to shifts worked in this team"
},
"qualifications": {
"type": "array",
"description": "The required qualifications to work in this team"
},
"assisting_team_ids": {
"type": "array",
"description": "The teams that will count toward this team's requirements on the roster"
},
"team_group": {
"type": "string",
"description": "A group of teams for rostering or reporting"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
}
},
"required": [
"id",
"location_id",
"name"
]
}
Headers
Content-Type: application/json
Body
{
"qualification_ids": [
1001,
1002
]
}
Headers
Content-Type: application/json
Body
{
"id": 808,
"location_id": 111,
"name": "Waiters",
"export_name": "WGB",
"colour": "#FBB829",
"staff": [
1,
2,
123456
],
"managers": [
4,
5
],
"associated_tags": [
"Level 2",
"Level 3 HD"
],
"qualifications": [
"1001",
"1002"
],
"assisting_team_ids": [
1234,
4321
],
"team_group": "Front of House",
"record_id": 532432
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the team"
},
"location_id": {
"type": "number",
"description": "The id of the team's location"
},
"name": {
"type": "string",
"description": "The name of the team"
},
"export_name": {
"type": "string",
"description": "30 (string) - The payroll export name of the team (if different to the name)"
},
"colour": {
"type": "string",
"description": "The team's colour"
},
"staff": {
"type": "array",
"description": "The user ids of the staff in the team"
},
"managers": {
"type": "array",
"description": "The user ids of the managers of the team"
},
"associated_tags": {
"type": "array",
"description": "Tags automatically assigned to shifts worked in this team"
},
"qualifications": {
"type": "array",
"description": "The required qualifications to work in this team"
},
"assisting_team_ids": {
"type": "array",
"description": "The teams that will count toward this team's requirements on the roster"
},
"team_group": {
"type": "string",
"description": "A group of teams for rostering or reporting"
},
"record_id": {
"type": "number",
"description": "the record ID, for use with Platform endpoints"
}
},
"required": [
"id",
"location_id",
"name"
]
}
Update TeamPUT/api/v2/departments/{id}
This method requires the department
scope (see Scopes for more information).
Updating users & managers
Updating a departmentâs users or managers through a PUT request will completely replace existing users and managers with the ids provided. It is recommended to only update users and managers on setup of an account. Users provided must also be active or your request will fail.
Updating required team qualifications
When providing qualification ids you wish to assign as ârequiredâ to join this team, users in the team must all have the qualification or else your request will fail.
Your account must also have the enable_qualifications
setting turned on.
- id
number
(required) Example: 111The id of the team
Headers
Content-Type: application/json
Team Versions ¶
Headers
Content-Type: application/json
Body
[
{
"version_id": 123456,
"time": 1459209907,
"event": "update",
"author": {
"id": 123456,
"name": "API v2"
},
"item_id": 1235435,
"item_type": "\"Department\"",
"changes": [
{
"field": "name",
"previous": "Wait staff",
"updated": "Waiters"
},
{
"field": "colour",
"previous": "#3FAFD7",
"updated": "#FBB829"
}
]
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get Team VersionsGET/api/v2/departments/{id}/versions
This method requires the department
scope (see Scopes for more information).
- id
number
(required) Example: 111The id of the team
- updated_after
number
(optional) Example: 1451570400Time filter to find recently created or modified team versions
Shift Details ¶
Shift details belong to a Team, and can be assigned on Schedules within that team.
Teams managers can read and update information about the shift details from the teams they manage. Admins can CRUD shift details.
Shift Detail List ¶
Headers
Content-Type: application/json
Body
[
{
"id": 36,
"department_id": 808,
"name": "Higher Duties"
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Headers
Content-Type: application/json
Body
{
"name": "Manager",
"department_id": 808
}
Headers
Content-Type: application/json
Body
{
"id": 532,
"department_id": "808",
"name": "Manager"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the shift detail"
},
"department_id": {
"type": "string",
"description": "The id of the shift detail's department"
},
"name": {
"type": "string",
"description": "The name of the shift detail"
}
},
"required": [
"id",
"department_id",
"name"
]
}
Shift Detail ¶
Headers
Content-Type: application/json
Body
{
"id": 36,
"department_id": 808,
"name": "Higher Duties"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the shift detail"
},
"department_id": {
"type": "number",
"description": "The id of the shift detail's department"
},
"name": {
"type": "string",
"description": "The name of the shift detail"
}
},
"required": [
"id",
"department_id",
"name"
]
}
Headers
Content-Type: application/json
Body
{
"name": "Shift Runner"
}
Headers
Content-Type: application/json
Body
{
"id": 36,
"department_id": 808,
"name": "Shift Runner"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the shift detail"
},
"department_id": {
"type": "number",
"description": "The id of the shift detail's department"
},
"name": {
"type": "string",
"description": "The name of the shift detail"
}
},
"required": [
"id",
"department_id",
"name"
]
}
Headers
Content-Type: application/json
Access & Roles ¶
By default only admin level users can access roles. But you can also define new roles that are able to access roles!
Platform Role List ¶
Headers
Content-Type: application/json
Body
[
{
"id": 3816,
"name": "Admin",
"description": "access to all functions in Tanda",
"type": "organisation_admin",
"enabled": true,
"native": true,
"sort_order": 1
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Headers
Content-Type: application/json
Body
[
{
"id": 3816,
"name": "Casual"
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Headers
Content-Type: application/json
Body
{
"id": 3816,
"name": "Casual"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the award tag"
},
"name": {
"type": "string",
"description": "The name of the award tag"
}
},
"required": [
"id",
"name"
]
}
Leave Requests ¶
Leave is time formally not worked by an employee, due to things like public holidays, sickness, or by accruing annual leave.
For specifying times when an employee requests not to be rostered, please see Unavailability.
Admins, payroll officers, and roster managers can create, read and update leave requests for all users, and department managers can create, read and update leave requests for users that they manage. Other users are able to create, read and update leave requests for themself. Note that the current user may not update status for their own leave requests unless they are an Admin, payroll officer or roster manager. Deletion of leave requests is not supported.
Leave List ¶
Headers
Content-Type: application/json
Body
[
{
"id": 666,
"department_id": 808,
"user_id": 123456,
"reason": "Terribly Sick",
"leave_type": "Personal/Carer's Leave",
"hours": 7.6,
"start": "2016-04-01",
"finish": "2016-04-01",
"start_time": "2000-01-01T09:30:00+10:00",
"finish_time": "2000-01-01T05:30:00+10:00",
"status": "pending",
"multitagging": "false",
"all_day": true,
"daily_breakdown": {
"2016-04-01": {},
"hours": 7.6,
"all_day": true,
"start_time": "2016-04-01T09:30:00+1000",
"finish_time": "2016-04-01T17:30:00+1000"
}
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
Get Leave ListGET/api/v2/leave{?ids,from,to,user_ids}
Lookup multiple leave requests in a single request.
Your URL parameters must include:
-
from
andto
, or -
ids
, or -
all 3 of the above
You can also specify user_ids
to further filter your request.
This method requires the leave
scope (see Scopes for more information).
You will only be able to query up to 366 days when specifying from
and to
.
- ids
string
(optional) Example: 1,2,666Comma separated list of leave ids to lookup
- from
string
(optional) Example: 2016-03-15From date to lookup leave in
- to
string
(optional) Example: 2016-04-05To date to lookup leave in
- user_ids
string
(optional) Example: 1,2,123456Comma separated list of user ids to lookup leave for
- page
number
(optional) Example: 1The page number for your leave request list
- page_size
number
(optional) Example: 50The number of leave requests retrieved per page. Maximum 100 per page.
- updated_after
number
(optional) Example: 1451570400Time filter to find recently created or modified leave requests
Headers
Content-Type: application/json
Body
{
"reason": "Sick Day",
"department_id": 2,
"user_id": 123456,
"hours": 114.0,
"start": "2016-03-07",
"start_time": "2000-01-01 09:30:00",
"finish": "2016-03-07",
"finish_time": "2000-01-01 17:30:00",
"leave_type": "Sick Leave",
"fallback_leave_type": "Unpaid Leave",
"status": "pending",
"all_day": false,
"file_id": "73fe3430-4f5d-3a0a-84a7-cffbeb5efeb2",
"daily_breakdown": [
{
"date": "2016-03-07"
"hours": 114.0,
"all_day": true,
"start_time": "2016-03-07T09:30:00+1000",
"finish_time": "2016-03-07T17:30:00+1000"
}
]
}
Headers
Content-Type: application/json
Body
{
"id": 7250,
"department_id": 808,
"user_id": 123456,
"reason": "Holiday in France",
"leave_type": "Annual Leave",
"hours": 114,
"start": "2016-03-07",
"finish": "2016-03-08",
"start_time": "2000-01-01T09:30:00",
"finish_time": "2000-01-01T17:30:00",
"status": "pending",
"multitagging": "false",
"all_day": "false",
"daily_breakdown": [],
"fallback_leave_type": "Unpaid Leave",
"verification": "http://springfieldfiles.com/albums/notes/0244.JPG"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "The id of the leave request"
},
"department_id": {
"type": "number",
"description": "The id of the team with which the leave request's shifts will be tagged"
},
"user_id": {
"type": "number",
"description": "The id of the user who owns the leave request"
},
"reason": {
"type": "string",
"description": "The reason for the leave request - optional"
},
"leave_type": {
"type": "string",
"description": "The type of leave request"
},
"hours": {
"type": "number",
"description": "The number of workable hours the leave request spans"
},
"start": {
"type": "string",
"description": "The start date for the leave request"
},
"finish": {
"type": "string",
"description": "The end date for the leave request"
},
"start_time": {
"type": "string",
"description": "The start time for a leave request event"
},
"finish_time": {
"type": "string",
"description": "The end time for a leave request event"
},
"status": {
"type": "string",
"description": "The status for the leave request. One of ['pending', 'approved', 'rejected']"
},
"multitagging": {
"type": "string",
"description": "Determines whether shifts on the leave request can be tagged differently."
},
"all_day": {
"type": "string",
"description": "Useful for all day leave requests."
},
"daily_breakdown": {},
"fallback_leave_type": {
"type": "string"
},
"verification": {
"type": "string"
},
"": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"hours": {
"type": "number"
},
"all_day": {
"type": "boolean"
},
"start_time": {
"type": "string"
},
"finish_time": {
"type": "string"
}
},
"required": [
"date",
"all_day",
"start_time",
"finish_time"
]
}
},
"required": [
"id",
"user_id",
"leave_type",
"hours",
"start",
"finish",
"status"
]
}
Create Leave RequestPOST/api/v2/leave
Note that a status for a new Leave Request is required. Managers can create approved leave requests for their staff, and themselves if permitted by the organisation settings. Admins can create approved leave requests for all staff. Employees may only create pending leave requests. The server will respond with a 400 when a user creates a leave request violating the above requirements.
Leave request status must be one of: âpendingâ, âapprovedâ, ârejectedâ.
When a leave request is created with status âapprovedâ, a Shift will be created for each day the leave request spans, and will be attached to the leave request. If a department_id
is passed, these shifts will be categorised with the team corresponding to the department_id
. Passing a department_id
will have no consequence if the leave request status is âpendingâ or ârejectedâ. Note that the department_id
will n