🚀 Tanda API v2

Getting Started

Welcome to the Tanda API! This documentation steps you through authenticating to the API, as well as the various endpoints and methods supported.

Not sure where to start? Check out the quick start guide, or browse some code samples on GitHub.

There’s two ways to connect to the API. Use Authorization Code if you’re making an add-on for other Tanda users to use, 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 Tanda customers to use. For example, if you are building an integration that connects your custom reporting platform to Tanda data, you’ll probably want to let lots of Tanda customers use it. This is the approach for you.

If you have a log in for the Tanda platform you have access to an Authorization code. This code is linked to your organisation and permisson levels. Just like using an account in Tanda 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 Tanda, you won’t be able to do so via the API.

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

1. Redirect the user to the authorize endpoint

Allow users on your website to authenticate themselves with Tanda by redirecting them to the following URL. Where APPLICATION_ID and REDIRECT_URI are the values specific to your app, and the scope parameter is the relevant Tanda OAuth2 scopes your want access to (more information: Scopes).

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 Tanda server will then redirect the request back to your redirect URI, with a request code in the URL parameters. So if your redirect URI is https://mysite.com/callback then the request will be made to https://mysite.com/callback?code=AUTHORIZATION_CODE.

For local testing, as the browser gets redirected to the URI, it is possible to set it to a local address (i.e. http://localhost:3000/callback) to allow you to test your OAuth web app before deploying your code.

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 }

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.

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 Tanda login details, or you can just set up an access token through the Tanda API management page.

Access tokens generated using Password authentication never expire, but can be revoked from the API management page.

1. Make a POST request to the token endpoint

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 }

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 Tanda 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 Tanda either through the website or the API.

You can query the current user endpoint to check if a user has a valid subscription.

Rate Limiting

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 Tanda API supports the If-None-Match HTTP header. All API responses will include an ETag response header. You can use the value of this header in future requests to the same endpoint by passing it to the If-None-Match request header. If the content the API would return has not changed, you will get back a 304 Not Modified response.

The right sidebar has an example of an ETag being included in a request. For more information about ETags and If-None-Match, see Mozilla’s guide.

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

TLS Version

The Tanda 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 Tanda API, additionally, in this documentation each endpoint specifies which scope/s it requires.

Dates and Times

All dates in the Tanda API are rendered in YYYY-MM-DD format. Any request you make must use YYYY-MM-DD format for all dates.

All times in the Tanda API are rendered as Unix time, this is to avoid confusion as there can be users with different timezones in the same organisation. A user’s timezone can be retrieved from the both the User endpoint and the Current User endpoint. Any request you make must use Unix time for all times.

Update Timestamps

As well as the fields listed in the API examples below, every API response will also include an updated_at timestamp. This represents the last time that an object was updated. Like all other times returned by the API, it will be formatted as a Unix timestamp.

Many GET endpoints support an updated_after querystring parameter. Use this to filter results API-side by the updated_at field. Some endpoints also support a show_costs parameter, and return a last_costed_at field. If you pass both show_costs and updated_after, we will compare to both the updated_at and last_costed_at field when filtering.

An example may illustrate this better. Say you have a shift, and at 10am you change its start time. Then, at 11am, costing details for the shift’s employee are changed, which causes the cost of the shift to update. The shift’s updated_at will be 10am, while its last_costed_at will be 11am. If you make a call to the shift GET endpoint with updated_after of 10:30am, the shift will not be returned. But if you include the show_costs parameter when making the call, the shift will be returned since it was last costed after 10:30am.

Audit Trails

Every change made in Tanda through the API is logged and added to the in-Tanda audit trail. By default, changes will be marked as being made by “API v2”, with the user ID that corresponds to the authenticated user. If you’re building an integration that requires more fine tuned auditing (for example, a token is shared by multiple users, but you’re able to identify which user is responsible for a particular action), you can customise the user ID and audit trail name that are displayed. 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]

Get Current User [GET]

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 Tanda API.
• utc_offset - the UTC offset for the current user, this can be used as a compliment to the time zone name. See our user guide for more on using times with the Tanda API.
• organisation - the name of the currently authenticated organisation. A user can belong to one or more organisations. Unless otherwise specified on the individual endpoint, only data from this organisation will be returned by any API calls using the current access token.
• organisation_id - the ID of the currently authenticated organisation. A user can belong to one or more organisations. Unless otherwise specified on the individual endpoint, only data from this organisation will be returned by any API calls using the current access token.
• locale - the locale of the user.
• country - the country the user’s organisation is based in.
• permissions - The user’s privilege levels in the system, from the set of ['organisation_admin', 'payroll_officer', 'roster_manager', 'manager', 'employee', 'partner'].
• valid_subscription - If true, the user will be able to access other API endpoints.
• user_ids - User IDs associated with this user. This array will contain more than one item if the user has multiple profiles. If you want to get all data relating to a person across all their workplaces, use these. If you need to restrict your API call to a specific user, you can use 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 Tanda 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.

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

Roster [/api/v2/rosters/{id}]

Get Roster [GET]

Get a roster by id.

• 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)
• 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
  • meta: (MetaData) (string) - The pagination metadata, if page and page_size parameters are set

Current Roster [/api/v2/rosters/current]

Get the Current Roster [GET]

Get the current roster.

• Parameters
  • show_costs: true (boolean) - Whether to show the costs for the roster (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
  • meta: (MetaData) (string) - The pagination metadata, if page and page_size parameters are set

Roster that Contains Date [/api/v2/rosters/on/{date}]

Get Roster that Contains Date [GET]

Get the roster that contains a date, will return a 204 response if there is no roster.

• 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)
  • 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
  • meta: (MetaData) (string) - The pagination metadata, if page and page_size parameters are set

Sales Targets [/api/v2/rosters/sales_targets/{type}/{date}]

Get Sales Target [GET]

Get the sales target for a given roster with no filter.

• 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}]

Get Target for Team [GET]

Get the sales target for a given roster filtered to a team.

• 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}]

Get Target for Location [GET]

Get the sales target for a given roster filtered to a location.

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

Schedules [/api/v2/schedules]

Get Schedules [GET]

Get multiple schedules by id.

• 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.
  • 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.
  • show_vacant_only: false (optional, boolean) - Only retrieve schedules that are vacant. Defaults to false.
• 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[ScheduleBreakData]) (string) - 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
  • cost: 20.19 (number) - The cost of the schedule, if show_costs=true parameter is 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.

Get Schedules by User [GET]

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.

• 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.
  • updated_after: 1451570400 (optional, number) - Time filter to find recently created or modified schedules
• 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[ScheduleBreakData]) (string) - 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
  • cost: 20.19 (number) - The cost of the schedule, if show_costs=true parameter is 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.

Create Schedule [POST]

This will create a Roster for the given date, if it does not already exist.

• Request Create Schedule (application/json)

  • Body

        {
          "user_id": 123456,
          "start": 1456903800,
          "finish": 1456911000,
          "department_id": 111,
          "automatic_break_length": 30
        }
    

• 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[ScheduleBreakData]) (string) - 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
    • cost: 20.19 (number) - The cost of the schedule, if show_costs=true parameter is 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.
      • 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[ScheduleBreakData]) (string) - 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
    • cost: 20.19 (number) - The cost of the schedule, if show_costs=true parameter is 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.
      • id: (number)

Schedule [/api/v2/schedules/{id}]

Get Schedule [GET]

Get a schedule by id.

• 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.
  • 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[ScheduleBreakData]) (string) - 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
  • cost: 20.19 (number) - The cost of the schedule, if show_costs=true parameter is 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.

Update Schedule [PUT]

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

• 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[ScheduleBreakData]) (string) - 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
    • cost: 20.19 (number) - The cost of the schedule, if show_costs=true parameter is 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.
      • 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[ScheduleBreakData]) (string) - 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
    • cost: 20.19 (number) - The cost of the schedule, if show_costs=true parameter is 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.
      • id: (number)

Delete Schedule [DELETE]

• Parameters
  • id: 31337157 (number) - The id of the schedule
• 200 OK (application/json)

Bulk Publish Schedules [/api/v2/schedules/publish]

Publish Multiple Schedules [POST]

Publish multiple schedules at once. Push notifications are sent to users whose schedules have changed since last publish.

• 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[ScheduleBreakData]) (string) - 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
  • cost: 20.19 (number) - The cost of the schedule, if show_costs=true parameter is 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.
• 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]

Get Schedule Versions [GET]

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

Exporting Timesheets

You can download a timesheet in an export format to be imported into a payroll system by providing the export_format URI parameter. This works with any of the timesheet endpoints.

For example, making a call to /api/v2/timesheets/7007?export_format=myob will return a MYOB-compatible export of the timesheet, and /api/v2/timesheets/on/2016-03-02?export_format=myob will return a MYOB-compatible export of all timesheets for that date range.

By default all timesheets will be returned. Provide the approved_only parameter to limit your export to approved timesheets (this is the default behaviour in the Tanda UI). For example, /api/v2/timesheets/7007?export_format=myob&approved_only=true.

The content-type of these responses will not be application/json as they are for other API calls - it will depend on the export format requested, but will generally be text/plain or text/csv.

Timesheets will have their status set to exported when accessed through this endpoint. If you don’t want this to happen, include the skip_status_update parameter - eg. /api/v2/timesheets/7007?export_format=myob&skip_status_update=true. Alternatively, use the update timesheeet endpoint to reset their status.

Current Timesheets [/api/v2/timesheets/current]

Get Current Timesheets [GET]

• Parameters
  • show_costs: true (optional, boolean) - Whether to show the costs for the timesheet (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
  • cost: 102.15 (number) - The total cost of the timesheet, if show_costs=true parameter is set
  • award_interpretation: (array[AwardInterpretationData]) (string) - 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}]

Get Timesheets on Date [GET]

• 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)
  • 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
  • cost: 102.15 (number) - The total cost of the timesheet, if show_costs=true parameter is set
  • award_interpretation: (array[AwardInterpretationData]) (string) - 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]

Get Current Timesheet for User [GET]

• 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)
  • 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
  • cost: 102.15 (number) - The total cost of the timesheet, if show_costs=true parameter is set
  • award_interpretation: (array[AwardInterpretationData]) (string) - 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}]

Get Timesheet for User on Date [GET]

• 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)
  • 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
  • cost: 102.15 (number) - The total cost of the timesheet, if show_costs=true parameter is set
  • award_interpretation: (array[AwardInterpretationData]) (string) - Award interpretation output, if show_award_interpretation=true parameter is set
  • notes: (optional, array[NoteData]) - Notes on the timesheet

Timesheet [/api/v2/timesheets/{id}]

Get Timesheet [GET]

• 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)
  • 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
  • cost: 102.15 (number) - The total cost of the timesheet, if show_costs=true parameter is set
  • award_interpretation: (array[AwardInterpretationData]) (string) - Award interpretation output, if show_award_interpretation=true parameter is set
  • notes: (optional, array[NoteData]) - Notes on the timesheet

Update Timesheet [PUT]

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
  • cost: 102.15 (number) - The total cost of the timesheet, if show_costs=true parameter is set
  • award_interpretation: (array[AwardInterpretationData]) (string) - 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.

Shifts [/api/v2/shifts]

Get Shifts [GET]

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.

• 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)
  • show_award_interpretation: true (optional, boolean) - Whether to show award interpretation for the shifts (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
  • award_interpretation: (array[AwardInterpretationData]) (string) - 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
  • 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

Create Shift [POST]

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.

• Request Create Shift (application/json)

  • Body

        {
          "user_id": 123456,
          "date": "2016-03-12",
          "start": 1457741040,
          "finish": 1457762640,
          "department_id": 808,
          "metadata": "My special metadata"
        }
    

• 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}]

Get Shift [GET]

Get a shift by id.

• 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)
  • show_award_interpretation: true (optional, boolean) - Whether to show award interpretation for the shift (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
  • award_interpretation: (array[AwardInterpretationData]) (string) - 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
  • 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

Update Shift [PUT]

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.

• 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
  • award_interpretation: (array[AwardInterpretationData]) (string) - 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
  • 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
    • 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
  • award_interpretation: (array[AwardInterpretationData]) (string) - 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
  • 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
    • 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
  • award_interpretation: (array[AwardInterpretationData]) (string) - 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
  • 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
    • 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
  • award_interpretation: (array[AwardInterpretationData]) (string) - 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
  • 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
    • allowances (array)
      • (object)
        • id: 987654 (number)
        • value: 1 (number)
      • (object)
        • id: 456789 (number)
        • value: 0.5 (number)
        • cost: 1.75 (number)

Delete Shift [DELETE]

• Parameters
  • id: 1337 (number) - The id of the shift
• 200 OK (application/json)

Active Status [/api/v2/shifts/active]

Get Active Shifts [GET]

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.

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

Get Shift’s Applicable Allowances [GET]

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.

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

Get Shift Versions [GET]

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

Get Shift’s Breaks [GET]

• 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

Create Shift Break [POST]

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

Get Shift Break [GET]

• 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

Update Shift Break [PUT]

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]

Get Shift Break Versions [GET]

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

Get Shift Limits [GET]

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

User List [/api/v2/users]

Get Users [GET]

Gets information about all visible users.

• 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) (string) - 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) (string) - 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) (string) - 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) (string) - the bank details of the employee
  • `address (Address)
  • tax_declaration: (object)` (string) - 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)
    • 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
  • qualifications: (array[UserQualification]) (string) - Information about qualifications the user holds, if Qualifications are enabled
  • regular_hours: (RegularHours) (string) - 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[EmergencyContact]) (string) - Read only

Create User [POST]

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.

To skip email validation when creating a user, use skip_validation=true.

• 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[number]) (string) - The award tag ids that apply to the user
    • report_department_id: 111 (number) - The user’s default team
    • managed_department_ids: (array[number]) (string) - 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) (string) - can the user see the costs data
    • One of
      • user_levels: (array[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) (string) - the tax declaration information of the employee
    • bank_details: (BankDetails) (string) - the bank details of the employee
    • super_fund_membership: (SuperFundMembership) (string) - information about the employees super fund membership
    • regular_hours: (RegularHours) (string) - 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[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[number]) (string) - 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[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[number]) (string) - 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)

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

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

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

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

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

Get Inactive Users [GET]

• 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}]

Get User [GET]

Gets information about a user.

• 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) (string) - 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) (string) - 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) (string) - 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) (string) - the bank details of the employee
  • `address (Address)
  • tax_declaration: (object)` (string) - 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)
    • 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
  • qualifications: (array[UserQualification]) (string) - Information about qualifications the user holds, if Qualifications are enabled
  • regular_hours: (RegularHours) (string) - 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[EmergencyContact]) (string) - Read only

Update User [PUT]

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[number]) (string) - The award tag ids that apply to the user
    • report_department_id: 111 (number) - The user’s default team
    • managed_department_ids: (array[number]) (string) - 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) (string) - can the user see the costs data
    • One of
      • user_levels: (array[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) (string) - the tax declaration information of the employee
    • bank_details: (BankDetails) (string) - the bank details of the employee
    • super_fund_membership: (SuperFundMembership) (string) - information about the employees super fund membership
    • regular_hours: (RegularHours) (string) - 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[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) (string) - 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) (string) - 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) (string) - 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) (string) - the bank details of the employee
  • `address (Address)
  • tax_declaration: (object)` (string) - 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)
    • 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
  • qualifications: (array[UserQualification]) (string) - Information about qualifications the user holds, if Qualifications are enabled
  • regular_hours: (RegularHours) (string) - 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[EmergencyContact]) (string) - 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) (string) - 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) (string) - 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) (string) - 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) (string) - the bank details of the employee
  • `address (Address)
  • tax_declaration: (object)` (string) - 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)
    • 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
  • qualifications: (array[UserQualification]) (string) - Information about qualifications the user holds, if Qualifications are enabled
  • regular_hours: (RegularHours) (string) - 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[EmergencyContact]) (string) - 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)

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

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

• Body

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

• Request Update Singapore Bank Details (application/json)

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

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

Delete User [DELETE]

This endpoint will just mark the user as inactive and return the user, this effectively does the same as the deactivate user request above.

• 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) (string) - 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) (string) - 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) (string) - 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) (string) - the bank details of the employee
  • `address (Address)
  • tax_declaration: (object)` (string) - 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)
    • 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
  • qualifications: (array[UserQualification]) (string) - Information about qualifications the user holds, if Qualifications are enabled
  • regular_hours: (RegularHours) (string) - 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[EmergencyContact]) (string) - Read only
    • active: false (boolean)
    • passcode: 01234568975461

Invite Users [/api/v2/users/{id}/invite]

Invite User [POST]

This endpoint takes a user ID and sends that user an email invite to use Tanda.

• Parameters
  • id: 654321 (number) - The id of the user
• 201 Created (application/json)

Invite New Users for Onboarding [/api/v2/users/onboarding]

Invite User for Onboarding [POST]

If you are using Tanda’s employee onboarding, you can use this endpoint to automatically invite new staff to be onboarded. It takes a name and email, and optionally a phone number and custom message, and sends the employee a link to a form where they can add their details.

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

Invite Existing User for Onboarding [POST]

If you have created a new user with the Create User endpoint and are using Tanda’s employee onboarding, you can use this endpoint to trigger the onboarding process for the new user.

• Parameters
  • id: 123456 (number) - The id of the user
• 201 Created (application/json)

Clocked In Users [/api/v2/users/clocked_in]

Get Clocked In Users [GET]

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.

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

Get User Versions [GET]

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

Get Alternate Rates [GET]

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

Update Alternate Rates [PUT]

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.

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

Delete Alternate Rates [DELETE]

• 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

Employee Payfields [/api/v2/user_pay_fields]

Get Payfields For All Users [GET]

Retrieves all pay field objects belonging to the users of the organisation. This endpoint can be paginated.

• 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}]

Get Payfields By Payfield ID [GET]

Retrieves one pay field object by it’s unique id.

• 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}]

Get Payfields By User [GET]

This endpoint takes a user ID and returns an array of all the users pay field objects.

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

Verify Payfields By User [GET]

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.

• 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}]

Update Payfield [PUT]

Update a specific param for a single payfield entry.

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

Create Payfield [POST]

user_id and from_date are all that are required in the request body to create a new payfield entry.

• 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}]

Create & Update Multiple Pay Fields For A User [POST]

This endpoint can be used through a POST request to manage a specific user’s pay field objects in bulk.

• 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}]

Delete Payfield By Id [DELETE]

Delete a specific payfield entry.

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

  • Body

            {
              "id": 54321
            }
    

• 201 Created (application/json)

Locations

Location List [/api/v2/locations]

Get Locations [GET]

• 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[SpecificHolidayDateData]) (string) - 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[BusinessHoursData]) (string) - The business hours of the location
  • record_id: 532432 (number) - the record ID, for use with Platform endpoints

Create Location [POST]

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.

• 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[SpecificHolidayDateData]) (string) - 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[BusinessHoursData]) (string) - 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}]

Get Location [GET]

• 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[SpecificHolidayDateData]) (string) - 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[BusinessHoursData]) (string) - The business hours of the location
  • record_id: 532432 (number) - the record ID, for use with Platform endpoints

Update Location [PUT]

Updating a location’s business hours

• 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[SpecificHolidayDateData]) (string) - 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[BusinessHoursData]) (string) - 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[SpecificHolidayDateData]) (string) - 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[BusinessHoursData]) (string) - 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)

Delete Location [DELETE]

• Parameters
  • id: 111 (number) - The id of the location
• 200 OK (application/json)

Location Versions [/api/v2/locations/{id}/versions]

Get Location Versions [GET]

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

Team List [/api/v2/departments]

Get Teams [GET]

• 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"
      }
    ]
    

Create Team [POST]

• 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}]

Get Team [GET]

• 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

Update Team [PUT]

Updating users & managers

Updating required team qualifications

• 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

Delete Team [DELETE]

• Parameters
  • id: 111 (number) - The id of the team
• 200 OK (application/json)

Team Versions [/api/v2/departments/{id}/versions]

Get Team Versions [GET]

• 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 Detail List [/api/v2/shift_details]

Get Shift Details [GET]

• 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

Create Shift Detail [POST]

• 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}]

Get Shift Detail [GET]

• 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

Update Shift Detail [PUT]

• 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
  

Delete Shift Detail [DELETE]

• Parameters
  • id: 36 (number) - The id of the shift detail
• 200 OK (application/json)

Access & Roles

Platform Role List [/api/v2/platform/roles]

Get Platform Roles [GET]

• 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

Award Tag List [/api/v2/award_tags]

Get Award Tags [GET]

• 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}]

Get Award Tag [GET]

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

Leave List [/api/v2/leave]

Get Leave List [GET]

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.

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

Create Leave Request [POST]

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.

• 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}]

Get Leave Request [GET]

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

Update Leave Request [PUT]

• 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}]

Get Leave Types for User [GET]

• 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}]

Get Leave Types with details for User [GET]

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

Get Leave Request Versions [GET]

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

Get Default Hours for a Leave Request [GET]

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.

• 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 List [/api/v2/leave_balances]

Get Leave Balances [GET]

Lookup leave balances for one or more user_ids.

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

Create Leave Balance [POST]

Use the Leave Types For User call to find accessible leave types for your user.

• 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}]

Get Leave Balance [GET]

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

Update Leave Balance with ID [PUT]

• 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}]

Update Leave Balance with User ID [PUT]

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

Predict Leave Balance [POST]

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.

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 }

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.

Unavailability List [/api/v2/unavailability]

Get Unavailabilities [GET]

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.

• 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
          }
        ]
    

Create Unavailability [POST]

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

Get Repeating Unavailabilities [GET]

• 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}]

Get Unavailability [GET]

• 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) (string) - 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) (string) - Info about the unavailabilities that are part of this repeating set of unavailabilities (if the unavailability is repeating)

Update Unavailability [PUT]

Update the unavailability’s title (in the case of repeating unavailability, all of the event’s titles will be updated).

• 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) (string) - Info about the unavailabilities that are part of this repeating set of unavailabilities (if the unavailability is repeating)
      • id: (number)

Delete Unavailability [DELETE]

• Parameters
  • id: 42 (number) - The id of the leave to delete
• 200 OK (application/json)

Data Streams

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.

Data Stream List [/api/v2/datastreams]

Get Data Streams [GET]

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

Create Data Stream [POST]

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’

• 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}]

Get Data Stream [GET]

• 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

Update Data Stream [PUT]

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

Delete Data Stream [DELETE]

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.

• Parameters
  • id: 26 (number) - The id of the data stream
• 202 Accepted (application/json)

Data Stream Versions [/api/v2/datastreams/{id}/versions]

Get Data Stream Versions [GET]

• 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

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.

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 Tanda would recommend that 4 staff be rostered for that half hour period.

Data Stream Join List [/api/v2/datastreamjoins]

Get Data Stream Joins [GET]

• 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
  • head_count_map: "1,2.5,5" (string) - The exact amounts of demand each team size can handle. This can be used to describe an ‘economies of scale’

Create Data Stream Join [POST]

• 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
  • head_count_map: "1,2.5,5" (string) - The exact amounts of demand each team size can handle. This can be used to describe an ‘economies of scale’

  + 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}]

Get Data Stream Join [GET]

• 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
  • head_count_map: "1,2.5,5" (string) - The exact amounts of demand each team size can handle. This can be used to describe an ‘economies of scale’

Update Data Stream Join [PUT]

• 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
  • head_count_map: "1,2.5,5" (string) - The exact amounts of demand each team size can handle. This can be used to describe an ‘economies of scale’

  + rostering_ratio: 1.5 (number)
  

Delete Data Stream Join [DELETE]

• Parameters
  • id: 162 (number) - The id of the data stream join to delete
• 200 OK (application/json)

Store Stats

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 Tanda, and differentiate them using the type parameter, but be aware of this special case.

Store Stats for Datastream [/api/v2/storestats/for_datastream/{datastream_id}/]

Store Stats for Datastream [GET]

• 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}]

Create Store Stats for Datastream [POST]

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.

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

• 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}]

Deleting Store Stats [POST]

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]

Create Store Stats for Multiple Datastreams [POST]

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.

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

Device List [/api/v2/devices]

Get Devices [GET]

• 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

Create Device [POST]

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]

Get Returned Devices [GET]

• 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