# Workforce.com API v2 Docs

Paste relevant sections below.

Endpoints needed:
- Auth / how bearer token is used in requests
- List employees (ideally filterable by department/location)
- Get scheduled shifts by date range (fields: employee, date, start time, end time or shift duration)

---

<!-- PASTE DOCS BELOW THIS LINE -->

🚀 Workforce API v2
Getting Started
Welcome to the Workforce 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 Workforce users to use, or 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 Workforce customers to use. For example, if you are building an integration that connects your custom reporting platform to Workforce data, you’ll probably want to let lots of Workforce customers use it. This is the approach for you.

If you have a log in for the Workforce platform you have access to an Authorization code. This code is linked to your organisation and permisson levels. Just like using an account in Workforce the permission levels will give you the same access in the API, e.g. if you don’t have permission to approve a timesheet in Workforce, you won’t be able to do so via the API.

Once you have permission an a working Workforce 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.

Tokens are encrypted, and the encryption key is different between environments. If you are testing in an environment that is not production, the tokens will not work.
1. Redirect the user to the authorize endpoint
Allow users on your website to authenticate themselves with Workforce 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 Workforce OAuth2 scopes your want access to (more information: Scopes).

https://my.workforce.com/api/oauth/authorize?scope=SCOPE1+SCOPE2&client_id=YOUR_APPLICATION_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code

2. Catch the request to your redirect URI
The Workforce 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.

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.workforce.com/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.
curl https://my.workforce.com/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"

Refreshing your 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.workforce.com/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.
curl https://my.workforce.com/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"

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 Workforce login details, or you can just set up an access token through the Workforce 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
From your server/application make a POST request to https://my.workforce.com/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.
curl https://my.workforce.com/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"

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 Workforce v2 API must include the token in the header like so:

Authorization: bearer 6833b9ecaa84ce420da3cafaa43124d241cb28b5287b72d131f6b38bcb64cd91

See the right hand sidebar for an example of a request that gets information about the user that just authenticated.

curl --header "Authorization: bearer 6833b9ecaa84ce420da3cafaa43124d241cb28b5287b72d131f6b38bcb64cd91" \ https://my.workforce.com/api/v2/users/me

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 Workforce 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
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
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!" }

Caching
The Workforce 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.

curl --header "If-None-Match: 17f1542065ae37d0963a608fd632b4615a288ceb" --header "Authorization: bearer 6833b9ecaa84ce420da3cafaa43124d241cb28b5287b72d131f6b38bcb64cd91" \ https://my.workforce.com/api/v2/users/me

TLS Version
The Workforce API only supports TLS version 1.2 or higher. If your API client attempts to connect with a lower version of TLS or SSL then you will recieve a TLS handshake error.

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 Workforce 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	Availability, Unavailability	Manage availability and 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)
communication	Announcements	Manage announcements
platform	Platform	Get platform data
Not only will you need the relevant scopes to access the endpoints, but also the correct system permissions in Workforce. 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 Workforce 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 Workforce 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 Workforce through the API is logged and added to the in-Workforce 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. Email 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:

Getting started
Building a connection to Salesforce
Show us what you built!
If you’ve built something neat using the API, we’d love to see it. If you’ve already been chatting to someone from our team, odds are they’d love to see a demo of your integration. Or if you haven’t met any of our team before, a good way to introduce yourself is to email developers@tanda.co.

General
Current User [/api/v2/users/me]
GETGet Current User
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 preferred name.
legal_first_name - the user’s legal first name.
legal_middle_names - the user’s legal middle name/s.
legal_last_name - the user’s legal last 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 Workforce 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 Workforce 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 the X-User-Id header and one of these IDs.
organisations - Organisations at which this user has profiles, based on user_ids. If your application needs to deal with people who may work at more than one Workforce organisation, you should use this. If you need to restrict your API call to a specific organisation, you can use the X-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).
200
OK
(application/json)
Body

    {
      "id": 123456,
      "name": "Lenny Leonard",
      "legal_first_name": "Lenny",
      "legal_middle_names: "James",
      "legal_last_name": "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
    }

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 Workforce permissions are required to use the roster endpoint.
On-cost amounts are estimates
On-cost amounts are estimates. They are calculated by applying the organisation’s on-cost configurations to award-interpreted wage costs, consistent with Workforce’s cost reports. They are not statutory payroll calculations. For example, employer National Insurance is estimated as the configured percentage of all eligible cost rather than HMRC’s banded calculation on earnings above the threshold, and superannuation rules that depend on age or contribution caps are not applied. Use payroll data for exact figures.

Some on-cost configurations only apply once an employee’s earnings pass a threshold (such as employer National Insurance). Eligibility can only be assessed against the employee’s full pay period, so these configurations are not included in on-cost amounts on the rosters endpoint for UK organisations. Use the timesheets endpoint for threshold-aware on-costs.

Roster [/api/v2/rosters/{id}]
GETGet Roster
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.

Parameters
id: 70074 (number) - The id of the roster
show_costs: true (optional, boolean) - Whether to show the costs for the roster (defaults to false)
include_oncosts: true (optional, boolean) - Whether to include on-cost additions alongside existing costs. Requires show_costs=true. Adds oncosts_breakdown and cost_with_oncosts to each schedule, and total_oncosts_breakdown and cost_with_oncosts to the roster total (defaults to false)
200
OK
(application/json)
Attributes:
id: 70074 (required) (number) - The id of the roster
schedules (required) (array of DailyScheduleData) - The roster broken down by days
start: 2016-02-29 (required) (string) - The date of the first day of the roster
finish: 2016-03-07 (required) (string) - The date of the last day of the roster
cost: 1200.2 (number) - The total cost of the roster, if show_costs=true parameter is set
total_oncosts_breakdown (array) - Per-configuration on-cost amounts for the returned schedules (e.g. [{"name": "Superannuation", "amount": 144.02}, {"name": "Workcover", "amount": 28.80}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover a schedule’s employee and location contribute entries. For UK organisations, earnings-threshold on-costs (such as employer National Insurance) are not included on this endpoint. Like cost, this reflects only the current page when pagination parameters are used.
cost_with_oncosts: 1344.22 (number) - The total roster cost including all on-costs, if show_costs=true and include_oncosts=true parameters are set
meta (MetaData) - The pagination metadata, if page and page_size parameters are set
Current Roster [/api/v2/rosters/current]
GETGet the Current Roster
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.

Parameters
show_costs: true (boolean) - Whether to show the costs for the roster (defaults to false)
include_oncosts: true (optional, boolean) - Whether to include on-cost additions alongside existing costs. Requires show_costs=true (defaults to false)
200
OK
(application/json)
Attributes:
id: 70074 (required) (number) - The id of the roster
schedules (required) (array of DailyScheduleData) - The roster broken down by days
start: 2016-02-29 (required) (string) - The date of the first day of the roster
finish: 2016-03-07 (required) (string) - The date of the last day of the roster
cost: 1200.2 (number) - The total cost of the roster, if show_costs=true parameter is set
total_oncosts_breakdown (array) - Per-configuration on-cost amounts for the returned schedules (e.g. [{"name": "Superannuation", "amount": 144.02}, {"name": "Workcover", "amount": 28.80}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover a schedule’s employee and location contribute entries. For UK organisations, earnings-threshold on-costs (such as employer National Insurance) are not included on this endpoint. Like cost, this reflects only the current page when pagination parameters are used.
cost_with_oncosts: 1344.22 (number) - The total roster cost including all on-costs, if show_costs=true and include_oncosts=true parameters are set
meta (MetaData) - The pagination metadata, if page and page_size parameters are set
Roster that Contains Date [/api/v2/rosters/on/{date}]
GETGet Roster that Contains Date
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.

Parameters
date: 2016-03-02 (string) - The date that’s contained in the roster you are looking for.
show_costs: true (optional, boolean) - Whether to show the costs for the roster (defaults to false)
include_oncosts: true (optional, boolean) - Whether to include on-cost additions alongside existing costs. Requires show_costs=true. Adds oncosts_breakdown and cost_with_oncosts to each schedule, and total_oncosts_breakdown and cost_with_oncosts to the roster total (defaults to false)
page: 1 (optional, number) - The page number for your nested schedule list
page_size: 50 (optional, number) - The number of nested schedules retrieved per page. Maximum 100 per page.
200
OK
(application/json)
Attributes:
id: 70074 (required) (number) - The id of the roster
schedules (required) (array of DailyScheduleData) - The roster broken down by days
start: 2016-02-29 (required) (string) - The date of the first day of the roster
finish: 2016-03-07 (required) (string) - The date of the last day of the roster
cost: 1200.2 (number) - The total cost of the roster, if show_costs=true parameter is set
total_oncosts_breakdown (array) - Per-configuration on-cost amounts for the returned schedules (e.g. [{"name": "Superannuation", "amount": 144.02}, {"name": "Workcover", "amount": 28.80}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover a schedule’s employee and location contribute entries. For UK organisations, earnings-threshold on-costs (such as employer National Insurance) are not included on this endpoint. Like cost, this reflects only the current page when pagination parameters are used.
cost_with_oncosts: 1344.22 (number) - The total roster cost including all on-costs, if show_costs=true and include_oncosts=true parameters are set
meta (MetaData) - The pagination metadata, if page and page_size parameters are set
Sales Targets [/api/v2/rosters/sales_targets/{type}/{date}]
GETGet Sales Target
Get the sales target for a given roster with no filter.

This method requires the roster scope (see Scopes for more information).
Parameters
type: (string) - There are two possible values: day and week.
date: 2018-02-26 (string) - A date within the roster you are looking for.
200
OK
(application/json)
Attributes:
target: 1234.56 (string) - Value of the sales target. null if there is no roster for the given date.
created_at: 1519621685 (required) (number, nullable) - When the user-entered sales target was first created, if there is one. Otherwise null.
updated_at: 1519621685 (required) (number, nullable) - When the user-entered sales target was last updated, if there is one. Otherwise null.
user_entered: true (required) (boolean) - Whether or not the default projection was overridden with a user-entered value.
Sales Targets for Team (Department) [/api/v2/rosters/sales_targets/{type}/{date}]
GETGet Target for Team
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).
Parameters
type: (string) - There are two possible values: day and week.
date: 2018-02-26 (string) - A date within the roster you are looking for.
department_id: 123 (optional, number) - The ID of a team to filter the roster to.
200
OK
(application/json)
Attributes:
target: 1234.56 (string) - Value of the sales target. null if there is no roster for the given date.
created_at: 1519621685 (required) (number, nullable) - When the user-entered sales target was first created, if there is one. Otherwise null.
updated_at: 1519621685 (required) (number, nullable) - When the user-entered sales target was last updated, if there is one. Otherwise null.
user_entered: true (required) (boolean) - Whether or not the default projection was overridden with a user-entered value.
Sales Targets for Location [/api/v2/rosters/sales_targets/{type}/{date}]
GETGet Target for Location
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).
Parameters
type: (string) - There are two possible values: day and week.
date: 2018-02-26 (string) - A date within the roster you are looking for.
location_id: 456 (optional, number) - The ID of a location to filter the roster to.
200
OK
(application/json)
Attributes:
target: 1234.56 (string) - Value of the sales target. null if there is no roster for the given date.
created_at: 1519621685 (required) (number, nullable) - When the user-entered sales target was first created, if there is one. Otherwise null.
updated_at: 1519621685 (required) (number, nullable) - When the user-entered sales target was last updated, if there is one. Otherwise null.
user_entered: true (required) (boolean) - Whether or not the default projection was overridden with a user-entered value.
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 Workforce 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 [/api/v2/schedules]
GETGet Schedules
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.

Parameters
ids: 1,2,31337157 (required, string) - Comma separated list of schedule ids
show_costs: true (optional, boolean) - Whether to show the costs for the schedule (defaults to false).
show_award_interpretation: true (optional, boolean) - Whether to show costs breakdown for the schedule (defaults to false).
include_names: false (optional, boolean) - If true, the department name and shift detail name (not just ID) will be included in the response. Defaults to false.
show_activities: false (optional, boolean) - If true, the activities within each schedule will be included in the response, each with its activity_code/activity_code_id and prorated worked hours. With show_costs=true (and the cost scope) each activity also includes its derived cost. With include_names=true, each activity also includes the activity code’s name. Defaults to false.
include_colleagues: false (optional, boolean) - If true, shifts for colleagues will be returned. If false, only shifts for the current user will be returned. Defaults to false.
platform: false (optional, boolean) - If true, Platform data will be returned (defaults to false).
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified schedules
published_only: false (optional, boolean) - Only retrieve schedules that have been published. Useful for managers to see only published schedules, where they would usually see any schedule. Defaults to false.
location_id: 111 (optional, number) - The id of the schedule’s location, for filtering.
location_ids: “111,112” (optional, string) - Comma delimited location ids, for filtering.
show_vacant_only: false (optional, boolean) - Only retrieve schedules that are vacant. Defaults to false.
page: 1 (optional, number) - The page number for your schedules list
page_size: 50 (optional, number) - The number of schedules retrieved per page. Maximum 100 per page.
200
OK
(application/json)
Attributes (array):
id: 31337157 (required) (number) - The id of the schedule
roster_id: 70074 (required) (number) - The id of the roster
user_id: 123456 (number) - The id of the user who is assigned the schedule
start: 1456902000 (number) - The start of the schedule
finish: 1456916400 (number) - The end of the schedule
breaks (array of ScheduleBreakData) - The breaks taken in the schedule
automatic_break_length: 30 (number) - Length of automatic break in minutes
department_id: 111 (number) - The department (team) id for the schedule
shift_detail_id: 36 (number) - The shift detail id for the schedule
activity_code_id: 7 (number) - The schedule’s own (fallback) activity code id, applied to worked time not covered by any activity, or null. Included (with the activity_code string) when show_activities=true; the name is included under include_names
cost: 20.19 (number) - The cost of the schedule, if show_costs=true parameter is set
oncosts_breakdown (array) - Per-configuration on-cost amounts for this schedule (e.g. [{"name": "Superannuation", "amount": 2.01}, {"name": "Workcover", "amount": 0.40}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the employee and location are included, so the array can be empty. For UK organisations, earnings-threshold on-costs (such as employer National Insurance) are not included on this endpoint and are only available through the timesheets endpoint.
cost_with_oncosts: 22.61 (number) - The cost of the schedule including on-costs, if show_costs=true and include_oncosts=true parameters are set
last_published_at: 1457002800 (number) - When the schedule was last published to its given employee
acceptance_status: not_accepted (string) - The current status of the schedule
record_id: 532432 (number) - the record ID, for use with Platform endpoints
needs_acceptance: true (boolean) - Has the schedule been accepted by the employee?
creation_method: manual (string) - How the schedule was created.
creation_platform: web (string) - Where the schedule was created.
activities (array of ScheduleActivityData) - The activities within the schedule, if show_activities=true parameter is set
GETGet Schedules by User
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.

Parameters
user_ids: 1,2,123456 (required, string) - Comma 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: 2016-03-02 (required, string) - From date to lookup schedules in. If provided, from and to can be at most 7 days apart.
to: 2016-03-02 (required, string) - To date to lookup schedules in. If provided, from and to can be at most 7 days apart.
show_costs: true (optional, boolean) - Whether to show the costs for the schedule (defaults to false).
show_award_interpretation: true (optional, boolean) - Whether to show costs breakdown for the schedule (defaults to false).
include_names: false (optional, boolean) - If true, the department name and shift detail name (not just ID) will be included in the response. Defaults to false.
show_activities: false (optional, boolean) - If true, the activities within each schedule will be included in the response, each with its activity_code/activity_code_id and prorated worked hours. With show_costs=true (and the cost scope) each activity also includes its derived cost. With include_names=true, each activity also includes the activity code’s name. Defaults to false.
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified schedules
location_id: 111 (optional, number) - The id of the schedule’s location, for filtering.
location_ids: “111,112” (optional, string) - Comma delimited location ids, for filtering.
200
OK
(application/json)
Attributes (array):
id: 31337157 (required) (number) - The id of the schedule
roster_id: 70074 (required) (number) - The id of the roster
user_id: 123456 (number) - The id of the user who is assigned the schedule
start: 1456902000 (number) - The start of the schedule
finish: 1456916400 (number) - The end of the schedule
breaks (array of ScheduleBreakData) - The breaks taken in the schedule
automatic_break_length: 30 (number) - Length of automatic break in minutes
department_id: 111 (number) - The department (team) id for the schedule
shift_detail_id: 36 (number) - The shift detail id for the schedule
activity_code_id: 7 (number) - The schedule’s own (fallback) activity code id, applied to worked time not covered by any activity, or null. Included (with the activity_code string) when show_activities=true; the name is included under include_names
cost: 20.19 (number) - The cost of the schedule, if show_costs=true parameter is set
oncosts_breakdown (array) - Per-configuration on-cost amounts for this schedule (e.g. [{"name": "Superannuation", "amount": 2.01}, {"name": "Workcover", "amount": 0.40}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the employee and location are included, so the array can be empty. For UK organisations, earnings-threshold on-costs (such as employer National Insurance) are not included on this endpoint and are only available through the timesheets endpoint.
cost_with_oncosts: 22.61 (number) - The cost of the schedule including on-costs, if show_costs=true and include_oncosts=true parameters are set
last_published_at: 1457002800 (number) - When the schedule was last published to its given employee
acceptance_status: not_accepted (string) - The current status of the schedule
record_id: 532432 (number) - the record ID, for use with Platform endpoints
needs_acceptance: true (boolean) - Has the schedule been accepted by the employee?
creation_method: manual (string) - How the schedule was created.
creation_platform: web (string) - Where the schedule was created.
activities (array of ScheduleActivityData) - The activities within the schedule, if show_activities=true parameter is set
POSTCreate Schedule
This will create a Roster for the given date, if it does not already exist.

Only one of breaks and automatic_break_length can be set to non-null values.
The optional activities array creates ScheduleActivityData activities within the schedule. Each entry has a start, finish, and optional activity_code_id (which must belong to the same organisation). See Update Schedule for how activities are reconciled on update.
The optional top-level activity_code_id sets the schedule’s own (fallback) activity code — applied to worked time not covered by any activity. The code must belong to the organisation, be unarchived, and apply to the schedule’s department. On update, pass null to clear it.
This method requires the roster scope (see Scopes for more information).
Request Create Schedule (application/json)
Body

    {
      "user_id": 123456,
      "start": 1456903800,
      "finish": 1456911000,
      "department_id": 111,
      "automatic_break_length": 30,
      "activities": [
        {
          "start": 1456905600,
          "finish": 1456909200,
          "activity_code_id": 7
        }
      ]
    }

200
OK
(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

Attributes:
id: 31337157 (required) (number) - The id of the schedule
roster_id: 70074 (required) (number) - The id of the roster
user_id: 123456 (number) - The id of the user who is assigned the schedule
start: 1456902000 (number) - The start of the schedule
finish: 1456916400 (number) - The end of the schedule
breaks (array of ScheduleBreakData) - The breaks taken in the schedule
automatic_break_length: 30 (number) - Length of automatic break in minutes
department_id: 111 (number) - The department (team) id for the schedule
shift_detail_id: 36 (number) - The shift detail id for the schedule
activity_code_id: 7 (number) - The schedule’s own (fallback) activity code id, applied to worked time not covered by any activity, or null. Included (with the activity_code string) when show_activities=true; the name is included under include_names
cost: 20.19 (number) - The cost of the schedule, if show_costs=true parameter is set
oncosts_breakdown (array) - Per-configuration on-cost amounts for this schedule (e.g. [{"name": "Superannuation", "amount": 2.01}, {"name": "Workcover", "amount": 0.40}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the employee and location are included, so the array can be empty. For UK organisations, earnings-threshold on-costs (such as employer National Insurance) are not included on this endpoint and are only available through the timesheets endpoint.
cost_with_oncosts: 22.61 (number) - The cost of the schedule including on-costs, if show_costs=true and include_oncosts=true parameters are set
last_published_at: 1457002800 (number) - When the schedule was last published to its given employee
acceptance_status: not_accepted (string) - The current status of the schedule
record_id: 532432 (number) - the record ID, for use with Platform endpoints
needs_acceptance: true (boolean) - Has the schedule been accepted by the employee?
creation_method: manual (string) - How the schedule was created.
creation_platform: web (string) - Where the schedule was created.
activities (array of ScheduleActivityData) - The activities within the schedule, if show_activities=true parameter is set
id: (number)
Request Create vacant Schedule (application/json)
Body

    {
      "start": 1456903800
    }

200
OK
(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

Attributes:
id: 31337157 (required) (number) - The id of the schedule
roster_id: 70074 (required) (number) - The id of the roster
user_id: 123456 (number) - The id of the user who is assigned the schedule
start: 1456902000 (number) - The start of the schedule
finish: 1456916400 (number) - The end of the schedule
breaks (array of ScheduleBreakData) - The breaks taken in the schedule
automatic_break_length: 30 (number) - Length of automatic break in minutes
department_id: 111 (number) - The department (team) id for the schedule
shift_detail_id: 36 (number) - The shift detail id for the schedule
activity_code_id: 7 (number) - The schedule’s own (fallback) activity code id, applied to worked time not covered by any activity, or null. Included (with the activity_code string) when show_activities=true; the name is included under include_names
cost: 20.19 (number) - The cost of the schedule, if show_costs=true parameter is set
oncosts_breakdown (array) - Per-configuration on-cost amounts for this schedule (e.g. [{"name": "Superannuation", "amount": 2.01}, {"name": "Workcover", "amount": 0.40}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the employee and location are included, so the array can be empty. For UK organisations, earnings-threshold on-costs (such as employer National Insurance) are not included on this endpoint and are only available through the timesheets endpoint.
cost_with_oncosts: 22.61 (number) - The cost of the schedule including on-costs, if show_costs=true and include_oncosts=true parameters are set
last_published_at: 1457002800 (number) - When the schedule was last published to its given employee
acceptance_status: not_accepted (string) - The current status of the schedule
record_id: 532432 (number) - the record ID, for use with Platform endpoints
needs_acceptance: true (boolean) - Has the schedule been accepted by the employee?
creation_method: manual (string) - How the schedule was created.
creation_platform: web (string) - Where the schedule was created.
activities (array of ScheduleActivityData) - The activities within the schedule, if show_activities=true parameter is set
id: (number)
Schedule [/api/v2/schedules/{id}]
GETGet Schedule
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.

Parameters
id: 31337157 (number) - The id of the schedule
show_costs: true (optional, boolean) - Whether to show the costs for the schedule (defaults to false)
show_award_interpretation: true (optional, boolean) - Whether to show costs breakdown for the schedule (defaults to false).
include_names: false (optional, boolean) - If true, the department name and shift detail name (not just ID) will be included in the response. Defaults to false.
show_activities: false (optional, boolean) - If true, the activities within each schedule will be included in the response, each with its activity_code/activity_code_id and prorated worked hours. With show_costs=true (and the cost scope) each activity also includes its derived cost. With include_names=true, each activity also includes the activity code’s name. Defaults to false.
platform: false (optional, boolean) - If true, Platform data will be returned (defaults to false).
200
OK
(application/json)
Attributes:
id: 31337157 (required) (number) - The id of the schedule
roster_id: 70074 (required) (number) - The id of the roster
user_id: 123456 (number) - The id of the user who is assigned the schedule
start: 1456902000 (number) - The start of the schedule
finish: 1456916400 (number) - The end of the schedule
breaks (array of ScheduleBreakData) - The breaks taken in the schedule
automatic_break_length: 30 (number) - Length of automatic break in minutes
department_id: 111 (number) - The department (team) id for the schedule
shift_detail_id: 36 (number) - The shift detail id for the schedule
activity_code_id: 7 (number) - The schedule’s own (fallback) activity code id, applied to worked time not covered by any activity, or null. Included (with the activity_code string) when show_activities=true; the name is included under include_names
cost: 20.19 (number) - The cost of the schedule, if show_costs=true parameter is set
oncosts_breakdown (array) - Per-configuration on-cost amounts for this schedule (e.g. [{"name": "Superannuation", "amount": 2.01}, {"name": "Workcover", "amount": 0.40}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the employee and location are included, so the array can be empty. For UK organisations, earnings-threshold on-costs (such as employer National Insurance) are not included on this endpoint and are only available through the timesheets endpoint.
cost_with_oncosts: 22.61 (number) - The cost of the schedule including on-costs, if show_costs=true and include_oncosts=true parameters are set
last_published_at: 1457002800 (number) - When the schedule was last published to its given employee
acceptance_status: not_accepted (string) - The current status of the schedule
record_id: 532432 (number) - the record ID, for use with Platform endpoints
needs_acceptance: true (boolean) - Has the schedule been accepted by the employee?
creation_method: manual (string) - How the schedule was created.
creation_platform: web (string) - Where the schedule was created.
activities (array of ScheduleActivityData) - The activities within the schedule, if show_activities=true parameter is set
PUTUpdate Schedule
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).
The optional activities array replaces the schedule’s ScheduleActivityData activities. Activities are reconciled by their time window (start and finish): an entry matching an existing activity updates that activity’s activity_code_id in place (the activity is kept, not recreated), existing activities absent from the array are deleted, and entries with a new window are created. Omitting activities leaves the schedule’s activities untouched; passing an empty array [] deletes all of them. Each entry’s activity_code_id must belong to the same organisation.
The top-level activity_code_id sets the schedule’s own (fallback) activity code; pass null to clear it, or omit it to leave it untouched.

This method requires the roster scope (see Scopes for more information).
Parameters
id: 31337157 (number) - The id of the schedule
Request Update Schedule (application/json)
Body

    {
      "start": 1456898400,
      "breaks": [
        {
          "start": 1456903800,
          "finish": 1456905600,
          "paid": false,
          "paid_meal_breaks": false,
          "length": 30
        },
        {
          "start": 1456909200,
          "finish": 1456911000,
          "paid": true,
          "paid_meal_breaks": false,
          "length": 30
        }
      ],
      "automatic_break_length": null,
      "department_id": null,
      "activities": [
        {
          "start": 1456905600,
          "finish": 1456909200,
          "activity_code_id": 7
        }
      ]
    }

200
OK
(application/json)
Body

    {
      "id": 31337157,
      "roster_id": 70074,
      "user_id": 123456,
      "start": 1456898400,
      "finish": 1456916400,
      "breaks": [
        {
          "start": 1456903800,
          "finish": 1456905600,
          "paid": false,
          "paid_meal_breaks": false,
          "length": 30
        },
        {
          "start": 1456909200,
          "finish": 1456911000,
          "paid": false,
          "paid_meal_breaks": false,
          "length": 30
        }
      ],
      "automatic_break_length": null,
      "department_id": null,
      "shift_detail_id": null,
      "last_published_at": null,
      "last_acknowledged_at": null,
      "acceptance_status": "not_accepted"
    }

Request Make Schedule vacant (application/json)
Body

    {
      "user_id": nil
    }

200
OK
(application/json)
Body

    {
      "id": 31337157,
      "roster_id": 70074,
      "user_id": null,
      "start": 1456902000,
      "finish": 1456916400,
      "breaks": [
        {
          "start": 1456909200,
          "finish": 1456911000,
          "paid": false,
          "paid_meal_break": false,
          "length": 30
        }
      ],
      "department_id": 111,
      "shift_detail_id": null,
      "last_published_at": null,
      "last_acknowledged_at": null,
      "acceptance_status": "not_accepted"
    }

Schema

Attributes:
id: 31337157 (required) (number) - The id of the schedule
roster_id: 70074 (required) (number) - The id of the roster
user_id: 123456 (number) - The id of the user who is assigned the schedule
start: 1456902000 (number) - The start of the schedule
finish: 1456916400 (number) - The end of the schedule
breaks (array of ScheduleBreakData) - The breaks taken in the schedule
automatic_break_length: 30 (number) - Length of automatic break in minutes
department_id: 111 (number) - The department (team) id for the schedule
shift_detail_id: 36 (number) - The shift detail id for the schedule
activity_code_id: 7 (number) - The schedule’s own (fallback) activity code id, applied to worked time not covered by any activity, or null. Included (with the activity_code string) when show_activities=true; the name is included under include_names
cost: 20.19 (number) - The cost of the schedule, if show_costs=true parameter is set
oncosts_breakdown (array) - Per-configuration on-cost amounts for this schedule (e.g. [{"name": "Superannuation", "amount": 2.01}, {"name": "Workcover", "amount": 0.40}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the employee and location are included, so the array can be empty. For UK organisations, earnings-threshold on-costs (such as employer National Insurance) are not included on this endpoint and are only available through the timesheets endpoint.
cost_with_oncosts: 22.61 (number) - The cost of the schedule including on-costs, if show_costs=true and include_oncosts=true parameters are set
last_published_at: 1457002800 (number) - When the schedule was last published to its given employee
acceptance_status: not_accepted (string) - The current status of the schedule
record_id: 532432 (number) - the record ID, for use with Platform endpoints
needs_acceptance: true (boolean) - Has the schedule been accepted by the employee?
creation_method: manual (string) - How the schedule was created.
creation_platform: web (string) - Where the schedule was created.
activities (array of ScheduleActivityData) - The activities within the schedule, if show_activities=true parameter is set
id: (number)
Request Give Schedule automatic break (application/json)
Body

    {
      "automatic_break_length": 25,
      "breaks": null
    }

200
OK
(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

Attributes:
id: 31337157 (required) (number) - The id of the schedule
roster_id: 70074 (required) (number) - The id of the roster
user_id: 123456 (number) - The id of the user who is assigned the schedule
start: 1456902000 (number) - The start of the schedule
finish: 1456916400 (number) - The end of the schedule
breaks (array of ScheduleBreakData) - The breaks taken in the schedule
automatic_break_length: 30 (number) - Length of automatic break in minutes
department_id: 111 (number) - The department (team) id for the schedule
shift_detail_id: 36 (number) - The shift detail id for the schedule
activity_code_id: 7 (number) - The schedule’s own (fallback) activity code id, applied to worked time not covered by any activity, or null. Included (with the activity_code string) when show_activities=true; the name is included under include_names
cost: 20.19 (number) - The cost of the schedule, if show_costs=true parameter is set
oncosts_breakdown (array) - Per-configuration on-cost amounts for this schedule (e.g. [{"name": "Superannuation", "amount": 2.01}, {"name": "Workcover", "amount": 0.40}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the employee and location are included, so the array can be empty. For UK organisations, earnings-threshold on-costs (such as employer National Insurance) are not included on this endpoint and are only available through the timesheets endpoint.
cost_with_oncosts: 22.61 (number) - The cost of the schedule including on-costs, if show_costs=true and include_oncosts=true parameters are set
last_published_at: 1457002800 (number) - When the schedule was last published to its given employee
acceptance_status: not_accepted (string) - The current status of the schedule
record_id: 532432 (number) - the record ID, for use with Platform endpoints
needs_acceptance: true (boolean) - Has the schedule been accepted by the employee?
creation_method: manual (string) - How the schedule was created.
creation_platform: web (string) - Where the schedule was created.
activities (array of ScheduleActivityData) - The activities within the schedule, if show_activities=true parameter is set
id: (number)
DELETEDelete Schedule
This method requires the roster scope (see Scopes for more information).
Parameters
id: 31337157 (number) - The id of the schedule
200
OK
(application/json)
Bulk Publish Schedules [/api/v2/schedules/publish]
POSTPublish Multiple Schedules
Publish multiple schedules at once. Push notifications are sent to users whose schedules have changed since last publish.

Only occupied schedules (schedules with a user assigned) will be published. Vacant schedules will be filtered out.
Schedules you do not have permission to update will be filtered out and not published.

This method requires the roster scope (see Scopes for more information).
Request Publish Schedules (application/json)
Body

    {
      "schedule_ids": [123, 456, 789]
    }

201
Created
(application/json)
Attributes (array):
id: 31337157 (required) (number) - The id of the schedule
roster_id: 70074 (required) (number) - The id of the roster
user_id: 123456 (number) - The id of the user who is assigned the schedule
start: 1456902000 (number) - The start of the schedule
finish: 1456916400 (number) - The end of the schedule
breaks (array of ScheduleBreakData) - The breaks taken in the schedule
automatic_break_length: 30 (number) - Length of automatic break in minutes
department_id: 111 (number) - The department (team) id for the schedule
shift_detail_id: 36 (number) - The shift detail id for the schedule
activity_code_id: 7 (number) - The schedule’s own (fallback) activity code id, applied to worked time not covered by any activity, or null. Included (with the activity_code string) when show_activities=true; the name is included under include_names
cost: 20.19 (number) - The cost of the schedule, if show_costs=true parameter is set
oncosts_breakdown (array) - Per-configuration on-cost amounts for this schedule (e.g. [{"name": "Superannuation", "amount": 2.01}, {"name": "Workcover", "amount": 0.40}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the employee and location are included, so the array can be empty. For UK organisations, earnings-threshold on-costs (such as employer National Insurance) are not included on this endpoint and are only available through the timesheets endpoint.
cost_with_oncosts: 22.61 (number) - The cost of the schedule including on-costs, if show_costs=true and include_oncosts=true parameters are set
last_published_at: 1457002800 (number) - When the schedule was last published to its given employee
acceptance_status: not_accepted (string) - The current status of the schedule
record_id: 532432 (number) - the record ID, for use with Platform endpoints
needs_acceptance: true (boolean) - Has the schedule been accepted by the employee?
creation_method: manual (string) - How the schedule was created.
creation_platform: web (string) - Where the schedule was created.
activities (array of ScheduleActivityData) - The activities within the schedule, if show_activities=true parameter is set
400
Bad Request
(application/json)
Body

    {
      "error": "Cannot publish more than 100 schedules at once"
    }

403
Forbidden
(application/json)
Body

    {
      "error": "You do not have permission to publish schedules!"
    }

404
Not Found
(application/json)
Body

    {
      "error": "No valid schedules found!"
    }

Schedule Versions [/api/v2/schedules/{id}/versions]
GETGet Schedule 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).
Parameters
id: 31337157 (number) - The id of the schedule
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified schedule versions
200
OK
(application/json)
Attributes (array):
version_id: 123456 (number)
time: 1459209907 (number)
event: update
author (object)
id: 123456 (number)
name: API v2
item_id: 1235435 (number)
item_type: “Schedule” (string)
changes (array)
(object)
field: start
previous: 1456898400 (number)
updated: 1456902000 (number)
(object)
field: finish
previous: 1456912800 (number)
updated: 1456916400 (number)
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 Workforce 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.

On-cost amounts are estimates
On-cost amounts are estimates. They are calculated by applying the organisation’s on-cost configurations to award-interpreted wage costs, consistent with Workforce’s cost reports. They are not statutory payroll calculations. For example, employer National Insurance is estimated as the configured percentage of all eligible cost rather than HMRC’s banded calculation on earnings above the threshold, and superannuation rules that depend on age or contribution caps are not applied. Use payroll data for exact figures.

For UK organisations, some on-cost configurations (such as employer National Insurance) only apply when an employee’s projected monthly earnings exceed the applicable HMRC Secondary Threshold. When include_oncosts=true is set, the timesheets endpoint determines threshold eligibility from the employee’s total pay-period earnings normalised to a 28-day monthly equivalent, matching the logic used in Workforce’s cost reports. This works for all pay period lengths. The shifts and rosters endpoints cannot assess threshold eligibility, so they do not include these configurations for UK organisations.

On-cost configurations restricted to ordinary hours return 0.0 for leave shifts. Configurations that are not restricted still apply to leave shifts.

For non-UK organisations, on-costs are applied at the flat rate regardless of earnings.

Current Timesheets [/api/v2/timesheets/current]
GETGet Current Timesheets
If you are using show_costs=true or show_award_interpretation=true, the cost scope is required.
Parameters
show_costs: true (optional, boolean) - Whether to show the costs for the timesheet (defaults to false)
include_oncosts: true (optional, boolean) - Whether to include on-cost additions (e.g. employer pension, levy) alongside existing costs. Requires show_costs=true. Adds oncosts_breakdown and cost_with_oncosts to each shift, and total_oncosts_breakdown and total_cost_with_oncosts to the timesheet. On-costs are calculated from the organisation’s on-cost configurations. For UK organisations, earnings-threshold rules (e.g. employer National Insurance) are applied using the full pay-period earnings - see the note above for details (defaults to false)
show_award_interpretation: true (optional, boolean) - Whether to show award interpretation for the timesheet (defaults to false)
show_notes: true (optional, boolean) - Whether 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: 1451570400 (optional, number) - Time filter to find recently created or modified timesheets
report_location_id: 111 (optional, number) - The 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: myob (optional, string) - The format in which timesheet data should be exported. See the Exporting Timesheets section above for more information.
skip_status_update: true (optional, boolean) - If true, timesheets will not have their status set to exported as part of the export. Default is false. Only used if export_format is provided.
approved_only: true (optional, boolean) - If true, only approved timesheets will be returned. Default is false.
200
OK
(application/json)
Attributes (array):
id: 7007 (required) (number) - The id of the timesheet
user_id: 123456 (required) (number) - The id of the user who worked the shift
start: 2016-02-29 (required) (string) - The start date of the timesheet
finish: 2016-03-14 (required) (string) - The end date of the timesheet
status: approved (required) (string) - One of pending, approved, exported
shifts (required) (array of ShiftData) - The shifts on the timesheet
total_cost: 102.15 (number) - The total cost of the timesheet, if show_costs=true parameter is set
total_oncosts_breakdown (array) - Per-configuration on-cost amounts across all shifts in the timesheet (e.g. [{"name": "Superannuation", "amount": 10.22}, {"name": "Workcover", "amount": 2.04}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the employee are included, so the array can be empty. For UK organisations, earnings-threshold rules (such as employer National Insurance) are evaluated using the employee’s full pay-period cost normalised to a monthly equivalent and appear with an amount of 0.0 when the employee is below the threshold.
total_cost_with_oncosts: 114.41 (number) - The total timesheet cost including all on-costs, if show_costs=true and include_oncosts=true parameters are set
award_interpretation (array of AwardInterpretationData) - Award interpretation output, if show_award_interpretation=true parameter is set
notes: (optional, array[NoteData]) - Notes on the timesheet
Timesheets on Date [/api/v2/timesheets/on/{date}]
GETGet Timesheets on Date
If you are using show_costs=true or show_award_interpretation=true, the cost scope is required.
Parameters
date: 2016-03-02 (date) - The date included in the timesheet to find
show_costs: true (optional, boolean) - Whether to show the costs for the timesheet (defaults to false)
include_oncosts: true (optional, boolean) - Whether to include on-cost additions (e.g. employer pension, levy) alongside existing costs. Requires show_costs=true. Adds oncosts_breakdown and cost_with_oncosts to each shift, and total_oncosts_breakdown and total_cost_with_oncosts to the timesheet. On-costs are calculated from the organisation’s on-cost configurations. For UK organisations, earnings-threshold rules (e.g. employer National Insurance) are applied using the full pay-period earnings - see the note above for details (defaults to false)
show_award_interpretation: true (optional, boolean) - Whether to show award interpretation for the timesheet (defaults to false)
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified timesheets
report_location_id: 111 (optional, number) - The 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: myob (optional, string) - The format in which timesheet data should be exported. See the Exporting Timesheets section above for more information.
skip_status_update: true (optional, boolean) - If true, timesheets will not have their status set to exported as part of the export. Default is false. Only used if export_format is provided.
approved_only: true (optional, boolean) - If true, only approved timesheets will be returned. Default is false.
page: 1 (optional, number) - The page number for your timesheet list
page_size: 50 (optional, number) - The number of timesheets retrieved per page. The maximum is 100 timesheets per request.
200
OK
(application/json)
Attributes (array):
id: 7007 (required) (number) - The id of the timesheet
user_id: 123456 (required) (number) - The id of the user who worked the shift
start: 2016-02-29 (required) (string) - The start date of the timesheet
finish: 2016-03-14 (required) (string) - The end date of the timesheet
status: approved (required) (string) - One of pending, approved, exported
shifts (required) (array of ShiftData) - The shifts on the timesheet
total_cost: 102.15 (number) - The total cost of the timesheet, if show_costs=true parameter is set
total_oncosts_breakdown (array) - Per-configuration on-cost amounts across all shifts in the timesheet (e.g. [{"name": "Superannuation", "amount": 10.22}, {"name": "Workcover", "amount": 2.04}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the employee are included, so the array can be empty. For UK organisations, earnings-threshold rules (such as employer National Insurance) are evaluated using the employee’s full pay-period cost normalised to a monthly equivalent and appear with an amount of 0.0 when the employee is below the threshold.
total_cost_with_oncosts: 114.41 (number) - The total timesheet cost including all on-costs, if show_costs=true and include_oncosts=true parameters are set
award_interpretation (array of AwardInterpretationData) - Award interpretation output, if show_award_interpretation=true parameter is set
notes: (optional, array[NoteData]) - Notes on the timesheet
Current Timesheet for User [/api/v2/timesheets/for/{user_id}/current]
GETGet Current Timesheet for User
If you are using show_costs=true or show_award_interpretation=true, the cost scope is required.
Parameters
user_id: 123456 (number) - The user’s id, me can also be used to reference the current user
show_costs: true (optional, boolean) - Whether to show the costs for the timesheet (defaults to false)
include_oncosts: true (optional, boolean) - Whether to include on-cost additions (e.g. employer pension, levy) alongside existing costs. Requires show_costs=true. Adds oncosts_breakdown and cost_with_oncosts to each shift, and total_oncosts_breakdown and total_cost_with_oncosts to the timesheet. On-costs are calculated from the organisation’s on-cost configurations. For UK organisations, earnings-threshold rules (e.g. employer National Insurance) are applied using the full pay-period earnings - see the note above for details (defaults to false)
show_award_interpretation: true (optional, boolean) - Whether to show award interpretation for the timesheet (defaults to false)
approved_only: true (optional, boolean) - If true, only approved timesheets will be returned. Default is false.
200
OK
(application/json)
Attributes:
id: 7007 (required) (number) - The id of the timesheet
user_id: 123456 (required) (number) - The id of the user who worked the shift
start: 2016-02-29 (required) (string) - The start date of the timesheet
finish: 2016-03-14 (required) (string) - The end date of the timesheet
status: approved (required) (string) - One of pending, approved, exported
shifts (required) (array of ShiftData) - The shifts on the timesheet
total_cost: 102.15 (number) - The total cost of the timesheet, if show_costs=true parameter is set
total_oncosts_breakdown (array) - Per-configuration on-cost amounts across all shifts in the timesheet (e.g. [{"name": "Superannuation", "amount": 10.22}, {"name": "Workcover", "amount": 2.04}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the employee are included, so the array can be empty. For UK organisations, earnings-threshold rules (such as employer National Insurance) are evaluated using the employee’s full pay-period cost normalised to a monthly equivalent and appear with an amount of 0.0 when the employee is below the threshold.
total_cost_with_oncosts: 114.41 (number) - The total timesheet cost including all on-costs, if show_costs=true and include_oncosts=true parameters are set
award_interpretation (array of AwardInterpretationData) - Award interpretation output, if show_award_interpretation=true parameter is set
notes: (optional, array[NoteData]) - Notes on the timesheet
Timesheet for User on Date [/api/v2/timesheets/for/{user_id}/on/{date}]
GETGet Timesheet for User on Date
If you are using show_costs=true or show_award_interpretation=true, the cost scope is required.
Parameters
user_id: 123456 (number) - The user’s id, me can also be used to reference the current user
date: 2016-03-02 (date) - The date included in the timesheet to find
show_costs: true (optional, boolean) - Whether to show the costs for the timesheet (defaults to false)
include_oncosts: true (optional, boolean) - Whether to include on-cost additions (e.g. employer pension, levy) alongside existing costs. Requires show_costs=true. Adds oncosts_breakdown and cost_with_oncosts to each shift, and total_oncosts_breakdown and total_cost_with_oncosts to the timesheet. On-costs are calculated from the organisation’s on-cost configurations. For UK organisations, earnings-threshold rules (e.g. employer National Insurance) are applied using the full pay-period earnings - see the note above for details (defaults to false)
show_award_interpretation: true (optional, boolean) - Whether to show award interpretation for the timesheet (defaults to false)
approved_only: true (optional, boolean) - If true, only approved timesheets will be returned. Default is false.
200
OK
(application/json)
Attributes:
id: 7007 (required) (number) - The id of the timesheet
user_id: 123456 (required) (number) - The id of the user who worked the shift
start: 2016-02-29 (required) (string) - The start date of the timesheet
finish: 2016-03-14 (required) (string) - The end date of the timesheet
status: approved (required) (string) - One of pending, approved, exported
shifts (required) (array of ShiftData) - The shifts on the timesheet
total_cost: 102.15 (number) - The total cost of the timesheet, if show_costs=true parameter is set
total_oncosts_breakdown (array) - Per-configuration on-cost amounts across all shifts in the timesheet (e.g. [{"name": "Superannuation", "amount": 10.22}, {"name": "Workcover", "amount": 2.04}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the employee are included, so the array can be empty. For UK organisations, earnings-threshold rules (such as employer National Insurance) are evaluated using the employee’s full pay-period cost normalised to a monthly equivalent and appear with an amount of 0.0 when the employee is below the threshold.
total_cost_with_oncosts: 114.41 (number) - The total timesheet cost including all on-costs, if show_costs=true and include_oncosts=true parameters are set
award_interpretation (array of AwardInterpretationData) - Award interpretation output, if show_award_interpretation=true parameter is set
notes: (optional, array[NoteData]) - Notes on the timesheet
Timesheet [/api/v2/timesheets/{id}]
GETGet Timesheet
If you are using show_costs=true or show_award_interpretation=true, the cost scope is required.
Parameters
id: 7007 (number) - The id of the timesheet
show_costs: true (optional, boolean) - Whether to show the costs for the timesheet (defaults to false)
include_oncosts: true (optional, boolean) - Whether to include on-cost additions (e.g. employer pension, levy) alongside existing costs. Requires show_costs=true. Adds oncosts_breakdown and cost_with_oncosts to each shift, and total_oncosts_breakdown and total_cost_with_oncosts to the timesheet. On-costs are calculated from the organisation’s on-cost configurations. For UK organisations, earnings-threshold rules (e.g. employer National Insurance) are applied using the full pay-period earnings - see the note above for details (defaults to false)
show_award_interpretation: true (optional, boolean) - Whether to show award interpretation for the timesheet (defaults to false)
show_notes: true (optional, boolean) - Whether to show notes for the timesheet (defaults to false)
approved_only: true (optional, boolean) - If true, only approved timesheets will be returned. Default is false.
200
OK
(application/json)
Attributes:
id: 7007 (required) (number) - The id of the timesheet
user_id: 123456 (required) (number) - The id of the user who worked the shift
start: 2016-02-29 (required) (string) - The start date of the timesheet
finish: 2016-03-14 (required) (string) - The end date of the timesheet
status: approved (required) (string) - One of pending, approved, exported
shifts (required) (array of ShiftData) - The shifts on the timesheet
total_cost: 102.15 (number) - The total cost of the timesheet, if show_costs=true parameter is set
total_oncosts_breakdown (array) - Per-configuration on-cost amounts across all shifts in the timesheet (e.g. [{"name": "Superannuation", "amount": 10.22}, {"name": "Workcover", "amount": 2.04}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the employee are included, so the array can be empty. For UK organisations, earnings-threshold rules (such as employer National Insurance) are evaluated using the employee’s full pay-period cost normalised to a monthly equivalent and appear with an amount of 0.0 when the employee is below the threshold.
total_cost_with_oncosts: 114.41 (number) - The total timesheet cost including all on-costs, if show_costs=true and include_oncosts=true parameters are set
award_interpretation (array of AwardInterpretationData) - Award interpretation output, if show_award_interpretation=true parameter is set
notes: (optional, array[NoteData]) - Notes on the timesheet
PUTUpdate Timesheet
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.

Parameters
id: 7007 (number) - The id of the timesheet
Request Update Timesheet (application/json)
Body

    {
      "status": "pending"
    }

200
OK
(application/json)
Attributes:
id: 7007 (required) (number) - The id of the timesheet
user_id: 123456 (required) (number) - The id of the user who worked the shift
start: 2016-02-29 (required) (string) - The start date of the timesheet
finish: 2016-03-14 (required) (string) - The end date of the timesheet
status: approved (required) (string) - One of pending, approved, exported
shifts (required) (array of ShiftData) - The shifts on the timesheet
total_cost: 102.15 (number) - The total cost of the timesheet, if show_costs=true parameter is set
total_oncosts_breakdown (array) - Per-configuration on-cost amounts across all shifts in the timesheet (e.g. [{"name": "Superannuation", "amount": 10.22}, {"name": "Workcover", "amount": 2.04}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the employee are included, so the array can be empty. For UK organisations, earnings-threshold rules (such as employer National Insurance) are evaluated using the employee’s full pay-period cost normalised to a monthly equivalent and appear with an amount of 0.0 when the employee is below the threshold.
total_cost_with_oncosts: 114.41 (number) - The total timesheet cost including all on-costs, if show_costs=true and include_oncosts=true parameters are set
award_interpretation (array of AwardInterpretationData) - Award interpretation output, if show_award_interpretation=true parameter is set
notes: (optional, array[NoteData]) - Notes on 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.
On-cost amounts are estimates
On-cost amounts are estimates. They are calculated by applying the organisation’s on-cost configurations to award-interpreted wage costs, consistent with Workforce’s cost reports. They are not statutory payroll calculations. For example, employer National Insurance is estimated as the configured percentage of all eligible cost rather than HMRC’s banded calculation on earnings above the threshold, and superannuation rules that depend on age or contribution caps are not applied. Use payroll data for exact figures.

Some on-cost configurations only apply once an employee’s earnings pass a threshold (such as employer National Insurance). Eligibility can only be assessed against the employee’s full pay period, so these configurations are not included in oncosts_breakdown or cost_with_oncosts on the shifts endpoint for UK organisations. Use the timesheets endpoint for threshold-aware on-costs.

On-cost configurations restricted to ordinary hours return 0.0 for leave shifts. Configurations that are not restricted still apply to leave shifts.

Shifts [/api/v2/shifts]
GETGet Shifts
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.

Parameters
ids: 1,2,1337 (optional, string) - Comma separated list of shift IDs
user_ids: 1,2,123456 (optional, string) - Comma separated list of user IDs
from: 2016-03-02 (optional, string) - From date to lookup shifts in
to: 2016-03-02 (optional, string) - To date to lookup shifts in
show_costs: true (optional, boolean) - Whether to show the costs for the shift (defaults to false)
include_oncosts: true (optional, boolean) - Whether to include on-cost additions (e.g. employer pension, levy) alongside existing costs. Requires show_costs=true. Adds oncosts_breakdown and cost_with_oncosts to each shift. On-costs are calculated from the organisation’s on-cost configurations (defaults to false)
show_award_interpretation: true (optional, boolean) - Whether to show award interpretation for the shifts (defaults to false)
show_activities: false (optional, boolean) - If true, the activities within each shift will be included in the response, each with its activity_code/activity_code_id and prorated worked hours. With show_costs=true (and the cost scope) each activity also includes its derived cost. With include_names=true, each activity also includes the activity code’s name. Defaults to false.
include_names: false (optional, boolean) - If true, the team name, location name, and user name (not just IDs) will be included in the response. Defaults to false.
show_associated_tag: true (optional, boolean) - Whether to show the associated tag for the shifts (defaults to false)

show_notes: true (optional, boolean) - Whether to show notes for the shifts (defaults to false)
report_location_id: 111 (optional, number) - The 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 with report_location_id=A will return that user’s shifts worked at location B.
platform: false (optional, boolean) - If true, Platform data will be returned (defaults to false).
page: 1 (optional, number) - The page number for your shifts list
page_size: 50 (optional, number) - The number of shifts retrieved per page. The maximum is 100 shifts per request.
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified shifts
200
OK
(application/json)
Attributes (array):
id: 1337 (required) (number) - The id of the shift
timesheet_id: 7007 (required) (number) - The id of the timesheet that the shift belongs on
user_id: 123456 (required) (number) - The id of the user who worked the shift
date: 2016-03-02 (required) (string) - The date the shift was worked
start: 1456902118 (number) - The start of the shift
break_start: 1456908143 (number) - The start of the break
break_finish: 1456909812 (number) - The end of the break
break_length: 27 (number) - The length of the break in minutes (NOTE: this can be different to (break_start - break_finish) / 60, see Shifts section)
breaks: (optional, array[ShiftBreakData]) - The shift’s breaks
finish: 1456916286 (number) - The end of the shift
status: PENDING (required) (string) - One of PENDING, APPROVED
allowances (required) (array of AllowanceData) - The allowances that apply to the shift
tag: Head Technician (string) - The name of the tag on the shift (can use tag_id instead)
tag_id: 65421 (number) - The id of the tag on the shift (can use tag instead)
cost: 20.1 (number) - The cost of the shift, if show_costs=true parameter is set
oncosts_breakdown (array) - Per-configuration on-cost amounts for this shift (e.g. [{"name": "Superannuation", "amount": 2.01}, {"name": "Workcover", "amount": 0.40}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the shift’s employee and location are included, so the array can be empty. Configurations restricted to ordinary hours return 0.0 for leave shifts. On the shifts endpoint, UK earnings-threshold on-costs (such as employer National Insurance) are not included. The timesheets endpoint assesses these against the whole pay period.
cost_with_oncosts: 22.51 (number) - The cost of the shift including on-costs, if show_costs=true and include_oncosts=true parameters are set
award_interpretation (array of AwardInterpretationData) - Award interpretation output, if show_award_interpretation=true parameter is set
department_id: 808 (number) - The ID for the team this shift was worked in
department_name: Front of House (string) - The name of the team this shift was worked in, included only if include_names=true
location_name: Brisbane CBD (string) - The name of the location this shift was worked at, included only if include_names=true
user_name: Jane Smith (string) - The name of the user who worked the shift, included only if include_names=true
metadata: My special metadata (string) - Custom string field that holds up to 500 characters
leave_request_id: 333 (number) - The ID for the leave request, if leave was taken, otherwise null.
record_id: 532432 (number) - The record ID, for use with Platform endpoints
approved_by: 123455 (number) - The ID of the user that approved the shift
approved_at: 1456988518 (string) - The time the shift was approved
notes: (optional, array[NoteData]) - Notes on the shift
activity_code_id: 7 (number) - The shift’s own (fallback) activity code id, applied to worked time not covered by any activity, or null. Included (with the activity_code string) when show_activities=true; the name is included under include_names
activities (array of ShiftActivityData) - The activities within the shift, if show_activities=true parameter is set
POSTCreate Shift
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.

The optional activities array creates ShiftActivityData activities within the shift. Each entry has a start, finish, and optional activity_code_id (which must belong to the same organisation). See Update Shift for how activities are reconciled on update.
The optional top-level activity_code_id sets the shift’s own (fallback) activity code — applied to worked time not covered by any activity. The code must belong to the organisation, be unarchived, and apply to the shift’s team. On update, pass null to clear it.
This method requires the timesheet scope (see Scopes for more information).
Request Create Shift (application/json)
Body

    {
      "user_id": 123456,
      "date": "2016-03-12",
      "start": 1457741040,
      "finish": 1457762640,
      "department_id": 808,
      "metadata": "My special metadata",
      "activities": [
        {
          "start": 1457743200,
          "finish": 1457746800,
          "activity_code_id": 7
        }
      ]
    }

200
OK
(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

Attributes:
id: 1337 (required) (number) - The id of the shift
timesheet_id: 7007 (required) (number) - The id of the timesheet that the shift belongs on
user_id: 123456 (required) (number) - The id of the user who worked the shift
date: 2016-03-02 (required) (string) - The date the shift was worked
start: 1456902118 (number) - The start of the shift
break_start: 1456908143 (number) - The start of the break
break_finish: 1456909812 (number) - The end of the break
break_length: 27 (number) - The length of the break in minutes (NOTE: this can be different to (break_finish - break_start) / 60, see Shifts section)
finish: 1456916286 (number) - The end of the shift
status: PENDING (required) (string) - One of PENDING, APPROVED
allowances (required) (array of AllowanceData) - The allowances that apply to the shift
tag: Head Technician (string) - The name of the tag on the shift (can use tag_id instead)
tag_id: 65421 (number) - The id of the tag on the shift (can use tag instead)
department_id: 808 (number) - The ID for the team this shift was worked in
record_id: 532432 (number) - the record ID, for use with Platform endpoints
id: (number)
Request Create Shift with breaks (application/json)
Body

    {
      "user_id": 123456,
      "date": "2016-03-12",
      "start": 1457741040,
      "finish": 1457762640,
      "break_start": 1457751660,
      "break_finish": 1457753280,
      "metadata": "My special metadata"
    }

200
OK
(application/json)
Attributes:
id: 1337 (required) (number) - The id of the shift
timesheet_id: 7007 (required) (number) - The id of the timesheet that the shift belongs on
user_id: 123456 (required) (number) - The id of the user who worked the shift
date: 2016-03-02 (required) (string) - The date the shift was worked
start: 1456902118 (number) - The start of the shift
break_start: 1456908143 (number) - The start of the break
break_finish: 1456909812 (number) - The end of the break
break_length: 27 (number) - The length of the break in minutes (NOTE: this can be different to (break_finish - break_start) / 60, see Shifts section)
finish: 1456916286 (number) - The end of the shift
status: PENDING (required) (string) - One of PENDING, APPROVED
allowances (required) (array of AllowanceData) - The allowances that apply to the shift
tag: Head Technician (string) - The name of the tag on the shift (can use tag_id instead)
tag_id: 65421 (number) - The id of the tag on the shift (can use tag instead)
department_id: 808 (number) - The ID for the team this shift was worked in
record_id: 532432 (number) - the record ID, for use with Platform endpoints
id: 9665 (number)
timesheet_id: 7007 (number)
user_id: 123456 (number)
date: 2016-03-12
start: 1457741040 (number)
break_start: 1457751660 (number)
break_finish: 1457753280 (number)
break_length: 27 (number)
finish: 1457762640 (number)
status: PENDING
allowances: (array)
metadata: My special metadata
Request Create approved Shift (application/json)
Body

    {
      "user_id": 123456,
      "date": "2016-03-12",
      "start": 1457741040,
      "finish": 1457762640,
      "status": "APPROVED",
      "tag": null
    }

200
OK
(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

Attributes:
id: 1337 (required) (number) - The id of the shift
timesheet_id: 7007 (required) (number) - The id of the timesheet that the shift belongs on
user_id: 123456 (required) (number) - The id of the user who worked the shift
date: 2016-03-02 (required) (string) - The date the shift was worked
start: 1456902118 (number) - The start of the shift
break_start: 1456908143 (number) - The start of the break
break_finish: 1456909812 (number) - The end of the break
break_length: 27 (number) - The length of the break in minutes (NOTE: this can be different to (break_finish - break_start) / 60, see Shifts section)
finish: 1456916286 (number) - The end of the shift
status: PENDING (required) (string) - One of PENDING, APPROVED
allowances (required) (array of AllowanceData) - The allowances that apply to the shift
tag: Head Technician (string) - The name of the tag on the shift (can use tag_id instead)
tag_id: 65421 (number) - The id of the tag on the shift (can use tag instead)
department_id: 808 (number) - The ID for the team this shift was worked in
record_id: 532432 (number) - the record ID, for use with Platform endpoints
id: (number)
Request Create Shift with Allowances (application/json)
Body

    {
      "user_id": 123456,
      "date": "2016-03-12",
      "start": 1457741040,
      "finish": 1457762640,
      "allowances": [
        {
          "id": 987654,
          "value": 1
        }
      ]
    }

200
OK
(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

Attributes:
id: 1337 (required) (number) - The id of the shift
timesheet_id: 7007 (required) (number) - The id of the timesheet that the shift belongs on
user_id: 123456 (required) (number) - The id of the user who worked the shift
date: 2016-03-02 (required) (string) - The date the shift was worked
start: 1456902118 (number) - The start of the shift
break_start: 1456908143 (number) - The start of the break
break_finish: 1456909812 (number) - The end of the break
break_length: 27 (number) - The length of the break in minutes (NOTE: this can be different to (break_finish - break_start) / 60, see Shifts section)
finish: 1456916286 (number) - The end of the shift
status: PENDING (required) (string) - One of PENDING, APPROVED
allowances (required) (array of AllowanceData) - The allowances that apply to the shift
tag: Head Technician (string) - The name of the tag on the shift (can use tag_id instead)
tag_id: 65421 (number) - The id of the tag on the shift (can use tag instead)
department_id: 808 (number) - The ID for the team this shift was worked in
record_id: 532432 (number) - the record ID, for use with Platform endpoints
id: (number)
Shift [/api/v2/shifts/{id}]
GETGet Shift
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.

Parameters
id: 1337 (number) - The id of the shift
show_costs: true (optional, boolean) - Whether to show the costs for the shift (defaults to false)
include_oncosts: true (optional, boolean) - Whether to include on-cost additions (e.g. employer pension, levy) alongside existing costs. Requires show_costs=true. Adds oncosts_breakdown and cost_with_oncosts to each shift. On-costs are calculated from the organisation’s on-cost configurations (defaults to false)
show_award_interpretation: true (optional, boolean) - Whether to show award interpretation for the shift (defaults to false)
show_activities: false (optional, boolean) - If true, the activities within the shift will be included in the response, each with its activity_code/activity_code_id and prorated worked hours. With show_costs=true (and the cost scope) each activity also includes its derived cost. With include_names=true, each activity also includes the activity code’s name. Defaults to false.
include_names: false (optional, boolean) - If true, the team name, location name, and user name (not just IDs) will be included in the response. Defaults to false.
show_associated_tag: true (optional, boolean) - Whether to show the associated tag for the shifts (defaults to false)

show_notes: true (optional, boolean) - Whether to show notes for the shift (defaults to false)
show_export_name: true (optional, boolean) - Whether to show the department’s export code that the employee worked on the shift (defaults to false)
platform: false (optional, boolean) - If true, Platform data will be returned (defaults to false).
200
OK
(application/json)
Attributes:
id: 1337 (required) (number) - The id of the shift
timesheet_id: 7007 (required) (number) - The id of the timesheet that the shift belongs on
user_id: 123456 (required) (number) - The id of the user who worked the shift
date: 2016-03-02 (required) (string) - The date the shift was worked
start: 1456902118 (number) - The start of the shift
break_start: 1456908143 (number) - The start of the break
break_finish: 1456909812 (number) - The end of the break
break_length: 27 (number) - The length of the break in minutes (NOTE: this can be different to (break_start - break_finish) / 60, see Shifts section)
breaks: (optional, array[ShiftBreakData]) - The shift’s breaks
finish: 1456916286 (number) - The end of the shift
status: PENDING (required) (string) - One of PENDING, APPROVED
allowances (required) (array of AllowanceData) - The allowances that apply to the shift
tag: Head Technician (string) - The name of the tag on the shift (can use tag_id instead)
tag_id: 65421 (number) - The id of the tag on the shift (can use tag instead)
cost: 20.1 (number) - The cost of the shift, if show_costs=true parameter is set
oncosts_breakdown (array) - Per-configuration on-cost amounts for this shift (e.g. [{"name": "Superannuation", "amount": 2.01}, {"name": "Workcover", "amount": 0.40}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the shift’s employee and location are included, so the array can be empty. Configurations restricted to ordinary hours return 0.0 for leave shifts. On the shifts endpoint, UK earnings-threshold on-costs (such as employer National Insurance) are not included. The timesheets endpoint assesses these against the whole pay period.
cost_with_oncosts: 22.51 (number) - The cost of the shift including on-costs, if show_costs=true and include_oncosts=true parameters are set
award_interpretation (array of AwardInterpretationData) - Award interpretation output, if show_award_interpretation=true parameter is set
department_id: 808 (number) - The ID for the team this shift was worked in
department_name: Front of House (string) - The name of the team this shift was worked in, included only if include_names=true
location_name: Brisbane CBD (string) - The name of the location this shift was worked at, included only if include_names=true
user_name: Jane Smith (string) - The name of the user who worked the shift, included only if include_names=true
metadata: My special metadata (string) - Custom string field that holds up to 500 characters
leave_request_id: 333 (number) - The ID for the leave request, if leave was taken, otherwise null.
record_id: 532432 (number) - The record ID, for use with Platform endpoints
approved_by: 123455 (number) - The ID of the user that approved the shift
approved_at: 1456988518 (string) - The time the shift was approved
notes: (optional, array[NoteData]) - Notes on the shift
activity_code_id: 7 (number) - The shift’s own (fallback) activity code id, applied to worked time not covered by any activity, or null. Included (with the activity_code string) when show_activities=true; the name is included under include_names
activities (array of ShiftActivityData) - The activities within the shift, if show_activities=true parameter is set
PUTUpdate Shift
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.
Passing activities replaces the shift’s activities with the supplied set: entries are matched to existing activities by their time window (start and finish). A matched entry updates that activity’s activity_code_id in place (the activity is kept, not recreated), unmatched existing activities are removed, and entries with a new window are created. Pass [] to clear all activities. Omit the key to leave activities unchanged.
The top-level activity_code_id sets the shift’s own (fallback) activity code, applied to worked time not covered by any activity. Pass null to clear it.
This method requires the timesheet scope (see Scopes for more information).
Parameters
id: 1337 (number) - The id of the shift
Request Approve Shift (application/json)
Body

    {
      "status": "APPROVED"
    }

200
OK
(application/json)
Attributes:
id: 1337 (required) (number) - The id of the shift
timesheet_id: 7007 (required) (number) - The id of the timesheet that the shift belongs on
user_id: 123456 (required) (number) - The id of the user who worked the shift
date: 2016-03-02 (required) (string) - The date the shift was worked
start: 1456902118 (number) - The start of the shift
break_start: 1456908143 (number) - The start of the break
break_finish: 1456909812 (number) - The end of the break
break_length: 27 (number) - The length of the break in minutes (NOTE: this can be different to (break_start - break_finish) / 60, see Shifts section)
breaks: (optional, array[ShiftBreakData]) - The shift’s breaks
finish: 1456916286 (number) - The end of the shift
status: PENDING (required) (string) - One of PENDING, APPROVED
allowances (required) (array of AllowanceData) - The allowances that apply to the shift
tag: Head Technician (string) - The name of the tag on the shift (can use tag_id instead)
tag_id: 65421 (number) - The id of the tag on the shift (can use tag instead)
cost: 20.1 (number) - The cost of the shift, if show_costs=true parameter is set
oncosts_breakdown (array) - Per-configuration on-cost amounts for this shift (e.g. [{"name": "Superannuation", "amount": 2.01}, {"name": "Workcover", "amount": 0.40}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the shift’s employee and location are included, so the array can be empty. Configurations restricted to ordinary hours return 0.0 for leave shifts. On the shifts endpoint, UK earnings-threshold on-costs (such as employer National Insurance) are not included. The timesheets endpoint assesses these against the whole pay period.
cost_with_oncosts: 22.51 (number) - The cost of the shift including on-costs, if show_costs=true and include_oncosts=true parameters are set
award_interpretation (array of AwardInterpretationData) - Award interpretation output, if show_award_interpretation=true parameter is set
department_id: 808 (number) - The ID for the team this shift was worked in
department_name: Front of House (string) - The name of the team this shift was worked in, included only if include_names=true
location_name: Brisbane CBD (string) - The name of the location this shift was worked at, included only if include_names=true
user_name: Jane Smith (string) - The name of the user who worked the shift, included only if include_names=true
metadata: My special metadata (string) - Custom string field that holds up to 500 characters
leave_request_id: 333 (number) - The ID for the leave request, if leave was taken, otherwise null.
record_id: 532432 (number) - The record ID, for use with Platform endpoints
approved_by: 123455 (number) - The ID of the user that approved the shift
approved_at: 1456988518 (string) - The time the shift was approved
notes: (optional, array[NoteData]) - Notes on the shift
activity_code_id: 7 (number) - The shift’s own (fallback) activity code id, applied to worked time not covered by any activity, or null. Included (with the activity_code string) when show_activities=true; the name is included under include_names
activities (array of ShiftActivityData) - The activities within the shift, if show_activities=true parameter is set
status: APPROVED
Request Update Shift times (application/json)
Body

    {
      "start": 1456901518,
      "finish": 1456916886
    }

200
OK
(application/json)
Attributes:
id: 1337 (required) (number) - The id of the shift
timesheet_id: 7007 (required) (number) - The id of the timesheet that the shift belongs on
user_id: 123456 (required) (number) - The id of the user who worked the shift
date: 2016-03-02 (required) (string) - The date the shift was worked
start: 1456902118 (number) - The start of the shift
break_start: 1456908143 (number) - The start of the break
break_finish: 1456909812 (number) - The end of the break
break_length: 27 (number) - The length of the break in minutes (NOTE: this can be different to (break_start - break_finish) / 60, see Shifts section)
breaks: (optional, array[ShiftBreakData]) - The shift’s breaks
finish: 1456916286 (number) - The end of the shift
status: PENDING (required) (string) - One of PENDING, APPROVED
allowances (required) (array of AllowanceData) - The allowances that apply to the shift
tag: Head Technician (string) - The name of the tag on the shift (can use tag_id instead)
tag_id: 65421 (number) - The id of the tag on the shift (can use tag instead)
cost: 20.1 (number) - The cost of the shift, if show_costs=true parameter is set
oncosts_breakdown (array) - Per-configuration on-cost amounts for this shift (e.g. [{"name": "Superannuation", "amount": 2.01}, {"name": "Workcover", "amount": 0.40}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the shift’s employee and location are included, so the array can be empty. Configurations restricted to ordinary hours return 0.0 for leave shifts. On the shifts endpoint, UK earnings-threshold on-costs (such as employer National Insurance) are not included. The timesheets endpoint assesses these against the whole pay period.
cost_with_oncosts: 22.51 (number) - The cost of the shift including on-costs, if show_costs=true and include_oncosts=true parameters are set
award_interpretation (array of AwardInterpretationData) - Award interpretation output, if show_award_interpretation=true parameter is set
department_id: 808 (number) - The ID for the team this shift was worked in
department_name: Front of House (string) - The name of the team this shift was worked in, included only if include_names=true
location_name: Brisbane CBD (string) - The name of the location this shift was worked at, included only if include_names=true
user_name: Jane Smith (string) - The name of the user who worked the shift, included only if include_names=true
metadata: My special metadata (string) - Custom string field that holds up to 500 characters
leave_request_id: 333 (number) - The ID for the leave request, if leave was taken, otherwise null.
record_id: 532432 (number) - The record ID, for use with Platform endpoints
approved_by: 123455 (number) - The ID of the user that approved the shift
approved_at: 1456988518 (string) - The time the shift was approved
notes: (optional, array[NoteData]) - Notes on the shift
activity_code_id: 7 (number) - The shift’s own (fallback) activity code id, applied to worked time not covered by any activity, or null. Included (with the activity_code string) when show_activities=true; the name is included under include_names
activities (array of ShiftActivityData) - The activities within the shift, if show_activities=true parameter is set
start: 1456901518 (number)
finish: 1456916886 (number)
Request Update Shift times on new date (application/json)
Body

    {
      "date": "2016-03-03",
      "start": 1456987918,
      "finish": 1457003286,
      "break_start": 1456994543,
      "break_finish": 1456996212
    }

200
OK
(application/json)
Attributes:
id: 1337 (required) (number) - The id of the shift
timesheet_id: 7007 (required) (number) - The id of the timesheet that the shift belongs on
user_id: 123456 (required) (number) - The id of the user who worked the shift
date: 2016-03-02 (required) (string) - The date the shift was worked
start: 1456902118 (number) - The start of the shift
break_start: 1456908143 (number) - The start of the break
break_finish: 1456909812 (number) - The end of the break
break_length: 27 (number) - The length of the break in minutes (NOTE: this can be different to (break_start - break_finish) / 60, see Shifts section)
breaks: (optional, array[ShiftBreakData]) - The shift’s breaks
finish: 1456916286 (number) - The end of the shift
status: PENDING (required) (string) - One of PENDING, APPROVED
allowances (required) (array of AllowanceData) - The allowances that apply to the shift
tag: Head Technician (string) - The name of the tag on the shift (can use tag_id instead)
tag_id: 65421 (number) - The id of the tag on the shift (can use tag instead)
cost: 20.1 (number) - The cost of the shift, if show_costs=true parameter is set
oncosts_breakdown (array) - Per-configuration on-cost amounts for this shift (e.g. [{"name": "Superannuation", "amount": 2.01}, {"name": "Workcover", "amount": 0.40}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the shift’s employee and location are included, so the array can be empty. Configurations restricted to ordinary hours return 0.0 for leave shifts. On the shifts endpoint, UK earnings-threshold on-costs (such as employer National Insurance) are not included. The timesheets endpoint assesses these against the whole pay period.
cost_with_oncosts: 22.51 (number) - The cost of the shift including on-costs, if show_costs=true and include_oncosts=true parameters are set
award_interpretation (array of AwardInterpretationData) - Award interpretation output, if show_award_interpretation=true parameter is set
department_id: 808 (number) - The ID for the team this shift was worked in
department_name: Front of House (string) - The name of the team this shift was worked in, included only if include_names=true
location_name: Brisbane CBD (string) - The name of the location this shift was worked at, included only if include_names=true
user_name: Jane Smith (string) - The name of the user who worked the shift, included only if include_names=true
metadata: My special metadata (string) - Custom string field that holds up to 500 characters
leave_request_id: 333 (number) - The ID for the leave request, if leave was taken, otherwise null.
record_id: 532432 (number) - The record ID, for use with Platform endpoints
approved_by: 123455 (number) - The ID of the user that approved the shift
approved_at: 1456988518 (string) - The time the shift was approved
notes: (optional, array[NoteData]) - Notes on the shift
activity_code_id: 7 (number) - The shift’s own (fallback) activity code id, applied to worked time not covered by any activity, or null. Included (with the activity_code string) when show_activities=true; the name is included under include_names
activities (array of ShiftActivityData) - The activities within the shift, if show_activities=true parameter is set
date: 2016-03-03
start: 1456987918 (number)
break_start: 1456994543 (number)
break_finish: 1456996212 (number)
finish: 1457003286 (number)
Request Update Shift allowances (application/json)
Body

    {
      "allowances": [
        {
          "id": 987654,
          "value": 1
        }
      ]
    }

200
OK
(application/json)
Attributes:
id: 1337 (required) (number) - The id of the shift
timesheet_id: 7007 (required) (number) - The id of the timesheet that the shift belongs on
user_id: 123456 (required) (number) - The id of the user who worked the shift
date: 2016-03-02 (required) (string) - The date the shift was worked
start: 1456902118 (number) - The start of the shift
break_start: 1456908143 (number) - The start of the break
break_finish: 1456909812 (number) - The end of the break
break_length: 27 (number) - The length of the break in minutes (NOTE: this can be different to (break_start - break_finish) / 60, see Shifts section)
breaks: (optional, array[ShiftBreakData]) - The shift’s breaks
finish: 1456916286 (number) - The end of the shift
status: PENDING (required) (string) - One of PENDING, APPROVED
allowances (required) (array of AllowanceData) - The allowances that apply to the shift
tag: Head Technician (string) - The name of the tag on the shift (can use tag_id instead)
tag_id: 65421 (number) - The id of the tag on the shift (can use tag instead)
cost: 20.1 (number) - The cost of the shift, if show_costs=true parameter is set
oncosts_breakdown (array) - Per-configuration on-cost amounts for this shift (e.g. [{"name": "Superannuation", "amount": 2.01}, {"name": "Workcover", "amount": 0.40}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the shift’s employee and location are included, so the array can be empty. Configurations restricted to ordinary hours return 0.0 for leave shifts. On the shifts endpoint, UK earnings-threshold on-costs (such as employer National Insurance) are not included. The timesheets endpoint assesses these against the whole pay period.
cost_with_oncosts: 22.51 (number) - The cost of the shift including on-costs, if show_costs=true and include_oncosts=true parameters are set
award_interpretation (array of AwardInterpretationData) - Award interpretation output, if show_award_interpretation=true parameter is set
department_id: 808 (number) - The ID for the team this shift was worked in
department_name: Front of House (string) - The name of the team this shift was worked in, included only if include_names=true
location_name: Brisbane CBD (string) - The name of the location this shift was worked at, included only if include_names=true
user_name: Jane Smith (string) - The name of the user who worked the shift, included only if include_names=true
metadata: My special metadata (string) - Custom string field that holds up to 500 characters
leave_request_id: 333 (number) - The ID for the leave request, if leave was taken, otherwise null.
record_id: 532432 (number) - The record ID, for use with Platform endpoints
approved_by: 123455 (number) - The ID of the user that approved the shift
approved_at: 1456988518 (string) - The time the shift was approved
notes: (optional, array[NoteData]) - Notes on the shift
activity_code_id: 7 (number) - The shift’s own (fallback) activity code id, applied to worked time not covered by any activity, or null. Included (with the activity_code string) when show_activities=true; the name is included under include_names
activities (array of ShiftActivityData) - The activities within the shift, if show_activities=true parameter is set
allowances (array)
(object)
id: 987654 (number)
value: 1 (number)
(object)
id: 456789 (number)
value: 0.5 (number)
cost: 1.75 (number)
Request Update Shift activities (application/json)
Body

    {
      "activity_code_id": 7,
      "activities": [
        {
          "start": 1456905600,
          "finish": 1456909200,
          "activity_code_id": 12
        }
      ]
    }

200
OK
(application/json)
Attributes:
id: 1337 (required) (number) - The id of the shift
timesheet_id: 7007 (required) (number) - The id of the timesheet that the shift belongs on
user_id: 123456 (required) (number) - The id of the user who worked the shift
date: 2016-03-02 (required) (string) - The date the shift was worked
start: 1456902118 (number) - The start of the shift
break_start: 1456908143 (number) - The start of the break
break_finish: 1456909812 (number) - The end of the break
break_length: 27 (number) - The length of the break in minutes (NOTE: this can be different to (break_start - break_finish) / 60, see Shifts section)
breaks: (optional, array[ShiftBreakData]) - The shift’s breaks
finish: 1456916286 (number) - The end of the shift
status: PENDING (required) (string) - One of PENDING, APPROVED
allowances (required) (array of AllowanceData) - The allowances that apply to the shift
tag: Head Technician (string) - The name of the tag on the shift (can use tag_id instead)
tag_id: 65421 (number) - The id of the tag on the shift (can use tag instead)
cost: 20.1 (number) - The cost of the shift, if show_costs=true parameter is set
oncosts_breakdown (array) - Per-configuration on-cost amounts for this shift (e.g. [{"name": "Superannuation", "amount": 2.01}, {"name": "Workcover", "amount": 0.40}]). Each entry has a name (the on-cost configuration’s name as entered in the organisation’s settings) and an amount. Names can change when a configuration is edited and are not unique, and configurations sharing a name appear as separate entries. Amounts are cost estimates, not statutory payroll calculations. Present if show_costs=true and include_oncosts=true and the organisation has on-cost configurations. Only configurations that cover the shift’s employee and location are included, so the array can be empty. Configurations restricted to ordinary hours return 0.0 for leave shifts. On the shifts endpoint, UK earnings-threshold on-costs (such as employer National Insurance) are not included. The timesheets endpoint assesses these against the whole pay period.
cost_with_oncosts: 22.51 (number) - The cost of the shift including on-costs, if show_costs=true and include_oncosts=true parameters are set
award_interpretation (array of AwardInterpretationData) - Award interpretation output, if show_award_interpretation=true parameter is set
department_id: 808 (number) - The ID for the team this shift was worked in
department_name: Front of House (string) - The name of the team this shift was worked in, included only if include_names=true
location_name: Brisbane CBD (string) - The name of the location this shift was worked at, included only if include_names=true
user_name: Jane Smith (string) - The name of the user who worked the shift, included only if include_names=true
metadata: My special metadata (string) - Custom string field that holds up to 500 characters
leave_request_id: 333 (number) - The ID for the leave request, if leave was taken, otherwise null.
record_id: 532432 (number) - The record ID, for use with Platform endpoints
approved_by: 123455 (number) - The ID of the user that approved the shift
approved_at: 1456988518 (string) - The time the shift was approved
notes: (optional, array[NoteData]) - Notes on the shift
activity_code_id: 7 (number) - The shift’s own (fallback) activity code id, applied to worked time not covered by any activity, or null. Included (with the activity_code string) when show_activities=true; the name is included under include_names
activities (array of ShiftActivityData) - The activities within the shift, if show_activities=true parameter is set
DELETEDelete Shift
This method requires the timesheet scope (see Scopes for more information).
Shifts can’t be deleted if their timesheet has already been exported.
Parameters
id: 1337 (number) - The id of the shift
200
OK
(application/json)
Active Status [/api/v2/shifts/active]
GETGet Active Shifts
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).
200
OK
(application/json)
Body [ {“user_id”: 123456, “shift_id”: 1337, “status”: “clocked_in”}, {“user_id”: 123457, “shift_id”: 1338, “status”: “on_break”} ]
Shift’s Applicable Allowances [/api/v2/shifts/{id}/applicable_allowances]
GETGet Shift’s 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).
Parameters
id: 1337 (number) - The id of the shift
200
OK
(application/json)
Attributes:
id: 456789 (required) (number) - The id of the allowance
name: Hazardous Environment Allowance (required, string) - The name of the allowance
export_name: HE Allowance (string) - The export name of the allowance
current_value: 0.5 (number) - How much of this allowance is currently applied to the shift
Shift Versions [/api/v2/shifts/{id}/versions]
GETGet Shift Versions
This method requires the timesheet scope (see Scopes for more information).
Parameters
id: 1337 (number) - The id of the shift
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified shift versions
200
OK
(application/json)
Attributes (array):
version_id: 123456 (number)
time: 1459209907 (number)
event: update
author (object)
id: 123456 (number)
name: API v2
item_id: 1235435 (number)
item_type: “Shift” (string)
changes (array)
(object)
field: finish
previous: 1456916286 (number)
updated: 1456916300 (number)
(object)
field: status
previous: PENDING
updated: APPROVED
Shift Breaks [/api/v2/shifts/{shift_id}/breaks]
Shift breaks represent a break in a Shift. A shift can have many breaks.

Shift breaks inherit access permissions from their parent shift.
All shift break actions require the timesheet scope (see Scopes for more information).

GETGet Shift’s Breaks
Parameters
shift_id: 1337 (number) - The id of the shift
200
OK
(application/json)
Attributes (array):
id: 42 (required) (number) - The id of the break
shift_id: 1337 (required) (number) - The id of the break’s shift
start: 1456908143 (number) - The start of the break
finish: 1456909812 (number) - The end of the break
length: 27 (number) - The length of the break in minutes (NOTE: this can be different to (break_start - break_finish) / 60, see Shifts section)
paid: false (boolean) - Whether the break is a paid break
selected_automatic_break_id: 73647 (number) - The id of the automatic break rule chosen to correspond to this shift break by the employee when they clocked in
POSTCreate Shift Break
Parameters
shift_id: 1337 (number) - The id of the shift
Request Create with times (application/json)
Body

    {
      "start": 1456908143,
      "finish": 1456909812,
    }

201
Created
(application/json)
Attributes:
id: 42 (required) (number) - The id of the break
shift_id: 1337 (required) (number) - The id of the break’s shift
start: 1456908143 (number) - The start of the break
finish: 1456909812 (number) - The end of the break
length: 27 (number) - The length of the break in minutes (NOTE: this can be different to (break_start - break_finish) / 60, see Shifts section)
paid: false (boolean) - Whether the break is a paid break
selected_automatic_break_id: 73647 (number) - The id of the automatic break rule chosen to correspond to this shift break by the employee when they clocked in
Request Create with length (application/json)
Body

    {
      "length": 45,
    }

201
Created
(application/json)
Body

    {
      "id": 42,
      "shift_id": 1337,
      "start": null,
      "finish": null,
      "length": 45,
      "paid": false,
    }

Request Create with paid (application/json)
Body

    {
      "paid": true,
    }

201
Created
(application/json)
Body

    {
      "id": 42,
      "shift_id": 1337,
      "start": null,
      "finish": null,
      "length": 45,
      "paid": true,
    }

Shift Break [/api/v2/shifts/{shift_id}/breaks/{break_id}]
Shift breaks represent a break in a Shift. A shift can have many breaks.

Shift breaks inherit access permissions from their parent shift.
All shift break actions require the timesheet scope (see Scopes for more information).

GETGet Shift Break
Parameters
shift_id: 1337 (number) - The id of the shift
break_id: 42 (number) - The id of the break
200
OK
(application/json)
Attributes:
id: 42 (required) (number) - The id of the break
shift_id: 1337 (required) (number) - The id of the break’s shift
start: 1456908143 (number) - The start of the break
finish: 1456909812 (number) - The end of the break
length: 27 (number) - The length of the break in minutes (NOTE: this can be different to (break_start - break_finish) / 60, see Shifts section)
paid: false (boolean) - Whether the break is a paid break
selected_automatic_break_id: 73647 (number) - The id of the automatic break rule chosen to correspond to this shift break by the employee when they clocked in
PUTUpdate Shift Break
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.

Parameters
shift_id: 1337 (number) - The id of the shift
break_id: 42 (number) - The id of the break
Request update shift break (application/json)
Body

    {
      "start": 1456908143
    }

200
OK
(application/json)
Attributes:
id: 42 (required) (number) - The id of the break
shift_id: 1337 (required) (number) - The id of the break’s shift
start: 1456908143 (number) - The start of the break
finish: 1456909812 (number) - The end of the break
length: 27 (number) - The length of the break in minutes (NOTE: this can be different to (break_start - break_finish) / 60, see Shifts section)
paid: false (boolean) - Whether the break is a paid break
selected_automatic_break_id: 73647 (number) - The id of the automatic break rule chosen to correspond to this shift break by the employee when they clocked in
Shift Break Versions [/api/v2/shifts/{shift_id}/breaks/{break_id}/versions]
GETGet Shift Break Versions
This method requires the timesheet scope (see Scopes for more information).
Parameters
id: 1337 (number) - The id of the shift
break_id: 42 (number) - The id of the break
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified shift break versions
200
OK
(application/json)
Attributes (array):
version_id: 123456 (number)
time: 1459209907 (number)
event: update
author (object)
id: 123456 (number)
name: API v2
item_id: 1235435 (number)
item_type: “ShiftBreak” (string)
changes (array)
(object)
field: break_finish
previous: 1456916286 (number)
updated: 1456916300 (number)
Shift Limits [/api/v2/shifts/limits?user_ids=123456,987654]
GETGet Shift Limits
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.

Parameters
user_ids: 123456,987654 (string) - Comma separated list of user IDs
include_names: false (optional, boolean) - If true, the team name, location name, and user name (not just IDs) will be included in the response. Defaults to false.
Response
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",
            "name": "Full Time Weekday Ordinary Hours",
            "export_name": "ORD 1x",
            "secondary_export_name": "PEN10",
            "ordinary_hours": true,
            "cost": 16.125,
            "base_rate_name": "09.232403.06 Base Hourly Level 1 20+ Years",
            "base_rate_export_name": "Base Hourly Level 1 20+ Years",
            "base_rate": 23.23,
            "from": 1456902000,
            "to": 1456916400
          }
        ],
        "department_id": 808,
        "department_export_name": "abc123",
        "employee_id":  "111"
        "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",
            "name": "Full Time Weekday Ordinary Hours",
            "export_name": "ORD 1x",
            "ordinary_hours": true,
            "cost": 16.125,
            "base_rate_name": "09.232403.06 Base Hourly Level 1 20+ Years",
            "base_rate_export_name": "Base Hourly Level 1 20+ Years",
            "base_rate": "23.23",
            "from": 1456902000,
            "to": 1456916400
          }
        ],
        "department_id": 808,
        "department_export_name": "abc123"
        "employee_id":  "111"
        "metadata": "My special metadata",
        "leave_request_id": 7889,
      }
    ]

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 [/api/v2/users]
GETGet Users
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 (including tax declarations, super fund memberships, and bank details), you’ll need the financial scope. Tax file numbers are only included when using 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.

Parameters
name: Homer Simpson (optional, string) - The user’s preferred name. Note, you cannot pass both name and email params.
legal_first_name: Homer (optional, string) - The user’s first name.
legal_middle_names: James (optional, string) - The user’s middle name/s.
legal_last_name: Simpson (optional, string) - The user’s last name.
email: homer.simpson@springfieldpowerplant.com (optional, string) - The user’s email.
show_wages: true (optional, boolean) - Whether to show the user’s wage (defaults to false)
show_qualifications: true (optional, boolean) - Should the response include qualifications for each user
show_regular_hours: true (optional, boolean) - Should the response include regular hours for each user
show_inactive: false (optional, boolean) - Include inactive staff in your response
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified users
location_id: 111 (optional, number) - The 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: 111 (optional, number) - The 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: employee (optional, number) - The 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: 111 (optional, string) - The 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: “CC123” (optional, string) - Employee ID to filter by.
normalised_phone: “%2B61408123654” (optional, string) - Normalised phone number to filter by.
platform: false (optional, boolean) - If true, Platform data will be returned (defaults to false).
page: 1 (optional, number) - The page number for your user list
page_size: 50 (optional, number) - The number of users retrieved per page. Maximum 100 per page.
200
OK
(application/json)
Attributes (array):
id: 123456 (required) (number) - The id of the user
name: Lenny Leonard (required, string) - The user’s preferred name
legal_first_name: Lenny (string) - The user’s first name
legal_middle_names: James (string) - The user’s middle name/s
legal_last_name: Leonard (string) - The user’s last name
date_of_birth: 1955-05-12 (string) - The user’s date of birth
employment_start_date: 1989-12-17 (string) - The user’s employment start date
employee_id: LL1 (string) - The user’s employee id, used for external systems
passcode: 0456 (required) (string) - The user’s system passcode (used for clocking in and out)
platform_role_ids: 18, 19, 22 (required, array[number]) - IDs of the user’s roles (see Access & Roles)
department_ids: 111 (required) (array[number]) - The department (team) ids that the user is a member of
preferred_hours: 20 (required) (number) - The preferred number of hours to be rostered each week
award (object) - Information about the user’s award, null if user isn’t on award
name: Fast Food Industry (required, string) - The name of the award
identifier: MA000003 (string) - The award’s identifier (will be the award code for all modern awards)
note: This field is deprecated, and may be removed in the future. Please rely on the award_template_organisation_id field instead. (string) - 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 (number) - The ID of the award template the user is on
award_template_organisation_id: 5624432 (number) - The internal ID of the award template the user is on
award_tag_ids: 3816 (required) (array[number]) - The award tag ids that apply to the user
report_department_id: 111 (number) - The user’s default team
managed_department_ids: 222 (array[number]) - The department ids that this user manages
active: true (required) (boolean) - Whether the user is active in the system
email: lenny.leonard@springfieldpowerplant.com (string) - The user’s email
payslip_email: lenny.personal@example.com (string) - The user’s payslip email address. Null if not explicitly set.
photo: http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png (string) - An avatar for the user
phone: 0404 123 123 (string) - Phone number for the user
normalised_phone: +61404123123 (string) - Phone number for user with international dialing code
salary: 1234.12 (number) - The weekly salary of the user, if show_wages=true parameter is set
hourly_rate: 32.47 (number) - The hourly rate of the user, if show_wages=true parameter is set, will not show if the salary exists
time_zone: Australia/Brisbane (string) - The user’s time zone
utc_offset: 36000 (required) (number) - The user’s time zone’s UTC offset
contracted_weekly_hours: The number of hours per week a user must work. Working under or over this number of hours may incur overtime or additional costs
part_time_fixed_hours: 20 (number) - Deprecated. This value will always be the same as contracted_weekly_hours.
expected_hours_in_pay_period: 38 (number) - readonly: for salaried staff, defines expected number of hours worked per pay period
days_overtime_averaged_over: 7 (number) - date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run
overtime_calculated_over_period_start: 2016-09-12 (string) - date from which overtime averaging periods should commence
super_fund (object) - information about the employees super fund
id: 1234 (number) - the unique ID of the employees fund
fund_name: FUND NAME (string) - the name of the fund
product_name: FUND PRODUCT (string) - the name of the fund product
smsf: true, false (boolean) - is the fund a self managed fund
abn: 123456789 (number) - the number of the fund
super_fund_membership (object) - information about the employees super fund membership
super_contribution_type: arpa (string) - the type of the employees super contribution
member_number: 123ACB (string) - the membership number of the employees super fund
occupational_rating: A1 (string) - the occupational rating of the employees super fund
super_fund_id: 1234 (required, number) - the record ID of the employees super fund
employer_preferred: 0 (required, number) - indication of an employers preferred super fund
employer_default: 1 (required, number) - indication of an employers default super fund
employer_generic: 2 (required, number) - indication of an employers generic super fund
bank_details (BankDetails) - the bank details of the employee
address (Address) - the residential address of the employee
tax_declaration (object) - the tax declaration information of the employee
previous_family_name: Smith (string) - the previous family name of the employee
australian_tax_resident: true (boolean) - is the user an Australia resident for tax purposes
australian_tax_residency_status: resident (string) - the normalised Australian tax residency status
tax_free_threshold: true (boolean) - is the employee under the tax free threshold?
senior_tax_offset: false (boolean) - can the employee claim a senior tax offset?
zone_overseas_carer: false (boolean) - can the employee claim a zone or overseas tax offset?
student_loan: true (boolean) - does the employee have a student loan?
financial_supplement_debt: true (boolean) - does the employee have a financial supplement debt?
tax_code: 1150L (string) - the employee’s tax code for tax services
uk_tax_year_status: first_job (string) - For UK residents, the stage of the employee’s career
uk_national_insurance_code: A (string) - For UK residents, the National Insurance category letter (e.g., A, B, C, D, E, F, H, I, J, K, L, M, N, S, V, X, Z)
national_insurance_number: AB123456C (string) - For UK organisations, the employee’s National Insurance number. Returns when the financial scope is in use, to the employee themselves or to a user who can read their sensitive data (such as an admin or payroll officer). This replaces tax_file_number for UK orgs, which is now legacy.
employment_basis: full_time (string) - the employment type the employee has specified on their TFN declaration
tax_scale_type: regular (string) - the tax scale type used for calculations
income_type: salary_and_wages (string) - the type of income for tax purposes
employment_type: employee (string) - the type of employment
senior_marital_status: single (string) - marital status for senior tax offset purposes
home_country: France (string) - the employee’s home country (required for working holiday makers)
nz_tax_code: M (string) - For NZ residents, the tax code
nz_esct_rate: 17.5 (string) - For NZ residents, the ESCT rate
nz_source_of_income: primary_income (string) - For NZ residents, the source of income
nz_varied_tax_rate: 25.0 (number) - For NZ residents, the varied tax rate (required for WT, STC, STC_SL tax codes)
onboarding_status: not_applicable, pending, invited, in_progress, completed, invitation_failed (string) - the status of the employee onboarding progress
kiwi_saver (object) - NZ only. The employee’s KiwiSaver settings. Only present for NZ employees who have KiwiSaver configured
status: active_member, automatically_enrolled, opted_in, not_eligible, opted_out, employed_less_than_28_days, not_required_to_be_automatically_enrolled (string) - the employee’s KiwiSaver enrolment status
ird_status_code: AK (string) - the IRD status code derived from the status (e.g. AK, AE, OK, NK); null when no code applies
employee_deduction_rate: 3.0 (number) - the employee’s contribution rate as a percentage of gross pay
employer_deduction_rate: 3.5 (number) - the employer’s contribution rate as a percentage of gross pay; may be null
savings_suspension: false (boolean) - whether the employee is currently on a savings suspension
opted_out_date: 2024-01-15 (string) - the date the employee opted out, if applicable; null otherwise
qualifications (array of UserQualification) - Information about qualifications the user holds, if Qualifications are enabled
regular_hours (RegularHours) - information about the employees regular hours of work
created_at: 1430715548 (required) (number) - When the user’s Tanda profile was created
record_id: 532432 (number) - the record ID, for use with Platform endpoints
next_pay_group_id: 53242 (number) - the ID for the pay group of the user’s next timesheet
last_synced_mobile_app: 1430715548 (number) - Read only: when the user last opened the mobile app.
automatic_break_rule_set_id: 1430715548 (number) - Read only: the ID for the user’s automatic break rule set.
temporary_employee_type: (TemporaryEmployeeType, optional) - Type of a temporary employee user. This field only exists if Enable Temporary Staff setting is turned on.
position_title: Bartender (string) - Read only
position_template: Bartender (Hourly) (string)
ssn: 123456789 (string) - Read only
emergency_contacts (array of EmergencyContact) - Read only
POSTCreate User
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 Workforce 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 (tax declarations, super fund memberships, bank details), you will need the financial scope.

Tax Declaration Requirements: When creating a user with tax declaration information, certain fields are required depending on the organisation’s country:
Australia (default): Must provide either australian_tax_resident or australian_tax_residency_status, plus tax_free_threshold, senior_tax_offset, zone_overseas_carer, student_loan, and financial_supplement_debt
United Kingdom: Must provide tax_code, student_loan, and uk_tax_year_status
Singapore: Must provide tax_file_number (NRIC/FIN format, e.g., S1234567A) and complete singapore_tax_detail with all required fields: legal_status, nationality, race, religion, marital_status. Additionally, issue_date is required for permanent residents and foreign worker passes, while expiry_date is required for foreign worker passes
New Zealand: Must provide tax_file_number (IRD number), nz_tax_code, and nz_esct_rate. Optionally provide nz_source_of_income and nz_varied_tax_rate (required when nz_tax_code is WT, STC, or STC_SL)
Working Holiday Makers: Must provide home_country when income_type or tax_scale_type is set to "working_holiday_maker"
Bank Details Requirements: When creating or updating a user with bank details, required fields vary by organisation country:

Australia (default): Must provide account_name, account_number, and bsb
IBAN Countries: Must provide account_name, bank_name, and iban
Singapore: Must provide account_name, account_number, and bank_name
Parameters
skip_validation: true (optional, boolean) - Skip’s checking if an employee already exists with this email address (defaults to false)
Request Create User (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
    }

Schema

Attributes:
name: Homer Simpson (required, string) - The user’s preferred name
legal_first_name: Homer (string) - The user’s first name
legal_middle_names: James (string) - The user’s middle name/s
legal_last_name: Simpson (string) - The user’s last name
date_of_birth: 1955-05-12 (string) - The user’s date of birth
employment_start_date: 1989-12-17 (string) - The user’s employment start date
employee_id: HS98 (string) - The user’s employee id, used for external systems
passcode: 1230 (string) - The user’s system passcode (used for clocking in and out)
department_ids: [111] (array[number]) - The department (team) ids that the user is a member of
preferred_hours: 20 (number) - The preferred number of hours to be rostered each week
contracted_weekly_hours: The number of hours per week a user must work. Working under or over this number of hours may incur overtime or additional costs
part_time_fixed_hours: 20 (number) - Deprecated. Please use contracted_weekly_hours or regular hours of work instead. Previously used for part time staff, can be used to configure when overtime starts to apply.
award_template_id: 990 (number) - The ID of the award template thte user is on
award_template_organisation_id: 12345 (number) - The ID of the award template organisation
award_tag_ids (array of number) - The award tag ids that apply to the user
report_department_id: 111 (number) - The user’s default team
managed_department_ids (array of number) - The department ids that this user manages
email: homer.simpson@springfieldpowerplant.com (string) - The user’s email
phone: 0404 123 123 (string) - Phone number for the user
days_overtime_averaged_over: 7 (number) - readonly: date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run
overtime_calculated_over_period_start: 2016-09-12 (string) - readonly: date from which overtime averaging periods should commence
can_see_costs (boolean) - can the user see the costs data
`One of
user_levels` (array of UserLevel)
platform_role_ids: [18] (array[number]) - IDs of the user’s roles (see Access & Roles)
hourly_rate: 24.80 (number, optional) - The users hourly rate
yearly_salary: 87450.0 (number, optional) - The users annual salary
position_template_name: ‘Bartender (Hourly)’ (string) - The name of the position template to assign to the user’s current Pay Conditions.
next_pay_group_id: 53242 (number) - the ID for the pay group of the user’s next timesheet
address (Address)
tax_declaration (TaxDeclaration) - the tax declaration information of the employee
bank_details (BankDetails) - the bank details of the employee
super_fund_membership (SuperFundMembership) - information about the employees super fund membership
regular_hours (RegularHours) - information about the employees regular hours of work
temporary_employee_type: (TemporaryEmployeeType, optional) - Type of a temporary employee user. This field only exists if Enable Temporary Staff setting is turned on.
200
OK
(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,
      "payroll_cessation_code": "voluntary_cessation",
      "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,
      "contracted_weekly_hours": 0.0,
      "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,
      "temporary_employee_type": null,
      "tax_declaration": {
        "previous_family_name": "Smith",
        "australian_tax_resident": true,
        "australian_tax_residency_status": "resident",
        "tax_free_threshold": true,
        "senior_tax_offset": false,
        "zone_overseas_carer": false,
        "student_loan": false,
        "financial_supplement_debt": false,
        "tax_code": "123456789",
        "uk_tax_year_status": null,
        "employment_basis": "full_time",
        "tax_scale_type": "regular",
        "income_type": "salary_and_wages",
        "employment_type": "employee",
        "senior_marital_status": null,
        "home_country": null,
        "singapore_tax_detail": {
          "legal_status": "singapore_citizen",
          "nationality": "singaporean",
          "race": "chinese",
          "religion": "buddhism",
          "marital_status": "single",
          "issue_date": "2020-01-15",
          "expiry_date": "2025-01-15"
        }
      },
      "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

Attributes:
id: 1234567 (required) (number) - The id of the user
name: Homer Simpson (required, string) - The user’s preferred name
legal_first_name: Homer (string) - The user’s first name
legal_middle_names: James (string) - The user’s middle name/s
legal_last_name: Simpson (string) - The user’s last name
date_of_birth: 1955-05-12 (string) - The user’s date of birth
employment_start_date: 1989-12-17 (string) - The user’s employment start date
employment_end_date: 1995-07-12 (string) - The users employment end date
employee_id: HS98 (string) - The user’s employee id, used for external systems
passcode: 1230 (required) (string) - The user’s system passcode (used for clocking in and out)
user_levels (array of UserLevel)
platform_role_ids: 3816, 3817 (required, array[number]) - IDs of the user’s roles (see Access & Roles)
department_ids: 111 (required) (array[number]) - The department (team) ids that the user is a member of
preferred_hours: 20 (required) (number) - The preferred number of hours to be rostered each week
award_template_id: 990 (number) - The ID of the award template thte user is on
award_template_organisation_id: 12087 (number) - The ID of the organisation
award_tag_ids (required) (array of number) - The award tag ids that apply to the user
report_department_id: 111 (number) - The user’s default team
managed_department_ids (array of number) - The department ids that this user manages
active: false (required) (boolean) - Whether the user is active in the system
enable_login: true (boolean) - Can the user login
can_see_costs: false (boolean) - Can the user see costing data
email: homer.simpson@springfieldpowerplant.com (string) - The user’s email
photo: http://vignette2.wikia.nocookie.net/simpsons/images/b/bd/Homer_Simpson.png (string) - An avatar for the user
phone: 0404 123 123 (string) - Phone number for the user
normalised_phone: +61404123123 (string) - Phone number for user with international dialing code
time_zone: Australia/Brisbane (string) - The user’s time zone
utc_offset: 36000 (required) (number) - The user’s time zone’s UTC offset
created_at: 1430715549 (required) (number) - When the user’s Tanda profile was created
contracted_weekly_hours: The number of hours per week a user must work. Working under or over this number of hours may incur overtime or additional costs
part_time_fixed_hours: 20 (number) - Deprecated. This value will always be the same as contracted_weekly_hours.
next_pay_group_id: 53242 (number) - the ID for the pay group of the user’s next timesheet
last_synced_mobile_app: 1430715548 (number) - Read only: when the user last opened the mobile app.
automatic_break_rule_set_id: 1430715548 (number) - Read only: the ID for the user’s automatic break rule set.
Request Minimum fields required (application/json)
Body

    {
      "name": "Carlton Carlson Jr."
    }

200
OK
(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,
      "payroll_cessation_code": null,
      "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,
      "contracted_weekly_hours": 0.0,
      "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,
      "temporary_employee_type": null,
      "tax_declaration": null,
      "onboarding_status": "not_applicable",
      "qualifications": [],
      "updated_at": 1562272900
    }

Schema

Attributes:
id: 1234567 (required) (number) - The id of the user
name: Homer Simpson (required, string) - The user’s preferred name
legal_first_name: Homer (string) - The user’s first name
legal_middle_names: James (string) - The user’s middle name/s
legal_last_name: Simpson (string) - The user’s last name
date_of_birth: 1955-05-12 (string) - The user’s date of birth
employment_start_date: 1989-12-17 (string) - The user’s employment start date
employment_end_date: 1995-07-12 (string) - The users employment end date
employee_id: HS98 (string) - The user’s employee id, used for external systems
passcode: 1230 (required) (string) - The user’s system passcode (used for clocking in and out)
user_levels (array of UserLevel)
platform_role_ids: 3816, 3817 (required, array[number]) - IDs of the user’s roles (see Access & Roles)
department_ids: 111 (required) (array[number]) - The department (team) ids that the user is a member of
preferred_hours: 20 (required) (number) - The preferred number of hours to be rostered each week
award_template_id: 990 (number) - The ID of the award template thte user is on
award_template_organisation_id: 12087 (number) - The ID of the organisation
award_tag_ids (required) (array of number) - The award tag ids that apply to the user
report_department_id: 111 (number) - The user’s default team
managed_department_ids (array of number) - The department ids that this user manages
active: false (required) (boolean) - Whether the user is active in the system
enable_login: true (boolean) - Can the user login
can_see_costs: false (boolean) - Can the user see costing data
email: homer.simpson@springfieldpowerplant.com (string) - The user’s email
photo: http://vignette2.wikia.nocookie.net/simpsons/images/b/bd/Homer_Simpson.png (string) - An avatar for the user
phone: 0404 123 123 (string) - Phone number for the user
normalised_phone: +61404123123 (string) - Phone number for user with international dialing code
time_zone: Australia/Brisbane (string) - The user’s time zone
utc_offset: 36000 (required) (number) - The user’s time zone’s UTC offset
created_at: 1430715549 (required) (number) - When the user’s Tanda profile was created
contracted_weekly_hours: The number of hours per week a user must work. Working under or over this number of hours may incur overtime or additional costs
part_time_fixed_hours: 20 (number) - Deprecated. This value will always be the same as contracted_weekly_hours.
next_pay_group_id: 53242 (number) - the ID for the pay group of the user’s next timesheet
last_synced_mobile_app: 1430715548 (number) - Read only: when the user last opened the mobile app.
automatic_break_rule_set_id: 1430715548 (number) - Read only: the ID for the user’s automatic break rule set.
Request Create Singapore User with Tax Details (application/json)
This example is only applicable for Singapore organisations. The singapore_tax_detail field will not be available for organisations in other countries.

Body

    {
      "name": "Li Wei",
      "employee_id": "LW001",
      "email": "li.wei@company.com.sg",
      "phone": "+6591234567",
      "employment_start_date": "2023-01-01",
      "user_levels": ["employee"],
      "department_ids": [111],
      "tax_declaration": {
        "tax_file_number": "S1234567A",
        "employment_basis": "full_time",
        "singapore_tax_detail": {
          "legal_status": "singapore_citizen",
          "nationality": "singaporean",
          "race": "chinese",
          "religion": "buddhism",
          "marital_status": "married"
        }
      }
    }

Request Create New Zealand User with Tax Details (application/json)

This example is only applicable for New Zealand organisations. The NZ tax detail fields will not be available for organisations in other countries.
Body

    {
      "name": "Kane Williamson",
      "employee_id": "KW001",
      "email": "kane.williamson@company.co.nz",
      "phone": "+6421234567",
      "employment_start_date": "2023-01-01",
      "user_levels": ["employee"],
      "department_ids": [111],
      "tax_declaration": {
        "tax_file_number": "49098576",
        "employment_basis": "full_time",
        "nz_tax_code": "ME",
        "nz_esct_rate": "17.5",
        "nz_source_of_income": "primary_income"
      }
    }

Request Create UK User with Tax Details (application/json)

This example is only applicable for UK organisations. The uk_national_insurance_code and uk_tax_year_status fields will not be available for organisations in other countries.
Body

    {
      "name": "John Smith",
      "employee_id": "JS001",
      "email": "john.smith@company.co.uk",
      "phone": "+447700900123",
      "employment_start_date": "2023-01-01",
      "user_levels": ["employee"],
      "department_ids": [111],
      "tax_declaration": {
        "tax_file_number": "AB123456C",
        "tax_code": "1150L",
        "uk_tax_year_status": "first_job",
        "uk_national_insurance_code": "A",
        "student_loan": false
      }
    }

Request Create Singapore User with Bank Details (application/json)

This example shows bank details creation for Singapore organisations
Body

    {
      "name": "Tan Wei Ming",
      "bank_details": {
        "bank_name": "DBS Bank Limited",
        "account_name": "Tan Wei Ming",
        "account_number": "0010572841"
      }
    }

Response 200 (application/json)

Body

    {
      "id": 12345679,
      "name": "Li Wei",
      "employee_id": "LW001",
      "email": "li.wei@company.com.sg",
      "phone": "+6591234567",
      "employment_start_date": "2023-01-01",
      "active": true,
      "enable_login": true,
      "tax_declaration": {
        "tax_file_number": "S1234567A",
        "employment_basis": "full_time",
        "singapore_tax_detail": {
          "legal_status": "singapore_citizen",
          "nationality": "singaporean",
          "race": "chinese",
          "religion": "buddhism",
          "marital_status": "married",
          "issue_date": null,
          "expiry_date": null
        }
      },
      "created_at": 1672531200,
      "updated_at": 1672531200
    }

The regular_hours object supports optional sleepovers, on_calls, and rostered_days_off arrays alongside schedules. These follow the same format as schedules but without breaks. See Sleepovers, On Calls, and Rostered Days Off for standalone CRUD endpoints.
Request Create Regular Hours (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"
          }
        ],
        "sleepovers": [
          {
            "week": 1,
            "day": "Monday",
            "start": "22:00",
            "end": "06:00",
            "department_id": 1234
          }
        ],
        "on_calls": [
          {
            "week": 1,
            "day": "Tuesday",
            "start": "18:00",
            "end": "06:00",
            "department_id": 1234
          }
        ],
        "rostered_days_off": [
          {
            "week": 1,
            "day": "Wednesday",
            "start": "00:00",
            "end": "00:00"
          }
        ]
      }
    }

200
OK
(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,
      "payroll_cessation_code": null,
      "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,
      "contracted_weekly_hours": 0.0,
      "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,
      "temporary_employee_type": 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"
          }
        ],
        "sleepovers": [
          {
            "week": 1,
            "day": "Monday",
            "start": "22:00",
            "end": "06:00",
            "department_id": 1234
          }
        ],
        "on_calls": [
          {
            "week": 1,
            "day": "Tuesday",
            "start": "18:00",
            "end": "06:00",
            "department_id": 1234
          }
        ],
        "rostered_days_off": [
          {
            "week": 1,
            "day": "Wednesday",
            "start": "00:00",
            "end": "00:00"
          }
        ]
      },
      "updated_at": 1562272900
    }

Inactive User List [/api/v2/users/inactive]
GETGet Inactive Users
This method requires the user scope (see Scopes for more information).
Parameters
name: Homer Simpson (optional, string) - The user’s preferred name. Note, you cannot pass both name and email params.
legal_first_name: Homer (optional, string) - The user’s first name.
legal_middle_names: James (optional, string) - The user’s middle name/s.
legal_last_name: Simpson (optional, string) - The user’s last name.
email: homer.simpson@springfieldpowerplant.com (optional, string) - The user’s email.
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified users
report_location_id: 111 (optional, number) - The 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.
page: 1 (optional, number) - The page number for your user list
page_size: 50 (optional, number) - The number of users retrieved per page. Maximum 100 per page.
200
OK
(application/json)
Body

    [
      {
        "id": 1234567,
        "name": "Homer Simpson",
        "legal_first_name": "Homer",
        "legal_middle_names": "James",
        "legal_last_name": "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,
        "payroll_cessation_code": "voluntary_cessation",
        "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,
        "contracted_weekly_hours": 0.0,
        "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,
        "temporary_employee_type": null,
        "tax_declaration": null,
        "onboarding_status": "not_applicable",
        "qualifications": [],
        "updated_at": 1562272900
      }
    ]

User [/api/v2/users/{id}]
GETGet User
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.

Parameters
id: 123456 (number) - The id of the user
show_wages: true (optional, boolean) - Whether to show the user’s wage (defaults to false)
show_regular_hours: true (optional, boolean) - Whether to show the user’s regular hours (defaults to false)
platform: false (optional, boolean) - If true, Platform data will be returned (defaults to false)
200
OK
(application/json)
Attributes:
id: 123456 (required) (number) - The id of the user
name: Lenny Leonard (required, string) - The user’s preferred name
legal_first_name: Lenny (string) - The user’s first name
legal_middle_names: James (string) - The user’s middle name/s
legal_last_name: Leonard (string) - The user’s last name
date_of_birth: 1955-05-12 (string) - The user’s date of birth
employment_start_date: 1989-12-17 (string) - The user’s employment start date
employee_id: LL1 (string) - The user’s employee id, used for external systems
passcode: 0456 (required) (string) - The user’s system passcode (used for clocking in and out)
platform_role_ids: 18, 19, 22 (required, array[number]) - IDs of the user’s roles (see Access & Roles)
department_ids: 111 (required) (array[number]) - The department (team) ids that the user is a member of
preferred_hours: 20 (required) (number) - The preferred number of hours to be rostered each week
award (object) - Information about the user’s award, null if user isn’t on award
name: Fast Food Industry (required, string) - The name of the award
identifier: MA000003 (string) - The award’s identifier (will be the award code for all modern awards)
note: This field is deprecated, and may be removed in the future. Please rely on the award_template_organisation_id field instead. (string) - 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 (number) - The ID of the award template the user is on
award_template_organisation_id: 5624432 (number) - The internal ID of the award template the user is on
award_tag_ids: 3816 (required) (array[number]) - The award tag ids that apply to the user
report_department_id: 111 (number) - The user’s default team
managed_department_ids: 222 (array[number]) - The department ids that this user manages
active: true (required) (boolean) - Whether the user is active in the system
email: lenny.leonard@springfieldpowerplant.com (string) - The user’s email
payslip_email: lenny.personal@example.com (string) - The user’s payslip email address. Null if not explicitly set.
photo: http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png (string) - An avatar for the user
phone: 0404 123 123 (string) - Phone number for the user
normalised_phone: +61404123123 (string) - Phone number for user with international dialing code
salary: 1234.12 (number) - The weekly salary of the user, if show_wages=true parameter is set
hourly_rate: 32.47 (number) - The hourly rate of the user, if show_wages=true parameter is set, will not show if the salary exists
time_zone: Australia/Brisbane (string) - The user’s time zone
utc_offset: 36000 (required) (number) - The user’s time zone’s UTC offset
contracted_weekly_hours: The number of hours per week a user must work. Working under or over this number of hours may incur overtime or additional costs
part_time_fixed_hours: 20 (number) - Deprecated. This value will always be the same as contracted_weekly_hours.
expected_hours_in_pay_period: 38 (number) - readonly: for salaried staff, defines expected number of hours worked per pay period
days_overtime_averaged_over: 7 (number) - date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run
overtime_calculated_over_period_start: 2016-09-12 (string) - date from which overtime averaging periods should commence
super_fund (object) - information about the employees super fund
id: 1234 (number) - the unique ID of the employees fund
fund_name: FUND NAME (string) - the name of the fund
product_name: FUND PRODUCT (string) - the name of the fund product
smsf: true, false (boolean) - is the fund a self managed fund
abn: 123456789 (number) - the number of the fund
super_fund_membership (object) - information about the employees super fund membership
super_contribution_type: arpa (string) - the type of the employees super contribution
member_number: 123ACB (string) - the membership number of the employees super fund
occupational_rating: A1 (string) - the occupational rating of the employees super fund
super_fund_id: 1234 (required, number) - the record ID of the employees super fund
employer_preferred: 0 (required, number) - indication of an employers preferred super fund
employer_default: 1 (required, number) - indication of an employers default super fund
employer_generic: 2 (required, number) - indication of an employers generic super fund
bank_details (BankDetails) - the bank details of the employee
address (Address) - the residential address of the employee
tax_declaration (object) - the tax declaration information of the employee
previous_family_name: Smith (string) - the previous family name of the employee
australian_tax_resident: true (boolean) - is the user an Australia resident for tax purposes
australian_tax_residency_status: resident (string) - the normalised Australian tax residency status
tax_free_threshold: true (boolean) - is the employee under the tax free threshold?
senior_tax_offset: false (boolean) - can the employee claim a senior tax offset?
zone_overseas_carer: false (boolean) - can the employee claim a zone or overseas tax offset?
student_loan: true (boolean) - does the employee have a student loan?
financial_supplement_debt: true (boolean) - does the employee have a financial supplement debt?
tax_code: 1150L (string) - the employee’s tax code for tax services
uk_tax_year_status: first_job (string) - For UK residents, the stage of the employee’s career
uk_national_insurance_code: A (string) - For UK residents, the National Insurance category letter (e.g., A, B, C, D, E, F, H, I, J, K, L, M, N, S, V, X, Z)
national_insurance_number: AB123456C (string) - For UK organisations, the employee’s National Insurance number. Returns when the financial scope is in use, to the employee themselves or to a user who can read their sensitive data (such as an admin or payroll officer). This replaces tax_file_number for UK orgs, which is now legacy.
employment_basis: full_time (string) - the employment type the employee has specified on their TFN declaration
tax_scale_type: regular (string) - the tax scale type used for calculations
income_type: salary_and_wages (string) - the type of income for tax purposes
employment_type: employee (string) - the type of employment
senior_marital_status: single (string) - marital status for senior tax offset purposes
home_country: France (string) - the employee’s home country (required for working holiday makers)
nz_tax_code: M (string) - For NZ residents, the tax code
nz_esct_rate: 17.5 (string) - For NZ residents, the ESCT rate
nz_source_of_income: primary_income (string) - For NZ residents, the source of income
nz_varied_tax_rate: 25.0 (number) - For NZ residents, the varied tax rate (required for WT, STC, STC_SL tax codes)
onboarding_status: not_applicable, pending, invited, in_progress, completed, invitation_failed (string) - the status of the employee onboarding progress
kiwi_saver (object) - NZ only. The employee’s KiwiSaver settings. Only present for NZ employees who have KiwiSaver configured
status: active_member, automatically_enrolled, opted_in, not_eligible, opted_out, employed_less_than_28_days, not_required_to_be_automatically_enrolled (string) - the employee’s KiwiSaver enrolment status
ird_status_code: AK (string) - the IRD status code derived from the status (e.g. AK, AE, OK, NK); null when no code applies
employee_deduction_rate: 3.0 (number) - the employee’s contribution rate as a percentage of gross pay
employer_deduction_rate: 3.5 (number) - the employer’s contribution rate as a percentage of gross pay; may be null
savings_suspension: false (boolean) - whether the employee is currently on a savings suspension
opted_out_date: 2024-01-15 (string) - the date the employee opted out, if applicable; null otherwise
qualifications (array of UserQualification) - Information about qualifications the user holds, if Qualifications are enabled
regular_hours (RegularHours) - information about the employees regular hours of work
created_at: 1430715548 (required) (number) - When the user’s Tanda profile was created
record_id: 532432 (number) - the record ID, for use with Platform endpoints
next_pay_group_id: 53242 (number) - the ID for the pay group of the user’s next timesheet
last_synced_mobile_app: 1430715548 (number) - Read only: when the user last opened the mobile app.
automatic_break_rule_set_id: 1430715548 (number) - Read only: the ID for the user’s automatic break rule set.
temporary_employee_type: (TemporaryEmployeeType, optional) - Type of a temporary employee user. This field only exists if Enable Temporary Staff setting is turned on.
position_title: Bartender (string) - Read only
position_template: Bartender (Hourly) (string)
ssn: 123456789 (string) - Read only
emergency_contacts (array of EmergencyContact) - Read only
PUTUpdate User
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_ids or managed_department_ids, you should pass null 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.
Parameters
id: 123456 (number) - The id of the user
skip_validation: true (optional, boolean) - Skip’s checking if an employee already exists with this email address
Request Update User (application/json)
Body

{
  "name": "Lenford Leonard",
  "legal_first_name": "Lenford",
  "legal_middle_names": "Leonard",
  "legal_last_name": "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,
      "training_provider_name": "Acme Training Ltd",
      "state_of_completion": "QLD",
      "license_number": "BCD234",
      "expires": "2012-11-21",
      "in_training": false,
      "file_id": "2d4ab757-637c-4be2-b2d6-5f89ae211ba4"
    }
  ]
}

Schema

Attributes:
name: Homer Simpson (required, string) - The user’s preferred name
legal_first_name: Homer (string) - The user’s first name
legal_middle_names: James (string) - The user’s middle name/s
legal_last_name: Simpson (string) - The user’s last name
date_of_birth: 1955-05-12 (string) - The user’s date of birth
employment_start_date: 1989-12-17 (string) - The user’s employment start date
employee_id: HS98 (string) - The user’s employee id, used for external systems
passcode: 1230 (string) - The user’s system passcode (used for clocking in and out)
department_ids: [111] (array[number]) - The department (team) ids that the user is a member of
preferred_hours: 20 (number) - The preferred number of hours to be rostered each week
contracted_weekly_hours: The number of hours per week a user must work. Working under or over this number of hours may incur overtime or additional costs
part_time_fixed_hours: 20 (number) - Deprecated. Please use contracted_weekly_hours or regular hours of work instead. Previously used for part time staff, can be used to configure when overtime starts to apply.
award_template_id: 990 (number) - The ID of the award template thte user is on
award_template_organisation_id: 12345 (number) - The ID of the award template organisation
award_tag_ids (array of number) - The award tag ids that apply to the user
report_department_id: 111 (number) - The user’s default team
managed_department_ids (array of number) - The department ids that this user manages
email: homer.simpson@springfieldpowerplant.com (string) - The user’s email
payslip_email: homer.personal@example.com (string) - The user’s payslip email address. Null if not explicitly set.
phone: 0404 123 123 (string) - Phone number for the user
days_overtime_averaged_over: 7 (number) - readonly: date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run
overtime_calculated_over_period_start: 2016-09-12 (string) - readonly: date from which overtime averaging periods should commence
can_see_costs (boolean) - can the user see the costs data
`One of
user_levels` (array of UserLevel)
platform_role_ids: [18] (array[number]) - IDs of the user’s roles (see Access & Roles)
hourly_rate: 24.80 (number, optional) - The users hourly rate
yearly_salary: 87450.0 (number, optional) - The users annual salary
position_template_name: ‘Bartender (Hourly)’ (string) - The name of the position template to assign to the user’s current Pay Conditions.
next_pay_group_id: 53242 (number) - the ID for the pay group of the user’s next timesheet
address (Address)
tax_declaration (TaxDeclaration) - the tax declaration information of the employee
bank_details (BankDetails) - the bank details of the employee
super_fund_membership (SuperFundMembership) - information about the employees super fund membership
regular_hours (RegularHours) - information about the employees regular hours of work
temporary_employee_type: (TemporaryEmployeeType, optional) - Type of a temporary employee user. This field only exists if Enable Temporary Staff setting is turned on.
employment_end_date: 1989-12-17 (string) - The user’s employment end date
active: true (boolean)
qualifications (UserQualification)
date_ranges: (object)
file_id: 123987 (string)
answered_questions (array of Answer)
minimum_base_hours: 15.0 (number) - Deprecated. Please use contracted_weekly_hours instead.
200
OK
(application/json)
Attributes:
id: 123456 (required) (number) - The id of the user
name: Lenny Leonard (required, string) - The user’s preferred name
legal_first_name: Lenny (string) - The user’s first name
legal_middle_names: James (string) - The user’s middle name/s
legal_last_name: Leonard (string) - The user’s last name
date_of_birth: 1955-05-12 (string) - The user’s date of birth
employment_start_date: 1989-12-17 (string) - The user’s employment start date
employee_id: LL1 (string) - The user’s employee id, used for external systems
passcode: 0456 (required) (string) - The user’s system passcode (used for clocking in and out)
platform_role_ids: 18, 19, 22 (required, array[number]) - IDs of the user’s roles (see Access & Roles)
department_ids: 111 (required) (array[number]) - The department (team) ids that the user is a member of
preferred_hours: 20 (required) (number) - The preferred number of hours to be rostered each week
award (object) - Information about the user’s award, null if user isn’t on award
name: Fast Food Industry (required, string) - The name of the award
identifier: MA000003 (string) - The award’s identifier (will be the award code for all modern awards)
note: This field is deprecated, and may be removed in the future. Please rely on the award_template_organisation_id field instead. (string) - 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 (number) - The ID of the award template the user is on
award_template_organisation_id: 5624432 (number) - The internal ID of the award template the user is on
award_tag_ids: 3816 (required) (array[number]) - The award tag ids that apply to the user
report_department_id: 111 (number) - The user’s default team
managed_department_ids: 222 (array[number]) - The department ids that this user manages
active: true (required) (boolean) - Whether the user is active in the system
email: lenny.leonard@springfieldpowerplant.com (string) - The user’s email
payslip_email: lenny.personal@example.com (string) - The user’s payslip email address. Null if not explicitly set.
photo: http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png (string) - An avatar for the user
phone: 0404 123 123 (string) - Phone number for the user
normalised_phone: +61404123123 (string) - Phone number for user with international dialing code
salary: 1234.12 (number) - The weekly salary of the user, if show_wages=true parameter is set
hourly_rate: 32.47 (number) - The hourly rate of the user, if show_wages=true parameter is set, will not show if the salary exists
time_zone: Australia/Brisbane (string) - The user’s time zone
utc_offset: 36000 (required) (number) - The user’s time zone’s UTC offset
contracted_weekly_hours: The number of hours per week a user must work. Working under or over this number of hours may incur overtime or additional costs
part_time_fixed_hours: 20 (number) - Deprecated. This value will always be the same as contracted_weekly_hours.
expected_hours_in_pay_period: 38 (number) - readonly: for salaried staff, defines expected number of hours worked per pay period
days_overtime_averaged_over: 7 (number) - date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run
overtime_calculated_over_period_start: 2016-09-12 (string) - date from which overtime averaging periods should commence
super_fund (object) - information about the employees super fund
id: 1234 (number) - the unique ID of the employees fund
fund_name: FUND NAME (string) - the name of the fund
product_name: FUND PRODUCT (string) - the name of the fund product
smsf: true, false (boolean) - is the fund a self managed fund
abn: 123456789 (number) - the number of the fund
super_fund_membership (object) - information about the employees super fund membership
super_contribution_type: arpa (string) - the type of the employees super contribution
member_number: 123ACB (string) - the membership number of the employees super fund
occupational_rating: A1 (string) - the occupational rating of the employees super fund
super_fund_id: 1234 (required, number) - the record ID of the employees super fund
employer_preferred: 0 (required, number) - indication of an employers preferred super fund
employer_default: 1 (required, number) - indication of an employers default super fund
employer_generic: 2 (required, number) - indication of an employers generic super fund
bank_details (BankDetails) - the bank details of the employee
address (Address) - the residential address of the employee
tax_declaration (object) - the tax declaration information of the employee
previous_family_name: Smith (string) - the previous family name of the employee
australian_tax_resident: true (boolean) - is the user an Australia resident for tax purposes
australian_tax_residency_status: resident (string) - the normalised Australian tax residency status
tax_free_threshold: true (boolean) - is the employee under the tax free threshold?
senior_tax_offset: false (boolean) - can the employee claim a senior tax offset?
zone_overseas_carer: false (boolean) - can the employee claim a zone or overseas tax offset?
student_loan: true (boolean) - does the employee have a student loan?
financial_supplement_debt: true (boolean) - does the employee have a financial supplement debt?
tax_code: 1150L (string) - the employee’s tax code for tax services
uk_tax_year_status: first_job (string) - For UK residents, the stage of the employee’s career
uk_national_insurance_code: A (string) - For UK residents, the National Insurance category letter (e.g., A, B, C, D, E, F, H, I, J, K, L, M, N, S, V, X, Z)
national_insurance_number: AB123456C (string) - For UK organisations, the employee’s National Insurance number. Returns when the financial scope is in use, to the employee themselves or to a user who can read their sensitive data (such as an admin or payroll officer). This replaces tax_file_number for UK orgs, which is now legacy.
employment_basis: full_time (string) - the employment type the employee has specified on their TFN declaration
tax_scale_type: regular (string) - the tax scale type used for calculations
income_type: salary_and_wages (string) - the type of income for tax purposes
employment_type: employee (string) - the type of employment
senior_marital_status: single (string) - marital status for senior tax offset purposes
home_country: France (string) - the employee’s home country (required for working holiday makers)
nz_tax_code: M (string) - For NZ residents, the tax code
nz_esct_rate: 17.5 (string) - For NZ residents, the ESCT rate
nz_source_of_income: primary_income (string) - For NZ residents, the source of income
nz_varied_tax_rate: 25.0 (number) - For NZ residents, the varied tax rate (required for WT, STC, STC_SL tax codes)
onboarding_status: not_applicable, pending, invited, in_progress, completed, invitation_failed (string) - the status of the employee onboarding progress
kiwi_saver (object) - NZ only. The employee’s KiwiSaver settings. Only present for NZ employees who have KiwiSaver configured
status: active_member, automatically_enrolled, opted_in, not_eligible, opted_out, employed_less_than_28_days, not_required_to_be_automatically_enrolled (string) - the employee’s KiwiSaver enrolment status
ird_status_code: AK (string) - the IRD status code derived from the status (e.g. AK, AE, OK, NK); null when no code applies
employee_deduction_rate: 3.0 (number) - the employee’s contribution rate as a percentage of gross pay
employer_deduction_rate: 3.5 (number) - the employer’s contribution rate as a percentage of gross pay; may be null
savings_suspension: false (boolean) - whether the employee is currently on a savings suspension
opted_out_date: 2024-01-15 (string) - the date the employee opted out, if applicable; null otherwise
qualifications (array of UserQualification) - Information about qualifications the user holds, if Qualifications are enabled
regular_hours (RegularHours) - information about the employees regular hours of work
created_at: 1430715548 (required) (number) - When the user’s Tanda profile was created
record_id: 532432 (number) - the record ID, for use with Platform endpoints
next_pay_group_id: 53242 (number) - the ID for the pay group of the user’s next timesheet
last_synced_mobile_app: 1430715548 (number) - Read only: when the user last opened the mobile app.
automatic_break_rule_set_id: 1430715548 (number) - Read only: the ID for the user’s automatic break rule set.
temporary_employee_type: (TemporaryEmployeeType, optional) - Type of a temporary employee user. This field only exists if Enable Temporary Staff setting is turned on.
position_title: Bartender (string) - Read only
position_template: Bartender (Hourly) (string)
ssn: 123456789 (string) - Read only
emergency_contacts (array of EmergencyContact) - Read only
name: Lenford Leonard
employee_id: Lenford
passcode: 0123
phone: 0404123122
normalised_phone: +61404123122
date_of_birth: 1990-12-12
employment_start_date: 2016-03-01
email: some_email@test.com
hourly_rate: 12.34 (number)
enable_login: true (boolean)
qualifications: [{}]
Request Deactivate User (application/json)
Body

    {
      "active": false
    }

200
OK
(application/json)
Attributes:
id: 123456 (required) (number) - The id of the user
name: Lenny Leonard (required, string) - The user’s preferred name
legal_first_name: Lenny (string) - The user’s first name
legal_middle_names: James (string) - The user’s middle name/s
legal_last_name: Leonard (string) - The user’s last name
date_of_birth: 1955-05-12 (string) - The user’s date of birth
employment_start_date: 1989-12-17 (string) - The user’s employment start date
employee_id: LL1 (string) - The user’s employee id, used for external systems
passcode: 0456 (required) (string) - The user’s system passcode (used for clocking in and out)
platform_role_ids: 18, 19, 22 (required, array[number]) - IDs of the user’s roles (see Access & Roles)
department_ids: 111 (required) (array[number]) - The department (team) ids that the user is a member of
preferred_hours: 20 (required) (number) - The preferred number of hours to be rostered each week
award (object) - Information about the user’s award, null if user isn’t on award
name: Fast Food Industry (required, string) - The name of the award
identifier: MA000003 (string) - The award’s identifier (will be the award code for all modern awards)
note: This field is deprecated, and may be removed in the future. Please rely on the award_template_organisation_id field instead. (string) - 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 (number) - The ID of the award template the user is on
award_template_organisation_id: 5624432 (number) - The internal ID of the award template the user is on
award_tag_ids: 3816 (required) (array[number]) - The award tag ids that apply to the user
report_department_id: 111 (number) - The user’s default team
managed_department_ids: 222 (array[number]) - The department ids that this user manages
active: true (required) (boolean) - Whether the user is active in the system
email: lenny.leonard@springfieldpowerplant.com (string) - The user’s email
payslip_email: lenny.personal@example.com (string) - The user’s payslip email address. Null if not explicitly set.
photo: http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png (string) - An avatar for the user
phone: 0404 123 123 (string) - Phone number for the user
normalised_phone: +61404123123 (string) - Phone number for user with international dialing code
salary: 1234.12 (number) - The weekly salary of the user, if show_wages=true parameter is set
hourly_rate: 32.47 (number) - The hourly rate of the user, if show_wages=true parameter is set, will not show if the salary exists
time_zone: Australia/Brisbane (string) - The user’s time zone
utc_offset: 36000 (required) (number) - The user’s time zone’s UTC offset
contracted_weekly_hours: The number of hours per week a user must work. Working under or over this number of hours may incur overtime or additional costs
part_time_fixed_hours: 20 (number) - Deprecated. This value will always be the same as contracted_weekly_hours.
expected_hours_in_pay_period: 38 (number) - readonly: for salaried staff, defines expected number of hours worked per pay period
days_overtime_averaged_over: 7 (number) - date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run
overtime_calculated_over_period_start: 2016-09-12 (string) - date from which overtime averaging periods should commence
super_fund (object) - information about the employees super fund
id: 1234 (number) - the unique ID of the employees fund
fund_name: FUND NAME (string) - the name of the fund
product_name: FUND PRODUCT (string) - the name of the fund product
smsf: true, false (boolean) - is the fund a self managed fund
abn: 123456789 (number) - the number of the fund
super_fund_membership (object) - information about the employees super fund membership
super_contribution_type: arpa (string) - the type of the employees super contribution
member_number: 123ACB (string) - the membership number of the employees super fund
occupational_rating: A1 (string) - the occupational rating of the employees super fund
super_fund_id: 1234 (required, number) - the record ID of the employees super fund
employer_preferred: 0 (required, number) - indication of an employers preferred super fund
employer_default: 1 (required, number) - indication of an employers default super fund
employer_generic: 2 (required, number) - indication of an employers generic super fund
bank_details (BankDetails) - the bank details of the employee
address (Address) - the residential address of the employee
tax_declaration (object) - the tax declaration information of the employee
previous_family_name: Smith (string) - the previous family name of the employee
australian_tax_resident: true (boolean) - is the user an Australia resident for tax purposes
australian_tax_residency_status: resident (string) - the normalised Australian tax residency status
tax_free_threshold: true (boolean) - is the employee under the tax free threshold?
senior_tax_offset: false (boolean) - can the employee claim a senior tax offset?
zone_overseas_carer: false (boolean) - can the employee claim a zone or overseas tax offset?
student_loan: true (boolean) - does the employee have a student loan?
financial_supplement_debt: true (boolean) - does the employee have a financial supplement debt?
tax_code: 1150L (string) - the employee’s tax code for tax services
uk_tax_year_status: first_job (string) - For UK residents, the stage of the employee’s career
uk_national_insurance_code: A (string) - For UK residents, the National Insurance category letter (e.g., A, B, C, D, E, F, H, I, J, K, L, M, N, S, V, X, Z)
national_insurance_number: AB123456C (string) - For UK organisations, the employee’s National Insurance number. Returns when the financial scope is in use, to the employee themselves or to a user who can read their sensitive data (such as an admin or payroll officer). This replaces tax_file_number for UK orgs, which is now legacy.
employment_basis: full_time (string) - the employment type the employee has specified on their TFN declaration
tax_scale_type: regular (string) - the tax scale type used for calculations
income_type: salary_and_wages (string) - the type of income for tax purposes
employment_type: employee (string) - the type of employment
senior_marital_status: single (string) - marital status for senior tax offset purposes
home_country: France (string) - the employee’s home country (required for working holiday makers)
nz_tax_code: M (string) - For NZ residents, the tax code
nz_esct_rate: 17.5 (string) - For NZ residents, the ESCT rate
nz_source_of_income: primary_income (string) - For NZ residents, the source of income
nz_varied_tax_rate: 25.0 (number) - For NZ residents, the varied tax rate (required for WT, STC, STC_SL tax codes)
onboarding_status: not_applicable, pending, invited, in_progress, completed, invitation_failed (string) - the status of the employee onboarding progress
kiwi_saver (object) - NZ only. The employee’s KiwiSaver settings. Only present for NZ employees who have KiwiSaver configured
status: active_member, automatically_enrolled, opted_in, not_eligible, opted_out, employed_less_than_28_days, not_required_to_be_automatically_enrolled (string) - the employee’s KiwiSaver enrolment status
ird_status_code: AK (string) - the IRD status code derived from the status (e.g. AK, AE, OK, NK); null when no code applies
employee_deduction_rate: 3.0 (number) - the employee’s contribution rate as a percentage of gross pay
employer_deduction_rate: 3.5 (number) - the employer’s contribution rate as a percentage of gross pay; may be null
savings_suspension: false (boolean) - whether the employee is currently on a savings suspension
opted_out_date: 2024-01-15 (string) - the date the employee opted out, if applicable; null otherwise
qualifications (array of UserQualification) - Information about qualifications the user holds, if Qualifications are enabled
regular_hours (RegularHours) - information about the employees regular hours of work
created_at: 1430715548 (required) (number) - When the user’s Tanda profile was created
record_id: 532432 (number) - the record ID, for use with Platform endpoints
next_pay_group_id: 53242 (number) - the ID for the pay group of the user’s next timesheet
last_synced_mobile_app: 1430715548 (number) - Read only: when the user last opened the mobile app.
automatic_break_rule_set_id: 1430715548 (number) - Read only: the ID for the user’s automatic break rule set.
temporary_employee_type: (TemporaryEmployeeType, optional) - Type of a temporary employee user. This field only exists if Enable Temporary Staff setting is turned on.
position_title: Bartender (string) - Read only
position_template: Bartender (Hourly) (string)
ssn: 123456789 (string) - Read only
emergency_contacts (array of EmergencyContact) - Read only
active: false (boolean)
passcode: 01234568975461
Request Remove Departments (application/json)
Body

    {
      "department_ids": null
    }

200
OK
(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,
  "payroll_cessation_code": null,
  "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
  "contracted_weekly_hours": 20.0,
  "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
}

Request Update Singapore Tax Details (application/json)
This example is only applicable for Singapore organisations. The singapore_tax_detail field will not be available for organisations in other countries.
Body

  {
    "tax_declaration": {
      "singapore_tax_detail": {
        "legal_status": "permanent_resident",
        "nationality": "malaysian",
        "race": "chinese",
        "religion": "christianity",
        "marital_status": "married",
        "issue_date": "2022-06-01"
      }
    }
  }

Request Update New Zealand Tax Details (application/json)

This example is only applicable for New Zealand organisations. The NZ tax detail fields will not be available for organisations in other countries.
Body

  {
    "tax_declaration": {
      "nz_tax_code": "ME_SL",
      "nz_esct_rate": "30",
      "nz_source_of_income": "secondary_income"
    }
  }

Request Update UK National Insurance Code (application/json)

This example is only applicable for UK organisations. The uk_national_insurance_code field will not be available for organisations in other countries.
Body

  {
    "tax_declaration": {
      "uk_national_insurance_code": "A"
    }
  }

Request Update Singapore Bank Details (application/json)

This example is only applicable for Singapore organisations. The bsb field is not required for Singapore bank details.
Body

  {
    "bank_details": {
      "bank_name": "OCBC Bank",
      "account_name": "Tan Wei Ming",
      "account_number": "1234567890"
    }
  }

Response 200 (application/json)

Body

  {
    "id": 123456,
    "name": "Li Wei",
    "tax_declaration": {
      "tax_file_number": "S1234567A",
      "employment_basis": "full_time",
      "singapore_tax_detail": {
        "legal_status": "permanent_resident",
        "nationality": "malaysian",
        "race": "chinese",
        "religion": "christianity",
        "marital_status": "married",
        "issue_date": "2022-06-01",
        "expiry_date": null
      }
    },
    "updated_at": 1672617600
  }

The regular_hours object supports optional sleepovers, on_calls, and rostered_days_off arrays alongside schedules. These follow the same format as schedules but without breaks. See Sleepovers, On Calls, and Rostered Days Off for standalone CRUD endpoints.
Request Update Regular Hours (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"
        }
      ],
      "sleepovers": [
        {
          "week": 1,
          "day": "Monday",
          "start": "22:00",
          "end": "06:00",
          "department_id": 1234
        }
      ],
      "on_calls": [
        {
          "week": 1,
          "day": "Tuesday",
          "start": "18:00",
          "end": "06:00",
          "department_id": 1234
        }
      ],
      "rostered_days_off": [
        {
          "week": 1,
          "day": "Wednesday",
          "start": "00:00",
          "end": "00:00"
        }
      ]
    }
  }

200
OK
(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,
    "payroll_cessation_code": null,
    "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
    "contracted_weekly_hours": 20.0,
    "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,
    "temporary_employee_type": 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"
        }
      ],
      "sleepovers": [
        {
          "week": 1,
          "day": "Monday",
          "start": "22:00",
          "end": "06:00",
          "department_id": 1234
        }
      ],
      "on_calls": [
        {
          "week": 1,
          "day": "Tuesday",
          "start": "18:00",
          "end": "06:00",
          "department_id": 1234
        }
      ],
      "rostered_days_off": [
        {
          "week": 1,
          "day": "Wednesday",
          "start": "00:00",
          "end": "00:00"
        }
      ]
    },
    "updated_at": 1562272900
  }

DELETEDelete User
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).
Parameters
id: 654321 (number) - The id of the user
200
OK
(application/json)
Attributes:
id: 123456 (required) (number) - The id of the user
name: Lenny Leonard (required, string) - The user’s preferred name
legal_first_name: Lenny (string) - The user’s first name
legal_middle_names: James (string) - The user’s middle name/s
legal_last_name: Leonard (string) - The user’s last name
date_of_birth: 1955-05-12 (string) - The user’s date of birth
employment_start_date: 1989-12-17 (string) - The user’s employment start date
employee_id: LL1 (string) - The user’s employee id, used for external systems
passcode: 0456 (required) (string) - The user’s system passcode (used for clocking in and out)
platform_role_ids: 18, 19, 22 (required, array[number]) - IDs of the user’s roles (see Access & Roles)
department_ids: 111 (required) (array[number]) - The department (team) ids that the user is a member of
preferred_hours: 20 (required) (number) - The preferred number of hours to be rostered each week
award (object) - Information about the user’s award, null if user isn’t on award
name: Fast Food Industry (required, string) - The name of the award
identifier: MA000003 (string) - The award’s identifier (will be the award code for all modern awards)
note: This field is deprecated, and may be removed in the future. Please rely on the award_template_organisation_id field instead. (string) - 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 (number) - The ID of the award template the user is on
award_template_organisation_id: 5624432 (number) - The internal ID of the award template the user is on
award_tag_ids: 3816 (required) (array[number]) - The award tag ids that apply to the user
report_department_id: 111 (number) - The user’s default team
managed_department_ids: 222 (array[number]) - The department ids that this user manages
active: true (required) (boolean) - Whether the user is active in the system
email: lenny.leonard@springfieldpowerplant.com (string) - The user’s email
payslip_email: lenny.personal@example.com (string) - The user’s payslip email address. Null if not explicitly set.
photo: http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png (string) - An avatar for the user
phone: 0404 123 123 (string) - Phone number for the user
normalised_phone: +61404123123 (string) - Phone number for user with international dialing code
salary: 1234.12 (number) - The weekly salary of the user, if show_wages=true parameter is set
hourly_rate: 32.47 (number) - The hourly rate of the user, if show_wages=true parameter is set, will not show if the salary exists
time_zone: Australia/Brisbane (string) - The user’s time zone
utc_offset: 36000 (required) (number) - The user’s time zone’s UTC offset
contracted_weekly_hours: The number of hours per week a user must work. Working under or over this number of hours may incur overtime or additional costs
part_time_fixed_hours: 20 (number) - Deprecated. This value will always be the same as contracted_weekly_hours.
expected_hours_in_pay_period: 38 (number) - readonly: for salaried staff, defines expected number of hours worked per pay period
days_overtime_averaged_over: 7 (number) - date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run
overtime_calculated_over_period_start: 2016-09-12 (string) - date from which overtime averaging periods should commence
super_fund (object) - information about the employees super fund
id: 1234 (number) - the unique ID of the employees fund
fund_name: FUND NAME (string) - the name of the fund
product_name: FUND PRODUCT (string) - the name of the fund product
smsf: true, false (boolean) - is the fund a self managed fund
abn: 123456789 (number) - the number of the fund
super_fund_membership (object) - information about the employees super fund membership
super_contribution_type: arpa (string) - the type of the employees super contribution
member_number: 123ACB (string) - the membership number of the employees super fund
occupational_rating: A1 (string) - the occupational rating of the employees super fund
super_fund_id: 1234 (required, number) - the record ID of the employees super fund
employer_preferred: 0 (required, number) - indication of an employers preferred super fund
employer_default: 1 (required, number) - indication of an employers default super fund
employer_generic: 2 (required, number) - indication of an employers generic super fund
bank_details (BankDetails) - the bank details of the employee
address (Address) - the residential address of the employee
tax_declaration (object) - the tax declaration information of the employee
previous_family_name: Smith (string) - the previous family name of the employee
australian_tax_resident: true (boolean) - is the user an Australia resident for tax purposes
australian_tax_residency_status: resident (string) - the normalised Australian tax residency status
tax_free_threshold: true (boolean) - is the employee under the tax free threshold?
senior_tax_offset: false (boolean) - can the employee claim a senior tax offset?
zone_overseas_carer: false (boolean) - can the employee claim a zone or overseas tax offset?
student_loan: true (boolean) - does the employee have a student loan?
financial_supplement_debt: true (boolean) - does the employee have a financial supplement debt?
tax_code: 1150L (string) - the employee’s tax code for tax services
uk_tax_year_status: first_job (string) - For UK residents, the stage of the employee’s career
uk_national_insurance_code: A (string) - For UK residents, the National Insurance category letter (e.g., A, B, C, D, E, F, H, I, J, K, L, M, N, S, V, X, Z)
national_insurance_number: AB123456C (string) - For UK organisations, the employee’s National Insurance number. Returns when the financial scope is in use, to the employee themselves or to a user who can read their sensitive data (such as an admin or payroll officer). This replaces tax_file_number for UK orgs, which is now legacy.
employment_basis: full_time (string) - the employment type the employee has specified on their TFN declaration
tax_scale_type: regular (string) - the tax scale type used for calculations
income_type: salary_and_wages (string) - the type of income for tax purposes
employment_type: employee (string) - the type of employment
senior_marital_status: single (string) - marital status for senior tax offset purposes
home_country: France (string) - the employee’s home country (required for working holiday makers)
nz_tax_code: M (string) - For NZ residents, the tax code
nz_esct_rate: 17.5 (string) - For NZ residents, the ESCT rate
nz_source_of_income: primary_income (string) - For NZ residents, the source of income
nz_varied_tax_rate: 25.0 (number) - For NZ residents, the varied tax rate (required for WT, STC, STC_SL tax codes)
onboarding_status: not_applicable, pending, invited, in_progress, completed, invitation_failed (string) - the status of the employee onboarding progress
kiwi_saver (object) - NZ only. The employee’s KiwiSaver settings. Only present for NZ employees who have KiwiSaver configured
status: active_member, automatically_enrolled, opted_in, not_eligible, opted_out, employed_less_than_28_days, not_required_to_be_automatically_enrolled (string) - the employee’s KiwiSaver enrolment status
ird_status_code: AK (string) - the IRD status code derived from the status (e.g. AK, AE, OK, NK); null when no code applies
employee_deduction_rate: 3.0 (number) - the employee’s contribution rate as a percentage of gross pay
employer_deduction_rate: 3.5 (number) - the employer’s contribution rate as a percentage of gross pay; may be null
savings_suspension: false (boolean) - whether the employee is currently on a savings suspension
opted_out_date: 2024-01-15 (string) - the date the employee opted out, if applicable; null otherwise
qualifications (array of UserQualification) - Information about qualifications the user holds, if Qualifications are enabled
regular_hours (RegularHours) - information about the employees regular hours of work
created_at: 1430715548 (required) (number) - When the user’s Tanda profile was created
record_id: 532432 (number) - the record ID, for use with Platform endpoints
next_pay_group_id: 53242 (number) - the ID for the pay group of the user’s next timesheet
last_synced_mobile_app: 1430715548 (number) - Read only: when the user last opened the mobile app.
automatic_break_rule_set_id: 1430715548 (number) - Read only: the ID for the user’s automatic break rule set.
temporary_employee_type: (TemporaryEmployeeType, optional) - Type of a temporary employee user. This field only exists if Enable Temporary Staff setting is turned on.
position_title: Bartender (string) - Read only
position_template: Bartender (Hourly) (string)
ssn: 123456789 (string) - Read only
emergency_contacts (array of EmergencyContact) - Read only
active: false (boolean)
passcode: 01234568975461
Invite Users [/api/v2/users/{id}/invite]
POSTInvite User
This endpoint takes a user ID and sends that user an email invite to use Workforce.

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

Parameters
id: 654321 (number) - The id of the user
201
Created
(application/json)
Invite New Users for Onboarding [/api/v2/users/onboarding]
POSTInvite User for Onboarding
If you are using Workforce’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.

Request Create User for Onboarding (application/json)
Body

    {
      "name": "Eddard Sheppard",
      "email": "carl.carlson@springfieldpowerplant.com",
      "phone": "+61408123654",
      "custom_message": "Welcome to the company!"
    }

201
Created
(application/json)
Invite Existing User for Onboarding [/api/v2/users/{id}/onboard]
POSTInvite Existing User for Onboarding
If you have created a new user with the Create User endpoint and are using Workforce’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 Workforce you cannot use this endpoint.
Parameters
id: 123456 (number) - The id of the user
201
Created
(application/json)
Clocked In Users [/api/v2/users/clocked_in]
GETGet Clocked In Users
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).
Parameters
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified users
200
OK
(application/json)
Body [{“user_id”: 123456, “shift_id”: 1337}]
User Versions [/api/v2/users/{id}/versions]
GETGet User Versions
This method requires the user scope (see Scopes for more information).
Parameters
id: 123456 (number) - The id of the user
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified user versions
200
OK
(application/json)
Attributes (array):
version_id: 123456 (number)
time: 1459209907 (number)
event: update
author (object)
id: 123456 (number)
name: API v2
item_id: 1235435 (number)
item_type: “User” (string)
changes (array)
(object)
field: name
previous: Lenny L Leonard
updated: Lenny Leonard
(object)
field: preferred_hours
previous: 28 (number)
updated: 20 (number)
Alternate Rates [/api/v2/users/{id}/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.
GETGet Alternate Rates
This method requires the user scope (see Scopes for more information).
Parameters
id: 162456 (required, number) - The ID of an user
employment_contract_id: 162456 (optional, number) - The ID of an user’s employment contract
200
OK
(application/json)
Attributes:
alternate_rates (array)
(object)
department_id: 123456 (string)
hourly_rate: 20.01 (string)
PUTUpdate 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.

Parameters
id: 123456 (required, number) - The ID of an user
employment_contract_id: 162456 (optional, number) - The ID of an user’s employment contract
alternate_rates: (required, array)
object: {“department_id”: 987654, “hourly_rate”: 20.01} (required, object) 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
Request Alternate Rates (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},
        ]
    }

201
Created
(application/json)
Attributes(AlternateRatesData)
DELETEDelete Alternate Rates
This method requires the user scope (see Scopes for more information).
This method will delete ALL alternate rates for the user.

Parameters
id: 162456 (required, number) - The ID of an user
employment_contract_id: 162456 (optional, number) - The ID of an user’s employment contract
200
OK
(application/json)
Body

    {
      "message": "Successfully deleted all alternate rates"
    }

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 [/api/v2/user_pay_fields]
GETGet Payfields For All Users
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).
Parameters
page: 1 (optional, number) - The page number for your pay fields list
page_size: 50 (optional, number) - The number of pay field objects retrieved per page. The maximum is 100 per page.
200
OK
(application/json)
Attributes (array):
id: 12345 (number) - The id of the payfield
reason_for_change: Pay Fields Update Jan 2022 (string) - The name of a pay field change, usually specifying the reason.
from_date: 1970-1-1 (string) - The effective date that the grouping of payfields applies after
to_date: 1970-1-1 (string) - The effective date that the grouping of payfields applies until
hourly_rate: 0.0 (number) - Hourly rate of the employee for the effective date
yearly_salary: 60000 (number) - Yearly Salary of the employee for the effective date
user_id: 12345 (number) - The id of the user these payfields apply to
award_template_organisation_id: 12345 (number) - The id of the award template organisation that is attached to this user
Get Payfields By Known ID [/api/v2/user_pay_fields/{id}]
GETGet Payfields By Payfield ID
Retrieves one pay field object by it’s unique id.

This method requires the cost scope (see Scopes for more information).
Parameters
id: 54321 (number) - The id of the payfield
200
OK
(application/json)
Attributes:
id: 12345 (number) - The id of the payfield
reason_for_change: Pay Fields Update Jan 2022 (string) - The name of a pay field change, usually specifying the reason.
from_date: 1970-1-1 (string) - The effective date that the grouping of payfields applies after
to_date: 1970-1-1 (string) - The effective date that the grouping of payfields applies until
hourly_rate: 0.0 (number) - Hourly rate of the employee for the effective date
yearly_salary: 60000 (number) - Yearly Salary of the employee for the effective date
user_id: 12345 (number) - The id of the user these payfields apply to
award_template_organisation_id: 12345 (number) - The id of the award template organisation that is attached to this user
Employee Payfields By User [/api/v2/user_pay_fields/user/{user_id}]
GETGet Payfields By User
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

Parameters
user_id: 654321 (number) - The id of the user
201
Created
(application/json)
Attributes (array):
id: 12345 (number) - The id of the payfield
reason_for_change: Pay Fields Update Jan 2022 (string) - The name of a pay field change, usually specifying the reason.
from_date: 1970-1-1 (string) - The effective date that the grouping of payfields applies after
to_date: 1970-1-1 (string) - The effective date that the grouping of payfields applies until
hourly_rate: 0.0 (number) - Hourly rate of the employee for the effective date
yearly_salary: 60000 (number) - Yearly Salary of the employee for the effective date
user_id: 12345 (number) - The id of the user these payfields apply to
award_template_organisation_id: 12345 (number) - The id of the award template organisation that is attached to this user
Verify Employee Payfields By User [/api/v2/user_pay_fields/user/{user_id}/verify]
GETVerify Payfields By User
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).
Parameters
user_id: 654321 (number) - The id of the user
200
OK
(application/json)
Attributes (array):
id: 12345 (number) - The id of the payfield
from (object)
date: 2022-01-01 (string)
valid: true (boolean)
to (object)
date: 2023-01-01 (string)
valid: true (boolean)
errors: Something is wrong, Something else is wrong (array[string])
Updating Pay Fields [/api/v2/user_pay_fields/{id}]
PUTUpdate Payfield
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.

Parameters
id: 54321 (number) - The ID of payfield entry.
Request Update Payfield (application/json)
Body

    {
      "id": 54321,
      "user_id": 654321,
      "from_date": "1970-1-1",
      "to_date": "2020-1-1",
      "hourly_rate": 0.0,
      "award_tags": "Casual,Level 1",
      "contracted_weekly_hours": 38,
      "yearly_salary": 60000,
      "award_template_organisation_id": 12345
    }

201
Created
(application/json)
Attributes:
id: 12345 (number) - The id of the payfield
reason_for_change: Pay Fields Update Jan 2022 (string) - The name of a pay field change, usually specifying the reason.
from_date: 1970-1-1 (string) - The effective date that the grouping of payfields applies after
to_date: 1970-1-1 (string) - The effective date that the grouping of payfields applies until
hourly_rate: 0.0 (number) - Hourly rate of the employee for the effective date
yearly_salary: 60000 (number) - Yearly Salary of the employee for the effective date
user_id: 12345 (number) - The id of the user these payfields apply to
award_template_organisation_id: 12345 (number) - The id of the award template organisation that is attached to this user
Creating Pay Fields [/api/v2/user_pay_fields]
POSTCreate Payfield
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.
Request Create Payfield (application/json)
Body

        {
          "user_id": 654321,
          "from_date": "1970-1-1",
          "to_date": "2020-1-1",
          "hourly_rate": 0.0,
          "award_tags": "Casual,Level 1",
          "yearly_salary": 60000,
          "contracted_weekly_hours": 38,
          "award_template_organisation_id": 12345
        }

200
OK
(application/json)
Body

      {
        "id": 123,
        "from_date": "1970-1-1",
        "to_date": "2020-1-1",
        "hourly_rate": 0.0,
        "award_tags": "Casual,Level 1",
        "yearly_salary": 60000,
        "contracted_weekly_hours": 38,
        "user_id": 654321,
        "award_template_organisation_id": 12345
      }

Schema

Attributes:
id: 12345 (number) - The id of the payfield
reason_for_change: Pay Fields Update Jan 2022 (string) - The name of a pay field change, usually specifying the reason.
from_date: 1970-1-1 (string) - The effective date that the grouping of payfields applies after
to_date: 1970-1-1 (string) - The effective date that the grouping of payfields applies until
hourly_rate: 0.0 (number) - Hourly rate of the employee for the effective date
yearly_salary: 60000 (number) - Yearly Salary of the employee for the effective date
user_id: 12345 (number) - The id of the user these payfields apply to
award_template_organisation_id: 12345 (number) - The id of the award template organisation that is attached to this user
Managing Multiple Pay Fields [/api/v2/user_pay_fields/{user_id}]
POSTCreate & Update Multiple Pay Fields For A User
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.

Parameters
user_id: 654321 (number) - The ID of the user
Request Create / Update Pay Fields (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.0,
              "award_tags": "Casual,Level 1",
              "yearly_salary": 60000,
              "contracted_weekly_hours": 38,
              "award_template_organisation_id": 12345
            }
          ]
        }

201
Created
(application/json)
Attributes (array):
id: 12345 (number) - The id of the payfield
reason_for_change: Pay Fields Update Jan 2022 (string) - The name of a pay field change, usually specifying the reason.
from_date: 1970-1-1 (string) - The effective date that the grouping of payfields applies after
to_date: 1970-1-1 (string) - The effective date that the grouping of payfields applies until
hourly_rate: 0.0 (number) - Hourly rate of the employee for the effective date
yearly_salary: 60000 (number) - Yearly Salary of the employee for the effective date
user_id: 12345 (number) - The id of the user these payfields apply to
award_template_organisation_id: 12345 (number) - The id of the award template organisation that is attached to this user
Deleting Pay Fields [/api/v2/user_pay_fields/{id}]
DELETEDelete Payfield By 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).

Parameters
id: 54321 (number) - The ID of payfield entry.
Request Delete Payfield (application/json)
Body

        {
          "id": 54321
        }

201
Created
(application/json)
Locations
Admins and general managers can CRUD locations. Team managers can read locations which contain teams they manage.
Location List [/api/v2/locations]
GETGet Locations
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.
Parameters
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified locations
platform: false (optional, boolean) - If true, Platform data will be returned (defaults to false).
show_business_hours: false (optional, boolean) - If true, business hours will be returned (defaults to false).
200
OK
(application/json)
Attributes (array):
id: 111 (required) (number) - The id of the location
name: Springfield (required) (string) - The name of the location
short_name: S (string) - The abbreviated form of the location’s name
latitude: -27.459687 (number) - The latitude of the location
longitude: 153.032108 (number) - The longitude of the location
address: Springfield Powerplant Reactors (string) - Address of the location
time_zone: Australia/Brisbane (required) (string) - The location’s time zone
utc_offset: 36000 (required) (number) - The location’s time zone’s UTC offset
public_holiday_regions: au, au_qld (array[string]) - Public holiday regions (see Locations section for list of options)
specific_holiday_dates (array of SpecificHolidayDateData) - The dates and times of specific holidays for the location
business_day_cutoff: 5 (number) - 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.
business_hours (array of BusinessHoursData) - The business hours of the location
record_id: 532432 (number) - the record ID, for use with Platform endpoints
POSTCreate Location
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).
Request Create Location (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
        }
      ]
    }

200
OK
(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
    }

Request Create basic Location (application/json)
Body

    {
      "name": "Springfield"
    }

200
OK
(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

Attributes:
id: 111 (required) (number) - The id of the location
name: Springfield (required) (string) - The name of the location
short_name: S (string) - The abbreviated form of the location’s name
latitude: -27.459687 (number) - The latitude of the location
longitude: 153.032108 (number) - The longitude of the location
address: Springfield Powerplant Reactors (string) - Address of the location
time_zone: Australia/Brisbane (required) (string) - The location’s time zone
utc_offset: 36000 (required) (number) - The location’s time zone’s UTC offset
public_holiday_regions: au, au_qld (array[string]) - Public holiday regions (see Locations section for list of options)
specific_holiday_dates (array of SpecificHolidayDateData) - The dates and times of specific holidays for the location
business_day_cutoff: 5 (number) - 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.
business_hours (array of BusinessHoursData) - The business hours of the location
record_id: 532432 (number) - the record ID, for use with Platform endpoints
id: (number)
Location [/api/v2/locations/{id}]
GETGet Location
This method requires the department scope (see Scopes for more information).
Parameters
id: 111 (number) - The id of the location
platform: false (optional, boolean) - If true, Platform data will be returned (defaults to false).
200
OK
(application/json)
Attributes:
id: 111 (required) (number) - The id of the location
name: Springfield (required) (string) - The name of the location
short_name: S (string) - The abbreviated form of the location’s name
latitude: -27.459687 (number) - The latitude of the location
longitude: 153.032108 (number) - The longitude of the location
address: Springfield Powerplant Reactors (string) - Address of the location
time_zone: Australia/Brisbane (required) (string) - The location’s time zone
utc_offset: 36000 (required) (number) - The location’s time zone’s UTC offset
public_holiday_regions: au, au_qld (array[string]) - Public holiday regions (see Locations section for list of options)
specific_holiday_dates (array of SpecificHolidayDateData) - The dates and times of specific holidays for the location
business_day_cutoff: 5 (number) - 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.
business_hours (array of BusinessHoursData) - The business hours of the location
record_id: 532432 (number) - the record ID, for use with Platform endpoints
PUTUpdate Location
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.
Parameters
id: 111 (number) - The id of the location
Request Update Location (application/json)
Body

    {
      "name": "Shelbyville",
      "short_name": "S",
      "latitude": -27.467004,
      "longitude": 153.025453
    }

200
OK
(application/json)
Attributes:
id: 111 (required) (number) - The id of the location
name: Springfield (required) (string) - The name of the location
short_name: S (string) - The abbreviated form of the location’s name
latitude: -27.459687 (number) - The latitude of the location
longitude: 153.032108 (number) - The longitude of the location
address: Springfield Powerplant Reactors (string) - Address of the location
time_zone: Australia/Brisbane (required) (string) - The location’s time zone
utc_offset: 36000 (required) (number) - The location’s time zone’s UTC offset
public_holiday_regions: au, au_qld (array[string]) - Public holiday regions (see Locations section for list of options)
specific_holiday_dates (array of SpecificHolidayDateData) - The dates and times of specific holidays for the location
business_day_cutoff: 5 (number) - 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.
business_hours (array of BusinessHoursData) - The business hours of the location
record_id: 532432 (number) - the record ID, for use with Platform endpoints
name: Shelbyville
Request Update Business Hours (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" },
      ]
    }

200
OK
(application/json)
Attributes:
id: 111 (required) (number) - The id of the location
name: Springfield (required) (string) - The name of the location
short_name: S (string) - The abbreviated form of the location’s name
latitude: -27.459687 (number) - The latitude of the location
longitude: 153.032108 (number) - The longitude of the location
address: Springfield Powerplant Reactors (string) - Address of the location
time_zone: Australia/Brisbane (required) (string) - The location’s time zone
utc_offset: 36000 (required) (number) - The location’s time zone’s UTC offset
public_holiday_regions: au, au_qld (array[string]) - Public holiday regions (see Locations section for list of options)
specific_holiday_dates (array of SpecificHolidayDateData) - The dates and times of specific holidays for the location
business_day_cutoff: 5 (number) - 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.
business_hours (array of BusinessHoursData) - The business hours of the location
record_id: 532432 (number) - the record ID, for use with Platform endpoints
business_hours (array)
(object)
weekday: 0 (number)
start: 08:30 (string)
finish: 17:00 (string)
(object)
weekday: 1 (number)
start: 06:00 (string)
finish: 14:00 (string)
(object)
weekday: 1 (number)
start: 15:00 (string)
finish: 20:00 (string)
(object)
weekday: 2 (number)
start: 11:30 (string)
finish: 23:45 (string)
DELETEDelete Location
This method requires the department scope (see Scopes for more information).
Locations cannot be deleted if they have any teams.
Parameters
id: 111 (number) - The id of the location
200
OK
(application/json)
Location Versions [/api/v2/locations/{id}/versions]
GETGet Location Versions
This method requires the department scope (see Scopes for more information).
Parameters
id: 111 (number) - The id of the location
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified location versions
200
OK
(application/json)
Attributes (array):
version_id: 123456 (number)
time: 1459209907 (number)
event: update
author (object)
id: 123456 (number)
name: API v2
item_id: 1235435 (number)
item_type: “Location” (string)
changes (array)
(object)
field: name
previous: Spring field
updated: Springfield
(object)
field: longitude
previous: 153.032108 (number)
updated: 100.500169 (number)
Teams (Departments)
Departments are often referred to as Teams inside Workforce. 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 [/api/v2/departments]
GETGet Teams
This method requires the department scope (see Scopes for more information).
Parameters
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified teams
platform: false (optional, boolean) - If true, Platform data will be returned (defaults to false).
tracking_categories: false (optional, boolean) - If true, tracking categories for each team will be returned (defaults to false).
page: 1 (optional, number) - The page number for your teams list
page_size: 50 (optional, number) - The number of teams retrieved per page. The maximum is 100 teams per page.
Request As a manager

200
OK
(application/json)
Attributes (array):
id: 808 (required) (number) - The id of the team
location_id: 111 (required) (number) - The id of the team’s location
name: Waiters (required) (string) - The name of the team
export_name: WGB-30 (string) - The payroll export name of the team (if different to the name)
colour: #FBB829 (string) - The team’s colour
staff: 1, 2, 123456 (array[number]) - The user ids of the staff in the team
managers: 4, 5 (array[number]) - The user ids of the managers of the team
associated_tags: Level 2, Level 3 HD (array[string]) - Tags automatically assigned to shifts worked in this team
qualification_ids: 1234, 4321 (array[number]) - The required qualifications to work in this team
assisting_team_ids: 1234, 4321 (array[number]) - The teams that will count toward this team’s requirements on the roster
team_group: Front of House (string) - A group of teams for rostering or reporting
record_id: 532432 (number) - the record ID, for use with Platform endpoints
Request As an employee

200
OK
(application/json)
Body

[
  {
    "id": 608,
    "name": "Waiters",
    "location_id": 111,
    "colour": "#FBB830"
  }
]

POSTCreate Team
This method requires the department scope (see Scopes for more information).
Request Create Team (application/json)
Body

    {
      "name": "Waiters",
      "location_id": 111,
      "export_name": "WGB-32",
      "colour": "#FBB830",
      "team_group": "Front of House",
      "qualification_ids" [123456],
      "manager_ids": [4444, 5555],
      "user_ids": [1111, 2222, 3333]
    }

200
OK
(application/json)
Attributes(DepartmentData)
id: 809 (number)
location_id: 111
name: Waiters
export_name: WGB-32
colour: #FBB830
staff: [1111, 2222, 3333]
managers: [4444, 5555]
team_group: Front of House
assisting_team_ids: (array)
Request Create Basic Team (application/json)
Body

    {
      "name": "Waiters",
      "location_id": "111",
    }

200
OK
(application/json)
Body

    {
      "id": 809,
      "location_id": 111,
      "name": "Waiters",
      "export_name": null,
      "colour": null,
      "staff": [],
      "managers": []
    }

Schema

Attributes:
id: 808 (required) (number) - The id of the team
location_id: 111 (required) (number) - The id of the team’s location
name: Waiters (required) (string) - The name of the team
export_name: WGB-30 (string) - The payroll export name of the team (if different to the name)
colour: #FBB829 (string) - The team’s colour
staff: 1, 2, 123456 (array[number]) - The user ids of the staff in the team
managers: 4, 5 (array[number]) - The user ids of the managers of the team
associated_tags: Level 2, Level 3 HD (array[string]) - Tags automatically assigned to shifts worked in this team
qualification_ids: 1234, 4321 (array[number]) - The required qualifications to work in this team
assisting_team_ids: 1234, 4321 (array[number]) - The teams that will count toward this team’s requirements on the roster
team_group: Front of House (string) - A group of teams for rostering or reporting
record_id: 532432 (number) - the record ID, for use with Platform endpoints
id: (number)
Team [/api/v2/departments/{id}]
GETGet Team
This method requires the department scope (see Scopes for more information).
Parameters
id: 111 (number) - The id of the team
platform: false (optional, boolean) - If true, Platform data will be returned (defaults to false).
tracking_categories: false (optional, boolean) - If true, tracking categories for each team will be returned (defaults to false).
200
OK
(application/json)
Attributes:
id: 808 (required) (number) - The id of the team
location_id: 111 (required) (number) - The id of the team’s location
name: Waiters (required) (string) - The name of the team
export_name: WGB-30 (string) - The payroll export name of the team (if different to the name)
colour: #FBB829 (string) - The team’s colour
staff: 1, 2, 123456 (array[number]) - The user ids of the staff in the team
managers: 4, 5 (array[number]) - The user ids of the managers of the team
associated_tags: Level 2, Level 3 HD (array[string]) - Tags automatically assigned to shifts worked in this team
qualification_ids: 1234, 4321 (array[number]) - The required qualifications to work in this team
assisting_team_ids: 1234, 4321 (array[number]) - The teams that will count toward this team’s requirements on the roster
team_group: Front of House (string) - A group of teams for rostering or reporting
record_id: 532432 (number) - the record ID, for use with Platform endpoints
PUTUpdate Team
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.
Parameters
id: 111 (number) - The id of the team
Request Update Team Name (application/json)
Body

    {
      "name": "Kitchen Staff"
    }

200
OK
(application/json)
Attributes:
id: 808 (required) (number) - The id of the team
location_id: 111 (required) (number) - The id of the team’s location
name: Waiters (required) (string) - The name of the team
export_name: WGB-30 (string) - The payroll export name of the team (if different to the name)
colour: #FBB829 (string) - The team’s colour
staff: 1, 2, 123456 (array[number]) - The user ids of the staff in the team
managers: 4, 5 (array[number]) - The user ids of the managers of the team
associated_tags: Level 2, Level 3 HD (array[string]) - Tags automatically assigned to shifts worked in this team
qualification_ids: 1234, 4321 (array[number]) - The required qualifications to work in this team
assisting_team_ids: 1234, 4321 (array[number]) - The teams that will count toward this team’s requirements on the roster
team_group: Front of House (string) - A group of teams for rostering or reporting
record_id: 532432 (number) - the record ID, for use with Platform endpoints
name: Kitchen Staff
Request Update Users & Managers (application/json)
Body

              {
                "user_ids": [1111, 2222, 3333],
                "manager_ids": [4444, 5555]
              }

200
OK
(application/json)
Attributes:
id: 808 (required) (number) - The id of the team
location_id: 111 (required) (number) - The id of the team’s location
name: Waiters (required) (string) - The name of the team
export_name: WGB-30 (string) - The payroll export name of the team (if different to the name)
colour: #FBB829 (string) - The team’s colour
staff: 1, 2, 123456 (array[number]) - The user ids of the staff in the team
managers: 4, 5 (array[number]) - The user ids of the managers of the team
associated_tags: Level 2, Level 3 HD (array[string]) - Tags automatically assigned to shifts worked in this team
qualification_ids: 1234, 4321 (array[number]) - The required qualifications to work in this team
assisting_team_ids: 1234, 4321 (array[number]) - The teams that will count toward this team’s requirements on the roster
team_group: Front of House (string) - A group of teams for rostering or reporting
record_id: 532432 (number) - the record ID, for use with Platform endpoints
staff: 1111, 2222, 3333
managers: 4444, 5555
Request Update Required Qualifications (application/json)
Body

    {
      "qualification_ids": [1001, 1002]
    }

200
OK
(application/json)
Attributes:
id: 808 (required) (number) - The id of the team
location_id: 111 (required) (number) - The id of the team’s location
name: Waiters (required) (string) - The name of the team
export_name: WGB-30 (string) - The payroll export name of the team (if different to the name)
colour: #FBB829 (string) - The team’s colour
staff: 1, 2, 123456 (array[number]) - The user ids of the staff in the team
managers: 4, 5 (array[number]) - The user ids of the managers of the team
associated_tags: Level 2, Level 3 HD (array[string]) - Tags automatically assigned to shifts worked in this team
qualification_ids: 1234, 4321 (array[number]) - The required qualifications to work in this team
assisting_team_ids: 1234, 4321 (array[number]) - The teams that will count toward this team’s requirements on the roster
team_group: Front of House (string) - A group of teams for rostering or reporting
record_id: 532432 (number) - the record ID, for use with Platform endpoints
qualifications: 1001, 1002
DELETEDelete Team
This method requires the department scope (see Scopes for more information).
Parameters
id: 111 (number) - The id of the team
200
OK
(application/json)
Team Versions [/api/v2/departments/{id}/versions]
GETGet Team Versions
This method requires the department scope (see Scopes for more information).
Parameters
id: 111 (number) - The id of the team
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified team versions
200
OK
(application/json)
Attributes (array):
version_id: 123456 (number)
time: 1459209907 (number)
event: update
author (object)
id: 123456 (number)
name: API v2
item_id: 1235435 (number)
item_type: “Department” (string)
changes (array)
(object)
field: name
previous: Wait staff
updated: Waiters
(object)
field: colour
previous: #3FAFD7
updated: #FBB829
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 [/api/v2/shift_details]
GETGet Shift Details
This method requires the department scope (see Scopes for more information).
200
OK
(application/json)
Attributes (array):
id: 36 (required) (number) - The id of the shift detail
department_id: 808 (required) (number) - The id of the shift detail’s department
name: Higher Duties (required, string) - The name of the shift detail
POSTCreate Shift Detail
This method requires the department scope (see Scopes for more information).
Request Create Shift Detail (application/json)
Body

    {
      "name": "Manager",
      "department_id": 808
    }

200
OK
(application/json)
Attributes(ShiftDetailData)
id: 532 (number)
department_id: 808
name: Manager
Shift Detail [/api/v2/shift_details/{id}]
GETGet Shift Detail
This method requires the department scope (see Scopes for more information).
Parameters
id: 36 (number) - The id of the shift detail
200
OK
(application/json)
Attributes:
id: 36 (required) (number) - The id of the shift detail
department_id: 808 (required) (number) - The id of the shift detail’s department
name: Higher Duties (required, string) - The name of the shift detail
PUTUpdate Shift Detail
This method requires the department scope (see Scopes for more information).
Parameters
id: 36 (number) - The id of the shift detail
Request Update Shift Detail (application/json)
Body

    {
      "name": "Shift Runner"
    }

200
OK
(application/json)
Attributes:
id: 36 (required) (number) - The id of the shift detail
department_id: 808 (required) (number) - The id of the shift detail’s department
name: Higher Duties (required, string) - The name of the shift detail
+ name: Shift Runner

DELETEDelete Shift Detail
This method requires the department scope (see Scopes for more information).
Parameters
id: 36 (number) - The id of the shift detail
200
OK
(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 [/api/v2/platform/roles]
GETGet Platform Roles
This method requires the platform scope (see Scopes for more information).
200
OK
(application/json)
Attributes (array):
id: 3816 (required) (number) - The id of the role
name: Admin (required) (string) - The name of the role
description: access to all functions in Tanda (required, string) - Description of the role
type: organisation_admin (required) (string) - organisation_admin	manager	employee
enabled: true (required) (boolean) - Can the role be applied to staff?
native: true (required) (boolean) - If false, the role was user-created. If true, system-created.
sort_order: 1 (required) (number) - Order the role should display in
Award Tags
No special permissions are required to read award tags.
Award Tag List [/api/v2/award_tags]
GETGet Award Tags
This method requires the user scope (see Scopes for more information).
Parameters
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified award tags
200
OK
(application/json)
Attributes (array):
id: 3816 (required) (number) - The id of the award tag
name: Casual (required) (string) - The name of the award tag
Award Tag [/api/v2/award_tags/{id}]
GETGet Award Tag
This method requires the user scope (see Scopes for more information).
Parameters
id: 3816 (number) - The id of the Award Tag
200
OK
(application/json)
Attributes:
id: 3816 (required) (number) - The id of the award tag
name: Casual (required) (string) - The name of the award tag
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 [/api/v2/leave]
GETGet Leave List
Lookup multiple leave requests in a single request.

Your URL parameters must include:

from and to, 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.
By default inactive users are excluded.
Parameters
ids: 1,2,666 (optional, string) - Comma separated list of leave ids to lookup
from: 2016-03-15 (optional, string) - From date to lookup leave in
to: 2016-04-05 (optional, string) - To date to lookup leave in
user_ids: 1,2,123456 (optional, string) - Comma separated list of user ids to lookup leave for
page: 1 (optional, number) - The page number for your leave request list
page_size: 50 (optional, number) - The number of leave requests retrieved per page. Maximum 100 per page.
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified leave requests
include_inactive: true (optional, boolean) - Include inactive staff in your response.
200
OK
(application/json)
Attributes (array):
id: 666 (required) (number) - The id of the leave request
department_id: 808 (number) - The id of the team with which the leave request’s shifts will be tagged
user_id: 123456 (required) (number) - The id of the user who owns the leave request
reason: Terribly Sick (string) - The reason for the leave request - optional
leave_type: Personal/Carer’s Leave (required, string) - The type of leave request
hours: 7.6 (required) (number) - The number of workable hours the leave request spans
start: 2016-04-01 (required) (string) - The start date for the leave request
finish: 2016-04-01 (required) (string) - The end date for the leave request
start_time: 2000-01-01T09:30:00+10:00 (optional, string) - The start time for a leave request event
finish_time: 2000-01-01T05:30:00+10:00 (optional, string) - The end time for a leave request event
status: pending (required) (string) - The status for the leave request. One of [‘pending’, ‘approved’, ‘rejected’]
multitagging: false (string) - Determines whether shifts on the leave request can be tagged differently.
all_day: true (optional, boolean) - Useful for all day leave requests.
include_inactive: false (optional, boolean) - Useful for all leave requests that include inactive staff.
daily_breakdown (object)
2016-04-01: (object)
hours: 7.6 (optional, number)
all_day: true (required, boolean)
start_time: 2016-04-01T09:30:00+1000 (required, string)
finish_time: 2016-04-01T17:30:00+1000 (required, string)
POSTCreate Leave Request
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 not be returned by the API, since technically it is a property of the shift, not of the leave request.

If you are building a user interface for the creation of leave requests, you might like to use the default hours endpoint to get recommendations for the hours field as the user chooses their dates.

You can attach a file when creating a leave request using the file_id parameter. See the temporary files endpoint for more information. The file should be a JPEG, PNG, GIF, or PDF.

This method requires the leave scope (see Scopes for more information).
New: time fields, and all_day boolean added to leave. Time fields allow leave to apply to a portion of a day, instead of a whole day. The date part of the time fields is not to be used and when returned from the API will always use the ruby default date of 2000-01-01.
Request Create Leave (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"
        }
      ]
    }

200
OK
(application/json)
Attributes:
id: 666 (required) (number) - The id of the leave request
department_id: 808 (number) - The id of the team with which the leave request’s shifts will be tagged
user_id: 123456 (required) (number) - The id of the user who owns the leave request
reason: Terribly Sick (string) - The reason for the leave request - optional
leave_type: Personal/Carer’s Leave (required, string) - The type of leave request
hours: 7.6 (required) (number) - The number of workable hours the leave request spans
start: 2016-04-01 (required) (string) - The start date for the leave request
finish: 2016-04-01 (required) (string) - The end date for the leave request
start_time: 2000-01-01T09:30:00+10:00 (optional, string) - The start time for a leave request event
finish_time: 2000-01-01T05:30:00+10:00 (optional, string) - The end time for a leave request event
status: pending (required) (string) - The status for the leave request. One of [‘pending’, ‘approved’, ‘rejected’]
multitagging: false (string) - Determines whether shifts on the leave request can be tagged differently.
all_day: true (optional, boolean) - Useful for all day leave requests.
include_inactive: false (optional, boolean) - Useful for all leave requests that include inactive staff.
daily_breakdown (object)
2016-04-01: (object)
hours: 7.6 (optional, number)
all_day: true (required, boolean)
start_time: 2016-04-01T09:30:00+1000 (required, string)
finish_time: 2016-04-01T17:30:00+1000 (required, string)
id: 7250 (number)
user_id: 123456 (number)
reason: Holiday in France
leave_type: Annual Leave
fallback_leave_type: Unpaid Leave
hours: 114.0 (number)
start: 2016-03-07
start_time: 2000-01-01T09:30:00
finish: 2016-03-08
finish_time: 2000-01-01T17:30:00
status: pending
all_day: false
verification: http://springfieldfiles.com/albums/notes/0244.JPG
daily_breakdown: (array)
(object)
date: 2016-03-07 (required, string)
hours: 7.6 (optional, number)
all_day: true (required, boolean)
start_time: 2016-03-07T09:30:00+1000 (required, string)
finish_time: 2016-03-07T17:30:00+1000 (required, string)
(object)
date: 2016-03-08 (required, string)
hours: 7.6 (optional, number)
all_day: true (required, boolean)
start_time: 2016-03-08T09:30:00+1000 (required, string)
finish_time: 2016-03-08T17:30:00+1000 (required, string)
Leave Request [/api/v2/leave/{id}]
GETGet Leave Request
This method requires the leave scope (see Scopes for more information).
Parameters
id: 666 (number) - The id of the leave to lookup
200
OK
(application/json)
Attributes:
id: 666 (required) (number) - The id of the leave request
department_id: 808 (number) - The id of the team with which the leave request’s shifts will be tagged
user_id: 123456 (required) (number) - The id of the user who owns the leave request
reason: Terribly Sick (string) - The reason for the leave request - optional
leave_type: Personal/Carer’s Leave (required, string) - The type of leave request
hours: 7.6 (required) (number) - The number of workable hours the leave request spans
start: 2016-04-01 (required) (string) - The start date for the leave request
finish: 2016-04-01 (required) (string) - The end date for the leave request
start_time: 2000-01-01T09:30:00+10:00 (optional, string) - The start time for a leave request event
finish_time: 2000-01-01T05:30:00+10:00 (optional, string) - The end time for a leave request event
status: pending (required) (string) - The status for the leave request. One of [‘pending’, ‘approved’, ‘rejected’]
multitagging: false (string) - Determines whether shifts on the leave request can be tagged differently.
all_day: true (optional, boolean) - Useful for all day leave requests.
include_inactive: false (optional, boolean) - Useful for all leave requests that include inactive staff.
daily_breakdown (object)
2016-04-01: (object)
hours: 7.6 (optional, number)
all_day: true (required, boolean)
start_time: 2016-04-01T09:30:00+1000 (required, string)
finish_time: 2016-04-01T17:30:00+1000 (required, string)
PUTUpdate Leave Request
This method requires the leave scope (see Scopes for more information).
Employees cannot update a leave request, with the exception of rejecting their own pending leave request.
Parameters
id: 666 (number) - The id of the leave to update
Request Update Leave (application/json)
Body

    {
      "reason": "Really Really Sick",
    }

200
OK
(application/json)
Attributes:
id: 666 (required) (number) - The id of the leave request
department_id: 808 (number) - The id of the team with which the leave request’s shifts will be tagged
user_id: 123456 (required) (number) - The id of the user who owns the leave request
reason: Terribly Sick (string) - The reason for the leave request - optional
leave_type: Personal/Carer’s Leave (required, string) - The type of leave request
hours: 7.6 (required) (number) - The number of workable hours the leave request spans
start: 2016-04-01 (required) (string) - The start date for the leave request
finish: 2016-04-01 (required) (string) - The end date for the leave request
start_time: 2000-01-01T09:30:00+10:00 (optional, string) - The start time for a leave request event
finish_time: 2000-01-01T05:30:00+10:00 (optional, string) - The end time for a leave request event
status: pending (required) (string) - The status for the leave request. One of [‘pending’, ‘approved’, ‘rejected’]
multitagging: false (string) - Determines whether shifts on the leave request can be tagged differently.
all_day: true (optional, boolean) - Useful for all day leave requests.
include_inactive: false (optional, boolean) - Useful for all leave requests that include inactive staff.
daily_breakdown (object)
2016-04-01: (object)
hours: 7.6 (optional, number)
all_day: true (required, boolean)
start_time: 2016-04-01T09:30:00+1000 (required, string)
finish_time: 2016-04-01T17:30:00+1000 (required, string)
reason: Really Really Sick
Leave Types [/api/v2/leave/types_for/{user_id}]
GETGet Leave Types for User
This method requires the leave scope (see Scopes for more information).
Parameters
user_id: 123456 (number) - The id of the user to lookup leave types for
200
OK
(application/json)
Attributes:
Annual Leave (string) - Leave type
Personal/Carer’s Leave (string) - Leave type
Leave Types With Details [/api/v2/leave/types_with_details_for/{user_id}]
GETGet Leave Types with details for User
This method requires the leave scope (see Scopes for more information).
Parameters
user_id: 123456 (number) - The id of the user to lookup leave types for
200
OK
(application/json)
Body

        [
          {
            name: "Annual Leave",
            prevent_negative: true,
            default_fallback_leave_type_name: "Unpaid Leave"
          },
          {
            name: "Unpaid Leave",
            prevent_negative: false,
            default_fallback_leave_type_name: nil
          } ]

Leave Request Versions [/api/v2/leave/{id}/versions]
GETGet Leave Request Versions
This method requires the leave scope (see Scopes for more information).
Parameters
id: 666 (number) - The id of the leave request
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified leave request versions
200
OK
(application/json)
Attributes (array):
version_id: 123456 (number)
time: 1459209907 (number)
event: update
author (object)
id: 123456 (number)
name: API v2
item_id: 1235435 (number)
item_type: “Leave” (string)
changes (array)
(object)
field: status
previous: pending
updated: approved
(object)
field: reason
previous: Holiday
updated: Terribly Sick
Default Leave Hours [/api/v2/leave/hours_between]
GETGet Default Hours for a Leave Request
Use this endpoint to get a recommendation for the number of hours of leave someone should take based on the given dates. This will take into account public holidays and weekends, and the default leave hours setting in an account. For example, if given a date range of 5 days, of which 1 is a weekend and 1 is a holiday, and with a default leave hours setting of 7.6, the endpoint will return 22.8 hours.

This method requires the leave scope (see Scopes for more information).
Parameters
user_id: 123456 (number) - The id of the user
start: 2016-03-15 (string) - Start date of leave request
finish: 2016-03-17 (string) - Finish date of leave request
leave_type: Annual Leave (optional, string) - The leave type
200
OK
(application/json)
Body

    {
      "hours": "22.8",
    }

Leave Balances
Leave balances denote how much leave (of each type) someone has accrued.

Leave balance interactions require the same permissions as leave requests.
Leave Balance List [/api/v2/leave_balances]
GETGet Leave Balances
Lookup leave balances for one or more user_ids.

This method requires the leave scope (see Scopes for more information).
Parameters
user_ids: 1,2,666 (required, string) - Comma separated list of user ids to lookup leave balances for
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified leave balances
200
OK
(application/json)
Attributes (array):
id: 666 (required) (number) - The id of the leave balance
user_id: 123456 (required) (number) - The id of the user who owns the leave balance
leave_type: Annual Leave (required, string) - The type of leave
hours: 4 (required) (number) - The number of hours of leave accrued
should_accrue: false (boolean) - If true, this leave balance will accrue in Tanda automatically. If false, you should keep it up to date. Default is false.
POSTCreate Leave Balance
Use the Leave Types For User call to find accessible leave types for your user.

This method requires the leave scope (see Scopes for more information).
Request Create Leave Balance (application/json)
Body

    {
      "user_id": 123456,
      "leave_type": "Annual Leave",
      "hours": 18.0
    }

200
OK
(application/json)
Attributes:
id: 666 (required) (number) - The id of the leave balance
user_id: 123456 (required) (number) - The id of the user who owns the leave balance
leave_type: Annual Leave (required, string) - The type of leave
hours: 4 (required) (number) - The number of hours of leave accrued
should_accrue: false (boolean) - If true, this leave balance will accrue in Tanda automatically. If false, you should keep it up to date. Default is false.
+ user_id: 123456 (number)
+ hours: 18.0 (number)
+ leave_type: Annual Leave

Request Create multiple Leave Balances (application/json)
Body

    {
      "balances": [
        {
          "user_id": 123456,
          "leave_type": "Annual Leave",
          "hours": 18.0
        },
        {
          "user_id": 654321,
          "leave_type": "Sick Leave",
          "hours": 22.0
        }
      ]
    }

Response 200 (application/json) Attributes (array):

+ (object)
    + user_id: 123456 (number)
    + hours: 18.0 (number)
    + leave_type: Annual Leave
+ (object)
    + user_id: 654321 (number)
    + hours: 22.0 (number)
    + leave_type: Sick Leave

Leave Balance [/api/v2/leave_balances/{id}]
GETGet Leave Balance
This method requires the leave scope (see Scopes for more information).
Parameters
id: 666 (number) - The ID of the leave balance to lookup
200
OK
(application/json)
Attributes:
id: 666 (required) (number) - The id of the leave balance
user_id: 123456 (required) (number) - The id of the user who owns the leave balance
leave_type: Annual Leave (required, string) - The type of leave
hours: 4 (required) (number) - The number of hours of leave accrued
should_accrue: false (boolean) - If true, this leave balance will accrue in Tanda automatically. If false, you should keep it up to date. Default is false.
PUTUpdate Leave Balance with ID
This method requires the leave scope (see Scopes for more information).
Parameters
id: 666 (number) - The ID of the leave balance to update
Request Update Leave (application/json)
Body

    {
      "hours": 22.5
    }

200
OK
(application/json)
Attributes:
id: 666 (required) (number) - The id of the leave balance
user_id: 123456 (required) (number) - The id of the user who owns the leave balance
leave_type: Annual Leave (required, string) - The type of leave
hours: 4 (required) (number) - The number of hours of leave accrued
should_accrue: false (boolean) - If true, this leave balance will accrue in Tanda automatically. If false, you should keep it up to date. Default is false.
+ hours: 22.5 (number)

Update Leave Balance with User ID [/api/v2/leave_balances/user/{user_id}]
PUTUpdate Leave Balance with User ID
This method requires the leave scope (see Scopes for more information).
Parameters
user_id: 123456 (number) - The ID of the user whose leave balance you want to update
Request Update Leave Balance with User ID (application/json)
Body

    {
      "leave_type": "Annual Leave",
      "hours": 18.0,
      "should_accrue": false
    }

200
OK
(application/json)
Attributes:
id: 666 (required) (number) - The id of the leave balance
user_id: 123456 (required) (number) - The id of the user who owns the leave balance
leave_type: Annual Leave (required, string) - The type of leave
hours: 4 (required) (number) - The number of hours of leave accrued
should_accrue: false (boolean) - If true, this leave balance will accrue in Tanda automatically. If false, you should keep it up to date. Default is false.
+ hours: 18.0 (number)

Request Create multiple Leave Balances with User ID (application/json)
Body

    {
      "balances": [
        {
          "leave_type": "Annual Leave",
          "hours": 18.0
        },
        {
          "leave_type": "Sick Leave",
          "hours": 22.0
        }
      ]
    }

Response 200 (application/json) Attributes (array):

+ (object)
    + hours: 18.0 (number)
    + leave_type: Annual Leave
+ (object)
    + hours: 22.0 (number)
    + leave_type: Sick Leave

Predict Leave Balances [/api/v2/leave_balances/{id}/predict]
POSTPredict Leave Balance
This endpoint takes a leave balance ID and a date, and predicts what the leave balance will be on the given date. The date must be in the future.

This method requires the leave scope (see Scopes for more information).
You should make it clear when displaying the result that this is a prediction. There is no guarantee the user’s actual leave balance will match this when the date comes.

Parameters
id: 654321 (number) - The ID of the leave balance
Request Predict Leave Balance (application/json)
Body

    {
      "date": "2019-12-24"
    }

200
OK
(application/json)
 { “prediction”: 22.5 }
Availability
Availability supersedes Unavailability for organisations that have migrated to the availability model.

All availability endpoints require the unavailability scope (see Scopes for more information).
Callers only see users they can already see via Users — user_ids is filtered against the caller’s visible-users scope. Unknown or hidden ids are silently dropped. Inactive (terminated) users are included when requested by explicit id, so reports covering past staff keep working.
Effective Availability [/api/v2/availability/effective]
GETGet Effective Availability
Returns the day-by-day merged projection of a user’s availability. Use this to answer the question “what is the availability of X users in Y date range?”.

This method requires the unavailability scope.
This endpoint returns a higher volume of data per user than /api/v2/unavailability. This makes year long ranges less practical to deliver. When fetching effective availability for all visible users (i.e. user_ids omitted) the from..to range is capped at 31 days. There is no date-range cap when fetching for a specific set of users. The upside of the larger payload is that the data is flatter and simpler to interpret than the previous unavailability format.
Parameters
from: 2026-04-20 (required, string) - Inclusive start of the projection window (ISO date, YYYY-MM-DD).
to: 2026-04-26 (required, string) - Inclusive end of the projection window (ISO date, YYYY-MM-DD).
user_ids: 42,123456 (optional, string) - Comma-separated list of user ids to project availability for. When omitted, defaults to all active users the caller can see. In that “all visible users” mode the from..to window must be 31 days or fewer. Explicit user_ids mode has no date range cap and includes inactive (terminated) users.
200
OK
(application/json)
Body

    [
      {
        "user_id": 42,
        "availability": [
          {
            "date": "2026-04-20",
            "time_blocks": [
              { "start": "00:00", "finish": "10:00" },
              { "start": "14:00", "finish": "24:00" }
            ]
          },
          {
            "date": "2026-04-21",
            "time_blocks": [
              { "start": "09:00", "finish": "17:00" }
            ]
          },
          {
            "date": "2026-04-23",
            "time_blocks": [
              { "start": "08:00", "finish": "18:00" }
            ]
          },
          {
            "date": "2026-04-26",
            "time_blocks": []
          }
        ]
      }
    ]

Notes:

availability contains exactly one entry per date in from..to inclusive, in chronological order.
time_blocks lists the availability windows for that date (when the employee is available). [] means fully unavailable; a full-day window is rendered as {"start": "00:00", "finish": "24:00"}.
An empty time blocks array ("time_blocks": []) means not available at all that day.
A finish that lands on the following midnight is rendered as "24:00" on the same day rather than "00:00" on the next.
Ongoing Availability [/api/v2/availability/ongoing]
GETGet Ongoing Availability
Returns each user’s ongoing patterns that are currently active or scheduled to start in the future — the pattern effective today plus any approved patterns with start_date > today. Superseded historical patterns are not returned; use Effective Availability to project day-by-day availability across the merged layers.

Use this to monitor scheduled patterns: what’s currently running, what’s about to change, what’s coming up, and how recently each pattern was edited.

This method requires the unavailability scope.
Parameters
user_ids: 4704593 (required, string) - Comma-separated list of user ids to fetch ongoing availability for. Inactive (terminated) users are included when requested by id.
200
OK
(application/json)
Body

    [
      {
        "user_id": 4704593,
        "ongoing": [
          {
            "id": 49,
            "start_date": "2026-06-01",
            "frequency": "weekly",
            "updated_at": "2026-05-20T03:21:00Z",
            "days": [
              { "day_in_pattern": 0, "time_blocks": [{ "start": "12:00", "finish": "22:00" }] },
              { "day_in_pattern": 1, "time_blocks": [{ "start": "16:00", "finish": "22:00" }] },
              { "day_in_pattern": 2, "time_blocks": [] },
              { "day_in_pattern": 3, "time_blocks": [] },
              { "day_in_pattern": 4, "time_blocks": [] },
              { "day_in_pattern": 5, "time_blocks": [] },
              { "day_in_pattern": 6, "time_blocks": [] }
            ]
          }
        ]
      }
    ]

Notes:

frequency is the repeat cadence of the pattern. One of weekly or fortnightly.
start_date is the first day the pattern applies. For the currently-effective pattern this may be in the past; for upcoming patterns it is in the future.
updated_at is an ISO-8601 timestamp of the last edit to the record.
days describes the repeating pattern. day_in_pattern is a zero-based index into the cycle (for weekly, 0 is Monday through 6 Sunday; for fortnightly, 0–13). Every slot in the cycle is always present in the response.
time_blocks lists availability windows directly (when the employee is available). An empty array means fully unavailable for that day-in-pattern; a day the employee is available for in full is rendered as an explicit full-day window ({"start": "00:00", "finish": "24:00"}), matching /api/v2/availability/effective.
Availability Requests [/api/v2/availability/requests]
GETGet Availability Requests
Returns each user’s individual availability requests. This includes ongoing patterns and temporary changes. This endpoint returns all statuses by default (pending, approved, and rejected), with one entry per underlying record. Use it to sync availability requests into external systems, mirroring what the deprecated /api/v2/unavailability endpoint provided.

Inactive (terminated) users are included when their ids are requested, so reports covering past staff keep working.

This method requires the unavailability scope.
Parameters
user_ids: 4704593 (optional, string) - Comma-separated list of user ids to fetch records for. When omitted, defaults to all active users the caller can see.
ids: 51,52 (optional, string) - Comma-separated list of record ids to fetch. Filters to these specific records.
statuses: pending,rejected (optional, string) - Comma-separated statuses to filter by. One or more of pending, approved, rejected. Defaults to all statuses.
from: 2026-06-01 (optional, string) - With to, keeps only records overlapping the window. Open-ended ongoing patterns overlap every window from their start_date onward.
to: 2026-06-30 (optional, string) - See from. Both or neither must be given.
updated_after: 1780000000 (optional, number) - Unix timestamp; keeps only records updated strictly after it. Use for incremental syncs.
200
OK
(application/json)
Body

    [
      {
        "id": 51,
        "user_id": 4704593,
        "type": "temporary",
        "status": "rejected",
        "reason": "UNPAID CASUAL LEAVE",
        "start_date": "2026-06-14",
        "finish_date": "2026-06-15",
        "all_day": true,
        "created_at": "2026-06-01T10:12:00+10:00",
        "updated_at": "2026-06-02T09:30:00+10:00"
      },
      {
        "id": 52,
        "user_id": 4704593,
        "type": "ongoing",
        "status": "approved",
        "reason": "Study",
        "start_date": "2026-06-01",
        "finish_date": null,
        "all_day": false,
        "frequency": "weekly",
        "days": [
          { "day_in_pattern": 0, "time_blocks": [{ "start": "09:00", "finish": "17:00" }] },
          { "day_in_pattern": 1, "time_blocks": [] },
          { "day_in_pattern": 2, "time_blocks": [] },
          { "day_in_pattern": 3, "time_blocks": [] },
          { "day_in_pattern": 4, "time_blocks": [] },
          { "day_in_pattern": 5, "time_blocks": [] },
          { "day_in_pattern": 6, "time_blocks": [] }
        ],
        "created_at": "2026-05-20T08:00:00+10:00",
        "updated_at": "2026-05-20T08:00:00+10:00"
      },
      {
        "id": 53,
        "user_id": 4704593,
        "type": "temporary",
        "status": "approved",
        "reason": "Partial day off",
        "start_date": "2026-06-20",
        "finish_date": "2026-06-20",
        "all_day": false,
        "days": [
          { "date": "2026-06-20", "time_blocks": [{ "start": "00:00", "finish": "10:00" }, { "start": "14:00", "finish": "24:00" }] }
        ],
        "created_at": "2026-06-05T08:00:00+10:00",
        "updated_at": "2026-06-05T08:00:00+10:00"
      }
    ]

Notes:

type is ongoing for a recurring pattern or temporary for a one-off change.
status is the approval workflow state: pending, approved, or rejected.
reason is the requester-supplied title for the record.
finish_date is null for open-ended ongoing patterns. temporary records are one-offs bounded by start_date/finish_date.
all_day is true when the record has no specific-time windows — it applies to whole days.
frequency (weekly or fortnightly) is present only for ongoing records.
days gives the time-of-day breakdown. It is always present for ongoing records; for temporary records it is present only when they have specific-time windows (all_day: false) and omitted for whole-day ones (all_day: true). In every case time_blocks are the periods the user is available, [] means fully unavailable, and a fully-available day is an explicit 00:00–24:00 block. The keying differs by type:
ongoing records follow Ongoing Availability: one {day_in_pattern, time_blocks} entry per slot in the cycle.
temporary records are keyed by concrete date: one {date, time_blocks} entry per date in start_date..finish_date, matching the shape of Effective Availability. A specific-time one-off carved out as unavailable is reported as its inverse — the windows the user remains available.
Records are ordered by start_date ascending.
Unavailability
Unavailability is an employee’s way to notify the person building the roster that they are not going to be available during a certain time period. Unavailability is most used by casual staff or employees with flexible hours.

For specifying times when an employee formally took time off, or to request time off (most often for part time and full time employees), please see Leave.

This endpoint group is deprecated and will be removed in a future release. Organisations that have migrated to the new availability model should read from /api/v2/availability/effective instead. For migrated organisations this endpoint reflects the legacy unavailability data only and will not include records created in the new availability model.
If the organisation has unavailability enabled, then all employees can CRUD unavailability about themselves. Roster managers, and admins can CRUD unavailability for everyone and department managers can CRUD unavailability for users they can manage.
Unavailability List [/api/v2/unavailability]
GETGet Unavailabilities
Lookup multiple leave requests in a single request.

You must specify either both from and to or ids (you can specify both if you want too). user_ids can be specified in any case.

This method requires the unavailability scope (see Scopes for more information).
You will only be able to query up to 366 days when specifying from and to.
Parameters
ids: 1,2,42 (optional, string) - Comma separated list of unavailability ids to lookup
from: 2016-03-15 (optional, string) - From date to lookup unavailability in
to: 2016-04-05 (optional, string) - To date to lookup unavailability in
user_ids: 1,2,123456 (optional, string) - Comma separated list of user ids to lookup unavailability for
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified unavailability
200
OK
(application/json)
Body

    [
      {
        "id": 42,
        "user_id": 123456,
        "title": "Doing errr... something",
        "start": 1459814400,
        "finish": 1459836000,
        "repeating": false,
        "repeating_info": null,
        "all_day": false
      }
    ]

POSTCreate Unavailability
This method requires the unavailability scope (see Scopes for more information).
There’s two ways to create unavailabilities: using dates (for all_day events), or using times (for events that don’t go all day).

Regardless of which method you use, you should use the unavailability minimum date from the Settings endpoint to validate your dates or times locally. If you pass a time that is earlier than the minimum date (in the given user’s time zone), the request will fail. You can override the failure by setting the override_validations flag.

To create an event using dates, use these parameters. Note that date_from and date_to are inclusive. If you have an unavailability that only goes for one day, they should have the same value. If you have an unavailability that goes for two full days, they should be one day apart, etc.

all_day: true
user_id - integer
title - string
repeating - boolean
date_from - string, eg “2016-03-15”
date_to - string, eg “2016-03-16” - In this example, you will be unavailable on the 15th AND the 16th of March
To create an event using times, use these parameters:

all_day: false
user_id - integer
title - string
repeating - boolean
start - integer, eg 1459375200
finish - integer, eg 1459382400 - In this example, you will be unavailable from 2016-03-30 22:00:00 UTC to 2016-03-31 00:00:00 UTC
To bypass checking minimum date and published schedule checks, use override_validations:

all_day: true
override_validations: true
user_id - integer
title - string
repeating - boolean
start - integer, eg 1459375200
finish - integer, eg 1459382400 - In this example, you will be unavailable from 2016-03-30 22:00:00 UTC to 2016-03-31 00:00:00 UTC
You can also use the repeating param to tell an event to repeat. For example:

all_day: false
user_id - integer
title - string
repeating - true
repeating_info: {"interval": "week","occurrences": 4}
start - integer, eg 1494838800
finish - integer, eg 1494867600 - In this example, you will be unavailable from 2017-05-15 09:00:00 UTC to 2017-05-15 17:00:00 UTC, and at the same times for the next 3 weeks after (4 weeks total).
There’s more examples in the sidebar. The examples are based on a user in the AEST+10 time zone.

Request Create Unavailability (application/json)
Body

    {
      "user_id": 123456,
      "title": "Buying a unicycle",
      "start": 1459375200,
      "finish": 1459382400,
      "repeating": false
    }

201
Created
(application/json)
Body

    {
      "id": 106092,
      "user_id": 123456,
      "title": "Buying a unicycle",
      "start": 1459375200,
      "finish": 1459382400,
      "repeating": false,
      "repeating_info": null,
      "all_day": false
    }

Request Create all day Unavailability (application/json)
Body

    {
      "user_id": 123456,
      "title": "Buying a unicycle",
      "date_from": "2017-05-15",
      "date_to": "2017-05-15",
      "repeating": false,
      "all_day": true
    }

201
Created
(application/json)
Body

    {
      "id": 106092,
      "user_id": 123456,
      "title": "Buying a unicycle",
      "start": 1494770400,
      "finish": 1494856800,
      "repeating": false,
      "repeating_info": null,
      "all_day": true
    }

Request Create repeating Unavailability (application/json)
Body

    {
      "user_id": 123456,
      "title": "Learning to ride my unicycle",
      "start": 1459382400,
      "finish": 1459389600,
      "repeating": true,
      "repeating_info": {
        "interval": "day",
        "occurrences": 3
      }
    }

201
Created
(application/json)
Body

    {
      "id": 106093,
      "user_id": 123456,
      "title": "Learning to ride my unicycle",
      "start": 1459382400,
      "finish": 1459389600,
      "repeating": true,
      "repeating_info": {
        "interval": "day",
        "occurrences": 3,
        "start": 1459382400,
        "ids": [
          106093,
          106094,
          106095
        ]
      },
      "all_day": false
    }

Repeating Unavailability List [/api/v2/unavailability/repeating_for/{id}]
GETGet Repeating Unavailabilities
This method requires the unavailability scope (see Scopes for more information).
Parameters
id: 43 (number) - The id of the unavailability to get repeating information for
200
OK
(application/json)
Attributes:
(FirstRepeatingUnavailabilityData)
(SecondRepeatingUnavailabilityData)
Unavailability [/api/v2/unavailability/{id}]
GETGet Unavailability
This method requires the unavailability scope (see Scopes for more information).
Parameters
id: 42 (number) - The id of unavailability to lookup
Request Non-repeating unavailability

200
OK
(application/json)
Body

    {
      "id": 42,
      "user_id": 123456,
      "title": "Doing errr... something",
      "start": 1459814400,
      "finish": 1459836000,
      "repeating": false,
      "repeating_info": null,
      "all_day": false
    }

Schema

Attributes:
id: 43 (required) (number) - The id of the unavailability
user_id: 123456 (required) (number) - The user that the unavailability applies for
title: Doing errr… something else (string) - The reason for the unavailability
start: 1459994400 (required) (number) - The start time for the unavailability
finish: 1460001600 (required) (number) - The end time for the unavailability
repeating: true (required) (boolean) - Whether this is part of a set of repeating unavailabilities
repeating_info (RepeatingUnavailabilityInfoData) - Info about the unavailabilities that are part of this repeating set of unavailabilities (if the unavailability is repeating)
id: (number)
Request Repeating unavailability

200
OK
(application/json)
Attributes:
id: 43 (required) (number) - The id of the unavailability
user_id: 123456 (required) (number) - The user that the unavailability applies for
title: Doing errr… something else (string) - The reason for the unavailability
start: 1459994400 (required) (number) - The start time for the unavailability
finish: 1460001600 (required) (number) - The end time for the unavailability
repeating: true (required) (boolean) - Whether this is part of a set of repeating unavailabilities
repeating_info (RepeatingUnavailabilityInfoData) - Info about the unavailabilities that are part of this repeating set of unavailabilities (if the unavailability is repeating)
PUTUpdate Unavailability
Update the unavailability’s title (in the case of repeating unavailability, all of the event’s titles will be updated).

This method requires the unavailability scope (see Scopes for more information).
Parameters
id: 42 (number) - The id of unavailability to lookup
Request Update Unavailability (application/json)
Body

    {
      "title": "Helping Grandma"
    }

200
OK
(application/json)
Body

    {
      "id": 42,
      "user_id": 123456,
      "title": "Helping Grandma",
      "start": 1459814400,
      "finish": 1459836000,
      "repeating": false,
      "repeating_info": null,
      "all_day": false
    }

Schema

Attributes:
id: 43 (required) (number) - The id of the unavailability
user_id: 123456 (required) (number) - The user that the unavailability applies for
title: Doing errr… something else (string) - The reason for the unavailability
start: 1459994400 (required) (number) - The start time for the unavailability
finish: 1460001600 (required) (number) - The end time for the unavailability
repeating: true (required) (boolean) - Whether this is part of a set of repeating unavailabilities
repeating_info (RepeatingUnavailabilityInfoData) - Info about the unavailabilities that are part of this repeating set of unavailabilities (if the unavailability is repeating)
id: (number)
DELETEDelete Unavailability
This method requires the unavailability scope (see Scopes for more information).
Parameters
id: 42 (number) - The id of the leave to delete
200
OK
(application/json)
Data Streams
Our user guide has more information on working with data streams through the API.
A data stream is a container for many Store Stats. The data stream specifies the origin of the data, an identifier for the origin (if any), and the interval of the data. All store stats added to a data stream should be totaled data for a time period equal to the data_interval.

Data streams themselves are nice for holding data, but they are made useful by joining them to other objects. See Data Stream Joins for more on how this works. The Data Streams endpoint provides some functionality for quickly creating joins, but you should use the Data Stream Joins endpoint if you need more control over their structure or additional attributes.

Team managers can read data streams that are joined to their team. General managers and payroll officers can read all data streams, and admins can create read and update all data streams.
Data Stream List [/api/v2/datastreams]
GETGet Data Streams
This method requires the datastream scope (see Scopes for more information).
Parameters
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified data streams
Response 200 (application/json) Attributes (array):

+ (GenericDatastreamData)
+ (UserEnteredDatastreamData)
+ (RetailExpressDatastreamData)

POSTCreate Data Stream
You cannot create more than one data stream via the API with the same name. If you try to create a data stream with a name that already exists, that data stream will instead be updated and returned (effectively this will function as a PUT request).

The data interval must be either 86400, 3600, 1800, or 900. This corresponds to 1 day, 1 hour, 30 minutes, or 15 minutes.

It’s highly recommended you give a data stream a ‘default_stat_type’. Having this means that when the data stream is joined to locations or teams, the correct data is joined. Without this field you may see some unexpected results. For example, if your data stream houses ‘sales’ and ‘transactions’, and you mainly want to use the ‘sales’ data, you should set the default_stat_type to ‘sales’

This method requires the datastream scope (see Scopes for more information).
Request Create Data Stream (application/json)
Body

    {
      "name": "My Special Data",
      "data_interval": 900,
      "default_stat_type": "sales"
    }

200
OK
(application/json)
Attributes:
id: 1069 (required) (number) - The id of the data stream
name: My Special Data (required, string) - The name of the data stream
source: api (string) - The data stream’s source
data_interval: 900 (required) (number) - The time between the data stream’s store stats in seconds
print_mode: hidden (optional, string) - Should the data stream be printed when printing a roster? Options: hidden, values, cumulative_sum
roster_display_mode: values (optional, string) - Should the data stream be displayed on rosters? Options: hidden, values, cumulative_sum
Data Stream [/api/v2/datastreams/{id}]
GETGet Data Stream
This method requires the datastream scope (see Scopes for more information).
Parameters
id: 26 (number) - The id of the data stream to lookup
200
OK
(application/json)
Attributes:
id: 26 (required) (number) - The id of the data stream
name: Reactor Revenue (Retail Express) (required) (string) - The name of the data stream
source: retail_express (required) (string) - The data stream’s source
section_identifier: 11223344 (string) - A way to map to the external data provider
data_interval: 900 (required) (number) - The time between the data stream’s store stats in seconds
print_mode: hidden (optional, string) - Should the data stream be printed when printing a roster? Options: hidden, values, cumulative_sum
roster_display_mode: values (optional, string) - Should the data stream be displayed on rosters? Options: hidden, values, cumulative_sum
PUTUpdate Data Stream
This method requires the datastream scope (see Scopes for more information).
Parameters
id: 26 (number) - The id of the data stream to update
Request Update Data Stream (application/json)
Body

    {
      "name": "Foot Traffic!",
    }

200
OK
(application/json)
Attributes:
id: 1069 (required) (number) - The id of the data stream
name: My Special Data (required, string) - The name of the data stream
source: api (string) - The data stream’s source
data_interval: 900 (required) (number) - The time between the data stream’s store stats in seconds
print_mode: hidden (optional, string) - Should the data stream be printed when printing a roster? Options: hidden, values, cumulative_sum
roster_display_mode: values (optional, string) - Should the data stream be displayed on rosters? Options: hidden, values, cumulative_sum
+ name: Foot Traffic!

DELETEDelete Data Stream
Only data streams created via the API can be deleted via the API. This also deletes all associated Data Stream Joins and Store Stats, and cannot be reversed.

The data stream will be scheduled for deletion, but may not be removed immediately. You can GET the data stream to check if it’s been deleted.
This method requires the datastream scope (see Scopes for more information).
Parameters
id: 26 (number) - The id of the data stream
202
Accepted
(application/json)
Data Stream Versions [/api/v2/datastreams/{id}/versions]
GETGet Data Stream Versions
This method requires the datastream scope (see Scopes for more information).
Parameters
id: 26 (number) - The id of the data stream
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified data stream versions
200
OK
(application/json)
Attributes (array):
version_id: 123456 (number)
time: 1459209907 (number)
event: update
author (object)
id: 123456 (number)
name: API v2
item_id: 1235435 (number)
item_type: “Datastream” (string)
changes (array)
(object)
field: data_interval
previous: 900 (number)
updated: 1800 (number)
(object)
field: name
previous: Employee Superfund
updated: Reactor Revenue
Data Stream Joins
Our user guide has more information on working with data streams through the API.
Data Stream Joins connect Data Streams to the object which owns the stream’s data. For example, data from a stream may be relate to a Team, Location, or to the Organisation itself.

If a data stream is joined to the organisation, it will show its store stats in the context of the whole organisation. Similarly, if it is joined to one or many teams, it will show its store stats when looking at stats for each of those teams. Data streams that are joined to a team, but not the organisation, will show their store stats in the context of the teams, but will not show when looking at the organisation as a whole (this is often useful for team specific stats).

Data Stream Joins also connect a single ‘stat_type’ from a data stream. You should specify which stat_type you want to join from the data stream to the Organisation, Location, or Department. For example, your data stream might have both ‘sales’ data and ‘transaction’ data in it. If you want to attach sales data to a team, then you must specify the stat_type_id for sales in the payload.

If you do not specify a stat_type, one will be inferred by what kind of data your datastream has. Eg if your data stream only has sales data in it, the join will automatically be given the sales stat type.

Only admins can manage data stream joins.
As well as managing this relationship, a Data Stream Join can also be given a rostering ratio, which is used to calculate how many staff should be rostered into the join’s object (the “streamable”) based on stream data. For example, a data stream might have a total value of 30 (values themselves are provided using Store Stats) for a half hour period, and the data stream’s join to a team might have a rostering ratio of 8. In this case Workforce would recommend that 4 staff be rostered for that half hour period.

Data Stream Join List [/api/v2/datastreamjoins]
GETGet Data Stream Joins
This method requires the datastream scope (see Scopes for more information).
Parameters
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified data stream joins
200
OK
(application/json)
Attributes (array):
id: 162 (required) (number) - The id of the data stream join
data_stream_id: 24 (required) (number) - The id of the data stream join’s data stream
data_streamable_id: 111 (required) (number) - The id of the data stream join’s data streamable (location or team)
data_streamable_type: Department (required) (string) - The type of the data stream join’s data streamable (“Location”, “Department”, or “Organisation”)
rostering_ratio: 1.175 (number) - The ratio of units to staff required when rostering to this data stream
POSTCreate Data Stream Join
This method requires the datastream scope (see Scopes for more information).
Request Create Joined to Team (application/json)
Body

    {
      "data_stream_id": 24,
      "data_streamable_id": 111,
      "data_streamable_type": "Department",
      "rostering_ratio": 2.5,
      "stat_type_id": 123
    }

200
OK
(application/json)
Attributes:
id: 162 (required) (number) - The id of the data stream join
data_stream_id: 24 (required) (number) - The id of the data stream join’s data stream
data_streamable_id: 111 (required) (number) - The id of the data stream join’s data streamable (location or team)
data_streamable_type: Department (required) (string) - The type of the data stream join’s data streamable (“Location”, “Department”, or “Organisation”)
rostering_ratio: 1.175 (number) - The ratio of units to staff required when rostering to this data stream
+ data_streamable_id: 111 (number)
+ data_streamable_type: Department (string)
+ rostering_ratio: 2.5 (number)
+ stat_type_id: 123 (number)

Request Create Joined to Organisation (application/json)
Body

    {
      "data_stream_id": 24,
      "data_streamable_type": "Organisation",
      "stat_type_id": 123
    }

200
OK
(application/json)
Body

      {
        "id": 162,
        "data_stream_id": 24,
        "data_streamable_id": null,
        "data_streamable_type": "Organisation",
        "rostering_ratio": 1.175,
        "stat_type_id": 123
      }

Data Stream Join [/api/v2/datastreamjoins/{id}]
GETGet Data Stream Join
This method requires the datastream scope (see Scopes for more information).
Parameters
id: 162 (number) - The id of the data stream join to lookup
200
OK
(application/json)
Attributes:
id: 162 (required) (number) - The id of the data stream join
data_stream_id: 24 (required) (number) - The id of the data stream join’s data stream
data_streamable_id: 111 (required) (number) - The id of the data stream join’s data streamable (location or team)
data_streamable_type: Department (required) (string) - The type of the data stream join’s data streamable (“Location”, “Department”, or “Organisation”)
rostering_ratio: 1.175 (number) - The ratio of units to staff required when rostering to this data stream
PUTUpdate Data Stream Join
This method requires the datastream scope (see Scopes for more information).
Parameters
id: 162 (number) - The id of the data stream join to update
Request Update Data Stream Join (application/json)
Body

    {
      "rostering_ratio": 1.5
    }

200
OK
(application/json)
Attributes:
id: 162 (required) (number) - The id of the data stream join
data_stream_id: 24 (required) (number) - The id of the data stream join’s data stream
data_streamable_id: 111 (required) (number) - The id of the data stream join’s data streamable (location or team)
data_streamable_type: Department (required) (string) - The type of the data stream join’s data streamable (“Location”, “Department”, or “Organisation”)
rostering_ratio: 1.175 (number) - The ratio of units to staff required when rostering to this data stream
+ rostering_ratio: 1.5 (number)

DELETEDelete Data Stream Join
This method requires the datastream scope (see Scopes for more information).
Parameters
id: 162 (number) - The id of the data stream join to delete
200
OK
(application/json)
Store Stats
Our user guide has more information on working with data streams through the API.
Store stats are the individual statistics that belong to a Data Stream. All store stats for a data stream should be totaled data for a time period equal to the data stream’s data_interval, starting at the store stat’s time.

Only store stats where the type parameter is equal to “sales” will be displayed on the weekly planner on the dashboard. You’re able to store a wide variety of stats in Workforce, and differentiate them using the type parameter, but be aware of this special case.

Store stats can be read by a user, if that user is able to read the data stream that the store stat belongs to.
Only admins can create store stats. They are able to do this for any data stream.

Store Stats for Datastream [/api/v2/storestats/for_datastream/{datastream_id}/]
GETStore Stats for Datastream
This method requires the datastream scope (see Scopes for more information).
You will only be able to query up to 31 days using the from and to parameters.
Parameters
datastream_id: 26 (number) - The id of the data stream to lookup store stats for
from: 2016-03-01 (string) - The start date of the range to lookup store stats in
to: 2016-03-20 (string) - The id of the data stream to lookup store stats for
type: sales (optional, string) - The type of store stats to lookup (if not specified, all stats are returned)
200
OK
(application/json)
Attributes (array):
id: 3518 (required) (number) - The id of the stat
time: 1459295100 (required) (number) - The time of the stat
stat: 3.50 (required) (number) - The value of the stat
type: sales (required) (string) - The type of the stat
datastream_id: 24 (required) (number) - The id of the data stream join’s data stream
Create Store Stats for Datastream [/api/v2/storestats/for_datastream/{datastream_id}]
POSTCreate Store Stats for Datastream
Store stats can either be posted one at a time, or in bulk. When posting store stats in bulk, all the store stats must be for the same data stream.

To post store stats in bulk, simply represent them all in an array, under the stats key. Note that each combination of time and type must be unique - you must not send duplicate data.

POSSIBLE DATA DELETION: All existing store stats on the data stream within the newly posted store stats’ time parameter range will be replaced with the newly posted store stats.
Please see the general Store Stat information above for an example.

Pass the optional top-level update_tips parameter as true to recompute any tip jars attached to this data stream across the affected date range once the store stats are saved. It defaults to false, so tip jar amounts are only refreshed when you explicitly opt in.
{ "update_tips": true, "stats": [ { "time": 1459296900, "stat": 3.5, "type": "sales" }, { "time": 1459297800, "stat": 1, "type": "transactions" } ] }

This method requires the datastream scope (see Scopes for more information).
Parameters
datastream_id: 27 (number) - The id of the data stream to create store stats on
Request Create single Store Stat (application/json)
Body

    {
      "time": 1459296900,
      "stat": 3.5,
      "type": "sales"
    }

201
Created
(application/json)
Attributes:
id: 3518 (required) (number) - The id of the stat
time: 1459295100 (required) (number) - The time of the stat
stat: 3.50 (required) (number) - The value of the stat
type: sales (required) (string) - The type of the stat
datastream_id: 24 (required) (number) - The id of the data stream join’s data stream
+ id: 12231 (number)
+ time: 1459296900 (number)
+ stat: 3.5 (number)
+ type: sales (string)

Request Create multiple Store Stats (application/json)
Body

    {
      "stats": [
        {
          "time": 1459296900,
          "stat": 3.5,
          "type": "sales"
        },
        {
          "time": 1459296900,
          "stat": 1,
          "type": "transactions"
        },
        {
          "time": 1459297800,
          "stat": 20.1,
          "type": "sales"
        }
      ]
    }

Response 201 (application/json) Attributes (array):

+ (object)
    + id: 12231 (number)
    + time: 1459296900 (number)
    + stat: 3.5 (number)
    + type: sales (string)
+ (object)
    + id: 12232 (number)
    + time: 1459296900 (number)
    + stat: 1 (number)
    + type: transactions (string)
+ (object)
    + id: 12233 (number)
    + time: 1459297800 (number)
    + stat: 20.1 (number)
    + type: sales (string)

Deleting Store Stats [/api/v2/storestats/for_datastream/{datastream_id}]
POSTDeleting Store Stats
To remove store stats generated through the API for a time period, you will need to make a POST, and provide store stats with a 0 as the stat for the start and end of that period.

For example, if you wanted to remove sales and transactions store stats for the period of 1459296900 to 1459383300 then posting the following data to the Create Store Stats endpoint would “delete” that data. This is becuase each post actually overrides existing store stat data for the period. { "stats": [ { "time": 1459296900, "stat": 0, "type": "sales" }, { "time": 1459296900, "stat": 0, "type": "transactions" }, { "time": 1459383300, "stat": 0, "type": "sales" }, { "time": 1459383300, "stat": 0, "type": "transactions" } ] }

Create Store Stats for multiple Datastreams [/api/v2/storestats/for_datastream]
POSTCreate Store Stats for Multiple Datastreams
Store stats can either be posted one at a time, or in bulk. When posting store stats in bulk, all the store stats must be for the same data stream.

To post store stats in bulk, simply represent them all in an array, with the datastream_id included for each stat. Note that each combination of datastream_id, time and type must be unique - you must not send duplicate data.

POSSIBLE DATA DELETION: All existing store stats on the data stream within the newly posted store stats’ time parameter range will be replaced with the newly posted store stats.
Please see the general Store Stat information above for an example.

Pass the optional top-level update_tips parameter as true to recompute the tip jars attached to each posted data stream across that stream’s affected date range once the store stats are saved. It defaults to false, so tip jar amounts are only refreshed when you explicitly opt in.
{ "update_tips": true, "stats": [ { "datastream_id": 123456, "time": 1459296900, "stat": 7.5, "type": "sales" }, { "datastream_id": 123456, "time": 1459297800, "stat": 3, "type": "transactions" } { "datastream_id": 123457, "time": 1459296900, "stat": 3.5, "type": "sales" }, { "datastream_id": 123457, "time": 1459297800, "stat": 1, "type": "transactions" } ] }

Request Create single Store Stat (application/json)
Body

    {
      "datastream_id": 123457,
      "time": 1459296900,
      "stat": 3.5,
      "type": "sales"
    }

201
Created
(application/json)
Attributes:
id: 3518 (required) (number) - The id of the stat
time: 1459295100 (required) (number) - The time of the stat
stat: 3.50 (required) (number) - The value of the stat
type: sales (required) (string) - The type of the stat
datastream_id: 24 (required) (number) - The id of the data stream join’s data stream
+ id: 12231 (number)
+ datastream_id: 123457 (number),
+ time: 1459296900 (number)
+ stat: 3.5 (number)
+ type: sales (string)

Request Create multiple Store Stats (application/json)
Body

            {
              "stats": [
                {
                  "datastream_id": 123456,
                  "time": 1459296900,
                  "stat": 7.5,
                  "type": "sales"
                },
                {
                  "datastream_id": 123456,
                  "time": 1459296900,
                  "stat": 3,
                  "type": "transactions"
                },
                {
                  "datastream_id": 123457,
                  "time": 1459297800,
                  "stat": 3.5,
                  "type": "sales"
                },
                {
                  "datastream_id": 123457,
                  "time": 1459297800,
                  "stat": 1,
                  "type": "transactions"
                }
                }
              ]
            }

Response 201 (application/json) Attributes (array):

+ (object)
    + id: 12231 (number)
    + datastream_id: 123456 (number),
    + time: 1459296900 (number)
    + stat: 7.5 (number)
    + type: sales (string)
+ (object)
    + id: 12232 (number)
    + datastream_id: 123456 (number),
    + time: 1459296900 (number)
    + stat: 3 (number)
    + type: transactions (string)
+ (object)
    + id: 12233 (number)
    + datastream_id: 123457 (number),
    + time: 1459297800 (number)
    + stat: 3.5 (number)
    + type: sales (string)
+ (object)
    + id: 12234 (number)
    + datastream_id: 123457 (number),
    + time: 1459297800 (number)
    + stat: 1 (number)
    + type: transactions (string)

Devices
Devices are physical time clocks that are used by employees for clocking in and out, a device has many Clock Ins.

Admins and department managers can read devices, and admins can and update all devices.
Device List [/api/v2/devices]
GETGet Devices
This method requires the device scope (see Scopes for more information).
Parameters
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified devices
200
OK
(application/json)
Attributes (array):
id: 1234 (required) (number) - The id of the device
location_id: 111 (optional, number) - The ID of the time clock’s location.
nickname: Reactor Timeclock (required, string) - The nickname of the device. If not provided, the location’s name is used.
returned: false (required) (boolean) - Whether the device has been returned
last_heard_from: 1459296900 (number) - The time that the device last communicated with the Tanda server
dispatch_date: 2016-01-02 (string) - The date that the device was sent out
location_specific: false (required) (boolean) - Whether the device is specific to the assigned location or not
POSTCreate Device
This method requires the device scope (see Scopes for more information).
Provide one or both of location_id and nickname when registering a time clock. If a location_id is provided, but a nickname isn’t, the location’s name is used as a nickname.

Request Create new timeclock (application/json)
Body

    {
      "nickname": "Old Reactor Timeclock",
      "location_id": 111
    }

200
OK
(application/json)
Attributes:
id: 1234 (required) (number) - The id of the device
location_id: 111 (optional, number) - The ID of the time clock’s location.
nickname: Reactor Timeclock (required, string) - The nickname of the device. If not provided, the location’s name is used.
returned: false (required) (boolean) - Whether the device has been returned
last_heard_from: 1459296900 (number) - The time that the device last communicated with the Tanda server
dispatch_date: 2016-01-02 (string) - The date that the device was sent out
location_specific: false (required) (boolean) - Whether the device is specific to the assigned location or not
nickname: Old Reactor Timeclock
Returned Device List [/api/v2/devices/returned]
GETGet Returned Devices
This method requires the device scope (see Scopes for more information).
Parameters
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified returned devices
200
OK
(application/json)
Attributes (array):
id: 8403 (required) (number) - The id of the device
location_id: 111 (optional, number) - The ID of the time clock’s location.
nickname: Meltdown Reactor Timeclock (required, string) - The nickname of the device. If not provided, the location’s name is used.
returned: true (required) (boolean) - Whether the device has been returned
return_date: 2016-03-02 (required) (string) - The date the device was returned
last_heard_from: 1456877652 (number) - The time that the device last communicated with the Tanda server
dispatch_date: 2015-10-12 (string) - The date that the device was sent out
location_specific: false (required) (boolean) - Whether the device is specific to the assigned location or not
Device [/api/v2/devices/{id}]
GETGet Device
This method requires the device scope (see Scopes for more information).
Parameters
id: 1234 (number) - The id of the device to lookup
Request Active device

200
OK
(application/json)
Attributes:
id: 1234 (required) (number) - The id of the device
location_id: 111 (optional, number) - The ID of the time clock’s location.
nickname: Reactor Timeclock (required, string) - The nickname of the device. If not provided, the location’s name is used.
returned: false (required) (boolean) - Whether the device has been returned
last_heard_from: 1459296900 (number) - The time that the device last communicated with the Tanda server
dispatch_date: 2016-01-02 (string) - The date that the device was sent out
location_specific: false (required) (boolean) - Whether the device is specific to the assigned location or not
Request Returned device

200
OK
(application/json)
Attributes:
id: 8403 (required) (number) - The id of the device
location_id: 111 (optional, number) - The ID of the time clock’s location.
nickname: Meltdown Reactor Timeclock (required, string) - The nickname of the device. If not provided, the location’s name is used.
returned: true (required) (boolean) - Whether the device has been returned
return_date: 2016-03-02 (required) (string) - The date the device was returned
last_heard_from: 1456877652 (number) - The time that the device last communicated with the Tanda server
dispatch_date: 2015-10-12 (string) - The date that the device was sent out
location_specific: false (required) (boolean) - Whether the device is specific to the assigned location or not
PUTUpdate Device
This method requires the device scope (see Scopes for more information).
Parameters
id: 1234 (number) - The id of the device to edit
Request Update device information (application/json)
Body

    {
      "nickname": "Old Reactor Timeclock",
      "location_id": 111
    }

200
OK
(application/json)
Attributes:
id: 1234 (required) (number) - The id of the device
location_id: 111 (optional, number) - The ID of the time clock’s location.
nickname: Reactor Timeclock (required, string) - The nickname of the device. If not provided, the location’s name is used.
returned: false (required) (boolean) - Whether the device has been returned
last_heard_from: 1459296900 (number) - The time that the device last communicated with the Tanda server
dispatch_date: 2016-01-02 (string) - The date that the device was sent out
location_specific: false (required) (boolean) - Whether the device is specific to the assigned location or not
nickname: Old Reactor Timeclock
Return Device [/api/v2/devices/{id}/return]
POSTReturn Device
This method requires the device scope (see Scopes for more information).
Parameters
id: 1234 (number) - The id of the device to return
200
OK
(application/json)
Attributes:
id: 1234 (required) (number) - The id of the device
location_id: 111 (optional, number) - The ID of the time clock’s location.
nickname: Reactor Timeclock (required, string) - The nickname of the device. If not provided, the location’s name is used.
returned: false (required) (boolean) - Whether the device has been returned
last_heard_from: 1459296900 (number) - The time that the device last communicated with the Tanda server
dispatch_date: 2016-01-02 (string) - The date that the device was sent out
location_specific: false (required) (boolean) - Whether the device is specific to the assigned location or not
returned: true
return_date: 2016-04-01 (string) - The date the device was returned
Device Versions [/api/v2/devices/{id}/versions]
GETGet Device Versions
This method requires the device scope (see Scopes for more information).
Parameters
id: 1234 (number) - The id of the device
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified device versions
200
OK
(application/json)
Attributes (array):
version_id: 123456 (number)
time: 1459209907 (number)
event: update
author (object)
id: 123456 (number)
name: API v2
item_id: 1235435 (number)
item_type: “Device” (string)
changes (array)
(object)
field: nickname
previous: Breakroom
updated: Reactor Timeclock
(object)
field: location_id
previous: 111 (number)
updated: 112 (number)
Device Access Code [/api/v2/devices/reset_access_code]
POSTReset Device Access Code
This method requires the device scope (see Scopes for more information).
The access code is used by admins when setting up a device as an alternative to entering their username and password.

200
OK
(application/json)
Attributes:
access_code: 12345678 (required) (string) - Randomly generated 8 digit string
Clock Ins
Clock ins represent actual times that the employee arrived and left from a location (most often a work site or office).

You must be able to manage the user to make a clock in for them. To read clock ins for a user or device, the user must be able to manage the the user, or read the device respectively.
Clock In [/api/v2/clockins]
POSTPerform Clock In for User
Use this endpoint to send clock ins to Workforce in “real time” as employees clock in or out of work. The clock in will be stored as a distinct object in Workforce, but will also be copied to a Shift, which will then be visible on a Timesheets. When posting clockins to Workforce, here’s a few things to be aware of:

Time rounding
It is possible in Workforce to configure rounding settings, to do things like round clock in times to the nearest 5 minutes. At the very least, the clock in time will be rounded to the floor of the minute when processed. Therefore, you should not expect that you will find a Shift in Workforce with exactly the same start or end time as the time that you provide here. Employees in Workforce are paid based on the output of Timesheets & Shifts, not of Clock Ins, so if you want to adjust a clocked time later you should adjust the relevant Shift instead.

De-duplication
If two very similar clock ins are posted one after the other (eg. two clock ins with the same type, and times within a few minutes of each other) then it is possible that Workforce will discard one. The intent of this logic is to prevent issues like people “misclicking” on physical time clocks. If you want complete control over how a Shift will be displayed in Workforce, use the Shifts endpoint. When querying for Clock Ins directly, any Clock In with true in its removed field has been removed from the Shift as another Clock In has replaced it.

Non-immediate processing
This endpoint will return a 201 HTTP status with the newly created Clock In if the request was valid. At this point the shift_id will be null. There will be a short delay between the Clock In being created, and it being processed. This processing entails adding the Clock In to a Timesheet, and recalculating the Timesheet’s costs. Once the Clock In has been processed, the shift_id field will be updated to be the ID of the Shift that the Clock In was applied to. During processing, if the Clock In is considered to be a duplicate, or needs to be discarded for any other reason, it may never be applied to a Shift. If this is the case, the removed field will be true.

Clock Ins are copied to timesheets
Use the Timesheets and Shifts endpoints to see the net result of your Clock Ins on staff timesheets. You can lookup clock ins using the Get Clock Ins endpoint, and once the clock in has been processed, you can use its shift_id to lookup the shift it applied to. Additionally, you can use either the Clock Ins for User, or the Clock Ins for Device methods, to view raw Clock Ins created through this endpoint.

Clock In image format
Images on Clock Ins are optional. However, if you wish to include an image with a Clock In, the image must be a base64 PNG or JPEG using the Data URI scheme. An example encoded image can be seen below: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAAAAAA6fptVAAAACklEQVQYV2P4DwABAQEAWk1v8QAAAABJRU5ErkJggg== If you do choose to provide an image, and the image isn’t in the correct format, you will receive a response with a 400 HTTP status. An example of the response can be seen on the right.

Don’t predict the future
Clock Ins with times more than 10 minutes into the future (as computed at the server’s time) will be rejected. Ensure your client’s time is correct.

The following fields are supported when clocking in or out. Examples of all these fields can be seen in the sidebar to the right.

user_id - required, integer - the ID of the User clocking in or out.
type - required, string - must be either start, finish, break_start, or break_finish.
time - required, integer - a unix timestamp representing when the clock in or out happened. This time cannot be in the future.
device_id - required, integer - the ID of the Time Clock used to clock in or out. Used to verify the location the clock in took place at.
photo - optional, string - a photo of the user clocking in. If provided, must be a base64 encoded PNG or JPEG image. The size of the PNG image (decoded) must not exceed 5MB in size.
department_id - optional, integer - the Team being clocked in to. If provided, the User must already be in this Team (otherwise it will be ignored). This will show on the user’s timesheet.
answers - optional, array of objects - one or more answers to timeclock questions. For each object, a timeclock_question_id, trigger, and answer are required. There is no validation performed on this - if your answer is invalid, it will be silently ignored. If you need validation, send a POST to the timeclock question answers endpoint.
This method requires the device scope (see Scopes for more information).
You will only be able to clock in for users you can manage, on devices you can see.
Request Clock In (application/json)
Body

    {
      "user_id": 123456,
      "type": "start",
      "time": 1459296192
    }

201
Created
(application/json)
Body

    {
      "id": 6108,
      "user_id": 123456,
      "device_id": 1234,
      "time": 1459296192,
      "type": "start",
      "latitude": null,
      "longitude": null,
      "photo": null,
      "department_id": null,
      "shift_id": null,
      "removed": false
    }

Request Clock Out (application/json)
Body

    {
      "user_id": 123456,
      "type": "finish",
      "time": 1459296192
    }

201
Created
(application/json)
Body

    {
      "id": 6108,
      "user_id": 123456,
      "device_id": 1234,
      "time": 1459296192,
      "type": "finish",
      "latitude": null,
      "longitude": null,
      "photo": null,
      "department_id": null,
      "shift_id": null,
      "removed": false
    }

Request Specific Photo & Time Clock (application/json)
Body

    {
      "user_id": 123456,
      "type": "start",
      "time": 1459296192,
      "device_id": 1234,
      "photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAB0AAAAaCAI..."
    }

201
Created
(application/json)
Body

    {
      "id": 6108,
      "user_id": 123456,
      "device_id": 1234,
      "time": 1459296192,
      "type": "start",
      "latitude": null,
      "longitude": null,
      "photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
      "department_id": null,
      "shift_id": null,
      "removed": false
    }

Request Specific Team (application/json)
Body

    {
      "user_id": 123456,
      "type": "start",
      "time": 1459296192,
      "department_id": 808
    }

201
Created
(application/json)
Body

    {
      "id": 6108,
      "user_id": 123456,
      "device_id": 1234,
      "time": 1459296192,
      "type": "start",
      "latitude": null,
      "longitude": null,
      "photo": null,
      "department_id": 808,
      "shift_id": null,
      "removed": false
    }

Request Bad Image (application/json)
Body

      {
        "user_id": 123456,
        "type": "start",
        "time": 1459296192,
        "department_id": 808,
        "photo": "non-base64 png string"
      }

400
Bad Request
(application/json)
Body

      {
        "error": "Photo parameter is not a valid base64 string!"
      }

Request Image Too Large (application/json)
Body

      {
        "user_id": 123456,
        "type": "start",
        "time": 1459296192,
        "department_id": 808,
        "photo": "very large base64 string"
      }

400
Bad Request
(application/json)
Body

      {
        "error": "Photo is too large. File size limit is 5 MB."
      }

Request Answer to TC Question (application/json)
Body

    {
      "user_id": 123456,
      "type": "finish",
      "time": 1459296192,
      "answers": [{ "timeclock_question_id": 42, "answer": 63.4, "trigger": "finish" }]
    }

201
Created
(application/json)
Body

    {
      "id": 6108,
      "user_id": 123456,
      "device_id": 1234,
      "time": 1459296192,
      "type": "start",
      "latitude": null,
      "longitude": null,
      "photo": null,
      "department_id": null,
      "shift_id": null,
      "removed": false
    }

Clock In List [/api/v2/clockins]
GETClock Ins for User
Both from and to are required, and at least one of user_id and device_id are required.

To get a list of users who are clocked in right now, use the Get Clocked In Users endpoint.

This method requires the device scope (see Scopes for more information).
You will only be able to query up to 31 days using the from and to parameters.
Parameters
user_id: 123456 (number) - The id of the user to lookup clock ins for
from: 2016-03-15 (required, string) - From date to lookup clock ins within
to: 2016-04-05 (required, string) - To date to lookup clock ins within
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified clock ins
include_inactive: true (optional, boolean) - User filter to return data for inactive staff
200
OK
(application/json)
Attributes (array):
id: 6108 (required) (number) - The id of the clock in
user_id: 123456 (required) (number) - The id of the user clocking in
device_id: 1234 (optional, number) - The id of the time clock the user clocks in using. If not provided a generic time clock record will be used.
time: 1459209907 (required) (number) - The time the clock in was made
type: start (required) (string) - start, finish, break_start, or break_finish
latitude: -27.459687 (number) - The latitude of the clock in
longitude: 153.032108 (number) - The longitude of the clock in
photo: http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png (string) - The photo the device took when the user clocked in
department_id: 808 (number) - The id of the department the clock in (if clock in was for a specific department)
shift_id: 1337 (number) - The id of the shift the clock in got applied to (will be nil until the clock in has been processed)
removed: false (required) (boolean) - True if the clock in was removed from the shift due to de-duplication or another reason, see the Clock In endpoint for more information
GETClock Ins for Device
Both from and to are required, and at least one of user_id and device_id are required.

This method requires the device scope (see Scopes for more information).
You will only be able to query up to 31 days using the from and to parameters.
Parameters
device_id: 1234 (number) - The id of the device to lookup clock ins for
from: 2016-03-15 (required, string) - From date to lookup clock ins within
to: 2016-04-05 (required, string) - To date to lookup clock ins within
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified clock ins
200
OK
(application/json)
Attributes (array):
id: 6108 (required) (number) - The id of the clock in
user_id: 123456 (required) (number) - The id of the user clocking in
device_id: 1234 (optional, number) - The id of the time clock the user clocks in using. If not provided a generic time clock record will be used.
time: 1459209907 (required) (number) - The time the clock in was made
type: start (required) (string) - start, finish, break_start, or break_finish
latitude: -27.459687 (number) - The latitude of the clock in
longitude: 153.032108 (number) - The longitude of the clock in
photo: http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png (string) - The photo the device took when the user clocked in
department_id: 808 (number) - The id of the department the clock in (if clock in was for a specific department)
shift_id: 1337 (number) - The id of the shift the clock in got applied to (will be nil until the clock in has been processed)
removed: false (required) (boolean) - True if the clock in was removed from the shift due to de-duplication or another reason, see the Clock In endpoint for more information
GETClock Ins for User on Device
Both from and to are required, and at least one of user_id and device_id are required.

This method requires the device scope (see Scopes for more information).
You will only be able to query up to 31 days using the from and to parameters.
Parameters
user_id: 123456 (number) - The id of the user to lookup clock ins for
device_id: 1234 (number) - The id of the device to lookup clock ins for
from: 2016-03-15 (required, string) - From date to lookup clock ins within
to: 2016-04-05 (required, string) - To date to lookup clock ins within
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified clock ins
200
OK
(application/json)
Attributes (array):
id: 6108 (required) (number) - The id of the clock in
user_id: 123456 (required) (number) - The id of the user clocking in
device_id: 1234 (optional, number) - The id of the time clock the user clocks in using. If not provided a generic time clock record will be used.
time: 1459209907 (required) (number) - The time the clock in was made
type: start (required) (string) - start, finish, break_start, or break_finish
latitude: -27.459687 (number) - The latitude of the clock in
longitude: 153.032108 (number) - The longitude of the clock in
photo: http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png (string) - The photo the device took when the user clocked in
department_id: 808 (number) - The id of the department the clock in (if clock in was for a specific department)
shift_id: 1337 (number) - The id of the shift the clock in got applied to (will be nil until the clock in has been processed)
removed: false (required) (boolean) - True if the clock in was removed from the shift due to de-duplication or another reason, see the Clock In endpoint for more information
Clock In [/api/v2/clockins/{id}]
GETGet Clock In
For information about how clock ins work, please see the Perform Clock In for User endpoint.

This method requires the device scope (see Scopes for more information).
You will only be able to see clock ins for users you can manage, or for devices you can see.
Parameters
id: 6108 (number) - The id of the clockin to lookup
200
OK
(application/json)
Attributes:
id: 6108 (required) (number) - The id of the clock in
user_id: 123456 (required) (number) - The id of the user clocking in
device_id: 1234 (optional, number) - The id of the time clock the user clocks in using. If not provided a generic time clock record will be used.
time: 1459209907 (required) (number) - The time the clock in was made
type: start (required) (string) - start, finish, break_start, or break_finish
latitude: -27.459687 (number) - The latitude of the clock in
longitude: 153.032108 (number) - The longitude of the clock in
photo: http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png (string) - The photo the device took when the user clocked in
department_id: 808 (number) - The id of the department the clock in (if clock in was for a specific department)
shift_id: 1337 (number) - The id of the shift the clock in got applied to (will be nil until the clock in has been processed)
removed: false (required) (boolean) - True if the clock in was removed from the shift due to de-duplication or another reason, see the Clock In endpoint for more information
Qualifications
The Qualifications Feature needs to be enabled before you can access this endpoint.
Qualifications List [/api/v2/qualifications]
GETGet Qualifications
This method requires the qualifications scope (see Scopes for more information).
200
OK
(application/json)
Attributes (array):
id: 123706 (number, required) - The qualification ID
name: Blue Card (string, required) - The name of the qualification
maximum_hours: 21.34 (number) - Maximum number of hours that can be worked per week if this qualification is enabled
POSTCreate Qualification
Once created, a qualification will be visible in your qualifications list. Use its ID to add it to staff profiles, and to teams.

This method requires the qualifications scope (see Scopes for more information).
Request (application/json)
Body

    {
      "name": "Responsible Service of Alcohol",
      "maximum_hours": 20.5
    }

200
OK
(application/json)
Attributes:
id: 123706 (number, required) - The qualification ID
name: Blue Card (string, required) - The name of the qualification
maximum_hours: 21.34 (number) - Maximum number of hours that can be worked per week if this qualification is enabled
+ name: Responsible Service of Alcohol
+ maximum_hours: 20.5

Qualification [/api/v2/qualifications/{id}]
GETGet Qualification
This method requires the qualifications scope (see Scopes for more information).
Parameters
id: 123706 (number) - The id of the qualification
200
OK
(application/json)
Attributes:
id: 123706 (number, required) - The qualification ID
name: Blue Card (string, required) - The name of the qualification
maximum_hours: 21.34 (number) - Maximum number of hours that can be worked per week if this qualification is enabled
PUTUpdate Qualification
This method requires the qualifications scope (see Scopes for more information).
Parameters
id: 123706 (number) - The id of the qualification to edit
Request (application/json)
Body

    {
      "name": "RSA v2"
    }

200
OK
(application/json)
Attributes:
id: 123706 (number, required) - The qualification ID
name: Blue Card (string, required) - The name of the qualification
maximum_hours: 21.34 (number) - Maximum number of hours that can be worked per week if this qualification is enabled
+ name: RSA v2

DELETEDelete Qualification
Deleting a qualification will also remove it from associated staff and teams.

This method requires the qualifications scope (see Scopes for more information).
Parameters
id: 123706 (number) - The id of the qualification
200
OK
(application/json)
System Settings
System settings are accessible through the API if they are visible on the Workforce settings page. Please refer to the settings page inside Workforce for up to date documentation on each setting and the options available.

Only admins are able to access settings.
Settings [/api/v2/settings]
GETGet Settings
This method requires the settings scope (see Scopes for more information).
The full range of properties that are returned may vary on a per-user basis. To the right is a sample, to illustrate the structure of responses. Therefore, your code should gracefully handle the condition where a particular key is not present.

200
OK
(application/json)
Attributes:
enable_availability: false (boolean) - Employees can use an app to enter unavailability
unavailability_minimum_date: 2016-02-29 (string) - The earliest date for which Unavailability can be entered.
enable_employee_leave: true (boolean) - Allow employees to enter leave requests through Tanda
leave_request_default_length: 7.6 (number) - Default leave request length (hours)
Settings Versions [/api/v2/settings/versions]
GETGet Settings Versions
This method requires the settings scope (see Scopes for more information).
The full range of properties that are returned may vary on a per-user basis. To the right is a sample, to illustrate the structure of responses. Therefore, your code should gracefully handle the condition where a particular key is not present.

Parameters
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified settings versions
200
OK
(application/json)
Attributes (array):
version_id: 123456 (number)
time: 1459209907 (number)
event: update
author (object)
id: 123456 (number)
name: API v2
item_id: 1235435 (number)
item_type: “Setting” (string)
changes (array)
(object)
field: enable_availability
previous: true (boolean)
updated: false (boolean)
(object)
field: unavailability_minimum_days
previous: 3 (number)
updated: 4 (number)
Award Templates
Use the award templates endpoint to read and update which managed awards an organisation has enabled.

Only admins are able to access this endpoint.
Award Templates List [/api/v2/award_templates]
GETGet Enabled Award Templates
This method returns a list of award templates enabled for the API user’s organisation.

This method requires the settings scope (see Scopes for more information).
Parameters
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified award templates
include_custom_award_templates: false (optional, boolean) - If true, award template organisation will be included in the response. Defaults to false.
200
OK
(application/json)
Attributes (array):
award_template_id: 990 (number, required) - The award template ID
name: Clerks Private Sector (string) - The name of the award or EBA
identifier: MA000002 (string) - An identifier for the award or EBA
award_template_organisation_id: 5624432 (number) - The internal ID linking this template to the organisation (if linked)
POSTEnable Award Template
Use this method to enable an award template for a particular organisation. A single field, the award_template_id, is required. This field is unique across Workforce. You can get a list of valid IDs by making a call to the available award templates method.

This method enables the award template, then triggers a background job to populate the Workforce organisation with the relevant payroll rules and allowances. It may take up to several hours for those to be created and costing information to be updated.

If you include the extract_leave_types parameter with a value of true, any leave types included in the template will be made user-visible and user-editable. The default is false which means that leave types will be managed by the template after it’s created.

If you include the replace_leave_types parameter with a value of true, any existing leave types in the organisation prior to the award template’s being added will be removed. The default is false which will not alter existing leave types.

This method requires the settings scope (see Scopes for more information).
Request Enable Award Template (application/json)
Body

    {
      "award_template_id": 990,
    }

200
OK
(application/json)
Attributes(AwardTemplateData)
award_template_id: 990 (number)
Request Enable Award Template With Leave Types Extracted (application/json)
Body

    {
      "award_template_id": 990,
      "extract_leave_types": true,
      "replace_leave_types": true
    }

200
OK
(application/json)
Attributes(AwardTemplateData)
award_template_id: 990 (number)
Award Templates List [/api/v2/award_templates/available]
GETGet Available Award Templates
This method returns a full list of award templates available in Workforce.

This method requires the settings scope (see Scopes for more information).
200
OK
(application/json)
Attributes (array):
award_template_id: 990 (number, required) - The award template ID
name: Clerks Private Sector (string) - The name of the award or EBA
identifier: MA000002 (string) - An identifier for the award or EBA
award_template_organisation_id: 5624432 (number) - The internal ID linking this template to the organisation (if linked)
Organisations
Use the organisations endpoint to get a list of clients you manage, and register new clients. If you have access to this endpoint, you can also get access tokens for clients you manage.

To get access to this endpoint, please contact Workforce.
Organisation List [/api/v2/organisations]
GETGet Organisations
This method requires the organisation scope (see Scopes for more information).
Parameters
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified organisations
200
OK
(application/json)
Attributes (array):
id: 747 (required) (number) - Organisation’s unique ID
name: Tom’s Restaurant (required, string) - The organisation’s name
payroll_system: myob (string) - The payroll software used by the organisation
country: Australia (required) (string) - The country in which the organisation is legally based
locale: en (string) - The i18n locale for the organisation
time_zone: Brisbane (string) - The organisation’s time zone name
industry: The organisation’s industry
customer_ids: 748, 749 (array[number]) - Organisation IDs for customers of this organisation
POSTCreate Organisation
This method requires the organisation scope (see Scopes for more information).
The following fields can be used when creating a new organisation:

name - required, string - the organisation’s name.
country - required, string - the country the organisation is legally established in.
timesheet_interval - required, integer - 1 for weekly timesheets, 2 for fortnightly timesheets.
week_start_day - required, integer - the day of the week that timesheets should start on. 0 is Sunday, 1 is Monday, and so on.
locale - optional, string - the language tag for system translation. Defaults to en. Click here for more information.
time_zone - optional, string - the time zone for the new organisation. If not provided, defaults to authenticated user’s time zone. Uses zone names from here, eg “Brisbane” or “Perth”.
award_template_ids - optional, array[integer] - IDs of award templates you’d like to make available to this organisation. Note that you’ll still need to enable the award template once the organisation is created.
industry - optional, string - the industry the organisation belongs to. e.g. ‘Aged Care’.
customer_ids - optional, array[integer] - IDs of other organisations which are customers of this organisation. This organisation will be able to access its customers and impersonate users within them through the Workforce UI.

Request Create Organisation (application/json)
Body

    {
      "name": "Vandelay Industries",
      "country": "New Zealand",
      "locale": "en-NZ",
      "timesheet_interval": 1,
      "week_start_day": 0,
      "time_zone": "Auckland",
      "award_template_ids": [1,2,3],
      "customer_ids": []
    }

200
OK
(application/json)
Attributes(OrganisationData)
id: 748 (number)
name: Vandelay Industries
country: New Zealand
locale: en-NZ
time_zone: Auckland
customer_ids: (array[number])
Organisation [/api/v2/organisations/{id}]
GETGet Organisation
Get an organisation by id.

This method requires the organisation scope (see Scopes for more information).
200
OK
(application/json)
Attributes:
id: 747 (required) (number) - Organisation’s unique ID
name: Tom’s Restaurant (required, string) - The organisation’s name
payroll_system: myob (string) - The payroll software used by the organisation
country: Australia (required) (string) - The country in which the organisation is legally based
locale: en (string) - The i18n locale for the organisation
time_zone: Brisbane (string) - The organisation’s time zone name
industry: The organisation’s industry
customer_ids: 748, 749 (array[number]) - Organisation IDs for customers of this organisation
PUTUpdate Organisation
This method requires the organisation scope (see Scopes for more information).
The following fields can be updated using this endpoint:

name - required, string - the organisation’s name.
country - required, string - the country the organisation is legally established in.
locale - optional, string - the language tag for system translation. Defaults to en. Click here for more information.
award_template_ids - optional, array[integer] - IDs of award templates you’d like to make available to this organisation. Note that you’ll still need to enable the award template once the organisation is created.
industry - optional, string - the industry the organisation belongs to. e.g. ‘Aged Care’.
customer_ids - optional, array[integer] - IDs of other organisations which are customers of this organisation. This organisation will be able to access its customers and impersonate users within them through the Workforce UI.

Parameters
id: 747 (number) - The ID of the organisation
Request Add Customer (application/json)
Body

    {
      "customer_ids": [
        737,
        727
      ]
    }

200
OK
(application/json)
Attributes(OrganisationData)
customer_ids: 727, 737 (array[number])
Request Clear Customers (application/json)
Body

    {
      "customer_ids": []
    }

200
OK
(application/json)
Attributes(OrganisationData)
customer_ids: (array[number])
Organisation Access Tokens [/api/oauth/token]
POSTCreate Access Token
Use this endpoint to get an access token for an organisation that you have read access to. To request a token, make a POST to /api/oauth/token - the same path you would use to request a regular Password access token. Supply these fields:

access_token - required, string - your current valid access token (the one you use to get a list of organisations)
organisation_id - required, integer - the organisation you’d like to get an access token for - get this from the list of organisations
scope - required, string - one or more Scopes separated by spaces
grant_type - required, string - must be partner_token
The right sidebar contains an example access token reques & response. The access token in the response will give you access to the organisation ID provided in the request.

Request Create Access Token
curl https://my.workforce.com/api/oauth/token -X POST -H "Cache-Control: no-cache" \ -F "access_token=YOUR_CURRENT_ACCESS_TOKEN" \ -F "organisation_id=747" \ -F "scope=user me" \ -F "grant_type=partner_token"

Response 200

        {
          "access_token": "6833b9ecaa84ce420da3cafaa43124d241cb28b5287b72d131f6b38bcb64cd91",
          "token_type": "bearer",
          "scope": "user me",
          "created_at": 1457304578
        }

Personal Details
View & update personal details.

All endpoints here require the personal scope. Some endpoints require the financial scope to view financial data, or the user scope to view data about an employee.
Your Personal Details [/api/v2/personal_details]
These details will apply to all accounts linked under your profile
GETGet Personal Details
Gets the personal details of the currently authenticated user

This method requires the personal scope.
To retrieve financial information, such as a Tax File Number, you must also have the financial scope.

200
OK
(application/json)
Body

    {
      "email": "bartsimpson@tanda.co",
      "gender": "male",
      "emergency_contacts": [{
        "name": "Marge Simpson",
        "relationship": "Mom",
        "phone": "0400 000 000"
      }]
    }

PUTUpdate Personal Details
Update the currently authenticated user’s personal details.

Any emergency_contacts provided will be appended to existing emergency contacts.
Employee’s Personal Details [/api/v2/personal_details/{user_id}]
GETGet Employee’s Personal Details
This endpoint requires the user and personal scopes. The authenticated user must also be a manager of the employee identified by user_id. The financial scope is required to see financial data.
Parameters
user_id: 123456 (number) - The id of the user
200
OK
(application/json)
Body

    {
      "email": "bartsimpson@tanda.co",
      "gender": "male",
      "emergency_contacts": [{
        "id": 1234,
        "name": "Marge Simpson",
        "relationship": "Mom",
        "phone": "0400 000 000"
      }]
    }

PUTUpdate Employee’s Personal Details
Update a user’s personal details.

This endpoint requires the user and personal scopes. The authenticated user must also be a manager of the employee identified by user_id. The financial scope is required to see financial data.
Any emergency_contacts provided will be appended to existing emergency contacts.
Parameters
user_id: 123456 (number) - The ID of the user
Webhooks
Get notified when things happen inside Workforce.

Check out our user guide to walk you through setting up a Webhook - there’s no programming knowledge required!
There are three concepts to understand when working with webhooks:

Topics: a topic is a type of event that can happen inside Workforce, for example “user.created” or “clockin.updated” - a full list of topics can be found below.
Subscriptions: a subscription is comprised of a URL (where we send the notification payload) and the specific events in Workforce (topics) you want sent to the URL, think of these as the events you have subscribed to be notified about.
Notifications: a notification is a HTTP POST request we make to the URL you configure in the subscription. All notifications received will follow the format outlined in the notification payload section below.
Notification Payload
Headers Content-Length: 475 Content-Type: application/json X-Webhook-Signature: g7LZCBPlwBg1vid0dOHgt7HToR0=

Payload { "hook_key": "", "hook_time": "", "payload": { "organisation_id": "", "body": {}, "topic": "" } }

hook_key: The hook_key is a UUID associated with the webhook event, if you’re worried about duplications interfering with your integration, use this to dedup.
hook_time: The hook_time is the time the event was emitted in epoch format.
body: The contents of the payload.body depend upon what topic the subscription is for, for each topic you can generally find the payload body under the corresponding API endpoint documentation e.g. a subscription to the leaverequest.created event will have the same fields as the response to the endpoint to create a leave request.
topic: This is the topic name as detailed in the ‘Topic’ column below.
Available Topics
Topic	Description
clockin.updated	Sent when a clockin is updated, for example to get a shift ID attached post-processing. Not sent for when a clockin with a photo is processed, use clockin.photo for this.
clockin.photo	Sent when a clockin with a photo is processed. Not all clockins have photos, so this will be a subset of clockin.updated.
department.created	Sent when a team is created.
department.updated	Sent when a team is updated.
department.destroyed	Sent when a team is destroyed.
leaverequest.approved	Sent when a leave request is approved.
leaverequest.created	Sent when a leave request is created.
leaverequest.rejected	Sent when a leave request is rejected.
leaverequest.updated	Sent when a leave request is updated (this includes approval and rejection).
schedule.created	Sent when a schedule is created (doesn't send for roster templates).
schedule.updated	Sent when a schedule is changed (doesn't send for roster templates).
schedule.destroyed	Sent when a schedule is deleted (doesn't send for roster templates).
schedule.published	Sent when a schedule is sent to an employee by email or SMS, or when it's printed
shift.approved	Sent when a shift is approved.
shift.unapproved	Sent when a shift is unapproved.
shift.updated	Sent when a shift is changed (includes approval).
super_fund_membership.updated	Sent when a user's super fund membership is changed.
timesheet.approved	Sent when a timesheet is approved.
timesheet.exported	Sent when a timesheet is exported.
timesheet.costed	Sent when a timesheet is recalculated due to a change elsewhere in the system. Note this is only sent if the recalculation results in a change in the total_cost field.
unavailability.created	Sent when an unavailability is created.
qualification.created	Sent when an qualification is created.
qualification.updated	Sent when an qualification is changed.
qualification.destroyed	Sent when an qualification is deleted.
user.created	Sent when a new user is created, either manually, by API, or by bulk import.
user.deactivated	Sent when a new user is deactivated, either manually or via the API.
user.reactivated	Sent when a new user is reactivated, either manually or via the API.
user.onboarding_complete	Sent when a user has complete their onboarding.
user.updated	Sent when a user is changed.
leavebalance.created	Sent when a leave balance is created.
leavebalance.updated	Sent when a leave balance is updated.
platform_record.created	Sent when a platform record is created.
platform_record.updated	Sent when a platform record is updated.
platform_record.destroyed	Sent when a platform record is destroyed.
ats_jobapplication.stage_changed	Sent when a job application stage is updated.
Want to see other topics added to this list? Let us know!

Creating Webhooks
To manage Webhooks you have two choices:

the API if this is part of a more complicated integration with Workforce.
the UI if the use case is simple enough.
Programmatically
Webhooks can be managed via API calls, please note you’ll need to be authenticated as an Admin user when making calls to the /api/v2/webhooks endpoints.

The available endpoints for working with subscriptions are documented below - you can also work with an individual subscription in various ways.

Through the UI
Workforce presents the Webhooks portal to manage existing and create new subscriptions through the UI.

Simply enter a URL, Security Token (covered in more detail here) and select the topics you wish to be notified about at the specified URL.

Testing your Webhooks
When working with webhooks you may find it useful to emit events to somewhere you can inspect them without having to setup a server, try and Google “testing Webhooks” or “tools for testing webhooks”.

Securing Webhooks
To validate that the webhook came from Workforce and not an unknown 3rd party, we attach a security token to each request in the X-Webhook-Signature header. The security token is constructed from a secret you provide when you first create the webhook subscription.

The token is computed using the HMAC SHA1 hashing algorithm. The secret you provide during subscription creation is used as the key and the request body (all of it) is the message passed to the hashing function.

X-Hook-Signature = HMACSHA1(Secret Token, Request Body)

By checking that the X-Webhook-Signature matches when you receive it you can be sure that the webhook came from Workforce & was not tampered with.

Some samples for validating the signature are below:

NodeJS
Python
Ruby
Warning: make sure you are checking the value sent in the X-Webhook-Signature header. Other headers may also be included (eg. X-Hook-Signature) but these are deprecated and should not be used.

Delivery Timeframes
While all efforts are made to ensure our webhook system is working without delay. Our webhook events are sent as best effort and there is no guarantee an event will be sent from our systems within a specific timeframe. It is important to keep in mind that the delivery timeframes may vary.

Event Ordering
We cannot guaratee that our systems will send events in order they occur in our systems, you should design your receiving systems to handle this.

Failures & Retries
When we send a notification, we expect to get back a 200 response code within 30 seconds. If we don’t get a 200 after 30 seconds, we’ll consider the webhook failed & begin retrying it.

We will retry 12 times, roughly every 5 minutes.
We will retry another 24 times, roughly every 1 hour.
We will stop retrying if we recieve a 200 status.
If after 36 attempts, we still haven’t recieved a 200 status, we will stop sending new webhook events to the URL in question. Webhook events that are currently processing will continue to process (up to 36 tries). To send new events, you will need to manually re-enable the webhook via the UI: https://my.workforce.com/api/webhooks

Best Practices
Before going live with your application, test that your integration is working properly.

If your webhook receiver performs complex computation or might be blocked by IO/network you may find it times out when trying to receive the webhook from Workforce. For this reason we recommend you acknowledge receipt of a webhook immediately by returning a 200.

Webhook endpoints might occasionally receive the same payload more than once. If your integrations logic is dependent upon exactly once delivery we advise you to safeguard against this by making your receiver idempotent, one way of doing this is by using the hook_key field and storing it temporarily, if you receive the same hook_key more than once you can discard it.

Due to the inherent complexities of sending data across the internet your webhook endpoints may receive payload events out of any inherent order. If your integrations logic is dependent upon ordered event payloads we advise you to safeguard against this by building your receiver system to handle this.

You should use security tokens, and verify them. See our instructions on Securing Webhooks.

Subscriptions List [/api/v2/webhooks]
Only admin users are able to access these endpoints. Webhook configuration is common across an organisation.
GETGet Subscriptions
200
OK
(application/json)
Attributes (array):
id: 123456 (number) - The Tanda defined ID for this subscription
url: https://requestb.in/TaNdA (required) (string) - The URL to send notifications to
token: IaMaSeCrEt (string) - A secret used to verify notification authenticity
topics: user.created, clockin.updated (required, array[string]) - A list of topics to get notifications for
POSTCreate Subscription
We will send a notification with the topic created when a webhook is first created.

Request (application/json)
Body

    {
      "url": "https://requestb.in/TaNdA",
      "token": "IaMaOptionalSeCrEt",
      "topics": ["user.created", "clockin.updated"]
    }

200
OK
(application/json)
Attributes:
id: 123456 (number) - The Tanda defined ID for this subscription
url: https://requestb.in/TaNdA (required) (string) - The URL to send notifications to
token: IaMaSeCrEt (string) - A secret used to verify notification authenticity
topics: user.created, clockin.updated (required, array[string]) - A list of topics to get notifications for
Subscription [/api/v2/webhooks/{id}]
GETGet Subscription
Parameters
id: 123456 (number) - The id of the subscription
200
OK
(application/json)
Attributes:
id: 123456 (number) - The Tanda defined ID for this subscription
url: https://requestb.in/TaNdA (required) (string) - The URL to send notifications to
token: IaMaSeCrEt (string) - A secret used to verify notification authenticity
topics: user.created, clockin.updated (required, array[string]) - A list of topics to get notifications for
DELETEDelete Subscription
Parameters
id: 123456 (number) - The id of the subscription
200
OK
(application/json)
Public Holidays
Here is a list of public holiday regions supported:

Region Code	Region Name
au	Australia (national holidays only)
au_act	Australian Capital Territory
au_nsw	New South Wales
au_nt	Northern Territory
au_qld	Queensland
au_sa	South Australia
au_tas	Tasmania
au_vic	Victoria
au_wa	Western Australia
cy	Cyprus (national holidays)
do	Dominican Republic (national holidays)
el	Greece (national holidays)
fi	Finland (Finnish) (national holidays)
gb	United Kingdom (national holidays only)
gb_eng	England
gb_nir	Northern Island
gb_sct	Scotland
gb_wls	Wales
jp	Japan (national holidays)
lr	Liberia (national holidays)
nz	New Zealand (national holidays)
mm	Myanmar (national holidays)
mt_en	Malta (English) (national holidays)
mu	Mauritius (national holidays)
us	United States of America (national holidays)
za	South Africa (national holidays)
ph	The Philippines (national holidays)
vi	Vietnam (national holidays)
ca	Canada (national holidays)
be_fr	Belgium (national holidays in French)
be_nl	Belgium (national holidays in Dutch)
th	Thailand (national holidays only)
uy	Uruguay (national holidays only)
You can see holiday dates in your System Settings.

Public Holidays [/api/v2/public_holidays]
GETGet Public Holidays
Given a list of regions, and years, returns a list of public holidays in those regions in those years.

Parameters
regions: au,au_qld (required, string) - one or more comma separated public holiday regions
years: 2018,2019 (required, string) - one or more comma separated public holiday years
201
Created
(application/json)
Body

    {
      "au": [{"date": "2018-01-01", "name": "New Year's Day"}],
      "au_qld": [{"date": "2018-01-01", "name": "New Year's Day"}]
    }

Temporary Files
Temporary Files [/api/v2/temporary_files]
POSTCreate Temporary File
Use this endpoint to upload files that will then be called by other endpoints. This allows you to process files “in the background” while a user is doing other things in your app. For example, if you are building a form for a user to request time off, you might start uploading to the temporary files endpoint as soon as the user chooses a verification photo. That way, when they submit the form, you have already uploaded the file and they don’t need to wait for it to upload.

Files must not be larger than 5mb.

Unlike other endpoints, this endpoint does not accept JSON. Instead it expects binary file data.

If you’re writing JavaScript, use the FormData API.
If you’re using CURL, use the -F (--form) flag.
If you’re using Postman, use the Form-data option, with a param of type “File” and key file.
If you like, you can pass a comma separated list of content types to the content_types param. If provided, the API will validate these against the uploaded file, and you will get a 400 status back if the file is invalid.

If the upload is successful, you’ll get back a file_id. Use this ID with endpoints that support file attachments. There’s a few things you should know about file IDs:

A file ID can only be used once. It will be deleted once the uploaded file has successfully been linked via another endpoint.
If a file ID isn’t used for a week it will be deleted.

Parameters
file: (required, file data)
content_types: image/gif,image/png (optional, string) - a comma separated list of content types to validate against
201
Created
(application/json)
Body

    {
      "file_id": "73fe3430-4f5d-3a0a-84a7-cffbeb5efeb2"
    }

Shift Reminders
Shift Reminders are sent as push notifications to the Workforce App before a schedule is set to start. Use this endpoint to configure reminders.

The minutes_before_shift_start param, used to control when reminders send, must be a multiple of 5, and must be between 5 and 1435 (ie. it can’t be more than 1 day). You can set up as many reminders as you like. Reminders are tied to the current authenticated user, which means they work across all organisations the user works at.

Shift Reminder List [/api/v2/shift_reminders]
GETGet Shift Reminders
This method requires the me scope (see Scopes for more information).
200
OK
(application/json)
Attributes (array):
id: 123706 (number, required) - The shift reminder ID
minutes_before_shift_start: 30 (number, required) - How long before a shift (in minutes) the reminder should send
POSTCreate Shift Reminder
This method requires the me scope (see Scopes for more information).
Request (application/json)
Body

    {
      "minutes_before_shift_start": 120
    }

200
OK
(application/json)
Attributes:
id: 123706 (number, required) - The shift reminder ID
minutes_before_shift_start: 30 (number, required) - How long before a shift (in minutes) the reminder should send
+ minutes_before_shift_start: 120

Shift Reminder [/api/v2/shift_reminders/{id}]
GETGet Shift Reminder
This method requires the me scope (see Scopes for more information).
Parameters
id: 123706 (number) - The ID of the shift reminder
200
OK
(application/json)
Attributes:
id: 123706 (number, required) - The shift reminder ID
minutes_before_shift_start: 30 (number, required) - How long before a shift (in minutes) the reminder should send
PUTUpdate Shift Reminder
This method requires the me scope (see Scopes for more information).
Parameters
id: 123706 (number) - The ID of the shift reminder to edit
Request (application/json)
Body

    {
      "minutes_before_shift_start": 45
    }

200
OK
(application/json)
Attributes:
id: 123706 (number, required) - The shift reminder ID
minutes_before_shift_start: 30 (number, required) - How long before a shift (in minutes) the reminder should send
+ minutes_before_shift_start: 45

DELETEDelete Shift Reminder
This method requires the me scope (see Scopes for more information).
Parameters
id: 123706 (number) - The ID of the shift reminder
200
OK
(application/json)
User Files
User files are documents that can be attached to a user’s profile. These files are visible to the user and their managers.

Only users with appropriate permissions can upload files. The user making the request must have permission to update the target user.
Unlike most endpoints, this endpoint does not accept JSON. Instead it expects multipart form data containing both the user_id and the file.

If you’re writing JavaScript, use the FormData API.
If you’re using CURL, use the -F (--form) flag.
If you’re using Postman, use the Form-data option.
Files must not be larger than 5mb.

User Files [/api/v2/user_files]
POSTUpload User File
Upload a file to be attached to a user’s profile.

This method requires the user scope (see Scopes for more information).
Parameters
user_id: 123456 (required, number) - The ID of the user to attach the file to
file: (required, file) - The file to upload
document_type: contract (optional, enum[string]) - How the file is classified. Defaults to other.
Members
warning
contract
document
performance_review
training
form
file_note
other
viewable_by_attached_user: true (optional, boolean) - Whether the attached user can see the file. Defaults to true.
viewable_by_attached_users_managers: true (optional, boolean) - Whether the attached user’s managers can see the file. Defaults to true.
Request Upload File (multipart/form-data)
Body

    {
      "user_id": 123456,
      "file": (binary),
      "document_type": "contract",
      "viewable_by_attached_user": true,
      "viewable_by_attached_users_managers": true
    }

200
OK
(application/json)
Body

    {
      "id": 42
    }

400
Bad Request
(application/json)
Body

    {
      "error": "file is missing"
    }

400
Bad Request
(application/json)
Body

    {
      "error": "document_type does not have a valid value"
    }

403
Forbidden
(application/json)
Body

    {
      "error": "You do not have access to this endpoint."
    }

404
Not Found
(application/json)
Body

    {
      "error": "No known user with that id!"
    }

Custom Events
Custom Events List [/api/v2/custom_events]
GETGet Custom Events List
Get a full list of custom events in a single request.

This method requires the roster and department scopes (see Scopes for more information).
Parameters
from: 2018-09-01 (required, string) - From date to lookup custom events
to: 2018-09-01 (required, string) - To date to lookup custom events
200
OK
(application/json)
Attributes (array):
id: 123677 (number, required) - The custom event ID
organisation_id: 23100 (number, required) - The organisation id where this custom event belongs to
start: 2018-09-01 (required) (string) - The date of the first day of the custom event
finish: 2018-09-01 (required) (string) - The last date of the custom event
name: Tanda Panda Day (required, string) - The name of the custom event
discourage_time_off: true (required) (boolean) - This states whether a custom events blocks time off or not
locations: 2002,2003,2004 (required) (array[number]) - The location ids to where the custom event applies
POSTCreate Custom Events List
Creates a custom event under the current organisation and placed under the specified location

This method requires the roster and department scopes (see Scopes for more information).
Request Create Custom Event (application/json)
Body

          {
            "name": "Workforce Panda Day",
            "start": "2018-09-01",
            "finish": "2018-09-01",
            "discourage_time_off": true,
            "custom_event_joins_attributes": [
              {"location_id": 2002},
              {"location_id": 2003},
              {"location_id": 2004}
            ]
          }

200
OK
(application/json)
Attributes:
id: 123677 (number, required) - The custom event ID
organisation_id: 23100 (number, required) - The organisation id where this custom event belongs to
start: 2018-09-01 (required) (string) - The date of the first day of the custom event
finish: 2018-09-01 (required) (string) - The last date of the custom event
name: Tanda Panda Day (required, string) - The name of the custom event
discourage_time_off: true (required) (boolean) - This states whether a custom events blocks time off or not
locations: 2002,2003,2004 (required) (array[number]) - The location ids to where the custom event applies
PUTUpdate Custom Event Request
This method requires the roster and department scopes (see Scopes for more information).
Parameters
id: 123677 (required, number) - The id of the custom event to update
Request Update Custom Event (application/json)
Body

            {
              "name": "Workforce Panda Month",
              "start": "2018-09-01",
              "finish": "2018-09-30",
              "discourage_time_off":true,
            }

200
OK
(application/json)
Attributes:
id: 123677 (number, required) - The custom event ID
organisation_id: 23100 (number, required) - The organisation id where this custom event belongs to
start: 2018-09-01 (required) (string) - The date of the first day of the custom event
finish: 2018-09-01 (required) (string) - The last date of the custom event
name: Tanda Panda Day (required, string) - The name of the custom event
discourage_time_off: true (required) (boolean) - This states whether a custom events blocks time off or not
locations: 2002,2003,2004 (required) (array[number]) - The location ids to where the custom event applies
+ name: Workforce Panda Month
+ start: `2018-09-01`
+ finish: `2018-09-30`
+ discourage_time_off: true

DELETEDelete Custom Event
This method requires the roster and department scopes (see Scopes for more information).
Parameters
id: 123677 (required, number) - The id of the custom event to delete
200
OK
(application/json)
Custom Event Locations [/api/v2/custom_events/{id}/locations]
PUTUpdate Custom Event Locations
This method requires the roster and department scopes (see Scopes for more information).
Parameters
id: 123677 (required, number) - The id of the custom event to update
location_ids: 2007 (required, array[number])
Request Update Custom Event locations (application/json)
Body

            {
              "location_ids": [2007]
            }

200
OK
(application/json)
Attributes:
id: 123677 (number, required) - The custom event ID
organisation_id: 23100 (number, required) - The organisation id where this custom event belongs to
start: 2018-09-01 (required) (string) - The date of the first day of the custom event
finish: 2018-09-01 (required) (string) - The last date of the custom event
name: Tanda Panda Day (required, string) - The name of the custom event
discourage_time_off: true (required) (boolean) - This states whether a custom events blocks time off or not
locations: 2002,2003,2004 (required) (array[number]) - The location ids to where the custom event applies
+ name: Workforce Panda Month
+ start: `2018-09-01`
+ finish: `2018-09-30`
+ discourage_time_off: true
+ locations: 2002, 2003, 2004, 2005, 2007

DELETEDelete Custom Event Location
This method requires the roster and department scopes (see Scopes for more information).
Parameters
id: 123677 (required, number) - The id of the custom event to update
location_ids: 2007 (required, array[number])
Request Update Custom Event locations (application/json)
Body { “location_ids”: [2005, 2007] }
200
OK
(application/json)
Attributes:
id: 123677 (number, required) - The custom event ID
organisation_id: 23100 (number, required) - The organisation id where this custom event belongs to
start: 2018-09-01 (required) (string) - The date of the first day of the custom event
finish: 2018-09-01 (required) (string) - The last date of the custom event
name: Tanda Panda Day (required, string) - The name of the custom event
discourage_time_off: true (required) (boolean) - This states whether a custom events blocks time off or not
locations: 2002,2003,2004 (required) (array[number]) - The location ids to where the custom event applies
+ name: Workforce Panda Month
+ start: `2018-09-01`
+ finish: `2018-09-30`
+ discourage_time_off: true
+ locations: 2002, 2003, 2004

Schedule Swap Plans
About
Models the life cycle of swapping a shift between two people. The two people involved in a swap are referred to as the sender (the original staff member) and the recipient (the new staff member).

Strategies
Schedule swap plans can be handled with different strategies. The strategy states include undecided, broadcasted and curated. Schedule swap plans in an undecided state, represent a plan that is new and has not had a strategy selected.

When a schedule swap plan is using the broadcasted strategy, managers will need to approve a person offering to cover the schedule.

When a schedule swap plan is using the curated strategy, the swap will be assigned to the first person accepting to cover the schedule.

Schedule swap plans created less than 3 days in advance of a schedule’s start are automatically broadcated.
States
A schedule swap plan can be in 3 states. The states are pending, approved and rejected.

Schedule Swap Plan List [/api/v2/schedule_swap_plans]
GETSchedule Swap Plan
Returns a list of schedule swap plans. Gets all plans by default, but you may specify which plans you would like to return using the statuses parameter. Schedule Swap Plans that are visible include:

Schedule swap plans where you are the sender
Schedule swap plans where you are a manager of the sender
This method requires the roster scope. (see Scopes for more information)
Request (appplication/json)
Body

  {
    "statuses": "pending,approved,rejected"
  }

200
OK
(application/json)
Attributes (array):
id: 1231342 (number, required) - The schedule swap plan ID
recipient_id: 3249234 (number) - The person who received the schedule
sender_id: 4593929 (number, required) - The person who offered to swap the schedule
schedule_id: 2340280 (number) - The schedule being swapped
status: approved (string) - The status of the swap. Will be one of ‘pending’, ‘approved’ or ‘rejected’
strategy: broadcasted (required) - the method of swapping the schedule. Will be one of ‘undecided’, ‘broadcasted’ or ‘curated’
reason: cannot work this shift - the reason the sender cannot work the schedule
POSTSchedule Swap Plan
Creates a new schedule swap plan. If the schedule’s start is more than 3 days away, the schedule swap plan will have a strategy of undecided, else it will automatically be broadcasted - unless the request is sent with the prepare_auto_broadcast: false parameter.

This method requires the roster scope. (see Scopes for more information)
Schedule swap plans can only be created for yourself or someone you manage
Schedule swap plans can only be created for schedules that meet the following criteria: - Is in the future - Has a start - Has a team
Request (application/json)
Body

  {
    "schedule_id": 10203834,
    // "prepare_auto_broadcast": true
  }

200
OK
(application/json)
Attributes:
id: 1231342 (number, required) - The schedule swap plan ID
recipient_id: 3249234 (number) - The person who received the schedule
sender_id: 4593929 (number, required) - The person who offered to swap the schedule
schedule_id: 2340280 (number) - The schedule being swapped
status: approved (string) - The status of the swap. Will be one of ‘pending’, ‘approved’ or ‘rejected’
strategy: broadcasted (required) - the method of swapping the schedule. Will be one of ‘undecided’, ‘broadcasted’ or ‘curated’
reason: cannot work this shift - the reason the sender cannot work the schedule
Broadcast [/api/v2/schedule_swap_plans/{id}/broadcast]
Transistions a swap from undecided to broadcasted making all concealed schedule swap proposals transition to pending. A schedule swap proposal will still require to be approved for this schedule swap plan to transition to approved

PUTBroadcast A Swap
This method requires the roster scope. (see Scopes for more information)
Parameters
id: 26 (number) - The schedule swap plan ID
200
OK
(application/json)
Attributes:
id: 1231342 (number, required) - The schedule swap plan ID
recipient_id: 3249234 (number) - The person who received the schedule
sender_id: 4593929 (number, required) - The person who offered to swap the schedule
schedule_id: 2340280 (number) - The schedule being swapped
status: approved (string) - The status of the swap. Will be one of ‘pending’, ‘approved’ or ‘rejected’
strategy: broadcasted (required) - the method of swapping the schedule. Will be one of ‘undecided’, ‘broadcasted’ or ‘curated’
reason: cannot work this shift - the reason the sender cannot work the schedule
Curate [/api/v2/schedule_swap_plans/{id}/curate]
Transistions a schedule swap plan from undecided to curated making all specified concealed schedule swap proposals transition to pending. This schedule swap plan will transition directly to approved when a user accepts to cover the schedule

PUTCurate A Swap
This method requires the roster scope. (see Scopes for more information)
Parameters
id: 26 (number) - The schedule swap plan ID
Request (application/json)
Body

  {
    "proposal_ids": [12312983, 12890371]
  }

200
OK
(application/json)
Attributes:
id: 1231342 (number, required) - The schedule swap plan ID
recipient_id: 3249234 (number) - The person who received the schedule
sender_id: 4593929 (number, required) - The person who offered to swap the schedule
schedule_id: 2340280 (number) - The schedule being swapped
status: approved (string) - The status of the swap. Will be one of ‘pending’, ‘approved’ or ‘rejected’
strategy: broadcasted (required) - the method of swapping the schedule. Will be one of ‘undecided’, ‘broadcasted’ or ‘curated’
reason: cannot work this shift - the reason the sender cannot work the schedule
Reject [/api/v2/schedule_swap_plans/{id}/reject]
PUTReject A Swap
Transitions a schedule swap plan to rejected making all its schedule swap proposals also transition to rejected

This method requires the roster scope. (see Scopes for more information)
Schedule swap plans can only be rejected yourself or for someone you manage
Parameters
id: 26 (number) - The schedule swap plan ID
200
OK
(application/json)
Attributes:
id: 1231342 (number, required) - The schedule swap plan ID
recipient_id: 3249234 (number) - The person who received the schedule
sender_id: 4593929 (number, required) - The person who offered to swap the schedule
schedule_id: 2340280 (number) - The schedule being swapped
status: approved (string) - The status of the swap. Will be one of ‘pending’, ‘approved’ or ‘rejected’
strategy: broadcasted (required) - the method of swapping the schedule. Will be one of ‘undecided’, ‘broadcasted’ or ‘curated’
reason: cannot work this shift - the reason the sender cannot work the schedule
Notify [/api/v2/schedule_swap_plans/{id}/notify]
PUTNotify Everyone Who Can Cover
Will send a notification to all users available to cover this shift through the Workforce App

Notifications will only be sent to users who have a schedule swap proposals in a pending or seen state.
This method requires the roster scope. (see Scopes for more information)
Only a manager of a swap can notify the users available
Parameters
id: 26 (number) - The schedule swap plan ID
200
OK
(application/json)
Attributes:
id: 1231342 (number, required) - The schedule swap plan ID
recipient_id: 3249234 (number) - The person who received the schedule
sender_id: 4593929 (number, required) - The person who offered to swap the schedule
schedule_id: 2340280 (number) - The schedule being swapped
status: approved (string) - The status of the swap. Will be one of ‘pending’, ‘approved’ or ‘rejected’
strategy: broadcasted (required) - the method of swapping the schedule. Will be one of ‘undecided’, ‘broadcasted’ or ‘curated’
reason: cannot work this shift - the reason the sender cannot work the schedule
Schedule Swap Proposals
About
Models the life cycle of vetting one potential recipient for a schedule swap plan.

States
Used to specify where a proposal is in its life cycle:

Schedule swap proposals which are concealed are only visible to managers. and are visible to enable a manager to curate a schedule swap plan.

Schedule swap proposals which are pending are new and have not been actioned by a user.

Schedule swap proposals which are seen have been marked as viewed by the users (e.g. a swap can be marked as seen through the API, or by the Workforce App)

Schedule swap proposals which are accepted have had a user offer to cover the shift but are awaiting approval by a manager.

Schedule swap proposals which are approved have been accepted, and the user of this proposal is now scheduled to work the shift.

Schedule swap proposals which are rejected have been declined by either the user or a manager of the user

Schedule Swap Proposal List [/api/v2/schedule_swap_proposals]
GETSchedule Swap Proposals
Returns a list of schedule swap proposals. Gets all proposals by default, but you may specify which proposals to return using the statuses parameter. Schedule swap proposals that are visible include:

schedule swap proposals of users you manage
schedule swap proposals for yourself (that are not concealed)
If a user has another commitment at the same time as the proposed schedule. There will be no proposal for this user
This method requires the roster scope. (see Scopes for more information)
Request (appplication/json)
Body

  {
    "statuses": "concealed,seen,pending,approved,rejected,accepted"
  }

200
OK
(application/json)
Attributes (array):
id: 23409 (number, required) - The schedule swap proposal ID
schedule_swap_plan_id: 23 (number, required) - The schedule swap plan ID that this proposal belongs to.
user_id: 1263 (number, required) - The user ID that this proposal is for
status: pending (string, required) - The state of the proposal. Will be one of ‘concealed’, ‘pending’, ‘seen’, ‘accepted’, ‘approved’, ‘rejected’
strategy: curated (string, required) - The strategy of the schedule swap plan this proposal belongs to. Will be one of ‘undecided’, ‘broadcasted’, ‘curated’
response: Thankyou for covering this shift 🙏 (string, optional) - A response for the user of the proposal from a manager
complete: true (boolean, required) - Whether the schedule swap proposal has been processed yet - most data will be empty until this is true
created_at: 1643637600 (number, required) - The date the schedule swap proposal was created, in unix time
updated_at: 1646056800 (number, required) - The date the schedule swap proposal was last updated, in unix time
schedule_details (object) - the details of the proposed schedule
automatic_break_length: 30 (number, required) - the length of automatic breaks in minutes
cost: 196.48 (number, required) - the cost the shift would have
department_id: 23423 (number, required) - the team ID the schedule will be in
finish: 230948239048 (number, optional) - the time the schedule would finish at
start: 1239182309902 (number, required) - the time the schedule would start at
shift_detail_id: 9210 (number, optional) - the shift detail ID for the detail the shift would have
breaks: (array[ScheduleBreakData]) - the breaks the schedule would have
roster_details (object) - the details of the proposed roster
hours_in_week: 32 (number, optional) - number of hours the employee will work
errors: (array[RosterError]) the validation errors that the roster would contain
Schedule Swap Proposal [/api/v2/schedule_swap_proposals/{id}/status]
PUTSchedule Swap Proposal
Useful to transition a proposal between states.

Proposals are only eligible for transitions under specific circumstances. The conditions are:
* Transition to seen - proposal must currently be pending or accepted - proposal must be your own

* Transition to acccepted - proposal must currently be pending or seen - proposal must be your own

* Transition to approved - proposal must be accepted - plan must be pending

* Transition to rejected - proposal must be pending, seen or accepted - proposal must be your own, or someones who you manage

Parameters
id: 23409 (number, required) - The ID of the schedule swap proposal to update
status: ‘seen’ (string, required) - Must be one of ‘seen’, ‘accepted’, ‘approved’, ‘rejected’
200
OK
(application/json)
Attributes:
id: 23409 (number, required) - The schedule swap proposal ID
schedule_swap_plan_id: 23 (number, required) - The schedule swap plan ID that this proposal belongs to.
user_id: 1263 (number, required) - The user ID that this proposal is for
status: pending (string, required) - The state of the proposal. Will be one of ‘concealed’, ‘pending’, ‘seen’, ‘accepted’, ‘approved’, ‘rejected’
strategy: curated (string, required) - The strategy of the schedule swap plan this proposal belongs to. Will be one of ‘undecided’, ‘broadcasted’, ‘curated’
response: Thankyou for covering this shift 🙏 (string, optional) - A response for the user of the proposal from a manager
complete: true (boolean, required) - Whether the schedule swap proposal has been processed yet - most data will be empty until this is true
created_at: 1643637600 (number, required) - The date the schedule swap proposal was created, in unix time
updated_at: 1646056800 (number, required) - The date the schedule swap proposal was last updated, in unix time
schedule_details (object) - the details of the proposed schedule
automatic_break_length: 30 (number, required) - the length of automatic breaks in minutes
cost: 196.48 (number, required) - the cost the shift would have
department_id: 23423 (number, required) - the team ID the schedule will be in
finish: 230948239048 (number, optional) - the time the schedule would finish at
start: 1239182309902 (number, required) - the time the schedule would start at
shift_detail_id: 9210 (number, optional) - the shift detail ID for the detail the shift would have
breaks: (array[ScheduleBreakData]) - the breaks the schedule would have
roster_details (object) - the details of the proposed roster
hours_in_week: 32 (number, optional) - number of hours the employee will work
errors: (array[RosterError]) the validation errors that the roster would contain
Timeclock Questions
Use Timeclock Questions to create workflows around clocking in. There are currently three types of questions. The types are allowance, shift_tag and shift_note. Answering the questions will perform the following:

An allowance question will apply an allowance to the shift
A shift_tag question will set the tag on the shift
A shift_note question will add a note to the shift
These triggers are available: * start – question is asked when a staff member enters a clockin. * finish – question is asked when a staff member enters a clockout.
These conditions are available: * early – question is only asked when a trigger is early for its corresponding schedule. * late – question is only asked when a trigger is late for its corresponding schedule. * unscheduled – question is only asked when a trigger has no corresponding schedule. * schedule_needs_acceptance - question is asked if the schedule still needs acceptance or if the schedule is accepted, but the clock in is early or late. * shift_length_over - question is only asked if the shift length exceeds the condition threshold in hours
All methods require the device scope (see Scopes for more information).
Timeclock Questions List [/api/v2/timeclock_questions]
GETGet Timeclock Questions
Parameters
ask_on_devices: timeclock,app (optional, string) - Filter to a particular type of question. Comma separated list of devices.
200
OK
(application/json)
Attributes (array):
id: 42 (number, required) - the question ID
question: What was your cash tips balance? (required) (string) - The question to ask
required: false (optional, boolean) - Should the shift data be considered incomplete if the question is not answered? (displays warning message to ensure employee is aware the question is required)
trigger_on: finish (required) (string) - when should the question be asked?
ask_on_devices: timeclock (optional, array[string]) - what devices should this question show on?
condition: early (optional, string) - conditions under which this question should show
type: allowance (required) (string) - type of answer expected
lenience: 15 (number, required) - for conditional question, how much lenience when asked
process: ask_question (required) (string) - what action should take place if the given criteria is met. ask_question	block_clockin
POSTCreate Timeclock Questions
When creating a timeclock questions you can also create answer options. This will allow Workforce to suggest options when asking the question.

Request (application/json)
Body

    {
      "condition": "late" // (optional),
      "name": "What is the meaning of life?",
      "trigger_on": "finish",
      "type": "shift_note",
      "required": true,
      "answer_options_attributes": [ // (optional)
        { answer: "42" },
      ]
    }

201
Created
(application/json)
Attributes:
id: 42 (number, required) - the question ID
question: What was your cash tips balance? (required) (string) - The question to ask
required: false (optional, boolean) - Should the shift data be considered incomplete if the question is not answered? (displays warning message to ensure employee is aware the question is required)
trigger_on: finish (required) (string) - when should the question be asked?
ask_on_devices: timeclock (optional, array[string]) - what devices should this question show on?
condition: early (optional, string) - conditions under which this question should show
type: allowance (required) (string) - type of answer expected
lenience: 15 (number, required) - for conditional question, how much lenience when asked
process: ask_question (required) (string) - what action should take place if the given criteria is met. ask_question	block_clockin
Timeclock Question [/api/v2/timeclock_questions/{id}]
DELETEDelete Timeclock Question
Deleting a timeclock question will not delete the corresponding allowance.

Parameters
id: 42 (number) - The id of the question
200
OK
(application/json)
Answer Questions [/api/v2/timeclock_questions/{id}/answer]
POSTAnswer Questions
This answer submits an answer to a timeclock question. The answer will be stored based on how the question is configured. For example it might be set as an allowance value, or a tag on a shift.

You can post answers through this endpoint, or as part of a clock in. If you use this endpoint, the answer will be validated, and you’ll get an error if it’s the wrong format. If you use the clock ins endpoint, no validation is performed.

The answers type depends on the question type. Expected types for answers are: - shift_note question expects string - allowance question expects number
Parameters
id: 42 (number, required) - The ID of the question
user_id: 234 (number, required) - the ID of the user answering
shift_id: 23432 (number, required) - the ID of the shift this question relates to
answer: 63.4 (string	number, required) - the actual answer to the question. the value type depends on the question.
Request Submit a cash tips balance (application/json)
Body

    {
      "user_id": 234,
      "shift_id": 23432,
      "answer": 63.4
    }

200
OK
(application/json)
Platform
All methods require the platform scope (see Scopes for more information).
Object List [/api/v2/platform/objects]
GETGet Objects
Gets all of your current platform objects

200
OK
(application/json)
Attributes (array[PlatformObjectData])
Object [/api/v2/platform/objects/{id}]
GETGet Object
Gets a specific platform object by id

Parameters

id: 42 (number) - The id of the object
Response 200 (application/json)

Attributes (PlatformObjectData)
PUTPut Object
Updates a specific platform object

Parameters

id: 42 (number) - The id of the object
Request (application/json)

Body

    {
      "fields": [
        { "name": "Description", "key": "description", "type": "text" },
        { "name": "Amount", "key": "amount", "type": "float" }
      ],
      "owned_associations": [
        { "name": "Client", "key": "client_id", "type": "has_one" },
        { "name": "Sales Rep", "key": "employee_id", "type": "has_many" }
      ]
    }

Response 201 (application/json)

Attributes (PlatformObjectData)
DELETEDelete Object
Deletes a specific platform object

Parameters

id: 42 (number) - The id of the object
Response 204 (application/json)

Record List [/api/v2/platform/{api_name}]
GETGet Records
Gets all platform records for a specific platform object

You cannot use this endpoint for native objects (shift, user, etc), only for custom ones.
Parameters

api_name: invoices (string) - The api name of the object
Response 200 (application/json)

Body

    {
      "id": 19283,
      "description": 'an invoice',
      "amount": 99.99
    }

POSTPost Record
Creates a platform record for a specific platform object

Parameters

api_name: invoices (string) - The api name of the object
Request (application/json)

Body

    {
      "description": 'an invoice',
      "amount": 99.99
    }

Response 201 (application/json)

Body

    {
      "id": 19283,
      "description": 'an invoice',
      "amount": 99.99
    }

Record [/api/v2/platform/{api_name}/{id}]
GETGet Record
Gets a specific platform record for a specific platform object

Parameters

api_name: invoices (string) - The api name of the object
id: 42 (number) - The id of the object
Response 200 (application/json)

Body

    {
      "id": 19283,
      "description": 'an invoice',
      "amount": 99.99
    }

PUTPut Record
Updates a specific platform record for a specific platform object

Parameters

api_name: invoices (string) - The api name of the object
id: 42 (number) - The id of the object
Request (application/json)

Body

    {
      "description": 'another invoice'
    }

Response 201 (application/json)

Body

    {
      "id": 19283,
      "description": 'an invoice',
      "amount": 99.99
    }

DELETEDelete Record
Deletes a specific platform record for a specific platform object

Parameters

api_name: invoices (string) - The api name of the object
id: 42 (number) - The id of the object
Response 204 (application/json)

Reports
The reports endpoint contains read-only endpoints to answer questions that get asked a lot where the answer is better off automated.

All reports require the cost scope (see Scopes for more information).
Adoption Metrics [/api/v2/reports/adoption_metrics]
GETGet Adoption Metrics
Provides a summary of adoption of key product features across the organisation.

Parameters
weeks: 1 (number) - 1	2	4 - number of weeks to aggregate data for
include_user_ids: false (optional, boolean) - if true, include user IDs for every property. Defaults to false.
200
OK
(application/json)
Body

      {
        "last_sign_in": 1586962894,
        "active_employees": 1797,
        "app": {
          "average": 655,
          "delta": 0
        },
        "timesheets": {
          "average": 0,
          "delta": 0
        },
        "approved_timesheets": {
          "average": 67,
          "delta": 3.728436282693378
        },
        "clockins": {
          "average": 307,
          "delta": 17.028380634390654
        },
        "rostering": {
          "average": 224,
          "delta": 10.127991096271565
        },
        "onboarding": {
          "completed": 0,
          "added_manually": 1792,
          "new": 1797
        }
      }

Shift Ratings
Either the user_id or employee_number fields are required to submit a shift rating. The user_id is the systems unique id (id field from /users) and the employee_number is the employee payroll_number (employee_number from /users).

Posting another shift rating for a user for that day will override the current shift rating.

Shift Rating requires the timesheet scope (see Scopes for more information).
Shift Ratings [/api/v2/shift_ratings]
POSTPost Shift Ratings
Allows for a shift rating from 1 to 5 to be added to a users shift in Workforce if they worked on that day.

Request Submit Shift Rating with user_id (application/json)
Body

    {
      "user_id": 12345,
      "date": "2020-07-22",
      "rating": 5
    }

Request Submit Shift Rating with employee_number (application/json)
Body

    {
      "employee_number": "abc123",
      "date": "2020-07-22",
      "rating": 5
    }

200
OK
(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,
      "rating": 5,
      "last_rated_by": 123345
    }

Cognitive Creator Configuration
Either the department_id or cognitive_creator_configuration_id fields are required to for creating or updating a cognitive creator configuration.

Cognitive creator configuration requires the department scope (see Scopes for more information).
Cognitive Creator Configuration list [/api/v2/cognitive_creator_configuration]
GETGet Cognitive Creator Configuration
Gets all your Cognitive Creator Configurations.

Parameters
updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified users
200
OK
(application/json)
Attributes (array[CognitiveCreatorConfigurationData])
Cognitive Creator Configuration [/api/v2/cognitive_creator_configuration/{id}]
GETGet Cognitive Creator Configuration
Gets the specified Cognitive Creator Configuration by ID.

200
OK
(application/json)
Attributes (CognitiveCreatorConfigurationData)
PUTPut Cognitive Creator Configuration
Update the specified Cognitive Creator Configuration by ID.

Request Cognitive Creator Configuration (application/json)
Body

    {
      "minimum_staff": 0,
      "maximum_staff": 3,
      "max_concurrent_start": 2,
      "min_length": 3.5,
      "max_length": 8,
      "time_to_open": 0.5,
      "time_to_close": 0.5,
      "undercoverage_penalty_ratio": 1.3,
      "round_down_head_count": true,
      "consolidate_shift_count": true
    }

200
OK
(application/json)
Attributes (CognitiveCreatorConfigurationData)
DELETEDelete Cognitive Creator Configuration
Delete the specified Cognitive Creator Configuration by ID. This will effectively reset the settings to default.

200
OK
(application/json)
Cognitive Creator Configuration by department [/api/v2/cognitive_creator_configuration/for_department/{department_id}]
GETGet Cognitive Creator Configuration
Get Cognitive Creator Configuration for a department.

200
OK
(application/json)
Attributes (CognitiveCreatorConfigurationData)
POSTPost Cognitive Creator Configuration
Create cognitive creator configuration for a department. Posting another cognitive creator configuration for a department will override the current configuration.

Request Cognitive Creator Configuration (application/json)
Body

    {
      "minimum_staff": 0,
      "maximum_staff": 3,
      "max_concurrent_start": 2,
      "min_length": 3.5,
      "max_length": 8,
      "time_to_open": 0.5,
      "time_to_close": 0.5,
      "undercoverage_penalty_ratio": 1.3,
      "round_down_head_count": true,
      "consolidate_shift_count": true
    }

200
OK
(application/json)
Attributes (CognitiveCreatorConfigurationData)
Predicted Store Stats
Our user guide has more information on working with data streams through the API.
Predicted store stats are identical to the Store Stats model, however, instead of being for what actually happened, they are the prediction of what will happen. All predicted store stats for a data stream should be totaled data for a time period equal to the data stream’s data_interval, ending at a predicted store stat’s time.

Only predicted store stats where the type parameter is equal to “sales” will be displayed on the weekly planner on the dashboard. You’re able to store a wide variety of stats in Workforce, and differentiate them using the type parameter, but be aware of this special case.

Predicted store stats can be read by a user, if that user is able to read the data stream that the store stat belongs to.
Only admins can create predicted store stats. They are able to do this for any data stream.

The api currently only supports POST and GET methods of Predicted Store Stats.

Predicted Store Stats for Datastream [/api/v2/predicted_storestats/for_datastream/{datastream_id}]
GETPredicted Store Stats for Datastream
This method requires the datastream scope (see Scopes for more information).
You will only be able to query up to 31 days using the from and to parameters.
Parameters
datastream_id: 26 (number) - The id of the data stream to lookup store stats for
from: 2016-03-01 (string) - The start date of the range to lookup store stats in
to: 2016-03-20 (string) - The id of the data stream to lookup store stats for
type: sales (optional, string) - The type of store stats to lookup (if not specified, all stats are returned)
200
OK
(application/json)
Attributes (array):
id: 3518 (required) (number) - The id of the stat
time: 1459295100 (required) (number) - The time of the stat
stat: 3.50 (required) (number) - The value of the stat
type: sales (required) (string) - The type of the stat
datastream_id: 24 (required) (number) - The id of the data stream join’s data stream
Predicted Store Stats for Location [/api/v2/predicted_storestats/for_location/{location_id}]
GETPredicted Store Stats for Location
This method requires the datastream scope (see Scopes for more information).
You will only be able to query up to 31 days using the from and to parameters.
Parameters
location_id: 26 (number) - The id of the location to lookup store stats for
from: 2016-03-01 (string) - The start date of the range to lookup store stats in.
to: 2016-03-20 (string) - The id of the data stream to lookup store stats for. We will crop the data to the nearest business day, eg if the location is open 8am -> midnight, then we will set the cuttoff time for the data to be 4am. Data before then will go to the previous business day, data after will come in for this business day.
200
OK
(application/json)
Attributes
data_stream: (GenericDatastreamData)
data_stream_joins: (array[DataStreamJoinData]),
stat_type: sales (string)
stats: (array[StoreStatData])
Predicted Store Stats for Multiple Datastreams [/api/v2/predicted_storestats/for_datastream]
POSTPredicted Store Stats for Multiple Datastreams
To post predicted store stats in bulk, simply represent them all in an array, with the datastream_id included for each stat. Note that each combination of datastream_id, time and type must be unique - you must not send duplicate data.

POSSIBLE DATA DELETION: All existing predicted store stats on the data stream within the newly posted store stats’ time parameter range will be replaced with the newly posted predicted store stats.
Please see the general Store Stat information above for an example.

{ "stats": [ { "datastream_id": 123456, "time": 1459296900, "stat": 7.5, "type": "sales" }, { "datastream_id": 123456, "time": 1459297800, "stat": 3, "type": "transactions" } { "datastream_id": 123457, "time": 1459296900, "stat": 3.5, "type": "sales" }, { "datastream_id": 123457, "time": 1459297800, "stat": 1, "type": "transactions" } ] }

Request Create single Predicted Store Stat (application/json)
Body

    {
      "datastream_id": 123457,
      "time": 1459296900,
      "stat": 3.5,
      "type": "sales"
    }

201
Created
(application/json)
Attributes:
id: 3518 (required) (number) - The id of the stat
time: 1459295100 (required) (number) - The time of the stat
stat: 3.50 (required) (number) - The value of the stat
type: sales (required) (string) - The type of the stat
datastream_id: 24 (required) (number) - The id of the data stream join’s data stream
+ id: 12231 (number)
+ datastream_id: 123457 (number),
+ time: 1459296900 (number)
+ stat: 3.5 (number)
+ type: sales (string)

Request Create multiple Store Stats (application/json)
Body

    {
      "stats": [
        {
          "datastream_id": 123456,
          "time": 1459296900,
          "stat": 7.5,
          "type": "sales"
        },
        {
          "datastream_id": 123456,
          "time": 1459296900,
          "stat": 3,
          "type": "transactions"
        },
        {
          "datastream_id": 123457,
          "time": 1459297800,
          "stat": 3.5,
          "type": "sales"
        },
        {
          "datastream_id": 123457,
          "time": 1459297800,
          "stat": 1,
          "type": "transactions"
        }
        }
      ]
    }

Response 201 (application/json) Attributes (array):

+ (object)
    + id: 12231 (number)
    + datastream_id: 123456 (number),
    + time: 1459296900 (number)
    + stat: 7.5 (number)
    + type: sales (string)
+ (object)
    + id: 12232 (number)
    + datastream_id: 123456 (number),
    + time: 1459296900 (number)
    + stat: 3 (number)
    + type: transactions (string)
+ (object)
    + id: 12233 (number)
    + datastream_id: 123457 (number),
    + time: 1459297800 (number)
    + stat: 3.5 (number)
    + type: sales (string)
+ (object)
    + id: 12234 (number)
    + datastream_id: 123457 (number),
    + time: 1459297800 (number)
    + stat: 1 (number)
    + type: transactions (string)

Delete Predicted Store Stats [/api/v2/predicted_storestats/for_datastream/{datastream_id}]
DELETEDelete Predicted Store Stats
This method requires the datastream scope (see Scopes for more information).
You will only be able to query up to 31 days using the from and to parameters.
Parameters
datastream_id: 26 (number) - The id of the datastream to lookup store stats for
from: 2016-03-01 (string) - The start date of the range to lookup store stats in.
to: 2016-03-20 (string) - The end of the date range of to lookup store stats in. We will crop the data to the nearest business day, eg if the location is open 8am -> midnight, then we will set the cuttoff time for the data to be 4am. Data before then will go to the previous business day, data after will come in for this business day.
200
OK
(application/json)
Attributes
stats: (array[PredictedStoreStatData])
Stat Types
Stat Types connect Data Streams to the object which owns the stream’s data. For example, data from a stream may be relate to a Team, Location, or to the Organisation itself.

Stat Type List [/api/v2/stat_types]
GETGet Stat Types
This method requires the datastream scope (see Scopes for more information).
200
OK
(application/json)
Attributes (array):
id: 162 (required) (number) - The id of the data stream join
stat_type: sales (required) (string) - The ket of the stat type, this much exactly match whats uploaded to StoreStats
label: Sales (required) (string) - The human readable name for this stat type
format: currency (string) - How this stat type is formatted
data_type: sum (string) - What kind of data this is (sum or static)
Stat Type [/api/v2/stat_types/{id}]
GETGet Stat Type
This method requires the datastream scope (see Scopes for more information).
Parameters
id: 162 (number) - The id of the stat type to lookup
200
OK
(application/json)
Attributes:
id: 162 (required) (number) - The id of the data stream join
stat_type: sales (required) (string) - The ket of the stat type, this much exactly match whats uploaded to StoreStats
label: Sales (required) (string) - The human readable name for this stat type
format: currency (string) - How this stat type is formatted
data_type: sum (string) - What kind of data this is (sum or static)
POSTCreate Stat Type
This method requires the datastream scope (see Scopes for more information).
Request Create Stat Type (application/json)
Body

    {
      "stat_type": "sales",
      "label": "Sales",
      "format": "currency",
      "data_type": "sum"
    }

200
OK
(application/json)
Attributes:
id: 162 (required) (number) - The id of the data stream join
stat_type: sales (required) (string) - The ket of the stat type, this much exactly match whats uploaded to StoreStats
label: Sales (required) (string) - The human readable name for this stat type
format: currency (string) - How this stat type is formatted
data_type: sum (string) - What kind of data this is (sum or static)
+ stat_type: sales (string)
+ label: Sales (string)
+ format: currency (string)
+ data_type: sum (string)

Request Create stat type with custom format (application/json)
Body

    {
      "stat_type": "deliveries",
      "label": "Deliveries",
      "format": "%{whole_number} 🚚",
      "data_type": "sum"
    }

200
OK
(application/json)
Body

        {
          "id": 162,
          "stat_type": "deliveries",
          "label": "Deliveries",
          "format": "%{whole_number} 🚚",
          "data_type": "sum"
        }

Request Create stat type for head counts (application/json)
Body

      {
        "stat_type": "required staff",
        "label": "Required Staff",
        "format": "people",
        "data_type": "static"
      }

200
OK
(application/json)
Body

        {
          "id": 162,
          "stat_type": "required staff",
          "label": "Required Staff",
          "format": "people",
          "data_type": "static"
        }

PUTUpdate Stat Type
This method requires the datastream scope (see Scopes for more information).
You cannot modify the stat_type field on a Stat Type. You must create a new stat type instead.

Parameters
id: 162 (number) - The id of the stat type to update
Request Update Stat Type (application/json)
Body

    {
      "format": "whole_number"
    }

200
OK
(application/json)
Attributes:
id: 162 (required) (number) - The id of the data stream join
stat_type: sales (required) (string) - The ket of the stat type, this much exactly match whats uploaded to StoreStats
label: Sales (required) (string) - The human readable name for this stat type
format: currency (string) - How this stat type is formatted
data_type: sum (string) - What kind of data this is (sum or static)
+ format: whole_number (string)

DELETEDelete Stat Type
This method requires the datastream scope (see Scopes for more information).
This will delete ALL store stats, and data stream joins that have been created with this stat type. Please be careful.

Parameters
id: 162 (number) - The id of the stat type to delete
200
OK
(application/json)
Wage Comparison
Wage Comparisons are used to compare the wage cost of employees under different rates of pay.

Wage Comparison List [/api/v2/wage_comparisons]
GETGet Wage Comparisons
This method requires the cost scope (see Scopes for more information).
200
OK
(application/json)
Attributes (array):
id: 34 (number, required) - The Wage Comparison ID
from_date: 2020-12-31 (string, required) - The date the Wage comparison Starts
to_date: 2021-11-29 (string, required) - the date the wage comparison Ends
award_template_organisation_id: 56 (number, optional) - The award template organisation id belonging to the desired award.
hourly_rate: 32.47 (number, optional) - The hourly rate of the user
salary: 1234.12 (number, optional) - The weekly salary of the user
award_tags: “Level 8,Full Time,First Aid Certificate” (string, optional) - a list of award tags that applies to the employee.
Wage Comparison [/api/v2/wage_comparisons/{id}]
GETGet Wage Comparison
This method requires the cost scope (see Scopes for more information).
Parameters
id: 162 (number) - The id of the wage comparison to lookup
200
OK
(application/json)
Attributes:
id: 34 (number, required) - The Wage Comparison ID
from_date: 2020-12-31 (string, required) - The date the Wage comparison Starts
to_date: 2021-11-29 (string, required) - the date the wage comparison Ends
award_template_organisation_id: 56 (number, optional) - The award template organisation id belonging to the desired award.
hourly_rate: 32.47 (number, optional) - The hourly rate of the user
salary: 1234.12 (number, optional) - The weekly salary of the user
award_tags: “Level 8,Full Time,First Aid Certificate” (string, optional) - a list of award tags that applies to the employee.
POSTCreate Wage Comparison
To post a wage comparison for an employee, include the user_id and from_date along with any required optional parameters. Note that from_date and to_date must not overlap for different wage comparisons for the same user.

This method requires the cost scope (see Scopes for more information).
Parameters
user_id: 1 (required, number) - The ID of the user being compared.
from_date: 2016-03-02 (required, string) - The date comparison starts from.
to_date: 2016-03-02 (optional, string) - The date the comparison goes to, will go forever and ever, if it’s left blank.
hourly_rate: 22.56 (optional, number) - The hourly rate of the comparison.
salary: 70592 (optional, number) - the salary of the comparison.
award_tags: ‘full time, meal break’ (optional, string) - A comma separated list of award tags that apply to the comparison.
award_template_organisation_id: 4 (optional, number) - the relevant award template organisation id.
Request Create Wage Comparison (application/json)
Body

    {
      "user_id": 123456,
      "from_date": "2016-03-12",
      "to_date": "2017-04-12",
      "hourly_rate": 22.36,
      "salary": 808,
      "award_tags": "full time, meal break",
      "award_template_organisation_id": 4
    }

201
Created
(application/json)
Attributes(WageComparisonData)
user_id: 123456
from_date: 2016-03-12
to_date: 2017-04-12
hourly_rate: 22.36
salary: 808
award_template_organisation_id: 4
award_tags: full time, meal break
Schema
Attributes:
id: 34 (number, required) - The Wage Comparison ID
from_date: 2020-12-31 (string, required) - The date the Wage comparison Starts
to_date: 2021-11-29 (string, required) - the date the wage comparison Ends
award_template_organisation_id: 56 (number, optional) - The award template organisation id belonging to the desired award.
hourly_rate: 32.47 (number, optional) - The hourly rate of the user
salary: 1234.12 (number, optional) - The weekly salary of the user
award_tags: “Level 8,Full Time,First Aid Certificate” (string, optional) - a list of award tags that applies to the employee.
id: (number)
PUTUpdate Wage Comparison
This method requires the cost scope (see Scopes for more information).
Parameters
id: 162 (required, number) - The id of the wage comparison to update
user_id: 1 (optional, number) - The ID of the user being compared.
from_date: 2016-03-02 (required, string) - The date comparison starts from.
to_date: 2016-03-02 (optional, string) - The date the comparison goes to, will go forever and ever, if it’s left blank.
hourly_rate: 22.56 (optional, number) - The hourly rate of the comparison.
salary: 70592 (optional, number) - the salary of the comparison.
award_tags: ‘full time, meal break’ (optional, string) - A comma separated list of award tags that apply to the comparison.
award_template_organisation_id: 4 (optional, number) - the relevant award template organisation id.
Request Update Wage Comparison (application/json)
Body

    {
      "user_id": 123456,
      "from_date": "2016-03-12",
      "to_date": "2017-04-12",
      "hourly_rate": 22.36,
      "salary": 808,
      "award_tags": "full time, meal break",
      "award_template_organisation_id": 4
    }

200
OK
(application/json)
Attributes(WageComparisonData)
user_id: 123456
from_date: 2016-03-12
to_date: 2017-04-12
hourly_rate: 22.36
salary: 808
award_template_organisation_id: 4
award_tags: full time, meal break
Schema
Attributes:
id: 34 (number, required) - The Wage Comparison ID
from_date: 2020-12-31 (string, required) - The date the Wage comparison Starts
to_date: 2021-11-29 (string, required) - the date the wage comparison Ends
award_template_organisation_id: 56 (number, optional) - The award template organisation id belonging to the desired award.
hourly_rate: 32.47 (number, optional) - The hourly rate of the user
salary: 1234.12 (number, optional) - The weekly salary of the user
award_tags: “Level 8,Full Time,First Aid Certificate” (string, optional) - a list of award tags that applies to the employee.
id: (number)
DELETEDelete Wage Comparison
This method requires the cost scope (see Scopes for more information).
Parameters
id: 162 (number) - The id of the wage comparison to delete
200
OK
(application/json)
Wage Comparison Outer Limits User Setting [/api/v2/wage_comparisons/{id}/outer_limits]
GETGet Wage Comparison Outer Limits User Setting
This method requires the cost scope (see Scopes for more information).
Parameters
id: 162 (number) - The ID of the wage comparison that has the outer limit user setting.
200
OK
(application/json)
Attributes(OuterLimitsUserSettingData)
Schema(OuterLimitsUserSettingData)
404
Not Found
(application/json)
Attributes
error: No known Wage Comparison with id 162
404
Not Found
(application/json)
Attributes
error: Wage comparison does not have any outer limits set
POSTCreate Wage Comparison Outer Limits User Setting
If a wage comparison does not have outer limits set, this endpoint creates them. If the wage comparison already has outer limits, an error will be returned.

The outer limit user setting that is created will also be returned in the response.

The request fields are as follows:

penalty_hours number: (required) Example: 6.
The outer limit of penalty hours.

overtime_hours number: (required) Example: 6.
The outer limit of overtime hours.

averaging_cadence string: (required) Example: pay_cycle.
The averaging cadence to use. Must be one of pay_cycle, overtime_averaging, or other.

custom_cycle_length string: (optional) Example: weekly.
If averaging_cadence is set to other, this value is required and is the cycle length that will be used. Otherwise, the value is ignored. Must be one of weekly, fortnightly, three_weekly, or four_weekly.

custom_anchor_date date: (optional) Example: 2022-01-24.
If averaging_cadence is set to other, this value is required and is used as the anchor for each cycle. For example, if the anchor date is set to Monday 24th January and the cycle length is weekly, the outer limit test period will be each Monday to the following Sunday.

This method requires the cost scope (see Scopes for more information).
Parameters
id: 162 (number) - The ID of the wage comparison that the outer limit setting will be created for.
Request (application/json)
Body

  {
      "penalty_hours": 6,
      "overtime_hours": 6,
      "averaging_cadence": "other",
      "custom_cycle_length": "weekly",
      "custom_anchor_date": "2022-01-24"
  }

200
OK
(application/json)
Attributes(OuterLimitsUserSettingData)
Schema(OuterLimitsUserSettingData)
409
Conflict
(application/json)
Attributes
error: Wage comparison already has outer limits set
404
Not Found
(application/json)
Attributes
error: No known Wage Comparison with id 162
PUTUpdate Wage Comparison Outer Limits User Setting
Updates an existing outer limits user setting with new data. This endpoint supports partial updates - you only need to specify the fields that you wish to update.

The full outer limits user setting will be returned in the response.

See Create Wage Comparison Outer Limits User Settings for more information about the request fields.

This method requires the cost scope (see Scopes for more information).
Parameters
id: 162 (number) - The ID of the wage comparison that the outer limit setting will be created for.
Request (application/json)
Body

  {
      "penalty_hours": 9
  }

200
OK
(application/json)
Attributes(OuterLimitsUserSettingData)
Schema(OuterLimitsUserSettingData)
404
Not Found
(application/json)
Attributes
error: No known Wage Comparison with id 162
404
Not Found
(application/json)
Attributes
error: Wage comparison does not have any outer limits set
DELETEDelete Wage Comparison Outer Limits User Setting
This endpoint deletes the outer limits settings for a wage comparison. If the deletion was successful, the response is empty.

This method requires the cost scope (see Scopes for more information).
Parameters
id: 162 (number) - The ID of the wage comparison that the outer limit setting will be created for.
Response 200 (application/json)

404
Not Found
(application/json)
Attributes
error: No known Wage Comparison with id 162
404
Not Found
(application/json)
Attributes
error: Wage comparison does not have any outer limits set
Recommended Hours
Recommended Hours refer to the optimal number of hours a roster should have dependent on Workforce’s congitive tool suite.

Recommended Hours [/api/v2/recommended_hours]
GETGet Recommended Hours
Get the recommended hours of work for a department, for a given date range. You need to provide all the listed paramters below (department_id, from_date, and to_date).

The endpoint recommends hours by date and dependent on your cognitive configurations for the department you are requesting. In cases where your business hours end after midnight, you can use the from_time and to_time parameters to specific a time range alongside the dates. The from_time will be used in conjunction with the from_date, to_time with the to_date.
This method requires the roster scope (see Scopes for more information).
Parameters
department_id: 1234 (required, number) - The ID of the department.
from_date: 2016-03-02 (required, string) - The starting date of the range.
to_date: 2016-03-02 (required, string) - The date the range will go to.
from_time: 06:00 (optional, string) - The starting time of the range.
to_time: 17:30 (optional, string) - The time the range will go to.
full_increments: true (optional, boolean) - This will show recommended hours by 15 minute increments.
in_minutes: 2016-03-02 (optional, boolean) - This will show recommended hours as minute values.
200
OK
(application/json)
Attributes:
department_id: 1234 (number, required) - The ID of the department
department_name: Delivery Team (string, required) - The name of the department
total_recommended_hours_for_date_range: 110.0 (string) - The total recommended hours for the date range
recommended_hours_by_date (object)
2016-04-01: 31.0 (number, required) - The number of hours for that date.
2016-04-02: 10.0 (number, required) - The number of hours for that date.
2016-04-03: 25.0 (number, required) - The number of hours for that date.
Rostered Days Off
Rostered Days Off (RDOs) represent planned days off for employees. They can be paid or unpaid and are used within rosters to streamline scheduling and ensure compliance with overtime rules.

Rostered Days Off are utilised for:

Quick building of rosters.
Automatic application of overtime rules where applicable.
To view or manage rostered days off, 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.
Rostered Days Off [/api/v2/rostered_days_off]
GETGet Rostered Days Off
Get rostered days off by roster ID, user ID, or by specific rostered day off IDs. At least one filter parameter is required. Multiple parameters can be used at once.

This method requires the roster scope (see Scopes for more information).
Parameters
roster_id: 123 (optional, integer) - ID of the roster
user_id: 456 (optional, integer) - ID of the user to filter rostered days off
ids: 1,2,3 (optional, string) - Comma-separated list of rostered day off IDs
page: 1 (optional, number) - The page number for your rostered days off list
page_size: 50 (optional, number) - The number of rostered days off retrieved per page. Maximum 100 per page.
200
OK
(application/json)
Attributes (array):
id: 123 (required) (number) - The ID of the rostered day off
user_id: 456 (number) - The ID of the user that the rostered day off belongs to
daily_schedule_id: 789 (number) - The ID of the daily schedule that the rostered day off belongs to
start: 1456902000 (number) - The start of the rostered day off in unix time
finish: 1456916400 (number) - The finish of the rostered day off in unix time
department_id: 111 (number) - The department (team) ID for the rostered day off
updated_at: 1519621685 (number) When the rostered day off record was last updated in unix time
POSTCreate Rostered Day Off
Create a new rostered day off for a user.

This method requires the roster scope (see Scopes for more information).
Request Create Rostered Day Off (application/json)
Body

    {
      "user_id": 456,
      "date": "2024-03-15",
      "start": 1710500400,
      "finish": 1710522000,
      "department_id": 789 (optional)
    }

200
OK
(application/json)
Body

    {
      "id": 101,
      "user_id": 456,
      "daily_schedule_id": 202,
      "start": 1710500400,
      "finish": 1710522000,
      "department_id": 789
    }

Schema

Attributes:
id: 123 (required) (number) - The ID of the rostered day off
user_id: 456 (number) - The ID of the user that the rostered day off belongs to
daily_schedule_id: 789 (number) - The ID of the daily schedule that the rostered day off belongs to
start: 1456902000 (number) - The start of the rostered day off in unix time
finish: 1456916400 (number) - The finish of the rostered day off in unix time
department_id: 111 (number) - The department (team) ID for the rostered day off
updated_at: 1519621685 (number) When the rostered day off record was last updated in unix time
id: (number)
Rostered Day Off [/api/v2/rostered_days_off/{id}]
GETGet Rostered Day Off
Get a specific rostered day off by ID.

This method requires the roster scope (see Scopes for more information).
Parameters
id: 101 (required, integer) - ID of the rostered day off
200
OK
(application/json)
Attributes:
id: 123 (required) (number) - The ID of the rostered day off
user_id: 456 (number) - The ID of the user that the rostered day off belongs to
daily_schedule_id: 789 (number) - The ID of the daily schedule that the rostered day off belongs to
start: 1456902000 (number) - The start of the rostered day off in unix time
finish: 1456916400 (number) - The finish of the rostered day off in unix time
department_id: 111 (number) - The department (team) ID for the rostered day off
updated_at: 1519621685 (number) When the rostered day off record was last updated in unix time
DELETEDelete Rostered Day Off
Delete a rostered day off by ID.

This method requires the roster scope (see Scopes for more information).
Parameters
id: 101 (required, integer) - ID of the rostered day off
200
OK
(application/json)
Sleepovers
Sleepovers represent periods where an employee is rostered for a sleepover shift, typically in care services. They are used within rosters alongside regular schedules and rostered days off.

Sleepovers are utilised for:

Quick building of rosters.
Automatic application of overtime rules where applicable.
To view or manage sleepovers, 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.
Sleepovers [/api/v2/sleepovers]
GETGet Sleepovers
Get sleepovers by roster ID, user ID, or by specific sleepover IDs. At least one filter parameter is required. Multiple parameters can be used at once.

This method requires the roster scope (see Scopes for more information).
Parameters
roster_id: 123 (optional, integer) - ID of the roster
user_id: 456 (optional, integer) - ID of the user to filter sleepovers
ids: 1,2,3 (optional, string) - Comma-separated list of sleepover IDs
page: 1 (optional, number) - The page number for your sleepovers list
page_size: 50 (optional, number) - The number of sleepovers retrieved per page. Maximum 100 per page.
200
OK
(application/json)
Attributes (array):
id: 123 (required) (number) - The ID of the sleepover
user_id: 456 (number) - The ID of the user that the sleepover belongs to
daily_schedule_id: 789 (number) - The ID of the daily schedule that the sleepover belongs to
start: 1456902000 (number) - The start of the sleepover in unix time
finish: 1456916400 (number) - The finish of the sleepover in unix time
department_id: 111 (number) - The department (team) ID for the sleepover
updated_at: 1519621685 (number) When the sleepover record was last updated in unix time
POSTCreate Sleepover
Create a new sleepover for a user.

This method requires the roster scope (see Scopes for more information).
Request Create Sleepover (application/json)
Body

    {
      "user_id": 456,
      "date": "2024-03-15",
      "start": 1710500400,
      "finish": 1710522000,
      "department_id": 789 (optional)
    }

200
OK
(application/json)
Body

    {
      "id": 101,
      "user_id": 456,
      "daily_schedule_id": 202,
      "start": 1710500400,
      "finish": 1710522000,
      "department_id": 789
    }

Schema

Attributes:
id: 123 (required) (number) - The ID of the sleepover
user_id: 456 (number) - The ID of the user that the sleepover belongs to
daily_schedule_id: 789 (number) - The ID of the daily schedule that the sleepover belongs to
start: 1456902000 (number) - The start of the sleepover in unix time
finish: 1456916400 (number) - The finish of the sleepover in unix time
department_id: 111 (number) - The department (team) ID for the sleepover
updated_at: 1519621685 (number) When the sleepover record was last updated in unix time
id: (number)
Sleepover [/api/v2/sleepovers/{id}]
GETGet Sleepover
Get a specific sleepover by ID.

This method requires the roster scope (see Scopes for more information).
Parameters
id: 101 (required, integer) - ID of the sleepover
200
OK
(application/json)
Attributes:
id: 123 (required) (number) - The ID of the sleepover
user_id: 456 (number) - The ID of the user that the sleepover belongs to
daily_schedule_id: 789 (number) - The ID of the daily schedule that the sleepover belongs to
start: 1456902000 (number) - The start of the sleepover in unix time
finish: 1456916400 (number) - The finish of the sleepover in unix time
department_id: 111 (number) - The department (team) ID for the sleepover
updated_at: 1519621685 (number) When the sleepover record was last updated in unix time
DELETEDelete Sleepover
Delete a sleepover by ID.

This method requires the roster scope (see Scopes for more information).
Parameters
id: 101 (required, integer) - ID of the sleepover
200
OK
(application/json)
On Calls
On calls represent periods where an employee is rostered to be on call. They are used within rosters alongside regular schedules and rostered days off.

On calls are utilised for:

Quick building of rosters.
Automatic application of overtime rules where applicable.
To view or manage on calls, 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.
On Calls [/api/v2/on_calls]
GETGet On Calls
Get on calls by roster ID, user ID, or by specific on call IDs. At least one filter parameter is required. Multiple parameters can be used at once.

This method requires the roster scope (see Scopes for more information).
Parameters
roster_id: 123 (optional, integer) - ID of the roster
user_id: 456 (optional, integer) - ID of the user to filter on calls
ids: 1,2,3 (optional, string) - Comma-separated list of on call IDs
page: 1 (optional, number) - The page number for your on calls list
page_size: 50 (optional, number) - The number of on calls retrieved per page. Maximum 100 per page.
200
OK
(application/json)
Attributes (array):
id: 123 (required) (number) - The ID of the on call
user_id: 456 (number) - The ID of the user that the on call belongs to
daily_schedule_id: 789 (number) - The ID of the daily schedule that the on call belongs to
start: 1456902000 (number) - The start of the on call in unix time
finish: 1456916400 (number) - The finish of the on call in unix time
department_id: 111 (number) - The department (team) ID for the on call
updated_at: 1519621685 (number) When the on call record was last updated in unix time
POSTCreate On Call
Create a new on call for a user.

This method requires the roster scope (see Scopes for more information).
Request Create On Call (application/json)
Body

    {
      "user_id": 456,
      "date": "2024-03-15",
      "start": 1710500400,
      "finish": 1710522000,
      "department_id": 789 (optional)
    }

200
OK
(application/json)
Body

    {
      "id": 101,
      "user_id": 456,
      "daily_schedule_id": 202,
      "start": 1710500400,
      "finish": 1710522000,
      "department_id": 789
    }

Schema

Attributes:
id: 123 (required) (number) - The ID of the on call
user_id: 456 (number) - The ID of the user that the on call belongs to
daily_schedule_id: 789 (number) - The ID of the daily schedule that the on call belongs to
start: 1456902000 (number) - The start of the on call in unix time
finish: 1456916400 (number) - The finish of the on call in unix time
department_id: 111 (number) - The department (team) ID for the on call
updated_at: 1519621685 (number) When the on call record was last updated in unix time

id: (number)
On Call [/api/v2/on_calls/{id}]
GETGet On Call
Get a specific on call by ID.

This method requires the roster scope (see Scopes for more information).
Parameters
id: 101 (required, integer) - ID of the on call
200
OK
(application/json)
Attributes:
id: 123 (required) (number) - The ID of the on call
user_id: 456 (number) - The ID of the user that the on call belongs to
daily_schedule_id: 789 (number) - The ID of the daily schedule that the on call belongs to
start: 1456902000 (number) - The start of the on call in unix time
finish: 1456916400 (number) - The finish of the on call in unix time
department_id: 111 (number) - The department (team) ID for the on call
updated_at: 1519621685 (number) When the on call record was last updated in unix time
DELETEDelete On Call
Delete an on call by ID.

This method requires the roster scope (see Scopes for more information).
Parameters
id: 101 (required, integer) - ID of the on call
200
OK
(application/json)
Payroll Payslips
Payslips contain information about an employee’s earnings for a specific pay period. They include details about gross pay, tax, deductions, superannuation, and net pay.

Payslips [/api/v2/payroll/payslips]
GETGet Payslips
Get all payslips for the current organisation. Results are paginated and sorted by pay run start date (newest first), then by payslip ID for consistent ordering within the same pay run.

Request
Headers Authorization: Bearer {access_token}
Parameters
page: 1 (number, optional) - The page of results to return
page_size: 100 (number, optional) - The number of results per page (max 100)
pay_run_id: 456 (number, optional) - Filter payslips by pay run ID. When provided, only payslips belonging to the specified pay run will be returned.
200
OK
(application/json)
Schema
Attributes (array):
id: 123 (number, required) - The ID of the payslip
pay_run_id: 456 (number, required) - The ID of the pay run this payslip belongs to
user_id: 789 (number, required) - The ID of the user this payslip is for
from_date: 2023-01-01 (string, required) - The start date of the pay period
to_date: 2023-01-15 (string, required) - The end date of the pay period
payment_date: 2023-01-20 (string, required) - The date when payment will be made
gross_pay: 1500.00 (number, required) - The total gross pay amount
tax: 300.00 (number, required) - The total tax amount
deductions: 100.00 (number, required) - The total deductions amount
super: 142.50 (number, required) - The total superannuation amount
net_pay: 1100.00 (number, required) - The net pay amount (after tax and deductions)
email_sent: true (boolean, required) - Whether the payslip has been emailed to the employee
kiwi_saver: 90.00 (number) - NZ only. The total KiwiSaver amount (employee deduction plus employer contribution)
employee_kiwi_saver_deduction: 45.00 (number) - NZ only. The total KiwiSaver amount deducted from the employee
employer_kiwi_saver_contribution: 45.00 (number) - NZ only. The total KiwiSaver amount contributed by the employer
Get Specific Payslip [GET /api/v2/payroll/payslips/{id}]
Get a specific payslip by ID.

Parameters
id: 123 (number, required) - The ID of the payslip
Request
Headers Authorization: Bearer {access_token}
200
OK
(application/json)
Schema
Attributes:
id: 123 (number, required) - The ID of the payslip
pay_run_id: 456 (number, required) - The ID of the pay run this payslip belongs to
user_id: 789 (number, required) - The ID of the user this payslip is for
from_date: 2023-01-01 (string, required) - The start date of the pay period
to_date: 2023-01-15 (string, required) - The end date of the pay period
payment_date: 2023-01-20 (string, required) - The date when payment will be made
gross_pay: 1500.00 (number, required) - The total gross pay amount
tax: 300.00 (number, required) - The total tax amount
deductions: 100.00 (number, required) - The total deductions amount
super: 142.50 (number, required) - The total superannuation amount
net_pay: 1100.00 (number, required) - The net pay amount (after tax and deductions)
email_sent: true (boolean, required) - Whether the payslip has been emailed to the employee
kiwi_saver: 90.00 (number) - NZ only. The total KiwiSaver amount (employee deduction plus employer contribution)
employee_kiwi_saver_deduction: 45.00 (number) - NZ only. The total KiwiSaver amount deducted from the employee
employer_kiwi_saver_contribution: 45.00 (number) - NZ only. The total KiwiSaver amount contributed by the employer
404
Not Found
(application/json)
Body { “error”: “Payslip not found!” }
Get Payslips For User [GET /api/v2/payroll/payslips/for/{user_id}]
Get all payslips for a specific user.

Parameters
user_id: 456 (number, required) - The ID of the user
Request
Headers Authorization: Bearer {access_token}
200
OK
(application/json)
Schema
Attributes (array):
id: 123 (number, required) - The ID of the payslip
pay_run_id: 456 (number, required) - The ID of the pay run this payslip belongs to
user_id: 789 (number, required) - The ID of the user this payslip is for
from_date: 2023-01-01 (string, required) - The start date of the pay period
to_date: 2023-01-15 (string, required) - The end date of the pay period
payment_date: 2023-01-20 (string, required) - The date when payment will be made
gross_pay: 1500.00 (number, required) - The total gross pay amount
tax: 300.00 (number, required) - The total tax amount
deductions: 100.00 (number, required) - The total deductions amount
super: 142.50 (number, required) - The total superannuation amount
net_pay: 1100.00 (number, required) - The net pay amount (after tax and deductions)
email_sent: true (boolean, required) - Whether the payslip has been emailed to the employee
kiwi_saver: 90.00 (number) - NZ only. The total KiwiSaver amount (employee deduction plus employer contribution)
employee_kiwi_saver_deduction: 45.00 (number) - NZ only. The total KiwiSaver amount deducted from the employee
employer_kiwi_saver_contribution: 45.00 (number) - NZ only. The total KiwiSaver amount contributed by the employer
404
Not Found
(application/json)
Body { “error”: “Employee not found!” }
Payroll Deduction Types
Deduction types define categories of deductions that can be applied to employee pay. They include information about tax reduction effects and payment details.

Deduction Types [/api/v2/payroll/deduction_types]
GETGet Deduction Types
Get all deduction types for the current organisation.

Request
Headers Authorization: Bearer {access_token}
200
OK
(application/json)
Schema
Attributes (array):
id: 123 (number, required) - The ID of the deduction type
name: Health Insurance (string, required) - The name of the deduction type
stp_category: H (string) - The STP reporting category code
reduces_tax: true (boolean, required) - Whether this deduction reduces taxable income
reduces_workcover: false (boolean, required) - Whether this deduction reduces workcover calculations
reduces_payroll_tax: false (boolean, required) - Whether this deduction reduces payroll tax calculations
payroll_account_id: 456 (number, required) - The ID of the payroll account this deduction is linked to
bank_detail (object) - Bank account details for the deduction
bsb: 123456 (string) - BSB number
account_name: Health Insurance Ltd (string) - Account name
account_number: 12345678 (string) - Account number
Get Specific Deduction Type [GET /api/v2/payroll/deduction_types/{id}]
Get a specific deduction type by ID.

Parameters
id: 123 (number, required) - The ID of the deduction type
Request
Headers Authorization: Bearer {access_token}
200
OK
(application/json)
Schema
Attributes:
id: 123 (number, required) - The ID of the deduction type
name: Health Insurance (string, required) - The name of the deduction type
stp_category: H (string) - The STP reporting category code
reduces_tax: true (boolean, required) - Whether this deduction reduces taxable income
reduces_workcover: false (boolean, required) - Whether this deduction reduces workcover calculations
reduces_payroll_tax: false (boolean, required) - Whether this deduction reduces payroll tax calculations
payroll_account_id: 456 (number, required) - The ID of the payroll account this deduction is linked to
bank_detail (object) - Bank account details for the deduction
bsb: 123456 (string) - BSB number
account_name: Health Insurance Ltd (string) - Account name
account_number: 12345678 (string) - Account number
404
Not Found
(application/json)
Body { “error”: “Deduction Type not found!” }
POSTCreate Deduction Type
Create a new deduction type for the organisation.

Request (application/json)
Headers Authorization: Bearer {access_token}

Body { “name”: “Salary Sacrifice”, “stp_category”: “O”, “reduces_tax”: true, “reduces_workcover”: false, “reduces_payroll_tax”: false, “payroll_account_id”: 123, “bank_detail”: { “bsb”: “123456”, “account_name”: “Salary Sacrifice Ltd”, “account_number”: “12345678” } }

200
OK
(application/json)
Schema
Attributes:
id: 123 (number, required) - The ID of the deduction type
name: Health Insurance (string, required) - The name of the deduction type
stp_category: H (string) - The STP reporting category code
reduces_tax: true (boolean, required) - Whether this deduction reduces taxable income
reduces_workcover: false (boolean, required) - Whether this deduction reduces workcover calculations
reduces_payroll_tax: false (boolean, required) - Whether this deduction reduces payroll tax calculations
payroll_account_id: 456 (number, required) - The ID of the payroll account this deduction is linked to
bank_detail (object) - Bank account details for the deduction
bsb: 123456 (string) - BSB number
account_name: Health Insurance Ltd (string) - Account name
account_number: 12345678 (string) - Account number
400
Bad Request
(application/json)
Body { “error”: “Payroll Account ID is required!” }
Update Deduction Type [PUT /api/v2/payroll/deduction_types/{id}]
Update an existing deduction type.

Parameters
id: 123 (number, required) - The ID of the deduction type
Request (application/json)
Headers Authorization: Bearer {access_token}

Body { “name”: “Updated Salary Sacrifice”, “reduces_tax”: false, “bank_detail”: { “bsb”: “654321”, “account_name”: “New Salary Sacrifice Ltd”, “account_number”: “87654321” } }

200
OK
(application/json)
Schema
Attributes:
id: 123 (number, required) - The ID of the deduction type
name: Health Insurance (string, required) - The name of the deduction type
stp_category: H (string) - The STP reporting category code
reduces_tax: true (boolean, required) - Whether this deduction reduces taxable income
reduces_workcover: false (boolean, required) - Whether this deduction reduces workcover calculations
reduces_payroll_tax: false (boolean, required) - Whether this deduction reduces payroll tax calculations
payroll_account_id: 456 (number, required) - The ID of the payroll account this deduction is linked to
bank_detail (object) - Bank account details for the deduction
bsb: 123456 (string) - BSB number
account_name: Health Insurance Ltd (string) - Account name
account_number: 12345678 (string) - Account number
404
Not Found
(application/json)
Body { “error”: “Deduction Type not found!” }
Delete Deduction Type [DELETE /api/v2/payroll/deduction_types/{id}]
Delete a deduction type.

Parameters
id: 123 (number, required) - The ID of the deduction type
Request
Headers Authorization: Bearer {access_token}
Response 200 (application/json)

404
Not Found
(application/json)
Body { “error”: “Deduction Type not found!” }
Payroll Accounts
Payroll accounts are used to track different types of financial transactions related to payroll, such as expense accounts and liability accounts.

Accounts [/api/v2/payroll/accounts]
GETGet Accounts
Get all payroll accounts for the current organisation.

Request
Headers Authorization: Bearer {access_token}
200
OK
(application/json)
Body [ { “id”: 123, “name”: “Wages Expense”, “code”: “6000”, “payroll_super_expense_account_id”: 456 }, { “id”: 456, “name”: “Superannuation Expense”, “code”: “6100”, “payroll_super_expense_account_id”: null } ]
Payroll Department Tracking Categories
Department tracking categories link departments (teams) to payroll tracking categories, allowing you to assign specific values to each department for payroll reporting.

Department Tracking Categories [/api/v2/payroll/department_tracking_categories]
GETGet Department Tracking Categories
Get all department tracking categories for the current organisation.

Request
Headers Authorization: Bearer {access_token}
200
OK
(application/json)
Schema
Attributes (array):
id: 34 (number, required) - The department tracking category’s ID
department_id: 44 (number, required) - The department’s ID
payroll_tracking_categories_id: (number, required) - The tracking category’s ID
value: Management (string, required) - The text field shared by the department and the tracking category
POSTCreate Department Tracking Category
Create a new department tracking category.

Request (application/json)
Headers Authorization: Bearer {access_token}

Body { “payroll_tracking_categories_id”: 123, “department_id”: 456, “value”: “Management” }

200
OK
(application/json)
Schema
Attributes:
id: 34 (number, required) - The department tracking category’s ID
department_id: 44 (number, required) - The department’s ID
payroll_tracking_categories_id: (number, required) - The tracking category’s ID
value: Management (string, required) - The text field shared by the department and the tracking category
404
Not Found
(application/json)
Body { “error”: “Tracking category not found!” }
Update Department Tracking Category [PUT /api/v2/payroll/department_tracking_categories/{id}]
Update an existing department tracking category.

Parameters
id: 123 (number, required) - The ID of the department tracking category
Request (application/json)
Headers Authorization: Bearer {access_token}

Body { “value”: “Administration” }

200
OK
(application/json)
Schema
Attributes:
id: 34 (number, required) - The department tracking category’s ID
department_id: 44 (number, required) - The department’s ID
payroll_tracking_categories_id: (number, required) - The tracking category’s ID
value: Management (string, required) - The text field shared by the department and the tracking category
404
Not Found
(application/json)
Body { “error”: “Department tracking category not found!” }
Delete Department Tracking Category [DELETE /api/v2/payroll/department_tracking_categories/{id}]
Delete a department tracking category.

Parameters
id: 123 (number, required) - The ID of the department tracking category
Request
Headers Authorization: Bearer {access_token}
Response 200 (application/json)

404
Not Found
(application/json)
Body { “error”: “Department tracking category not found!” }
Payroll Pay Runs
Pay runs represent a complete payroll processing cycle. They include information about the pay period, payment date, and current status.

Pay Runs [/api/v2/payroll/pay_runs]
GETGet Pay Runs
Get all pay runs for the current organisation, with optional filtering by date range, status, or pay group.

Parameters
from: 2023-01-01 (date, optional) - Start date for filtering pay runs
to: 2023-01-31 (date, optional) - End date for filtering pay runs. Must be provided if from is provided
status: open (string, optional) - Filter by pay run status
pay_group_id: 123 (number, optional) - Filter by pay group ID
Request
Headers Authorization: Bearer {access_token}
200
OK
(application/json)
Body [ { “id”: 123, “company_file_name”: “My Company”, “company_file_id”: 789, “pay_group_id”: 456, “start_date”: “2023-01-01”, “finish_date”: “2023-01-15”, “payment_date”: “2023-01-20”, “status”: “open” }, { “id”: 124, “company_file_name”: “My Company”, “company_file_id”: 789, “pay_group_id”: 456, “start_date”: “2023-01-16”, “finish_date”: “2023-01-31”, “payment_date”: “2023-02-05”, “status”: “draft” } ]
Pay Run [/api/v2/payroll/pay_runs/{id}]
GETGet Pay Run
Get a specific pay run by ID.

Parameters
id: 123 (number, required) - Pay run ID
Request
Headers Authorization: Bearer {access_token}
200
OK
(application/json)
Body { “id”: 123, “company_file_name”: “My Company”, “company_file_id”: 789, “pay_group_id”: 456, “start_date”: “2023-01-01”, “finish_date”: “2023-01-15”, “payment_date”: “2023-01-20”, “status”: “open” }
404
Not Found
(application/json)
Body { “error”: “Pay run not found!” }
Pay Run Journal [/api/v2/payroll/pay_runs/{id}/journal]
GETGet Pay Run Journal
Get the accounting journal entries for a specific pay run. The journal includes all debit and credit lines that would be posted to your accounting system for this pay run.

Parameters
id: 123 (number, required) - Pay run ID
Request
Headers Authorization: Bearer {access_token}
200
OK
(application/json)
Body { “id”: 123, “company_file_name”: “My Company”, “company_file_id”: 789, “pay_group_id”: 456, “start_date”: “2023-01-01”, “finish_date”: “2023-01-15”, “payment_date”: “2023-01-20”, “status”: “open”, “debit_lines”: [ { “account”: { “id”: 1001, “name”: “Wages Expense”, “code”: “WAG-01” }, “amount”: “2500.00”, “tracking_categories”: [“Sydney”, “Manager”], “narration”: “” }, { “account”: { “id”: 1002, “name”: “Overtime”, “code”: “WAG-02” }, “amount”: “375.00”, “tracking_categories”: [“Sydney”, “Manager”], “narration”: “” }, { “account”: { “id”: 1003, “name”: “Superannuation”, “code”: “SUP-01” }, “amount”: “287.50”, “tracking_categories”: [“Sydney”, “Manager”], “narration”: “” } ], “credit_lines”: [ { “account”: { “id”: 2001, “name”: “Wages Payable”, “code”: “LIB-01” }, “amount”: “2300.00”, “tracking_categories”: [””, “”], “narration”: “” }, { “account”: { “id”: 2002, “name”: “Withholding Payable”, “code”: “LIB-02” }, “amount”: “575.00”, “tracking_categories”: [””, “”], “narration”: “” }, { “account”: { “id”: 2003, “name”: “Super Payable”, “code”: “LIB-03” }, “amount”: “287.50”, “tracking_categories”: [””, “”], “narration”: “” } ] }
404
Not Found
(application/json)
Body { “error”: “Pay run not found!” }
Journal Response Fields
id: The ID of the pay run
company_file_name: The name of the payroll company file
company_file_id: The ID of the payroll company file
pay_group_id: The ID of the pay group
start_date: Start date of the pay period
finish_date: End date of the pay period
payment_date: The date when payment will be made
status: The current status of the pay run
debit_lines: Array of journal entries that represent debits (expenses and assets)
credit_lines: Array of journal entries that represent credits (liabilities and income)
Each journal line includes:

account: Object containing account details
id: The ID of the payroll account
name: Name of the payroll account
code: Code/reference for the account
amount: Monetary amount in dollars, as a string
tracking_categories: Array of tracking category values (empty strings if no tracking categories are configured)
narration: Additional description or notes for the journal entry
Pay Run Payslips [/api/v2/payroll/pay_runs/{id}/payslips]
GETGet Payslips for Pay Run
Get all payslips belonging to a specific pay run. Results are paginated and sorted by payslip ID for consistent ordering.

Parameters
id: 123 (number, required) - Pay run ID
page: 1 (number, optional) - The page of results to return
page_size: 100 (number, optional) - The number of results per page (max 100)
Request
Headers Authorization: Bearer {access_token}
200
OK
(application/json)
Schema
Attributes (array):
id: 123 (number, required) - The ID of the payslip
pay_run_id: 456 (number, required) - The ID of the pay run this payslip belongs to
user_id: 789 (number, required) - The ID of the user this payslip is for
from_date: 2023-01-01 (string, required) - The start date of the pay period
to_date: 2023-01-15 (string, required) - The end date of the pay period
payment_date: 2023-01-20 (string, required) - The date when payment will be made
gross_pay: 1500.00 (number, required) - The total gross pay amount
tax: 300.00 (number, required) - The total tax amount
deductions: 100.00 (number, required) - The total deductions amount
super: 142.50 (number, required) - The total superannuation amount
net_pay: 1100.00 (number, required) - The net pay amount (after tax and deductions)
email_sent: true (boolean, required) - Whether the payslip has been emailed to the employee
kiwi_saver: 90.00 (number) - NZ only. The total KiwiSaver amount (employee deduction plus employer contribution)
employee_kiwi_saver_deduction: 45.00 (number) - NZ only. The total KiwiSaver amount deducted from the employee
employer_kiwi_saver_contribution: 45.00 (number) - NZ only. The total KiwiSaver amount contributed by the employer
404
Not Found
(application/json)
Body { “error”: “Pay run not found!” }
Payroll Tracking Categories
Tracking categories are used in payroll systems to categorize expenses and income for reporting purposes. They can be linked to departments via department tracking categories.

Tracking Categories [/api/v2/payroll/tracking_categories]
GETGet Tracking Categories
Get all tracking categories for the current organisation.

Request
Headers Authorization: Bearer {access_token}
200
OK
(application/json)
Schema
Attributes (array):
id: 34 (number, required) - The tracking category’s ID
payroll_integration_id: 29 (number, required) - The associated payroll integration ID
name: Cost Centre (string, required) - The name of the tracking category
Announcements
Announcements are messages posted to announcement rooms within your organisation. Use these endpoints to manage announcements and announcement rooms.

Announcement List [/api/v2/announcements]
GETGet Announcements
This method requires the communication scope (see Scopes for more information).
Parameters
communication_room_id: 456 (number, optional) - Filter by announcement room ID
updated_after: 1451606400 (number, optional) - Only return announcements updated after this unix timestamp
page: 1 (number, optional) - Page number for pagination
page_size: 25 (number, optional) - Number of results per page (1-100)
200
OK
(application/json)
Attributes (array):
id: 789 (number, required) - The announcement message ID
title: Office Closure (string, required) - The title of the announcement
content: The office will be closed on Friday for maintenance. (string, optional) - The plain text body content of the announcement
rich_content: <div>The office will be closed on <strong>Friday</strong> for maintenance.</div> (string, optional) - The rich text HTML content of the announcement
sender_id: 123456 (number, required) - The ID of the user who posted the announcement
communication_room_id: 456 (number, required) - The ID of the announcement room
communication_room_name: Company Announcements (string, required) - The name of the announcement room
created_at: 1456902000 (number, required) - When the announcement was created (unix timestamp)
POSTCreate Announcement
This method requires the communication scope (see Scopes for more information).
Request (application/json)
Body

    {
      "communication_room_id": 456,
      "title": "Office Closure",
      "content": "The office will be closed on Friday for maintenance.",
      "sender_id": 123456,
      "created_at": 1456902000,
      "notify": false
    }

201
Created
(application/json)
Attributes:
id: 789 (number, required) - The announcement message ID
title: Office Closure (string, required) - The title of the announcement
content: The office will be closed on Friday for maintenance. (string, optional) - The plain text body content of the announcement
rich_content: <div>The office will be closed on <strong>Friday</strong> for maintenance.</div> (string, optional) - The rich text HTML content of the announcement
sender_id: 123456 (number, required) - The ID of the user who posted the announcement
communication_room_id: 456 (number, required) - The ID of the announcement room
communication_room_name: Company Announcements (string, required) - The name of the announcement room
created_at: 1456902000 (number, required) - When the announcement was created (unix timestamp)
Announcement [/api/v2/announcements/{id}]
GETGet Announcement
This method requires the communication scope (see Scopes for more information).
Parameters
id: 789 (number) - The ID of the announcement
200
OK
(application/json)
Attributes:
id: 789 (number, required) - The announcement message ID
title: Office Closure (string, required) - The title of the announcement
content: The office will be closed on Friday for maintenance. (string, optional) - The plain text body content of the announcement
rich_content: <div>The office will be closed on <strong>Friday</strong> for maintenance.</div> (string, optional) - The rich text HTML content of the announcement
sender_id: 123456 (number, required) - The ID of the user who posted the announcement
communication_room_id: 456 (number, required) - The ID of the announcement room
communication_room_name: Company Announcements (string, required) - The name of the announcement room
created_at: 1456902000 (number, required) - When the announcement was created (unix timestamp)
Announcement Room List [/api/v2/announcement_rooms]
GETGet Announcement Rooms
Returns all announcement rooms accessible to the authenticated user.

This method requires the communication scope (see Scopes for more information).
Parameters
updated_after: 1451606400 (number, optional) - Only return rooms updated after this unix timestamp
page: 1 (number, optional) - Page number for pagination
page_size: 25 (number, optional) - Number of results per page (1-100)
200
OK
(application/json)
Attributes (array):
id: 456 (number, required) - The announcement room ID
name: Warehouse Announcements (string, required) - The name of the announcement room
organisation_id: 23100 (number, required) - The ID of the organisation the room belongs to
team_ids: 123, 456 (array[number], required) - Team IDs the room is assigned to
location_ids: 78, 90 (array[number], required) - Location IDs the room is assigned to
archived: false (boolean, required) - Whether the room has been archived
created_at: 1456902000 (number, required) - When the room was created (unix timestamp)
updated_at: 1456902000 (number, required) - When the room was last updated (unix timestamp)
POSTCreate Announcement Room
Creates a new announcement room for the authenticated user’s organisation. Specify either team_ids or location_ids (not both) to define which teams or locations the room is visible to.

The caller must have permission to create announcement rooms in their organisation.

This method requires the communication scope (see Scopes for more information).
Request (application/json)
Body

    {
      "name": "Warehouse Announcements",
      "team_ids": [123, 456]
    }

201
Created
(application/json)
Attributes:
id: 456 (number, required) - The announcement room ID
name: Warehouse Announcements (string, required) - The name of the announcement room
organisation_id: 23100 (number, required) - The ID of the organisation the room belongs to
team_ids: 123, 456 (array[number], required) - Team IDs the room is assigned to
location_ids: 78, 90 (array[number], required) - Location IDs the room is assigned to
archived: false (boolean, required) - Whether the room has been archived
created_at: 1456902000 (number, required) - When the room was created (unix timestamp)
updated_at: 1456902000 (number, required) - When the room was last updated (unix timestamp)
Announcement Room [/api/v2/announcement_rooms/{id}]
GETGet Announcement Room
Returns a single announcement room by ID.

This method requires the communication scope (see Scopes for more information).
Parameters
id: 456 (number) - The ID of the announcement room
200
OK
(application/json)
Attributes:
id: 456 (number, required) - The announcement room ID
name: Warehouse Announcements (string, required) - The name of the announcement room
organisation_id: 23100 (number, required) - The ID of the organisation the room belongs to
team_ids: 123, 456 (array[number], required) - Team IDs the room is assigned to
location_ids: 78, 90 (array[number], required) - Location IDs the room is assigned to
archived: false (boolean, required) - Whether the room has been archived
created_at: 1456902000 (number, required) - When the room was created (unix timestamp)
updated_at: 1456902000 (number, required) - When the room was last updated (unix timestamp)
PUTUpdate Announcement Room
Updates an existing announcement room. Specify either team_ids or location_ids (not both) to redefine which teams or locations the room is visible to. Cannot update archived or organisation-wide rooms.

This method requires the communication scope (see Scopes for more information).
Parameters
id: 456 (number) - The ID of the announcement room
Request (application/json)
Body

    {
      "name": "Updated Warehouse Announcements",
      "team_ids": [123, 789]
    }

200
OK
(application/json)
Attributes:
id: 456 (number, required) - The announcement room ID
name: Warehouse Announcements (string, required) - The name of the announcement room
organisation_id: 23100 (number, required) - The ID of the organisation the room belongs to
team_ids: 123, 456 (array[number], required) - Team IDs the room is assigned to
location_ids: 78, 90 (array[number], required) - Location IDs the room is assigned to
archived: false (boolean, required) - Whether the room has been archived
created_at: 1456902000 (number, required) - When the room was created (unix timestamp)
updated_at: 1456902000 (number, required) - When the room was last updated (unix timestamp)
Payroll Deduction Templates
Deduction templates define specific deductions that apply to individual employees. They can be fixed amounts or percentage-based deductions.

Deduction Templates [/api/v2/payroll/deduction_templates]
GETGet Deduction Templates
Get all deduction templates for the current organisation.

Request
Headers Authorization: Bearer {access_token}
200
OK
(application/json)
Schema
Attributes (array):
id: 123 (number, required) - The ID of the deduction template
user_id: 456 (number, required) - The ID of the user this deduction template applies to
payroll_deduction_type_id: 789 (number, required) - The ID of the deduction type
fixed_amount: 100.50 (number) - The fixed amount to deduct (mutually exclusive with percent_of_income)
percent_of_income: 5.0 (number) - The percentage of income to deduct (mutually exclusive with fixed_amount)
include_in_aba: true (boolean) - Whether to include this deduction in ABA files
aba_reference: REF123 (string) - Reference number for ABA files
Get Specific Deduction Template [GET /api/v2/payroll/deduction_templates/{id}]
Get a specific deduction template by ID.

Parameters
id: 123 (number, required) - The ID of the deduction template
Request
Headers Authorization: Bearer {access_token}
200
OK
(application/json)
Schema
Attributes:
id: 123 (number, required) - The ID of the deduction template
user_id: 456 (number, required) - The ID of the user this deduction template applies to
payroll_deduction_type_id: 789 (number, required) - The ID of the deduction type
fixed_amount: 100.50 (number) - The fixed amount to deduct (mutually exclusive with percent_of_income)
percent_of_income: 5.0 (number) - The percentage of income to deduct (mutually exclusive with fixed_amount)
include_in_aba: true (boolean) - Whether to include this deduction in ABA files
aba_reference: REF123 (string) - Reference number for ABA files
404
Not Found
(application/json)
Body { “error”: “Deduction Template not found!” }
Get Deduction Templates For User [GET /api/v2/payroll/deduction_templates/for/{user_id}]
Get all deduction templates for a specific user.

Parameters
user_id: 456 (number, required) - The ID of the user
Request
Headers Authorization: Bearer {access_token}
200
OK
(application/json)
Schema
Attributes (array):
id: 123 (number, required) - The ID of the deduction template
user_id: 456 (number, required) - The ID of the user this deduction template applies to
payroll_deduction_type_id: 789 (number, required) - The ID of the deduction type
fixed_amount: 100.50 (number) - The fixed amount to deduct (mutually exclusive with percent_of_income)
percent_of_income: 5.0 (number) - The percentage of income to deduct (mutually exclusive with fixed_amount)
include_in_aba: true (boolean) - Whether to include this deduction in ABA files
aba_reference: REF123 (string) - Reference number for ABA files
404
Not Found
(application/json)
Body { “error”: “Employee not found!” }
POSTCreate Deduction Template
Create a new deduction template.

Request (application/json)
Headers Authorization: Bearer {access_token}

Body { “user_id”: 456, “payroll_deduction_type_id”: 789, “fixed_amount”: 100.50, “include_in_aba”: true, “aba_reference”: “REF123” }

200
OK
(application/json)
Schema
Attributes:
id: 123 (number, required) - The ID of the deduction template
user_id: 456 (number, required) - The ID of the user this deduction template applies to
payroll_deduction_type_id: 789 (number, required) - The ID of the deduction type
fixed_amount: 100.50 (number) - The fixed amount to deduct (mutually exclusive with percent_of_income)
percent_of_income: 5.0 (number) - The percentage of income to deduct (mutually exclusive with fixed_amount)
include_in_aba: true (boolean) - Whether to include this deduction in ABA files
aba_reference: REF123 (string) - Reference number for ABA files
400
Bad Request
(application/json)
Body { “error”: “Deduction Template can only have fixed_amount OR percent_of_income set!” }
404
Not Found
(application/json)
Body { “error”: “Employee for deduction template not found!” }
Update Deduction Template [PUT /api/v2/payroll/deduction_templates/{id}]
Update an existing deduction template.

Parameters
id: 123 (number, required) - The ID of the deduction template
Request (application/json)
Headers Authorization: Bearer {access_token}

Body { “user_id”: 456, “payroll_deduction_type_id”: 789, “percent_of_income”: 5.0, “fixed_amount”: null, “include_in_aba”: false, “aba_reference”: null }

200
OK
(application/json)
Schema
Attributes:
id: 123 (number, required) - The ID of the deduction template
user_id: 456 (number, required) - The ID of the user this deduction template applies to
payroll_deduction_type_id: 789 (number, required) - The ID of the deduction type
fixed_amount: 100.50 (number) - The fixed amount to deduct (mutually exclusive with percent_of_income)
percent_of_income: 5.0 (number) - The percentage of income to deduct (mutually exclusive with fixed_amount)
include_in_aba: true (boolean) - Whether to include this deduction in ABA files
aba_reference: REF123 (string) - Reference number for ABA files
404
Not Found
(application/json)
Body { “error”: “Deduction Template not found!” }
Delete Deduction Template [DELETE /api/v2/payroll/deduction_templates/{id}]
Delete a deduction template.

Parameters
id: 123 (number, required) - The ID of the deduction template
Request
Headers Authorization: Bearer {access_token}
Response 200 (application/json)

404
Not Found
(application/json)
Body { “error”: “Deduction Template not found!” }
Hire
The Workforce Hire endpoints allow you to manage job postings, applications, candidate data, and hiring workflows.

All Workforce Hire endpoints require users to have appropriate Workforce Hire permissions. The specific permission requirements are noted for each endpoint.
Jobs [/api/v2/ats/jobs]
GETGet Jobs
Gets information about all accessible job postings.

This method requires the ats scope and read permissions for jobs.
Parameters
status: status (optional, string) - Filter by application acceptance status. Options: accepting, not_accepting
visibility: public (optional, string) - Filter by job visibility. Options: public, internal
updated_after: 1451570400 (optional, number) - Time filter to find recently modified jobs
page: 1 (optional, number) - The page number for pagination
page_size: 50 (optional, number) - The number of jobs per page. Maximum 100.
200
OK
(application/json)
Attributes (array):
id: 123 (number) - The job ID
title: Software Engineer (string) - The job title
created_at: 1451570400 (number) - Creation timestamp
Get Single Job [GET /api/v2/ats/jobs/{job_id}]
Gets information about a specific job posting.

This method requires the ats scope and read permissions for the specific job.
Parameters
job_id: 123 (required, number) - The ID of the job
200
OK
(application/json)
Attributes:
id: 123 (number) - The job ID
title: Software Engineer (string) - The job title
created_at: 1451570400 (number) - Creation timestamp
Individual Job Applications [/api/v2/ats/applications/{application_id}]
Create Job Application [POST /api/v2/ats/applications]
Creates a new job application with candidate information.

This method requires the ats scope and create permissions for candidates.
This endpoint creates a job application and handles candidate creation automatically:

If a candidate with the provided email already exists in the organisation, their information will be updated and they will be linked to the job
If no candidate exists, a new candidate will be created
The application will be created in the specified stage, or the default “Received” stage if no stage is provided
Location assignments for the candidate are handled automatically
Required fields: job_id, legal_first_name, legal_last_name, email

Optional fields: stage_id, candidate_message, source, skip_new_candidate_notification, legal_middle_names, phone, current_position, address, date_of_birth, right_to_work, location_ids

The source parameter tracks where the application came from and defaults to “API-V2” if not provided. The skip_new_candidate_notification parameter controls whether new candidate notification emails are sent and defaults to false.

Request Create Job Application (application/json)
Body

    {
      "job_id": 123,
      "stage_id": 456,
      "candidate_message": "I am very interested in this position and believe I would be a great fit.",
      "source": "Company Website",
      "skip_new_candidate_notification": true,
      "legal_first_name": "Jane",
      "legal_last_name": "Smith", 
      "email": "jane.smith@example.com",
      "legal_middle_names": "Marie",
      "phone": "0412345678",
      "current_position": "Senior Software Developer",
      "address": "123 Collins St, Melbourne VIC",
      "date_of_birth": "1990-05-15",
      "right_to_work": "citizen",
      "location_ids": [123, 456]
    }

201
Created
(application/json)
Attributes:
id: 789 (number) - The application ID
current_stage_id: 456 (JobApplicationStageData) - Current application stage
job_id: 123 (number) - Job ID
candidate (object) - Candidate information (filtered by permissions)
name: Jane Smith (string) - Full name (only if user has PII permissions)
email: jane@example.com (string) - Email (only if user has PII permissions)
phone: +61400000000 (string) - Phone (only if user has PII permissions)
created_at: 1451570400 (number) - Application timestamp
PUTUpdate Application Stage
Updates the current stage of a job application.

This method requires the ats scope and update permissions for job applications.
This action will update the application’s current stage, and trigger any configured email notifications. It will also send a webhook notification if configured.

Parameters
application_id: 789 (required, number) - The ID of the application
stage_id: 456 (required, number) - The ID of the new stage
Request Update Application Stage (application/json)
Body

    {
      "stage_id": 456
    }

200
OK
(application/json)
Get Single Application [GET /api/v2/ats/applications/{application_id}]
Gets detailed information about a specific job application.

Parameters
application_id: 789 (required, number) - The ID of the application
200
OK
(application/json)
Attributes:
id: 789 (number) - The application ID
current_stage_id: 456 (JobApplicationStageData) - Current application stage
job_id: 123 (number) - Job ID
candidate (object) - Candidate information (filtered by permissions)
name: Jane Smith (string) - Full name (only if user has PII permissions)
email: jane@example.com (string) - Email (only if user has PII permissions)
phone: +61400000000 (string) - Phone (only if user has PII permissions)
created_at: 1451570400 (number) - Application timestamp
Job Applications by Job [/api/v2/ats/jobs/{job_id}/applications]
GETGet Applications for Job
Gets all applications for a specific job posting.

This method requires the ats scope and read permissions for both the job and job applications.
Parameters
job_id: 123 (required, number) - The ID of the job
stage_id: 456 (optional, number) - Filter by current application stage
page: 1 (optional, number) - The page number for pagination
page_size: 50 (optional, number) - The number of applications per page. Maximum 100.
200
OK
(application/json)
Attributes (array):
id: 789 (number) - The application ID
current_stage_id: 456 (JobApplicationStageData) - Current application stage
job_id: 123 (number) - Job ID
candidate (object) - Candidate information (filtered by permissions)
name: Jane Smith (string) - Full name (only if user has PII permissions)
email: jane@example.com (string) - Email (only if user has PII permissions)
phone: +61400000000 (string) - Phone (only if user has PII permissions)
created_at: 1451570400 (number) - Application timestamp
Application Stages [/api/v2/ats/stages]
GETGet Stages
Gets all available application stages for the organization.

This method requires the ats scope and read permissions for application stages.
200
OK
(application/json)
Attributes (array):
id: 456 (number) - The stage ID
name: Interview (string) - Stage name
is_active: true (boolean) - Whether the stage is active
created_at: 1451570400 (number) - Creation timestamp
Candidates [/api/v2/ats/candidates]
POSTCreate Candidate
Creates a new candidate in your hiring pipeline.

This method requires the ats scope and create permissions for candidates.
Required fields: legal_first_name, legal_last_name, email Optional fields: phone, current_position, address, date_of_birth, right_to_work, location_ids

The location_ids parameter accepts an array of location IDs that the candidate is interested in. Invalid location IDs are ignored.

Request Create Candidate (application/json)
Body

    {
      "legal_first_name": "Jane",
      "legal_last_name": "Smith",
      "email": "jane.smith@example.com",
      "phone": "0412345678",
      "current_position": "Software Developer",
      "address": "123 Collins St, Melbourne VIC",
      "date_of_birth": "1990-05-15",
      "right_to_work": "citizen",
      "location_ids": [123, 456]
    }

201
Created
(application/json)
Attributes:
id: 789 (number) - The candidate ID
legal_first_name: Jane (string) - Candidate’s legal first name
legal_last_name: Smith (string) - Candidate’s legal last name
legal_middle_names: Mary (string) - Candidate’s legal middle names
email: jane.smith@example.com (string) - Candidate’s email address
phone: +61412345678 (string) - Candidate’s phone number
current_position: Software Developer (string) - Candidate’s current job position
address: 123 Collins St, Melbourne VIC (string) - Candidate’s address
date_of_birth: 1990-05-15 (string) - Candidate’s date of birth
right_to_work: citizen (string) - Candidate’s right to work status (citizen or visa)
agreed_to_terms_at: 1451570400 (number) - When candidate agreed to terms
created_at: 1451570400 (number) - Creation timestamp
POSTCreate Stage
Creates a new custom application stage.

This method requires the ats scope and manage permissions for application stages.
Request Create Stage (application/json)
Body

    {
      "name": "Technical Interview",
      "color": "#F59E0B",
      "sort_order": 5,
      "email_enabled": true,
      "email_subject": "Next Steps - Technical Interview",
      "allow_interview_scheduling": true
    }

200
OK
(application/json)
Attributes:
id: 456 (number) - The stage ID
name: Interview (string) - Stage name
is_active: true (boolean) - Whether the stage is active
created_at: 1451570400 (number) - Creation timestamp
Update Stage [PUT /api/v2/ats/stages/{stage_id}]
Updates an existing application stage.

Parameters
stage_id: 456 (required, number) - The ID of the stage
Request Update Stage (application/json)
Body

    {
      "name": "Final Interview",
      "color": "#10B981",
      "email_enabled": false,
      "is_active": true
    }

200
OK
(application/json)
Attributes:
id: 456 (number) - The stage ID
name: Interview (string) - Stage name
is_active: true (boolean) - Whether the stage is active
created_at: 1451570400 (number) - Creation timestamp
Delete Stage [DELETE /api/v2/ats/stages/{stage_id}]
Deletes a custom application stage.

- System stages cannot be deleted - Stages with active applications cannot be deleted - This action is permanent and cannot be undone
Parameters
stage_id: 456 (required, number) - The ID of the stage
204
No Content
(application/json)
Application Notes
Get Single Note [GET /api/v2/ats/notes/{note_id}]
Gets details of a specific application note.

Parameters
note_id: 999 (required, number) - The ID of the note
200
OK
(application/json)
Attributes:
id: 999 (number) - The note ID
content: Great candidate, very experienced (string) - Note content (rich text rendered as string)
date: 1451570400 (number) - Note date timestamp
author_id: 555 (number) - User ID
has_attachments: false (boolean) - Whether the note has file attachments
created_at: 1451570400 (number) - Creation timestamp
Application Notes by Application [/api/v2/ats/applications/{application_id}/notes]
GETGet Notes for Application
Gets all notes for a specific job application.

Parameters
application_id: 789 (required, number) - The ID of the application
page: 1 (optional, number) - The page number for pagination
page_size: 100 (optional, number) - The number of notes per page. Maximum 100.
200
OK
(application/json)
Attributes (array):
id: 999 (number) - The note ID
content: Great candidate, very experienced (string) - Note content (rich text rendered as string)
date: 1451570400 (number) - Note date timestamp
author_id: 555 (number) - User ID
has_attachments: false (boolean) - Whether the note has file attachments
created_at: 1451570400 (number) - Creation timestamp
POSTCreate Note
Adds a new note to a job application.

Notes support rich text content and file attachments. File attachments should be uploaded first using the temporary files endpoint, then referenced by their file IDs.

This method requires the ats scope and create permissions for application notes.
Parameters
application_id: 789 (required, number) - The ID of the application
Request Create Note (application/json)
Body

    {
      "content": "Candidate showed strong technical skills during the phone screen. Recommend moving to technical interview stage.",
      "date": "2024-01-15",
      "file_ids": ["temp-file-uuid-1", "temp-file-uuid-2"]
    }

200
OK
(application/json)
Attributes:
id: 999 (number) - The note ID
content: Great candidate, very experienced (string) - Note content (rich text rendered as string)
date: 1451570400 (number) - Note date timestamp
author_id: 555 (number) - User ID
has_attachments: false (boolean) - Whether the note has file attachments
created_at: 1451570400 (number) - Creation timestamp
Payroll Company Files
Company files represent Workforce payroll integrations within your organisation. Each company file corresponds to a separate legal entity or payroll structure and determines which locations or employees are included in its payroll processing.

Company Files [/api/v2/payroll/company_files]
GETGet Company Files
Get all Workforce payroll company files for the current organisation.

Request
Headers Authorization: Bearer {access_token}
200
OK
(application/json)
Body [ { “id”: 123, “legal_name”: “ACME Organisation Pty Ltd”, “trading_name”: “ACME Org”, “applies_to”: “reporting_location”, “applies_to_location_ids”: [45, 67, 89] }, { “id”: 456, “legal_name”: “ACME Services Limited”, “trading_name”: “ACME Services”, “applies_to”: “everyone”, “applies_to_location_ids”: [] } ]

Attributes (array):
id: 123 (number, required) - The ID of the company file
legal_name: ACME Organisation Pty Ltd (string, required) - The legal registered name of the company
trading_name: ACME Org (string, required) - The trading or business name of the company
applies_to: reporting_location (string, required) - Determines which employees are included. One of everyone, noone, reporting_location, pay_group
applies_to_location_ids: 45, 67, 89 (array[number], required) - Array of location IDs when applies_to is reporting_location, empty array otherwise
Company File [/api/v2/payroll/company_files/{id}]
GETGet Company File
Get a single Workforce payroll company file by ID.

Parameters
id (number, required) - The company file ID
Request
Headers Authorization: Bearer {access_token}
200
OK
(application/json)
Body { “id”: 123, “legal_name”: “ACME Organisation Pty Ltd”, “trading_name”: “ACME Org”, “applies_to”: “reporting_location”, “applies_to_location_ids”: [45, 67, 89] }

Attributes:
id: 123 (number, required) - The ID of the company file
legal_name: ACME Organisation Pty Ltd (string, required) - The legal registered name of the company
trading_name: ACME Org (string, required) - The trading or business name of the company
applies_to: reporting_location (string, required) - Determines which employees are included. One of everyone, noone, reporting_location, pay_group
applies_to_location_ids: 45, 67, 89 (array[number], required) - Array of location IDs when applies_to is reporting_location, empty array otherwise
404
Not Found
(application/json)
Body { “error”: “Company file not found” }