🚀 Tanda API v2

API Endpoint
https://my.tanda.co

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. 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 users to use.

Once you have your application id, and secret, and redirect URI which is available from the applications page, then the following steps can be taken to authenticate a user using the Authorization Code authentication flow.

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

1. Redirect the user to the authorize endpoint

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

2. Catch the request to your redirect URI

The Tanda server will then redirect the request back to your redirect URI, with a request code in the URL parameters. So if your redirect URI is https://mysite.com/callback then the request will be made to https://mysite.com/callback?code=AUTHORIZATION_CODE.

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

curl https://my.tanda.co/api/oauth/token -X POST -H "Cache-Control: no-cache" \
-F "client_id=YOUR_APPLICATION_ID" \
-F "client_secret=YOUR_SECRET" \
-F "code=AUTHORIZATION_CODE" \
-F "redirect_uri=YOUR_REDIRECT_URI" \
-F "grant_type=authorization_code"

3. Make a POST request to the token endpoint

Now that you’ve got your authorization code, you can finally make the POST request to get your access token (don’t worry, this is the last step).

From your server/application make a POST request to https://my.tanda.co/api/oauth/token.

The response should look something like this:

{
  "access_token": "6833b9ecaa84ce420da3cafaa43124d241cb28b5287b72d131f6b38bcb64cd91",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "ddeb6480f06247e3635826dd5e3875ece6f64a27044516731a914897431ab446",
  "scope": "me",
  "created_at": 1457304578
}

expires_in is in seconds, so your token will last 2 hours. To learn how to refresh your token, see Refreshing your Token.

Refreshing your Token 

curl https://my.tanda.co/api/oauth/token -X POST -H "Cache-Control: no-cache" \
-F "client_id=YOUR_APPLICATION_ID" \
-F "client_secret=YOUR_SECRET" \
-F "refresh_token=REFRESH_TOKEN" \
-F "redirect_uri=YOUR_REDIRECT_URI" \
-F "grant_type=refresh_token"

If you got your token using the Authorization Code authentication flow, and it expires, then using the the refresh_token you got above, you are able to refresh it by making a POST request to https://my.tanda.co/api/oauth/token.

The response should look something like this:

{
  "access_token": "ddeb6480f06247e3635826dd5e3875ece6f64a27044516731a914897431ab446",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "d0692903972ff6559ec5f0e3165cabd5b87f47e3613431ad53805b5397268206",
  "scope": "me",
  "created_at": 1457311778
}

You can now go on using this new access token for another 2 hours.

If your application’s access is revoked by the user, then you will need to run through the authentication process again to obtain a new access token.

Although the tokens only last for 2 hours, you can refresh your token as many times as you want. The refresh token has no expiry but can only be used once.

Authentication (Password)

Use Password authentication if you’re building an integration just for your own account.

If you’re using the API for a single account, the Password authentication flow is an easier way to get set up. You can authenticate via the command line using your Tanda login details, or you can just set up an access token through the Tanda API management page.

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

1. Make a POST request to the token endpoint 

curl https://my.tanda.co/api/oauth/token -X POST -H "Cache-Control: no-cache" \
-F "username=USER_EMAIL" \
-F "password=USER_PASSWORD" \
-F "scope=SCOPE1 SCOPE2" \
-F "grant_type=password"

From your server/application make a POST request to https://my.tanda.co/api/oauth/token with the user’s email and password.

The response should look something like this:

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

Password authenticated tokens have no expiry. They can also be created and revoked from the access tokens page.

Making Requests

Once either of the above authentication methods have been completed, you’ll have an access token (in the case of Authorization Code authentication, the token will only last for 2 hours).

Your access token will look something like this: 6833b9ecaa84ce420da3cafaa43124d241cb28b5287b72d131f6b38bcb64cd91. From here on out all requests you make to the Tanda v2 API must include the token in the header like so:

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

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

Invalid Subscriptions

If you receive a 402 response status with this message:

Your account is locked out for billing purposes, and cannot use the API!

This indicates that the customer’s account does not have a valid credit card or other billing method set, and their free trial has ended. Therefore they will not be able to access some components of Tanda either through the website or the API.

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

Rate Limiting

If you reach the rate limit, you’ll get the following 429 response:

Headers

X-RateLimit-Limit:       100
X-RateLimit-RateLimited: true
X-RateLimit-Remaining:   0
X-RateLimit-Reset:       1461211225

Body

{
  "error": "API rate limit exceeded!"
}

Requests to the API are rate limited to 100 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:     100
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:

  • 99 requests with token_1

  • 1 request with token_2 (I have 100 requests/min for all my Password Access Tokens)

  • 100 requests on my behalf through user_2's OAuth app

  • 100 requests on my behalf through my OAuth app

  • 100 requests on user_1's behalf through my OAuth app

  • 100 requests on user_2's behalf through my OAuth app

In summary the distinct requesters in this example are:

  • Me through my Password Access Tokens

  • Me through user_2's OAuth app

  • Me through my OAuth app

  • user_1 through my OAuth app

  • user_2 through my OAuth app

Caching 

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

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

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

Scopes

In both the Authorization Code and Password authentication methods, you are required to include a scope parameter. Here is a complete list of the scopes in the Tanda API, additionally, in this documentation each endpoint specifies which scope/s it requires.

Scope Endpoints Description
me Users Access information about the current user
roster Rosters, Schedules Manage roster and schedule information
timesheet Timesheets, Shifts Manage timesheet and shift information
department Locations, Teams (Departments), Shift Details Manage location, department (team), and shift detail information
user Users, Award Tags, Clock Ins Manage information about your employees (without wages)
cost Users, Timesheets, Shifts, Rosters, Schedules Mange information about your employee’s wage, and see costs for timesheets and rosters
leave Leave Requests, Leave Balances Manage leave requests and balances
unavailability Unavailability Manage unavailability
datastream Data Streams, Data Stream Joins, Store Stats Manage your data streams and store stats
device Devices, Clock Ins Manage timeclock information, and read clock ins for devices
qualifications Qualifications Manage qualifications
settings Settings, Award Templates Settings and award related configuration
organisation Organisations View & create client organisations
sms SMS Send SMS

Not only will you need the relevant scopes to access the endpoints, but also the correct system permissions in Tanda. For more information please see each endpoint group.

By selecting only the bare minimum scopes that your application needs, users will feel more comfortable authorizing your application.

For example: If you had all scopes selected but your application simply collects information about users (using the User endpoint, and user scope) people will question why your application needs to have access to timesheet data (timesheet scope) and will be less likely to approve it.

Dates and Times

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

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

Our user guide has more information on working with unix times through the API.

Update Timestamps

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

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

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

Audit Trails

Every change made in Tanda through the API is logged and added to the in-Tanda audit trail. By default, changes will be marked as being made by “API v2”, with the user ID that corresponds to the authenticated user. If you’re building an integration that requires more fine tuned auditing (for example, a token is shared by multiple users, but you’re able to identify which user is responsible for a particular action), you can customise the user ID and audit trail name that are displayed. Please contact developers@tanda.co and we can help you set this up.

Code Samples

We have a repository of code samples available on GitHub. There’s also user guides and links to other helpful API information there. Please check it out, contributions are always welcome!

General

Current User

GET https://my.tanda.co/api/v2/users/me
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 123456,
  "name": "Lenny Leonard",
  "email": "lenny.leonard@springfieldpowerplant.com",
  "photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
  "time_zone": "Australia/Brisbane",
  "utc_offset": 36000,
  "organisation": "Moe's Tavern",
  "organisation_id": 126546,
  "locale": "en-US",
  "country": "United States",
  "permissions": [
    "employee",
    "manager"
  ],
  "valid_subscription": true,
  "user_ids": [
    1,
    2,
    123456
  ],
  "organisations": [
    {
      "name": "Moe's Tavern",
      "id": 1,
      "user_id": 1,
      "locale": "en-US",
      "country": "United States"
    },
    {
      "name": "Bob's Burgers",
      "id": 2,
      "user_id": 1,
      "locale": "en-US",
      "country": "United States"
    },
    {
      "name": "Dave's Doors",
      "id": 3,
      "user_id": 123456,
      "locale": "en-AU",
      "country": "Australia"
    }
  ],
  "updated_at": 1478650040
}

Get Current User
GET/api/v2/users/me

Gets information about the current user (i.e. the user that has been authenticated).

The following fields are returned:

  • id - the user’s unique ID.

  • name - the user’s name.

  • email - the user’s email.

  • photo - if present, a link to a photo of the user.

  • time_zone - the name of the time zone the user is in - uses zone names from the IANA Time Zone Database. See our user guide for more on using times with the Tanda API.

  • utc_offset - the UTC offset for the current user, this can be used as a compliment to the time zone name. See our user guide for more on using times with the Tanda API.

  • organisation - the name of the currently authenticated organisation. A user can belong to one or more organisations. Unless otherwise specified on the individual endpoint, only data from this organisation will be returned by any API calls using the current access token.

  • organisation_id - the ID of the currently authenticated organisation. A user can belong to one or more organisations. Unless otherwise specified on the individual endpoint, only data from this organisation will be returned by any API calls using the current access token.

  • locale - the locale of the user.

  • country - the country the user’s organisation is based in.

  • permissions - The user’s privilege levels in the system, from the set of ['organisation_admin', 'payroll_officer', 'roster_manager', 'manager', 'employee', 'partner'].

  • valid_subscription - If true, the user will be able to access other API endpoints.

  • user_ids - User IDs associated with this user, this array will contain more than one item if the user has profiles at several organisations. If you want to get all data relating to a person across all their workplaces, use these.

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

This method requires the me scope (see Scopes for more information).

Rosters

Rosters are the container for scheduled shifts, each roster runs for 1 week and contains Schedules. For actual times worked, please see Timesheets or Shifts.

Rosters are not created directly. Instead a roster will be created when creating through the Schedules endpoint.

No special Tanda permissions are required to use the roster endpoint.

Roster

GET https://my.tanda.co/api/v2/rosters/70074?show_costs=true
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 70074,
  "schedules": [
    {
      "date": "2016-03-02",
      "schedules": [
        {
          "id": 31337157,
          "roster_id": 70074,
          "user_id": 123456,
          "start": 1456902000,
          "finish": 1456916400,
          "breaks": [
            {
              "start": 1456909200,
              "finish": 1456911000
            }
          ],
          "automatic_break_length": 30,
          "department_id": 111,
          "shift_detail_id": 36,
          "cost": 20.19,
          "last_published_at": 1457002800
        }
      ]
    }
  ],
  "start": "2016-02-29",
  "finish": "2016-03-07",
  "cost": 1200.2
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the roster"
    },
    "schedules": {
      "type": "array",
      "description": "The roster broken down by days"
    },
    "start": {
      "type": "string",
      "description": "The date of the first day of the roster"
    },
    "finish": {
      "type": "string",
      "description": "The date of the last day of the roster"
    },
    "cost": {
      "type": "number",
      "description": "The total cost of the roster, if `show_costs=true` parameter is set"
    }
  },
  "required": [
    "id",
    "schedules",
    "start",
    "finish"
  ]
}

Get Roster
GET/api/v2/rosters/{id}{?show_costs}

Get a roster by id.

This method requires the roster scope (see Scopes for more information).

If you are using show_costs=true, the cost scope is also required.

URI Parameters
HideShow
id
number (required) Example: 70074

The id of the roster

show_costs
boolean (optional) Example: true

Whether to show the costs for the roster (defaults to false)

Current Roster

GET https://my.tanda.co/api/v2/rosters/current?show_costs=true
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 70074,
  "schedules": [
    {
      "date": "2016-03-02",
      "schedules": [
        {
          "id": 31337157,
          "roster_id": 70074,
          "user_id": 123456,
          "start": 1456902000,
          "finish": 1456916400,
          "breaks": [
            {
              "start": 1456909200,
              "finish": 1456911000
            }
          ],
          "automatic_break_length": 30,
          "department_id": 111,
          "shift_detail_id": 36,
          "cost": 20.19,
          "last_published_at": 1457002800
        }
      ]
    }
  ],
  "start": "2016-02-29",
  "finish": "2016-03-07",
  "cost": 1200.2
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the roster"
    },
    "schedules": {
      "type": "array",
      "description": "The roster broken down by days"
    },
    "start": {
      "type": "string",
      "description": "The date of the first day of the roster"
    },
    "finish": {
      "type": "string",
      "description": "The date of the last day of the roster"
    },
    "cost": {
      "type": "number",
      "description": "The total cost of the roster, if `show_costs=true` parameter is set"
    }
  },
  "required": [
    "id",
    "schedules",
    "start",
    "finish"
  ]
}

Get the Current Roster
GET/api/v2/rosters/current{?show_costs}

Get the current roster.

This method requires the roster scope (see Scopes for more information).

If you are using show_costs=true, the cost scope is also required.

URI Parameters
HideShow
show_costs
boolean (required) Example: true

Whether to show the costs for the roster (defaults to false)

Roster that Contains Date

GET https://my.tanda.co/api/v2/rosters/on/2016-03-02?show_costs=true
Responses200204
Headers
Content-Type: application/json
Body
{
  "id": 70074,
  "schedules": [
    {
      "date": "2016-03-02",
      "schedules": [
        {
          "id": 31337157,
          "roster_id": 70074,
          "user_id": 123456,
          "start": 1456902000,
          "finish": 1456916400,
          "breaks": [
            {
              "start": 1456909200,
              "finish": 1456911000
            }
          ],
          "automatic_break_length": 30,
          "department_id": 111,
          "shift_detail_id": 36,
          "cost": 20.19,
          "last_published_at": 1457002800
        }
      ]
    }
  ],
  "start": "2016-02-29",
  "finish": "2016-03-07",
  "cost": 1200.2
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the roster"
    },
    "schedules": {
      "type": "array",
      "description": "The roster broken down by days"
    },
    "start": {
      "type": "string",
      "description": "The date of the first day of the roster"
    },
    "finish": {
      "type": "string",
      "description": "The date of the last day of the roster"
    },
    "cost": {
      "type": "number",
      "description": "The total cost of the roster, if `show_costs=true` parameter is set"
    }
  },
  "required": [
    "id",
    "schedules",
    "start",
    "finish"
  ]
}
Headers
Content-Type: application/json

Get Roster that Contains Date
GET/api/v2/rosters/on/{date}{?show_costs}

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

This method requires the roster scope (see Scopes for more information).

If you are using show_costs=true, the cost scope is also required.

URI Parameters
HideShow
date
string (required) Example: 2016-03-02

The date that’s contained in the roster you are looking for.

show_costs
boolean (optional) Example: true

Whether to show the costs for the roster (defaults to false)

Sales Targets

GET https://my.tanda.co/api/v2/rosters/sales_targets/type/2018-02-26
Responses200
Headers
Content-Type: application/json
Body
{
  "target": "1234.56",
  "created_at": 1519621685,
  "updated_at": 1519621685,
  "user_entered": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "description": "Value of the sales target. null if there is no roster for the given date."
    },
    "created_at": {
      "type": [
        "number",
        "null"
      ],
      "description": "When the user-entered sales target was first created, if there is one. Otherwise null."
    },
    "updated_at": {
      "type": [
        "number",
        "null"
      ],
      "description": "When the user-entered sales target was last updated, if there is one. Otherwise null."
    },
    "user_entered": {
      "type": "boolean",
      "description": "Whether or not the default projection was overridden with a user-entered value."
    }
  },
  "required": [
    "created_at",
    "updated_at",
    "user_entered"
  ]
}

Sales Targets
GET/api/v2/rosters/sales_targets/{type}/{date}

Get the sales target for a given roster, optionally filtered to a location or department.

If you specify department_id or location_id, then you are required to have read access to the department/location you are requesting. Otherwise you are required to be an Admin or General Manager.

This method requires the roster scope (see Scopes for more information).

URI Parameters
HideShow
type
string (required) 

There are two possible values: day and week.

date
string (required) Example: 2018-02-26

A date within the roster you are looking for.

department_id
number (optional) 

The ID of a department to filter the roster to. Shouldn’t be used with location_id.

location_id
number (optional) 

The ID of a location to filter the roster to. Shouldn’t be used with department_id.

Schedules

Schedules represent planned shifts for a user and are contained in a Roster, for actual times worked please see Timesheets or Shifts.

No special Tanda permissions are required to view schedules, however only the schedules that would be visible through the UI are visible through the API.

To create or change schedules, the user must be a team manager, roster manager, or admin. In the case of the team manager, the shift must be for someone in the user’s managed teams.

Employees can only see published schedules. Specifying ids of unpublished schedules, or using the published_only flag will not change this.

Looking to just get the roster for an individual employee? Check out our user guide for a workflow.

Schedules

GET https://my.tanda.co/api/v2/schedules?ids=1,2,31337157&show_costs=true&include_names=false
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 31337157,
    "roster_id": 70074,
    "user_id": 123456,
    "start": 1456902000,
    "finish": 1456916400,
    "breaks": [
      {
        "start": 1456909200,
        "finish": 1456911000
      }
    ],
    "automatic_break_length": 30,
    "department_id": 111,
    "shift_detail_id": 36,
    "cost": 20.19,
    "last_published_at": 1457002800
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Schedules
GET/api/v2/schedules{?ids,show_costs,include_names}

Get multiple schedules by id.

This method requires the roster scope (see Scopes for more information).

If you are using show_costs=true, the cost scope is also required.

URI Parameters
HideShow
ids
string (required) Example: 1,2,31337157

Comma separated list of schedule ids

show_costs
boolean (optional) Example: true

Whether to show the costs for the schedule (defaults to false)

include_names
boolean (optional) Example: false

If true, the department name and shift detail name (not just ID) will be included in the response. Defaults to false.

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified schedules

published_only
boolean (optional) Example: false

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.

GET https://my.tanda.co/api/v2/schedules?user_ids=1,2,123456&from=2016-03-02&to=2016-03-02&show_costs=true&include_names=false
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 31337157,
    "roster_id": 70074,
    "user_id": 123456,
    "start": 1456902000,
    "finish": 1456916400,
    "breaks": [
      {
        "start": 1456909200,
        "finish": 1456911000
      }
    ],
    "automatic_break_length": 30,
    "department_id": 111,
    "shift_detail_id": 36,
    "cost": 20.19,
    "last_published_at": 1457002800
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Schedules by User
GET/api/v2/schedules{?user_ids,from,to,show_costs,include_names}

Get multiple schedules by user IDs, from, and to date. From and to date are required, while user IDs are optional. If no user IDs are provided, all visible schedules (based on the current user’s permission levels) will be returned.

This method requires the roster scope (see Scopes for more information).

If you are using show_costs=true, the cost scope is also required.

URI Parameters
HideShow
user_ids
string (required) Example: 1,2,123456

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
string (required) Example: 2016-03-02

From date to lookup schedules in. If provided, from and to can be at most 7 days apart.

to
string (required) Example: 2016-03-02

To date to lookup schedules in. If provided, from and to can be at most 7 days apart.

show_costs
boolean (optional) Example: true

Whether to show the costs for the schedule (defaults to false)

include_names
boolean (optional) Example: false

If true, the department name and shift detail name (not just ID) will be included in the response. Defaults to false.

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified schedules

POST https://my.tanda.co/api/v2/schedules
RequestsCreate ScheduleCreate vacant Schedule
Headers
Content-Type: application/json
Body
{
  "user_id": 123456,
  "start": 1456903800,
  "finish": 1456911000,
  "department_id": 111,
  "automatic_break_length": 30
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 31337158,
  "roster_id": 70074,
  "user_id": 123456,
  "start": 1456903800,
  "finish": 1456911000,
  "breaks": [],
  "automatic_break_length": 30,
  "department_id": 111,
  "shift_detail_id": null,
  "last_published_at": null
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the schedule"
    },
    "roster_id": {
      "type": "number",
      "description": "The id of the roster"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who is assigned the schedule"
    },
    "start": {
      "type": "number",
      "description": "The start of the schedule"
    },
    "finish": {
      "type": "number",
      "description": "The end of the schedule"
    },
    "breaks": {
      "type": "array",
      "description": "The breaks taken in the schedule"
    },
    "automatic_break_length": {
      "type": "number",
      "description": "Length of automatic break in minutes"
    },
    "department_id": {
      "type": "number",
      "description": "The department (team) id for the schedule"
    },
    "shift_detail_id": {
      "type": "number",
      "description": "The shift detail id for the schedule"
    },
    "cost": {
      "type": "number",
      "description": "The cost of the schedule, if `show_costs=true` parameter is set"
    },
    "last_published_at": {
      "type": "number",
      "description": "When the schedule was last published to its given employee"
    }
  },
  "required": [
    "id",
    "roster_id"
  ]
}
Headers
Content-Type: application/json
Body
{
  "start": 1456903800
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 31337158,
  "roster_id": 70074,
  "user_id": null,
  "start": 1456903800,
  "finish": null,
  "breaks": [],
  "automatic_break_length": null,
  "department_id": null,
  "shift_detail_id": null,
  "last_published_at": null
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the schedule"
    },
    "roster_id": {
      "type": "number",
      "description": "The id of the roster"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who is assigned the schedule"
    },
    "start": {
      "type": "number",
      "description": "The start of the schedule"
    },
    "finish": {
      "type": "number",
      "description": "The end of the schedule"
    },
    "breaks": {
      "type": "array",
      "description": "The breaks taken in the schedule"
    },
    "automatic_break_length": {
      "type": "number",
      "description": "Length of automatic break in minutes"
    },
    "department_id": {
      "type": "number",
      "description": "The department (team) id for the schedule"
    },
    "shift_detail_id": {
      "type": "number",
      "description": "The shift detail id for the schedule"
    },
    "cost": {
      "type": "number",
      "description": "The cost of the schedule, if `show_costs=true` parameter is set"
    },
    "last_published_at": {
      "type": "number",
      "description": "When the schedule was last published to its given employee"
    }
  },
  "required": [
    "id",
    "roster_id"
  ]
}

Create Schedule
POST/api/v2/schedules

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

Only one of breaks and automatic_break_length can be set to non-null values.

This method requires the roster scope (see Scopes for more information).

Schedule

GET https://my.tanda.co/api/v2/schedules/31337157?show_costs=true&include_names=false
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 31337157,
  "roster_id": 70074,
  "user_id": 123456,
  "start": 1456902000,
  "finish": 1456916400,
  "breaks": [
    {
      "start": 1456909200,
      "finish": 1456911000
    }
  ],
  "automatic_break_length": 30,
  "department_id": 111,
  "shift_detail_id": 36,
  "cost": 20.19,
  "last_published_at": 1457002800
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the schedule"
    },
    "roster_id": {
      "type": "number",
      "description": "The id of the roster"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who is assigned the schedule"
    },
    "start": {
      "type": "number",
      "description": "The start of the schedule"
    },
    "finish": {
      "type": "number",
      "description": "The end of the schedule"
    },
    "breaks": {
      "type": "array",
      "description": "The breaks taken in the schedule"
    },
    "automatic_break_length": {
      "type": "number",
      "description": "Length of automatic break in minutes"
    },
    "department_id": {
      "type": "number",
      "description": "The department (team) id for the schedule"
    },
    "shift_detail_id": {
      "type": "number",
      "description": "The shift detail id for the schedule"
    },
    "cost": {
      "type": "number",
      "description": "The cost of the schedule, if `show_costs=true` parameter is set"
    },
    "last_published_at": {
      "type": "number",
      "description": "When the schedule was last published to its given employee"
    }
  },
  "required": [
    "id",
    "roster_id"
  ]
}

Get Schedule
GET/api/v2/schedules/{id}{?show_costs,include_names}

Get a schedule by id.

If you are not able to see the schedule through the UI then you will not be able to see it through the API.

This method requires the roster scope (see Scopes for more information).

If you are using show_costs=true, the cost scope is also required.

URI Parameters
HideShow
id
number (required) Example: 31337157

The id of the schedule

show_costs
boolean (optional) Example: true

Whether to show the costs for the schedule (defaults to false)

include_names
boolean (optional) Example: false

If true, the department name and shift detail name (not just ID) will be included in the response. Defaults to false.

PUT https://my.tanda.co/api/v2/schedules/31337157
RequestsUpdate ScheduleMake Schedule vacantGive Schedule automatic break
Headers
Content-Type: application/json
Body
{
  "start": 1456898400,
  "breaks": [
    {
      "start": 1456903800,
      "finish": 1456905600
    },
    {
      "start": 1456909200,
      "finish": 1456911000
    }
  ],
  "automatic_break_length": null,
  "department_id": null
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 31337157,
  "roster_id": 70074,
  "user_id": 123456,
  "start": 1456898400,
  "finish": 1456916400,
  "breaks": [
    {
      "start": 1456903800,
      "finish": 1456905600
    },
    {
      "start": 1456909200,
      "finish": 1456911000
    }
  ],
  "automatic_break_length": null,
  "department_id": null,
  "shift_detail_id": null,
  "last_published_at": null
}
Headers
Content-Type: application/json
Body
{
  "user_id": nil
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 31337157,
  "roster_id": 70074,
  "user_id": null,
  "start": 1456902000,
  "finish": 1456916400,
  "breaks": [
    {
      "start": 1456909200,
      "finish": 1456911000
    }
  ],
  "department_id": 111,
  "shift_detail_id": null,
  "last_published_at": null
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the schedule"
    },
    "roster_id": {
      "type": "number",
      "description": "The id of the roster"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who is assigned the schedule"
    },
    "start": {
      "type": "number",
      "description": "The start of the schedule"
    },
    "finish": {
      "type": "number",
      "description": "The end of the schedule"
    },
    "breaks": {
      "type": "array",
      "description": "The breaks taken in the schedule"
    },
    "automatic_break_length": {
      "type": "number",
      "description": "Length of automatic break in minutes"
    },
    "department_id": {
      "type": "number",
      "description": "The department (team) id for the schedule"
    },
    "shift_detail_id": {
      "type": "number",
      "description": "The shift detail id for the schedule"
    },
    "cost": {
      "type": "number",
      "description": "The cost of the schedule, if `show_costs=true` parameter is set"
    },
    "last_published_at": {
      "type": "number",
      "description": "When the schedule was last published to its given employee"
    }
  },
  "required": [
    "id",
    "roster_id"
  ]
}
Headers
Content-Type: application/json
Body
{
  "automatic_break_length": 25,
  "breaks": null
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 31337157,
  "roster_id": 70074,
  "user_id": 123456,
  "start": 1456902000,
  "finish": 1456916400,
  "breaks": [],
  "automatic_break_length": 25,
  "department_id": 111,
  "shift_detail_id": null,
  "last_published_at": null
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the schedule"
    },
    "roster_id": {
      "type": "number",
      "description": "The id of the roster"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who is assigned the schedule"
    },
    "start": {
      "type": "number",
      "description": "The start of the schedule"
    },
    "finish": {
      "type": "number",
      "description": "The end of the schedule"
    },
    "breaks": {
      "type": "array",
      "description": "The breaks taken in the schedule"
    },
    "automatic_break_length": {
      "type": "number",
      "description": "Length of automatic break in minutes"
    },
    "department_id": {
      "type": "number",
      "description": "The department (team) id for the schedule"
    },
    "shift_detail_id": {
      "type": "number",
      "description": "The shift detail id for the schedule"
    },
    "cost": {
      "type": "number",
      "description": "The cost of the schedule, if `show_costs=true` parameter is set"
    },
    "last_published_at": {
      "type": "number",
      "description": "When the schedule was last published to its given employee"
    }
  },
  "required": [
    "id",
    "roster_id"
  ]
}

Update Schedule
PUT/api/v2/schedules/{id}

Only one of breaks and automatic_break_length can be set to non-null values. If automatic_break_length or breaks is already set, you will not be able to change the other unless the set field is cleared (can be done in the same request by setting the currently set field to null).

This method requires the roster scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 31337157

The id of the schedule

DELETE https://my.tanda.co/api/v2/schedules/31337157
Responses200
Headers
Content-Type: application/json

Delete Schedule
DELETE/api/v2/schedules/{id}

This method requires the roster scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 31337157

The id of the schedule

Schedule Versions

GET https://my.tanda.co/api/v2/schedules/31337157/versions
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "version_id": 123456,
    "time": 1459209907,
    "event": "update",
    "author": {
      "id": 123456,
      "name": "API v2"
    },
    "changes": [
      {
        "field": "start",
        "previous": 1456898400,
        "updated": 1456902000
      },
      {
        "field": "finish",
        "previous": 1456912800,
        "updated": 1456916400
      }
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Schedule Versions
GET/api/v2/schedules/{id}/versions

If you are not able to see the schedule through the UI then you will not be able to see it through the API.

This method requires the roster scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 31337157

The id of the schedule

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified schedule versions

Timesheets

Timesheets are the container for actual shifts worked, a timesheet can be for a period of 1 or 2 weeks depending on how the organisation pays their staff. Each timesheet contains many Shifts. For rostered times, please see Rosters or Schedules.

Timesheets are not created directly. Instead a timesheet will be created when creating through the Shifts endpoint.

Regular employees can only see their own timesheets, roster managers and admins can see all timesheets, and department managers can only see timesheets for staff that they manage.

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

GET https://my.tanda.co/api/v2/timesheets/current?show_costs=true&show_award_interpretation=true
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 7007,
    "user_id": 123456,
    "start": "2016-02-29",
    "finish": "2016-03-14",
    "status": "approved",
    "shifts": [
      {
        "id": 1337,
        "timesheet_id": 7007,
        "user_id": 123456,
        "date": "2016-03-02",
        "start": 1456902118,
        "break_start": 1456908143,
        "break_finish": 1456909812,
        "break_length": 27,
        "finish": 1456916286,
        "status": "PENDING",
        "allowances": [
          {
            "id": 456789,
            "name": "Hazardous Environment Allowance",
            "value": 0.5,
            "cost": 1.75
          }
        ],
        "tag": "Head Technician",
        "tag_id": 65421,
        "sub_cost_centre": "0212",
        "cost": 20.1,
        "award_interpretation": [
          {
            "units": 6.45,
            "date": "2016-02-29",
            "export_name": "ORD 1x",
            "ordinary_hours": true,
            "cost": 16.125,
            "from": 1456902000,
            "to": 1456916400
          }
        ],
        "department_id": 808,
        "metadata": "My special metadata",
        "leave_request_id": 333
      }
    ],
    "cost": 102.15,
    "award_interpretation": [
      {
        "units": 6.45,
        "date": "2016-02-29",
        "export_name": "ORD 1x",
        "ordinary_hours": true,
        "cost": 16.125,
        "from": 1456902000,
        "to": 1456916400
      }
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Current Timesheets
GET/api/v2/timesheets/current{?show_costs,show_award_interpretation}

This method requires the timesheet scope (see Scopes for more information).

If you are using show_costs=true or show_award_interpretation=true, the cost scope is also required.

URI Parameters
HideShow
show_costs
boolean (optional) Example: true

Whether to show the costs for the timesheet (defaults to false)

show_award_interpretation
boolean (optional) Example: true

Whether to show award interpretation for the timesheet (defaults to false)

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified timesheets

report_location_id
number (optional) Example: 111

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
string (optional) Example: myob

The format in which timesheet data should be exported. See the Exporting Timesheets section above for more information.

skip_status_update
boolean (optional) Example: true

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
boolean (optional) Example: true

If true, only approved timesheets will be returned. Default is false.

Timesheets on Date

GET https://my.tanda.co/api/v2/timesheets/on/2016-03-02?show_costs=true&show_award_interpretation=true
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 7007,
    "user_id": 123456,
    "start": "2016-02-29",
    "finish": "2016-03-14",
    "status": "approved",
    "shifts": [
      {
        "id": 1337,
        "timesheet_id": 7007,
        "user_id": 123456,
        "date": "2016-03-02",
        "start": 1456902118,
        "break_start": 1456908143,
        "break_finish": 1456909812,
        "break_length": 27,
        "finish": 1456916286,
        "status": "PENDING",
        "allowances": [
          {
            "id": 456789,
            "name": "Hazardous Environment Allowance",
            "value": 0.5,
            "cost": 1.75
          }
        ],
        "tag": "Head Technician",
        "tag_id": 65421,
        "sub_cost_centre": "0212",
        "cost": 20.1,
        "award_interpretation": [
          {
            "units": 6.45,
            "date": "2016-02-29",
            "export_name": "ORD 1x",
            "ordinary_hours": true,
            "cost": 16.125,
            "from": 1456902000,
            "to": 1456916400
          }
        ],
        "department_id": 808,
        "metadata": "My special metadata",
        "leave_request_id": 333
      }
    ],
    "cost": 102.15,
    "award_interpretation": [
      {
        "units": 6.45,
        "date": "2016-02-29",
        "export_name": "ORD 1x",
        "ordinary_hours": true,
        "cost": 16.125,
        "from": 1456902000,
        "to": 1456916400
      }
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Timesheets on Date
GET/api/v2/timesheets/on/{date}{?show_costs,show_award_interpretation}

This method requires the timesheet scope (see Scopes for more information).

If you are using show_costs=true or show_award_interpretation=true, the cost scope is also required.

URI Parameters
HideShow
date
date (required) Example: 2016-03-02

The date included in the timesheet to find

show_costs
boolean (optional) Example: true

Whether to show the costs for the timesheet (defaults to false)

show_award_interpretation
boolean (optional) Example: true

Whether to show award interpretation for the timesheet (defaults to false)

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified timesheets

report_location_id
number (optional) Example: 111

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
string (optional) Example: myob

The format in which timesheet data should be exported. See the Exporting Timesheets section above for more information.

skip_status_update
boolean (optional) Example: true

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
boolean (optional) Example: true

If true, only approved timesheets will be returned. Default is false.

Current Timesheet for User

GET https://my.tanda.co/api/v2/timesheets/for/123456/current?show_costs=true&show_award_interpretation=true
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 7007,
  "user_id": 123456,
  "start": "2016-02-29",
  "finish": "2016-03-14",
  "status": "approved",
  "shifts": [
    {
      "id": 1337,
      "timesheet_id": 7007,
      "user_id": 123456,
      "date": "2016-03-02",
      "start": 1456902118,
      "break_start": 1456908143,
      "break_finish": 1456909812,
      "break_length": 27,
      "finish": 1456916286,
      "status": "PENDING",
      "allowances": [
        {
          "id": 456789,
          "name": "Hazardous Environment Allowance",
          "value": 0.5,
          "cost": 1.75
        }
      ],
      "tag": "Head Technician",
      "tag_id": 65421,
      "sub_cost_centre": "0212",
      "cost": 20.1,
      "award_interpretation": [
        {
          "units": 6.45,
          "date": "2016-02-29",
          "export_name": "ORD 1x",
          "ordinary_hours": true,
          "cost": 16.125,
          "from": 1456902000,
          "to": 1456916400
        }
      ],
      "department_id": 808,
      "metadata": "My special metadata",
      "leave_request_id": 333
    }
  ],
  "cost": 102.15,
  "award_interpretation": [
    {
      "units": 6.45,
      "date": "2016-02-29",
      "export_name": "ORD 1x",
      "ordinary_hours": true,
      "cost": 16.125,
      "from": 1456902000,
      "to": 1456916400
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the timesheet"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who worked the shift"
    },
    "start": {
      "type": "string",
      "description": "The start date of the timesheet"
    },
    "finish": {
      "type": "string",
      "description": "The end date of the timesheet"
    },
    "status": {
      "type": "string",
      "description": "One of `pending`, `approved`, `exported`"
    },
    "shifts": {
      "type": "array",
      "description": "The shifts on the timesheet"
    },
    "cost": {
      "type": "number",
      "description": "The total cost of the timesheet, if `show_costs=true` parameter is set"
    },
    "award_interpretation": {
      "type": "array",
      "description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
    }
  },
  "required": [
    "id",
    "user_id",
    "start",
    "finish",
    "status",
    "shifts"
  ]
}

Get Current Timesheet for User
GET/api/v2/timesheets/for/{user_id}/current{?show_costs,show_award_interpretation}

This method requires the timesheet scope (see Scopes for more information).

If you are using show_costs=true or show_award_interpretation=true, the cost scope is also required.

URI Parameters
HideShow
user_id
number (required) Example: 123456

The user’s id, me can also be used to reference the current user

show_costs
boolean (optional) Example: true

Whether to show the costs for the timesheet (defaults to false)

show_award_interpretation
boolean (optional) Example: true

Whether to show award interpretation for the timesheet (defaults to false)

approved_only
boolean (optional) Example: true

If true, only approved timesheets will be returned. Default is false.

Timesheet for User on Date

GET https://my.tanda.co/api/v2/timesheets/for/123456/on/2016-03-02?show_costs=true&show_award_interpretation=true
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 7007,
  "user_id": 123456,
  "start": "2016-02-29",
  "finish": "2016-03-14",
  "status": "approved",
  "shifts": [
    {
      "id": 1337,
      "timesheet_id": 7007,
      "user_id": 123456,
      "date": "2016-03-02",
      "start": 1456902118,
      "break_start": 1456908143,
      "break_finish": 1456909812,
      "break_length": 27,
      "finish": 1456916286,
      "status": "PENDING",
      "allowances": [
        {
          "id": 456789,
          "name": "Hazardous Environment Allowance",
          "value": 0.5,
          "cost": 1.75
        }
      ],
      "tag": "Head Technician",
      "tag_id": 65421,
      "sub_cost_centre": "0212",
      "cost": 20.1,
      "award_interpretation": [
        {
          "units": 6.45,
          "date": "2016-02-29",
          "export_name": "ORD 1x",
          "ordinary_hours": true,
          "cost": 16.125,
          "from": 1456902000,
          "to": 1456916400
        }
      ],
      "department_id": 808,
      "metadata": "My special metadata",
      "leave_request_id": 333
    }
  ],
  "cost": 102.15,
  "award_interpretation": [
    {
      "units": 6.45,
      "date": "2016-02-29",
      "export_name": "ORD 1x",
      "ordinary_hours": true,
      "cost": 16.125,
      "from": 1456902000,
      "to": 1456916400
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the timesheet"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who worked the shift"
    },
    "start": {
      "type": "string",
      "description": "The start date of the timesheet"
    },
    "finish": {
      "type": "string",
      "description": "The end date of the timesheet"
    },
    "status": {
      "type": "string",
      "description": "One of `pending`, `approved`, `exported`"
    },
    "shifts": {
      "type": "array",
      "description": "The shifts on the timesheet"
    },
    "cost": {
      "type": "number",
      "description": "The total cost of the timesheet, if `show_costs=true` parameter is set"
    },
    "award_interpretation": {
      "type": "array",
      "description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
    }
  },
  "required": [
    "id",
    "user_id",
    "start",
    "finish",
    "status",
    "shifts"
  ]
}

Get Timesheet for User on Date
GET/api/v2/timesheets/for/{user_id}/on/{date}{?show_costs,show_award_interpretation}

This method requires the timesheet scope (see Scopes for more information).

If you are using show_costs=true or show_award_interpretation=true, the cost scope is also required.

URI Parameters
HideShow
user_id
number (required) Example: 123456

The user’s id, me can also be used to reference the current user

date
date (required) Example: 2016-03-02

The date included in the timesheet to find

show_costs
boolean (optional) Example: true

Whether to show the costs for the timesheet (defaults to false)

show_award_interpretation
boolean (optional) Example: true

Whether to show award interpretation for the timesheet (defaults to false)

approved_only
boolean (optional) Example: true

If true, only approved timesheets will be returned. Default is false.

Timesheet

GET https://my.tanda.co/api/v2/timesheets/7007?show_costs=true&show_award_interpretation=true
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 7007,
  "user_id": 123456,
  "start": "2016-02-29",
  "finish": "2016-03-14",
  "status": "approved",
  "shifts": [
    {
      "id": 1337,
      "timesheet_id": 7007,
      "user_id": 123456,
      "date": "2016-03-02",
      "start": 1456902118,
      "break_start": 1456908143,
      "break_finish": 1456909812,
      "break_length": 27,
      "finish": 1456916286,
      "status": "PENDING",
      "allowances": [
        {
          "id": 456789,
          "name": "Hazardous Environment Allowance",
          "value": 0.5,
          "cost": 1.75
        }
      ],
      "tag": "Head Technician",
      "tag_id": 65421,
      "sub_cost_centre": "0212",
      "cost": 20.1,
      "award_interpretation": [
        {
          "units": 6.45,
          "date": "2016-02-29",
          "export_name": "ORD 1x",
          "ordinary_hours": true,
          "cost": 16.125,
          "from": 1456902000,
          "to": 1456916400
        }
      ],
      "department_id": 808,
      "metadata": "My special metadata",
      "leave_request_id": 333
    }
  ],
  "cost": 102.15,
  "award_interpretation": [
    {
      "units": 6.45,
      "date": "2016-02-29",
      "export_name": "ORD 1x",
      "ordinary_hours": true,
      "cost": 16.125,
      "from": 1456902000,
      "to": 1456916400
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the timesheet"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who worked the shift"
    },
    "start": {
      "type": "string",
      "description": "The start date of the timesheet"
    },
    "finish": {
      "type": "string",
      "description": "The end date of the timesheet"
    },
    "status": {
      "type": "string",
      "description": "One of `pending`, `approved`, `exported`"
    },
    "shifts": {
      "type": "array",
      "description": "The shifts on the timesheet"
    },
    "cost": {
      "type": "number",
      "description": "The total cost of the timesheet, if `show_costs=true` parameter is set"
    },
    "award_interpretation": {
      "type": "array",
      "description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
    }
  },
  "required": [
    "id",
    "user_id",
    "start",
    "finish",
    "status",
    "shifts"
  ]
}

Get Timesheet
GET/api/v2/timesheets/{id}{?show_costs,show_award_interpretation}

This method requires the timesheet scope (see Scopes for more information).

If you are using show_costs=true or show_award_interpretation=true, the cost scope is also required.

URI Parameters
HideShow
id
number (required) Example: 7007

The id of the timesheet

show_costs
boolean (optional) Example: true

Whether to show the costs for the timesheet (defaults to false)

show_award_interpretation
boolean (optional) Example: true

Whether to show award interpretation for the timesheet (defaults to false)

approved_only
boolean (optional) Example: true

If true, only approved timesheets will be returned. Default is false.

PUT https://my.tanda.co/api/v2/timesheets/7007
RequestsUpdate Timesheet
Headers
Content-Type: application/json
Body
{
  "status": "pending"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 7007,
  "user_id": 123456,
  "start": "2016-02-29",
  "finish": "2016-03-14",
  "status": "exported",
  "shifts": [
    {
      "id": 1337,
      "timesheet_id": 7007,
      "user_id": 123456,
      "date": "2016-03-02",
      "start": 1456902118,
      "break_start": 1456908143,
      "break_finish": 1456909812,
      "break_length": 27,
      "finish": 1456916286,
      "status": "PENDING",
      "allowances": [
        {
          "id": 456789,
          "name": "Hazardous Environment Allowance",
          "value": 0.5,
          "cost": 1.75
        }
      ],
      "tag": "Head Technician",
      "tag_id": 65421,
      "sub_cost_centre": "0212",
      "cost": 20.1,
      "award_interpretation": [
        {
          "units": 6.45,
          "date": "2016-02-29",
          "export_name": "ORD 1x",
          "ordinary_hours": true,
          "cost": 16.125,
          "from": 1456902000,
          "to": 1456916400
        }
      ],
      "department_id": 808,
      "metadata": "My special metadata",
      "leave_request_id": 333
    }
  ],
  "cost": 102.15,
  "award_interpretation": [
    {
      "units": 6.45,
      "date": "2016-02-29",
      "export_name": "ORD 1x",
      "ordinary_hours": true,
      "cost": 16.125,
      "from": 1456902000,
      "to": 1456916400
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the timesheet"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who worked the shift"
    },
    "start": {
      "type": "string",
      "description": "The start date of the timesheet"
    },
    "finish": {
      "type": "string",
      "description": "The end date of the timesheet"
    },
    "status": {
      "type": "string",
      "description": "One of `pending`, `approved`, `exported`"
    },
    "shifts": {
      "type": "array",
      "description": "The shifts on the timesheet"
    },
    "cost": {
      "type": "number",
      "description": "The total cost of the timesheet, if `show_costs=true` parameter is set"
    },
    "award_interpretation": {
      "type": "array",
      "description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
    }
  },
  "required": [
    "id",
    "user_id",
    "start",
    "finish",
    "status",
    "shifts"
  ]
}

Update Timesheet
PUT/api/v2/timesheets/{id}

Use this endpoint to change a timesheet’s status. Three values are accepted: pending, approved, or exported.

If a timesheet is exported it cannot be edited and its costs are locked. If you are exporting data out of timesheets through the API to be costed externally, you should mark those timesheets as exported at that time.

This method requires the timesheet scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 7007

The id of the timesheet

Shifts

Shifts represent actual times worked for a user and are contained in a Timesheet. For rostered times, please see Rosters or Schedules.

A user can see all the shifts on each timesheet that they can see. Shifts can be created, updated and deleted by staff if they have the ability to see their own timesheets (a system setting). All shifts can be created, updated and deleted by roster managers and admins, and department managers can create, update and delete shifts for staff that they manage.

Shifts

GET https://my.tanda.co/api/v2/shifts?ids=1,2,1337&user_ids=1,2,123456&from=2016-03-02&to=2016-03-02&show_costs=true&show_award_interpretation=true&report_location_id=111
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 1337,
    "timesheet_id": 7007,
    "user_id": 123456,
    "date": "2016-03-02",
    "start": 1456902118,
    "break_start": 1456908143,
    "break_finish": 1456909812,
    "break_length": 27,
    "finish": 1456916286,
    "status": "PENDING",
    "allowances": [
      {
        "id": 456789,
        "name": "Hazardous Environment Allowance",
        "value": 0.5,
        "cost": 1.75
      }
    ],
    "tag": "Head Technician",
    "tag_id": 65421,
    "sub_cost_centre": "0212",
    "cost": 20.1,
    "award_interpretation": [
      {
        "units": 6.45,
        "date": "2016-02-29",
        "export_name": "ORD 1x",
        "ordinary_hours": true,
        "cost": 16.125,
        "from": 1456902000,
        "to": 1456916400
      }
    ],
    "department_id": 808,
    "metadata": "My special metadata",
    "leave_request_id": 333
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Shifts
GET/api/v2/shifts{?ids,user_ids,from,to,show_costs,show_award_interpretation,report_location_id}

Get multiple shifts by IDs, user IDs, or from/to dates.

This method requires the timesheet scope (see Scopes for more information).

If you are using show_costs=true or show_award_interpretation=true, the cost scope is also required.

URI Parameters
HideShow
ids
string (optional) Example: 1,2,1337

Comma separated list of shift IDs

user_ids
string (optional) Example: 1,2,123456

Comma separated list of user IDs

from
string (optional) Example: 2016-03-02

From date to lookup shifts in

to
string (optional) Example: 2016-03-02

To date to lookup shifts in

show_costs
boolean (optional) Example: true

Whether to show the costs for the shift (defaults to false)

show_award_interpretation
boolean (optional) Example: true

Whether to show award interpretation for the shifts (defaults to false)

report_location_id
number (optional) Example: 111

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.

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified shifts

POST https://my.tanda.co/api/v2/shifts
RequestsCreate ShiftCreate Shift with breaksCreate approved ShiftCreate Shift with Allowances
Headers
Content-Type: application/json
Body
{
  "user_id": 123456,
  "date": "2016-03-12",
  "start": 1457741040,
  "finish": 1457762640,
  "department_id": 808,
  "metadata": "My special metadata"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 9665,
  "timesheet_id": 7007,
  "user_id": 123456,
  "date": "2016-03-12",
  "start": 1457741040,
  "break_start": null,
  "break_finish": null,
  "break_length": null,
  "finish": 1457762640,
  "status": "PENDING",
  "allowances": [],
  "tag": null,
  "tag_id": null,
  "sub_cost_centre": null,
  "department_id": 808,
  "metadata": "My special metadata",
  "leave_request_id": null
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the shift"
    },
    "timesheet_id": {
      "type": "number",
      "description": "The id of the timesheet that the shift belongs on"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who worked the shift"
    },
    "date": {
      "type": "string",
      "description": "The date the shift was worked"
    },
    "start": {
      "type": "number",
      "description": "The start of the shift"
    },
    "break_start": {
      "type": "number",
      "description": "The start of the break"
    },
    "break_finish": {
      "type": "number",
      "description": "The end of the break"
    },
    "break_length": {
      "type": "number",
      "description": "The length of the break in minutes (NOTE: this can be different to `(break_finish - break_start) / 60`, see Shifts section)"
    },
    "finish": {
      "type": "number",
      "description": "The end of the shift"
    },
    "status": {
      "type": "string",
      "description": "One of `PENDING`, `APPROVED`"
    },
    "allowances": {
      "type": "array",
      "description": "The allowances that apply to the shift"
    },
    "tag": {
      "type": "string",
      "description": "The name of the tag on the shift  (can use `tag_id` instead)"
    },
    "tag_id": {
      "type": "number",
      "description": "The id of the tag on the shift (can use `tag` instead)"
    },
    "sub_cost_centre": {
      "type": "string",
      "description": "The sub cost centre of the shift"
    },
    "department_id": {
      "type": "number",
      "description": "The ID for the team this shift was worked in"
    }
  },
  "required": [
    "id",
    "timesheet_id",
    "user_id",
    "date",
    "status",
    "allowances"
  ]
}
Headers
Content-Type: application/json
Body
{
  "user_id": 123456,
  "date": "2016-03-12",
  "start": 1457741040,
  "finish": 1457762640,
  "break_start": 1457751660,
  "break_finish": 1457753280,
  "metadata": "My special metadata"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 9665,
  "timesheet_id": 7007,
  "user_id": 123456,
  "date": "2016-03-12",
  "start": 1457741040,
  "break_start": 1457751660,
  "break_finish": 1457753280,
  "break_length": 27,
  "finish": 1457762640,
  "status": "PENDING",
  "allowances": [],
  "tag": "Head Technician",
  "tag_id": 65421,
  "sub_cost_centre": "0212",
  "department_id": 808,
  "metadata": "My special metadata"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the shift"
    },
    "timesheet_id": {
      "type": "number",
      "description": "The id of the timesheet that the shift belongs on"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who worked the shift"
    },
    "date": {
      "type": "string",
      "description": "The date the shift was worked"
    },
    "start": {
      "type": "number",
      "description": "The start of the shift"
    },
    "break_start": {
      "type": "number",
      "description": "The start of the break"
    },
    "break_finish": {
      "type": "number",
      "description": "The end of the break"
    },
    "break_length": {
      "type": "number",
      "description": "The length of the break in minutes (NOTE: this can be different to `(break_finish - break_start) / 60`, see Shifts section)"
    },
    "finish": {
      "type": "number",
      "description": "The end of the shift"
    },
    "status": {
      "type": "string",
      "description": "One of `PENDING`, `APPROVED`"
    },
    "allowances": {
      "description": "The allowances that apply to the shift"
    },
    "tag": {
      "type": "string",
      "description": "The name of the tag on the shift  (can use `tag_id` instead)"
    },
    "tag_id": {
      "type": "number",
      "description": "The id of the tag on the shift (can use `tag` instead)"
    },
    "sub_cost_centre": {
      "type": "string",
      "description": "The sub cost centre of the shift"
    },
    "department_id": {
      "type": "number",
      "description": "The ID for the team this shift was worked in"
    },
    "metadata": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "timesheet_id",
    "user_id",
    "date",
    "status",
    "allowances"
  ]
}
Headers
Content-Type: application/json
Body
{
  "user_id": 123456,
  "date": "2016-03-12",
  "start": 1457741040,
  "finish": 1457762640,
  "status": "APPROVED",
  "tag": null,
  "sub_cost_centre": null
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 9665,
  "timesheet_id": 7007,
  "user_id": 123456,
  "start": 1457741040,
  "break_start": null,
  "break_finish": null,
  "break_length": null,
  "finish": 1457762640,
  "status": "APPROVED",
  "allowances": [],
  "tag": null,
  "tag_id": null,
  "sub_cost_centre": null,
  "metadata": null,
  "leave_request_id": null
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the shift"
    },
    "timesheet_id": {
      "type": "number",
      "description": "The id of the timesheet that the shift belongs on"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who worked the shift"
    },
    "date": {
      "type": "string",
      "description": "The date the shift was worked"
    },
    "start": {
      "type": "number",
      "description": "The start of the shift"
    },
    "break_start": {
      "type": "number",
      "description": "The start of the break"
    },
    "break_finish": {
      "type": "number",
      "description": "The end of the break"
    },
    "break_length": {
      "type": "number",
      "description": "The length of the break in minutes (NOTE: this can be different to `(break_finish - break_start) / 60`, see Shifts section)"
    },
    "finish": {
      "type": "number",
      "description": "The end of the shift"
    },
    "status": {
      "type": "string",
      "description": "One of `PENDING`, `APPROVED`"
    },
    "allowances": {
      "type": "array",
      "description": "The allowances that apply to the shift"
    },
    "tag": {
      "type": "string",
      "description": "The name of the tag on the shift  (can use `tag_id` instead)"
    },
    "tag_id": {
      "type": "number",
      "description": "The id of the tag on the shift (can use `tag` instead)"
    },
    "sub_cost_centre": {
      "type": "string",
      "description": "The sub cost centre of the shift"
    },
    "department_id": {
      "type": "number",
      "description": "The ID for the team this shift was worked in"
    }
  },
  "required": [
    "id",
    "timesheet_id",
    "user_id",
    "date",
    "status",
    "allowances"
  ]
}
Headers
Content-Type: application/json
Body
{
  "user_id": 123456,
  "date": "2016-03-12",
  "start": 1457741040,
  "finish": 1457762640,
  "allowances": [
    {
      "id": 987654,
      "value": 1
    }
  ]
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 9665,
  "timesheet_id": 7007,
  "user_id": 123456,
  "date": "2016-03-12",
  "start": 1457741040,
  "break_start": null,
  "break_finish": null,
  "break_length": null,
  "finish": 1457762640,
  "status": "PENDING",
  "allowances": [
    {
      "id": 987654,
      "value": 1
    }
  ],
  "tag": null,
  "tag_id": null,
  "sub_cost_centre": null,
  "metadata": null,
  "leave_request_id": null
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the shift"
    },
    "timesheet_id": {
      "type": "number",
      "description": "The id of the timesheet that the shift belongs on"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who worked the shift"
    },
    "date": {
      "type": "string",
      "description": "The date the shift was worked"
    },
    "start": {
      "type": "number",
      "description": "The start of the shift"
    },
    "break_start": {
      "type": "number",
      "description": "The start of the break"
    },
    "break_finish": {
      "type": "number",
      "description": "The end of the break"
    },
    "break_length": {
      "type": "number",
      "description": "The length of the break in minutes (NOTE: this can be different to `(break_finish - break_start) / 60`, see Shifts section)"
    },
    "finish": {
      "type": "number",
      "description": "The end of the shift"
    },
    "status": {
      "type": "string",
      "description": "One of `PENDING`, `APPROVED`"
    },
    "allowances": {
      "type": "array",
      "description": "The allowances that apply to the shift"
    },
    "tag": {
      "type": "string",
      "description": "The name of the tag on the shift  (can use `tag_id` instead)"
    },
    "tag_id": {
      "type": "number",
      "description": "The id of the tag on the shift (can use `tag` instead)"
    },
    "sub_cost_centre": {
      "type": "string",
      "description": "The sub cost centre of the shift"
    },
    "department_id": {
      "type": "number",
      "description": "The ID for the team this shift was worked in"
    }
  },
  "required": [
    "id",
    "timesheet_id",
    "user_id",
    "date",
    "status",
    "allowances"
  ]
}

Create Shift
POST/api/v2/shifts

Create a shift for a user, with specified times, on a specified date.

This will create a timesheet for the user for the given pay period, if one doesn’t exist already. The shift object that is returned will have both an id (to use for Shift lookups) and a timesheet_id (for Timesheet lookups).

When a shift is created, the times provided for the start, finish, break_start, and break_finish keys will be rounded to the nearest minute. To avoid potentially confusing, you can round them before passing them to the API.

This method requires the timesheet scope (see Scopes for more information).

Shift

GET https://my.tanda.co/api/v2/shifts/1337?show_costs=true&show_award_interpretation=true
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 1337,
  "timesheet_id": 7007,
  "user_id": 123456,
  "date": "2016-03-02",
  "start": 1456902118,
  "break_start": 1456908143,
  "break_finish": 1456909812,
  "break_length": 27,
  "finish": 1456916286,
  "status": "PENDING",
  "allowances": [
    {
      "id": 456789,
      "name": "Hazardous Environment Allowance",
      "value": 0.5,
      "cost": 1.75
    }
  ],
  "tag": "Head Technician",
  "tag_id": 65421,
  "sub_cost_centre": "0212",
  "cost": 20.1,
  "award_interpretation": [
    {
      "units": 6.45,
      "date": "2016-02-29",
      "export_name": "ORD 1x",
      "ordinary_hours": true,
      "cost": 16.125,
      "from": 1456902000,
      "to": 1456916400
    }
  ],
  "department_id": 808,
  "metadata": "My special metadata",
  "leave_request_id": 333
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the shift"
    },
    "timesheet_id": {
      "type": "number",
      "description": "The id of the timesheet that the shift belongs on"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who worked the shift"
    },
    "date": {
      "type": "string",
      "description": "The date the shift was worked"
    },
    "start": {
      "type": "number",
      "description": "The start of the shift"
    },
    "break_start": {
      "type": "number",
      "description": "The start of the break"
    },
    "break_finish": {
      "type": "number",
      "description": "The end of the break"
    },
    "break_length": {
      "type": "number",
      "description": "The length of the break in minutes (NOTE: this can be different to `(break_start - break_finish) / 60`, see Shifts section)"
    },
    "finish": {
      "type": "number",
      "description": "The end of the shift"
    },
    "status": {
      "type": "string",
      "description": "One of `PENDING`, `APPROVED`"
    },
    "allowances": {
      "type": "array",
      "description": "The allowances that apply to the shift"
    },
    "tag": {
      "type": "string",
      "description": "The name of the tag on the shift (can use `tag_id` instead)"
    },
    "tag_id": {
      "type": "number",
      "description": "The id of the tag on the shift (can use `tag` instead)"
    },
    "sub_cost_centre": {
      "type": "string",
      "description": "The sub cost centre of the shift"
    },
    "cost": {
      "type": "number",
      "description": "The cost of the shift, if `show_costs=true` parameter is set"
    },
    "award_interpretation": {
      "type": "array",
      "description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
    },
    "department_id": {
      "type": "number",
      "description": "The ID for the team this shift was worked in"
    },
    "metadata": {
      "type": "string",
      "description": "Custom string field that holds up to 500 characters"
    },
    "leave_request_id": {
      "type": "number",
      "description": "The ID for the leave request, if leave was taken, otherwise null."
    }
  },
  "required": [
    "id",
    "timesheet_id",
    "user_id",
    "date",
    "status",
    "allowances"
  ]
}

Get Shift
GET/api/v2/shifts/{id}{?show_costs,show_award_interpretation}

Get a shift by id.

This method requires the timesheet scope (see Scopes for more information).

If you are using show_costs=true or show_award_interpretation=true, the cost scope is also required.

URI Parameters
HideShow
id
number (required) Example: 1337

The id of the shift

show_costs
boolean (optional) Example: true

Whether to show the costs for the shift (defaults to false)

show_award_interpretation
boolean (optional) Example: true

Whether to show award interpretation for the shifts (defaults to false)

PUT https://my.tanda.co/api/v2/shifts/1337
RequestsApprove ShiftUpdate Shift timesUpdate Shift times on new dateManually set Shift's break lengthUpdate Shift allowances
Headers
Content-Type: application/json
Body
{
  "status": "APPROVED"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 1337,
  "timesheet_id": 7007,
  "user_id": 123456,
  "date": "2016-03-02",
  "start": 1456902118,
  "break_start": 1456908143,
  "break_finish": 1456909812,
  "break_length": 27,
  "finish": 1456916286,
  "status": "APPROVED",
  "allowances": [
    {
      "id": 456789,
      "name": "Hazardous Environment Allowance",
      "value": 0.5,
      "cost": 1.75
    }
  ],
  "tag": "Head Technician",
  "tag_id": 65421,
  "sub_cost_centre": "0212",
  "cost": 20.1,
  "award_interpretation": [
    {
      "units": 6.45,
      "date": "2016-02-29",
      "export_name": "ORD 1x",
      "ordinary_hours": true,
      "cost": 16.125,
      "from": 1456902000,
      "to": 1456916400
    }
  ],
  "department_id": 808,
  "metadata": "My special metadata",
  "leave_request_id": 333
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the shift"
    },
    "timesheet_id": {
      "type": "number",
      "description": "The id of the timesheet that the shift belongs on"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who worked the shift"
    },
    "date": {
      "type": "string",
      "description": "The date the shift was worked"
    },
    "start": {
      "type": "number",
      "description": "The start of the shift"
    },
    "break_start": {
      "type": "number",
      "description": "The start of the break"
    },
    "break_finish": {
      "type": "number",
      "description": "The end of the break"
    },
    "break_length": {
      "type": "number",
      "description": "The length of the break in minutes (NOTE: this can be different to `(break_start - break_finish) / 60`, see Shifts section)"
    },
    "finish": {
      "type": "number",
      "description": "The end of the shift"
    },
    "status": {
      "type": "string",
      "description": "One of `PENDING`, `APPROVED`"
    },
    "allowances": {
      "type": "array",
      "description": "The allowances that apply to the shift"
    },
    "tag": {
      "type": "string",
      "description": "The name of the tag on the shift (can use `tag_id` instead)"
    },
    "tag_id": {
      "type": "number",
      "description": "The id of the tag on the shift (can use `tag` instead)"
    },
    "sub_cost_centre": {
      "type": "string",
      "description": "The sub cost centre of the shift"
    },
    "cost": {
      "type": "number",
      "description": "The cost of the shift, if `show_costs=true` parameter is set"
    },
    "award_interpretation": {
      "type": "array",
      "description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
    },
    "department_id": {
      "type": "number",
      "description": "The ID for the team this shift was worked in"
    },
    "metadata": {
      "type": "string",
      "description": "Custom string field that holds up to 500 characters"
    },
    "leave_request_id": {
      "type": "number",
      "description": "The ID for the leave request, if leave was taken, otherwise null."
    }
  },
  "required": [
    "id",
    "timesheet_id",
    "user_id",
    "date",
    "status",
    "allowances"
  ]
}
Headers
Content-Type: application/json
Body
{
  "start": 1456901518,
  "finish": 1456916886
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 1337,
  "timesheet_id": 7007,
  "user_id": 123456,
  "date": "2016-03-02",
  "start": 1456901518,
  "break_start": 1456908143,
  "break_finish": 1456909812,
  "break_length": 27,
  "finish": 1456916886,
  "status": "PENDING",
  "allowances": [
    {
      "id": 456789,
      "name": "Hazardous Environment Allowance",
      "value": 0.5,
      "cost": 1.75
    }
  ],
  "tag": "Head Technician",
  "tag_id": 65421,
  "sub_cost_centre": "0212",
  "cost": 20.1,
  "award_interpretation": [
    {
      "units": 6.45,
      "date": "2016-02-29",
      "export_name": "ORD 1x",
      "ordinary_hours": true,
      "cost": 16.125,
      "from": 1456902000,
      "to": 1456916400
    }
  ],
  "department_id": 808,
  "metadata": "My special metadata",
  "leave_request_id": 333
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the shift"
    },
    "timesheet_id": {
      "type": "number",
      "description": "The id of the timesheet that the shift belongs on"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who worked the shift"
    },
    "date": {
      "type": "string",
      "description": "The date the shift was worked"
    },
    "start": {
      "type": "number",
      "description": "The start of the shift"
    },
    "break_start": {
      "type": "number",
      "description": "The start of the break"
    },
    "break_finish": {
      "type": "number",
      "description": "The end of the break"
    },
    "break_length": {
      "type": "number",
      "description": "The length of the break in minutes (NOTE: this can be different to `(break_start - break_finish) / 60`, see Shifts section)"
    },
    "finish": {
      "type": "number",
      "description": "The end of the shift"
    },
    "status": {
      "type": "string",
      "description": "One of `PENDING`, `APPROVED`"
    },
    "allowances": {
      "type": "array",
      "description": "The allowances that apply to the shift"
    },
    "tag": {
      "type": "string",
      "description": "The name of the tag on the shift (can use `tag_id` instead)"
    },
    "tag_id": {
      "type": "number",
      "description": "The id of the tag on the shift (can use `tag` instead)"
    },
    "sub_cost_centre": {
      "type": "string",
      "description": "The sub cost centre of the shift"
    },
    "cost": {
      "type": "number",
      "description": "The cost of the shift, if `show_costs=true` parameter is set"
    },
    "award_interpretation": {
      "type": "array",
      "description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
    },
    "department_id": {
      "type": "number",
      "description": "The ID for the team this shift was worked in"
    },
    "metadata": {
      "type": "string",
      "description": "Custom string field that holds up to 500 characters"
    },
    "leave_request_id": {
      "type": "number",
      "description": "The ID for the leave request, if leave was taken, otherwise null."
    }
  },
  "required": [
    "id",
    "timesheet_id",
    "user_id",
    "date",
    "status",
    "allowances"
  ]
}
Headers
Content-Type: application/json
Body
{
  "date": "2016-03-03",
  "start": 1456987918,
  "finish": 1457003286,
  "break_start": 1456994543,
  "break_finish": 1456996212
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 1337,
  "timesheet_id": 7007,
  "user_id": 123456,
  "date": "2016-03-03",
  "start": 1456987918,
  "break_start": 1456994543,
  "break_finish": 1456996212,
  "break_length": 27,
  "finish": 1457003286,
  "status": "PENDING",
  "allowances": [
    {
      "id": 456789,
      "name": "Hazardous Environment Allowance",
      "value": 0.5,
      "cost": 1.75
    }
  ],
  "tag": "Head Technician",
  "tag_id": 65421,
  "sub_cost_centre": "0212",
  "cost": 20.1,
  "award_interpretation": [
    {
      "units": 6.45,
      "date": "2016-02-29",
      "export_name": "ORD 1x",
      "ordinary_hours": true,
      "cost": 16.125,
      "from": 1456902000,
      "to": 1456916400
    }
  ],
  "department_id": 808,
  "metadata": "My special metadata",
  "leave_request_id": 333
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the shift"
    },
    "timesheet_id": {
      "type": "number",
      "description": "The id of the timesheet that the shift belongs on"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who worked the shift"
    },
    "date": {
      "type": "string",
      "description": "The date the shift was worked"
    },
    "start": {
      "type": "number",
      "description": "The start of the shift"
    },
    "break_start": {
      "type": "number",
      "description": "The start of the break"
    },
    "break_finish": {
      "type": "number",
      "description": "The end of the break"
    },
    "break_length": {
      "type": "number",
      "description": "The length of the break in minutes (NOTE: this can be different to `(break_start - break_finish) / 60`, see Shifts section)"
    },
    "finish": {
      "type": "number",
      "description": "The end of the shift"
    },
    "status": {
      "type": "string",
      "description": "One of `PENDING`, `APPROVED`"
    },
    "allowances": {
      "type": "array",
      "description": "The allowances that apply to the shift"
    },
    "tag": {
      "type": "string",
      "description": "The name of the tag on the shift (can use `tag_id` instead)"
    },
    "tag_id": {
      "type": "number",
      "description": "The id of the tag on the shift (can use `tag` instead)"
    },
    "sub_cost_centre": {
      "type": "string",
      "description": "The sub cost centre of the shift"
    },
    "cost": {
      "type": "number",
      "description": "The cost of the shift, if `show_costs=true` parameter is set"
    },
    "award_interpretation": {
      "type": "array",
      "description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
    },
    "department_id": {
      "type": "number",
      "description": "The ID for the team this shift was worked in"
    },
    "metadata": {
      "type": "string",
      "description": "Custom string field that holds up to 500 characters"
    },
    "leave_request_id": {
      "type": "number",
      "description": "The ID for the leave request, if leave was taken, otherwise null."
    }
  },
  "required": [
    "id",
    "timesheet_id",
    "user_id",
    "date",
    "status",
    "allowances"
  ]
}
Headers
Content-Type: application/json
Body
{
  "break_length": 35
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 1337,
  "timesheet_id": 7007,
  "user_id": 123456,
  "date": "2016-03-02",
  "start": 1456902118,
  "break_start": 1456908143,
  "break_finish": 1456909812,
  "break_length": 35,
  "finish": 1456916286,
  "status": "PENDING",
  "allowances": [
    {
      "id": 456789,
      "name": "Hazardous Environment Allowance",
      "value": 0.5,
      "cost": 1.75
    }
  ],
  "tag": "Head Technician",
  "tag_id": 65421,
  "sub_cost_centre": "0212",
  "cost": 20.1,
  "award_interpretation": [
    {
      "units": 6.45,
      "date": "2016-02-29",
      "export_name": "ORD 1x",
      "ordinary_hours": true,
      "cost": 16.125,
      "from": 1456902000,
      "to": 1456916400
    }
  ],
  "department_id": 808,
  "metadata": "My special metadata",
  "leave_request_id": 333
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the shift"
    },
    "timesheet_id": {
      "type": "number",
      "description": "The id of the timesheet that the shift belongs on"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who worked the shift"
    },
    "date": {
      "type": "string",
      "description": "The date the shift was worked"
    },
    "start": {
      "type": "number",
      "description": "The start of the shift"
    },
    "break_start": {
      "type": "number",
      "description": "The start of the break"
    },
    "break_finish": {
      "type": "number",
      "description": "The end of the break"
    },
    "break_length": {
      "type": "number",
      "description": "The length of the break in minutes (NOTE: this can be different to `(break_start - break_finish) / 60`, see Shifts section)"
    },
    "finish": {
      "type": "number",
      "description": "The end of the shift"
    },
    "status": {
      "type": "string",
      "description": "One of `PENDING`, `APPROVED`"
    },
    "allowances": {
      "type": "array",
      "description": "The allowances that apply to the shift"
    },
    "tag": {
      "type": "string",
      "description": "The name of the tag on the shift (can use `tag_id` instead)"
    },
    "tag_id": {
      "type": "number",
      "description": "The id of the tag on the shift (can use `tag` instead)"
    },
    "sub_cost_centre": {
      "type": "string",
      "description": "The sub cost centre of the shift"
    },
    "cost": {
      "type": "number",
      "description": "The cost of the shift, if `show_costs=true` parameter is set"
    },
    "award_interpretation": {
      "type": "array",
      "description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
    },
    "department_id": {
      "type": "number",
      "description": "The ID for the team this shift was worked in"
    },
    "metadata": {
      "type": "string",
      "description": "Custom string field that holds up to 500 characters"
    },
    "leave_request_id": {
      "type": "number",
      "description": "The ID for the leave request, if leave was taken, otherwise null."
    }
  },
  "required": [
    "id",
    "timesheet_id",
    "user_id",
    "date",
    "status",
    "allowances"
  ]
}
Headers
Content-Type: application/json
Body
{
  "allowances": [
    {
      "id": 987654,
      "value": 1
    }
  ]
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 1337,
  "timesheet_id": 7007,
  "user_id": 123456,
  "date": "2016-03-02",
  "start": 1456902118,
  "break_start": 1456908143,
  "break_finish": 1456909812,
  "break_length": 27,
  "finish": 1456916286,
  "status": "PENDING",
  "allowances": [
    {
      "id": 987654,
      "value": 1
    },
    {
      "id": 456789,
      "value": 0.5,
      "cost": 1.75
    }
  ],
  "tag": "Head Technician",
  "tag_id": 65421,
  "sub_cost_centre": "0212",
  "cost": 20.1,
  "award_interpretation": [
    {
      "units": 6.45,
      "date": "2016-02-29",
      "export_name": "ORD 1x",
      "ordinary_hours": true,
      "cost": 16.125,
      "from": 1456902000,
      "to": 1456916400
    }
  ],
  "department_id": 808,
  "metadata": "My special metadata",
  "leave_request_id": 333
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the shift"
    },
    "timesheet_id": {
      "type": "number",
      "description": "The id of the timesheet that the shift belongs on"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who worked the shift"
    },
    "date": {
      "type": "string",
      "description": "The date the shift was worked"
    },
    "start": {
      "type": "number",
      "description": "The start of the shift"
    },
    "break_start": {
      "type": "number",
      "description": "The start of the break"
    },
    "break_finish": {
      "type": "number",
      "description": "The end of the break"
    },
    "break_length": {
      "type": "number",
      "description": "The length of the break in minutes (NOTE: this can be different to `(break_start - break_finish) / 60`, see Shifts section)"
    },
    "finish": {
      "type": "number",
      "description": "The end of the shift"
    },
    "status": {
      "type": "string",
      "description": "One of `PENDING`, `APPROVED`"
    },
    "allowances": {
      "type": "array",
      "description": "The allowances that apply to the shift"
    },
    "tag": {
      "type": "string",
      "description": "The name of the tag on the shift (can use `tag_id` instead)"
    },
    "tag_id": {
      "type": "number",
      "description": "The id of the tag on the shift (can use `tag` instead)"
    },
    "sub_cost_centre": {
      "type": "string",
      "description": "The sub cost centre of the shift"
    },
    "cost": {
      "type": "number",
      "description": "The cost of the shift, if `show_costs=true` parameter is set"
    },
    "award_interpretation": {
      "type": "array",
      "description": "Award interpretation output, if `show_award_interpretation=true` parameter is set"
    },
    "department_id": {
      "type": "number",
      "description": "The ID for the team this shift was worked in"
    },
    "metadata": {
      "type": "string",
      "description": "Custom string field that holds up to 500 characters"
    },
    "leave_request_id": {
      "type": "number",
      "description": "The ID for the leave request, if leave was taken, otherwise null."
    }
  },
  "required": [
    "id",
    "timesheet_id",
    "user_id",
    "date",
    "status",
    "allowances"
  ]
}

Update Shift
PUT/api/v2/shifts/{id}

When a shift is updated, 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.

It is possible for a shift’s break_length to be different to (break_finish - break_start) / 60.

If you would like to manually set the shift’s break length, set the break_length field to be the shift’s break length in minutes in a POST or PUT request. This can also be changed through the Tanda UI. When this happens, the shift’s break length is marked internally as being overridden.

If you want the break length to be recalculated and the overridden flag removed, change the shift’s break_start or break_finish in a PUT request or through the UI. At this stage the break_length will also update.

This method requires the timesheet scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 1337

The id of the shift

DELETE https://my.tanda.co/api/v2/shifts/1337
Responses200
Headers
Content-Type: application/json

Delete Shift
DELETE/api/v2/shifts/{id}

This method requires the timesheet scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 1337

The id of the shift

Shift's Applicable Allowances

GET https://my.tanda.co/api/v2/shifts/1337/applicable_allowances
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 456789,
    "name": "Hazardous Environment Allowance",
    "export_name": "HE Allowance",
    "current_value": 0.5
  },
  {
    "id": 987654,
    "name": "Meal Allowance"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Shift's Applicable Allowances
GET/api/v2/shifts/{id}/applicable_allowances

Our user guide has more information on working with allowances through the API.

Get list of manually applied allowances that can apply to a shift, along with the current amount currently applied to the given shift.

The allowance IDs returned will be the same for all shifts within the organisation, but the values may differ from shift to shift.

Allowances that are configured to apply automatically will not be returned by this endpoint. They will update automatically every time a shift is saved.

This method requires the timesheet scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 1337

The id of the shift

Shift Versions

GET https://my.tanda.co/api/v2/shifts/1337/versions
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "version_id": 123456,
    "time": 1459209907,
    "event": "update",
    "author": {
      "id": 123456,
      "name": "API v2"
    },
    "changes": [
      {
        "field": "finish",
        "previous": 1456916286,
        "updated": 1456916300
      },
      {
        "field": "status",
        "previous": "PENDING",
        "updated": "APPROVED"
      }
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Shift Versions
GET/api/v2/shifts/{id}/versions

This method requires the timesheet scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 1337

The id of the shift

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified shift versions

Staff (Users)

There are no special system permissions to see information about the current user /users/me. However, to CRUD users in the organisation, the user will need to be a payroll officer, department manager, roster manager, or admin.

User List

GET https://my.tanda.co/api/v2/users?show_wages=true
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 123456,
    "name": "Lenny Leonard",
    "date_of_birth": "1955-05-12",
    "employment_start_date": "1989-12-17",
    "employee_id": "LL1",
    "passcode": "0456",
    "user_levels": [
      "employee",
      "manager",
      "organisation_admin"
    ],
    "department_ids": [
      111
    ],
    "preferred_hours": 20,
    "award": {
      "name": "Fast Food Industry",
      "identifier": "MA000003",
      "note": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_id` field instead."
    },
    "award_template_id": 990,
    "award_tag_ids": [
      3816
    ],
    "report_department_id": 111,
    "managed_department_ids": [
      222
    ],
    "active": true,
    "email": "lenny.leonard@springfieldpowerplant.com",
    "photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
    "phone": "0404 123 123",
    "normalised_phone": "+61404123123",
    "salary": 1234.12,
    "hourly_rate": 32.47,
    "time_zone": "Australia/Brisbane",
    "utc_offset": 36000,
    "part_time_fixed_hours": 20,
    "expected_hours_in_pay_period": 38,
    "days_overtime_averaged_over": 7,
    "overtime_calculated_over_period_start": "2016-09-12",
    "qualifications": {
      "enabled": true,
      "license_number": "ABC123",
      "expires": "2012-10-20",
      "in_training": false
    },
    "created_at": 1430715548
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Users
GET/api/v2/users{?show_wages}

Gets information about all visible users.

This method requires the user scope (see Scopes for more information).

If you are using show_wages=true, the cost scope is also required.

If you want to see financial data, you’ll need the financial scope.

URI Parameters
HideShow
show_wages
boolean (optional) Example: true

Whether to show the user’s wage (defaults to false)

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified users

report_location_id
number (optional) Example: 111

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.

POST https://my.tanda.co/api/v2/users
RequestsCreate UserCreate basic User
Headers
Content-Type: application/json
Body
{
  "name": "Carlton Carlson Jr.",
  "employee_id": "CC123",
  "passcode": "6789",
  "phone": "+61408123654",
  "date_of_birth": "1956-09-25",
  "employment_start_date": "1986-09-24",
  "email": "carl.carlson@springfieldpowerplant.com",
  "report_department_id": 111,
  "preferred_hours": 22,
  "award_template_id": 990,
  "award_tag_ids": [
    3816
  ],
  "department_ids": [
    111
  ],
  "managed_department_ids": [
    111
  ],
  "user_levels": [
    "roster_manager",
    "employee"
  ],
  "yearly_salary": 40000
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 12345678,
  "name": "Carlton Carlson Jr.",
  "employee_id": "CC123",
  "passcode": "6789",
  "phone": "+61408123654",
  "normalised_phone": "+61408123654",
  "user_levels": [
    "manager",
    "roster_manager",
    "employee"
  ],
  "preferred_hours": 22,
  "award": null,
  "award_template_id": 990,
  "award_tag_ids": [
    3816
  ],
  "department_ids": [
    111
  ],
  "date_of_birth": "1956-09-25",
  "employment_start_date": "1986-09-24",
  "email": "carl.carlson@springfieldpowerplant.com",
  "report_department_id": 111,
  "managed_department_ids": [
    111
  ],
  "active": true,
  "time_zone": "Australia/Brisbane",
  "utc_offset": 36000,
  "created_at": 1459476813
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the user"
    },
    "name": {
      "type": "string",
      "description": "The user's name"
    },
    "date_of_birth": {
      "type": "string",
      "description": "The user's date of birth"
    },
    "employment_start_date": {
      "type": "string",
      "description": "The user's employment start date"
    },
    "employee_id": {
      "type": "string",
      "description": "The user's employee id, used for external systems"
    },
    "passcode": {
      "type": "string",
      "description": "The user's system passcode (used for clocking in and out)"
    },
    "user_levels": {
      "type": "array",
      "description": "The user's privilege levels in the system, must be in set of `['organisation_admin', 'payroll_officer', 'roster_manager', 'employee', 'partner']`"
    },
    "department_ids": {
      "type": "array",
      "description": "The department (team) ids that the user is a member of"
    },
    "preferred_hours": {
      "type": "number",
      "description": "The preferred number of hours to be rostered each week"
    },
    "award": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the award"
        },
        "identifier": {
          "type": "string",
          "description": "The award's identifier (will be the award code for all modern awards)"
        },
        "note": {
          "type": "string",
          "description": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_id` field instead."
        }
      },
      "required": [
        "name"
      ],
      "description": "Information about the user's award, null if user isn't on award"
    },
    "award_template_id": {
      "type": "number",
      "description": "The ID of the award template thte user is on"
    },
    "award_tag_ids": {
      "type": "array",
      "description": "The award tag ids that apply to the user"
    },
    "report_department_id": {
      "type": "number",
      "description": "The user's default team"
    },
    "managed_department_ids": {
      "type": "array",
      "description": "The department ids that this user manages"
    },
    "active": {
      "type": "boolean",
      "description": "Whether the user is active in the system"
    },
    "email": {
      "type": "string",
      "description": "The user's email"
    },
    "photo": {
      "type": "string",
      "description": "An avatar for the user"
    },
    "phone": {
      "type": "string",
      "description": "Phone number for the user"
    },
    "normalised_phone": {
      "type": "string",
      "description": "Phone number for user with international dialing code"
    },
    "time_zone": {
      "type": "string",
      "description": "The user's time zone"
    },
    "utc_offset": {
      "type": "number",
      "description": "The user's time zone's UTC offset"
    },
    "oauth_provider": {
      "type": "string",
      "description": "If oAuth login enabled, login provider"
    },
    "oauth_uid": {
      "type": "string",
      "description": "If oAuth login enabled, login UID"
    },
    "part_time_fixed_hours": {
      "type": "number",
      "description": "readonly: for part time staff, can be used to configure when overtime starts to apply"
    },
    "expected_hours_in_pay_period": {
      "type": "number",
      "description": "readonly: for salaried staff, defines expected number of hours worked per pay period"
    },
    "days_overtime_averaged_over": {
      "type": "number",
      "description": "readonly: date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run"
    },
    "overtime_calculated_over_period_start": {
      "type": "string",
      "description": "readonly: date from which overtime averaging periods should commence"
    },
    "created_at": {
      "type": "number",
      "description": "When the user's Tanda profile was created"
    }
  },
  "required": [
    "id",
    "name",
    "passcode",
    "user_levels",
    "department_ids",
    "preferred_hours",
    "award_tag_ids",
    "active",
    "utc_offset",
    "created_at"
  ]
}
Headers
Content-Type: application/json
Body
{
  "name": "Carlton Carlson Jr."
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 12345678,
  "name": "Carlton Carlson Jr.",
  "employee_id": null,
  "passcode": null,
  "phone": null,
  "normalised_phone": null,
  "user_levels": [
    "employee"
  ],
  "preferred_hours": 22,
  "award": null,
  "award_template_id": null,
  "award_tag_ids": [],
  "department_ids": [],
  "date_of_birth": null,
  "employment_start_date": null,
  "email": null,
  "report_department_id": null,
  "managed_department_ids": [],
  "active": true,
  "time_zone": "Australia/Brisbane",
  "utc_offset": 36000,
  "created_at": 1459476813
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the user"
    },
    "name": {
      "type": "string",
      "description": "The user's name"
    },
    "date_of_birth": {
      "type": "string",
      "description": "The user's date of birth"
    },
    "employment_start_date": {
      "type": "string",
      "description": "The user's employment start date"
    },
    "employee_id": {
      "type": "string",
      "description": "The user's employee id, used for external systems"
    },
    "passcode": {
      "type": "string",
      "description": "The user's system passcode (used for clocking in and out)"
    },
    "user_levels": {
      "type": "array",
      "description": "The user's privilege levels in the system, must be in set of `['organisation_admin', 'payroll_officer', 'roster_manager', 'employee', 'partner']`"
    },
    "department_ids": {
      "type": "array",
      "description": "The department (team) ids that the user is a member of"
    },
    "preferred_hours": {
      "type": "number",
      "description": "The preferred number of hours to be rostered each week"
    },
    "award": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the award"
        },
        "identifier": {
          "type": "string",
          "description": "The award's identifier (will be the award code for all modern awards)"
        },
        "note": {
          "type": "string",
          "description": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_id` field instead."
        }
      },
      "required": [
        "name"
      ],
      "description": "Information about the user's award, null if user isn't on award"
    },
    "award_template_id": {
      "type": "number",
      "description": "The ID of the award template thte user is on"
    },
    "award_tag_ids": {
      "type": "array",
      "description": "The award tag ids that apply to the user"
    },
    "report_department_id": {
      "type": "number",
      "description": "The user's default team"
    },
    "managed_department_ids": {
      "type": "array",
      "description": "The department ids that this user manages"
    },
    "active": {
      "type": "boolean",
      "description": "Whether the user is active in the system"
    },
    "email": {
      "type": "string",
      "description": "The user's email"
    },
    "photo": {
      "type": "string",
      "description": "An avatar for the user"
    },
    "phone": {
      "type": "string",
      "description": "Phone number for the user"
    },
    "normalised_phone": {
      "type": "string",
      "description": "Phone number for user with international dialing code"
    },
    "time_zone": {
      "type": "string",
      "description": "The user's time zone"
    },
    "utc_offset": {
      "type": "number",
      "description": "The user's time zone's UTC offset"
    },
    "oauth_provider": {
      "type": "string",
      "description": "If oAuth login enabled, login provider"
    },
    "oauth_uid": {
      "type": "string",
      "description": "If oAuth login enabled, login UID"
    },
    "part_time_fixed_hours": {
      "type": "number",
      "description": "readonly: for part time staff, can be used to configure when overtime starts to apply"
    },
    "expected_hours_in_pay_period": {
      "type": "number",
      "description": "readonly: for salaried staff, defines expected number of hours worked per pay period"
    },
    "days_overtime_averaged_over": {
      "type": "number",
      "description": "readonly: date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run"
    },
    "overtime_calculated_over_period_start": {
      "type": "string",
      "description": "readonly: date from which overtime averaging periods should commence"
    },
    "created_at": {
      "type": "number",
      "description": "When the user's Tanda profile was created"
    }
  },
  "required": [
    "id",
    "name",
    "passcode",
    "user_levels",
    "department_ids",
    "preferred_hours",
    "award_tag_ids",
    "active",
    "utc_offset",
    "created_at"
  ]
}

Create User
POST/api/v2/users

Only the name field is required to create a user.

To create a manager, you should provide the IDs of Teams they manage in the managed_department_ids field. Note that setting “manager” in the user_levels field will not work. For a user to be a manager, Tanda must know which teams they manage.

This method requires the user scope (see Scopes for more information).

If you plan to assign wage information you will need the cost scope. This includes the employee_id field.

To set financial information, you will need the financial scope.

Inactive User List

GET https://my.tanda.co/api/v2/users/inactive
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 1234567,
    "name": "Homer Simpson",
    "employee_id": "HS98",
    "passcode": "1230",
    "user_levels": [
      "employee"
    ],
    "department_ids": [
      111
    ],
    "preferred_hours": 22,
    "award": {
      "name": "Fast Food Industry",
      "identifier": "MA000003"
    },
    "award_tag_ids": [],
    "report_department_id": 111,
    "managed_department_ids": [],
    "active": false,
    "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
  }
]

Get Inactive Users
GET/api/v2/users/inactive

This method requires the user scope (see Scopes for more information).

URI Parameters
HideShow
updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified users

User

GET https://my.tanda.co/api/v2/users/123456?show_wages=true
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 123456,
  "name": "Lenny Leonard",
  "date_of_birth": "1955-05-12",
  "employment_start_date": "1989-12-17",
  "employee_id": "LL1",
  "passcode": "0456",
  "user_levels": [
    "employee",
    "manager",
    "organisation_admin"
  ],
  "department_ids": [
    111
  ],
  "preferred_hours": 20,
  "award": {
    "name": "Fast Food Industry",
    "identifier": "MA000003",
    "note": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_id` field instead."
  },
  "award_template_id": 990,
  "award_tag_ids": [
    3816
  ],
  "report_department_id": 111,
  "managed_department_ids": [
    222
  ],
  "active": true,
  "email": "lenny.leonard@springfieldpowerplant.com",
  "photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
  "phone": "0404 123 123",
  "normalised_phone": "+61404123123",
  "salary": 1234.12,
  "hourly_rate": 32.47,
  "time_zone": "Australia/Brisbane",
  "utc_offset": 36000,
  "part_time_fixed_hours": 20,
  "expected_hours_in_pay_period": 38,
  "days_overtime_averaged_over": 7,
  "overtime_calculated_over_period_start": "2016-09-12",
  "qualifications": {
    "enabled": true,
    "license_number": "ABC123",
    "expires": "2012-10-20",
    "in_training": false
  },
  "created_at": 1430715548
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the user"
    },
    "name": {
      "type": "string",
      "description": "The user's name"
    },
    "date_of_birth": {
      "type": "string",
      "description": "The user's date of birth"
    },
    "employment_start_date": {
      "type": "string",
      "description": "The user's employment start date"
    },
    "employee_id": {
      "type": "string",
      "description": "The user's employee id, used for external systems"
    },
    "passcode": {
      "type": "string",
      "description": "The user's system passcode (used for clocking in and out)"
    },
    "user_levels": {
      "type": "array",
      "description": "The user's privilege levels in the system, must be in set of `['organisation_admin', 'payroll_officer', 'roster_manager', 'employee', 'partner']`"
    },
    "department_ids": {
      "type": "array",
      "description": "The department (team) ids that the user is a member of"
    },
    "preferred_hours": {
      "type": "number",
      "description": "The preferred number of hours to be rostered each week"
    },
    "award": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the award"
        },
        "identifier": {
          "type": "string",
          "description": "The award's identifier (will be the award code for all modern awards)"
        },
        "note": {
          "type": "string",
          "description": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_id` field instead."
        }
      },
      "required": [
        "name"
      ],
      "description": "Information about the user's award, null if user isn't on award"
    },
    "award_template_id": {
      "type": "number",
      "description": "The ID of the award template thte user is on"
    },
    "award_tag_ids": {
      "type": "array",
      "description": "The award tag ids that apply to the user"
    },
    "report_department_id": {
      "type": "number",
      "description": "The user's default team"
    },
    "managed_department_ids": {
      "type": "array",
      "description": "The department ids that this user manages"
    },
    "active": {
      "type": "boolean",
      "description": "Whether the user is active in the system"
    },
    "email": {
      "type": "string",
      "description": "The user's email"
    },
    "photo": {
      "type": "string",
      "description": "An avatar for the user"
    },
    "phone": {
      "type": "string",
      "description": "Phone number for the user"
    },
    "normalised_phone": {
      "type": "string",
      "description": "Phone number for user with international dialing code"
    },
    "salary": {
      "type": "number",
      "description": "The weekly salary of the user, if `show_wages=true` parameter is set"
    },
    "hourly_rate": {
      "type": "number",
      "description": "The hourly rate of the user, if `show_wages=true` parameter is set, will not show if the salary exists"
    },
    "time_zone": {
      "type": "string",
      "description": "The user's time zone"
    },
    "utc_offset": {
      "type": "number",
      "description": "The user's time zone's UTC offset"
    },
    "part_time_fixed_hours": {
      "type": "number",
      "description": "readonly: for part time staff, can be used to configure when overtime starts to apply"
    },
    "expected_hours_in_pay_period": {
      "type": "number",
      "description": "readonly: for salaried staff, defines expected number of hours worked per pay period"
    },
    "days_overtime_averaged_over": {
      "type": "number",
      "description": "readonly: date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run"
    },
    "overtime_calculated_over_period_start": {
      "type": "string",
      "description": "readonly: date from which overtime averaging periods should commence"
    },
    "qualifications": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "license_number": {
          "type": "string"
        },
        "expires": {
          "type": "string"
        },
        "in_training": {
          "type": "boolean"
        }
      },
      "description": "Information about qualifications the user holds, if Qualifications are enabled"
    },
    "created_at": {
      "type": "number",
      "description": "When the user's Tanda profile was created"
    }
  },
  "required": [
    "id",
    "name",
    "passcode",
    "user_levels",
    "department_ids",
    "preferred_hours",
    "award_tag_ids",
    "active",
    "utc_offset",
    "created_at"
  ]
}

Get User
GET/api/v2/users/{id}{?show_wages}

Gets information about a user.

This method requires the user scope (see Scopes for more information).

If you are using show_wages=true, the cost scope is also required.

URI Parameters
HideShow
id
number (required) Example: 123456

The id of the user

show_wages
boolean (optional) Example: true

Whether to show the user’s wage (defaults to false)

PUT https://my.tanda.co/api/v2/users/123456
RequestsUpdate UserDeactivate UserRemove Departments
Headers
Content-Type: application/json
Body
{
  "name": "Lenford Leonard",
  "employee_id": "Lenford",
  "passcode": "0123",
  "phone": "0404123122",
  "date_of_birth": "1990-12-12",
  "employment_start_date": "2016-03-01",
  "email": "some_email@test.com",
  "hourly_rate": 12.34,
  "user_levels": [
    "employee"
  ]
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 123456,
  "name": "Lenford Leonard",
  "date_of_birth": "1990-12-12",
  "employment_start_date": "2016-03-01",
  "employee_id": "Lenford",
  "passcode": "0123",
  "user_levels": [
    "employee"
  ],
  "department_ids": [
    111
  ],
  "preferred_hours": 20,
  "award": {
    "name": "Fast Food Industry",
    "identifier": "MA000003",
    "note": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_id` field instead."
  },
  "award_template_id": 990,
  "award_tag_ids": [
    3816
  ],
  "report_department_id": 111,
  "managed_department_ids": [
    222
  ],
  "active": true,
  "email": "some_email@test.com",
  "photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
  "phone": "0404123122",
  "normalised_phone": "+61404123122",
  "salary": 1234.12,
  "hourly_rate": 12.34,
  "time_zone": "Australia/Brisbane",
  "utc_offset": 36000,
  "part_time_fixed_hours": 20,
  "expected_hours_in_pay_period": 38,
  "days_overtime_averaged_over": 7,
  "overtime_calculated_over_period_start": "2016-09-12",
  "qualifications": {
    "enabled": true,
    "license_number": "ABC123",
    "expires": "2012-10-20",
    "in_training": false
  },
  "created_at": 1430715548
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the user"
    },
    "name": {
      "type": "string",
      "description": "The user's name"
    },
    "date_of_birth": {
      "type": "string",
      "description": "The user's date of birth"
    },
    "employment_start_date": {
      "type": "string",
      "description": "The user's employment start date"
    },
    "employee_id": {
      "type": "string",
      "description": "The user's employee id, used for external systems"
    },
    "passcode": {
      "type": "string",
      "description": "The user's system passcode (used for clocking in and out)"
    },
    "user_levels": {
      "type": "array",
      "description": "The user's privilege levels in the system, must be in set of `['organisation_admin', 'payroll_officer', 'roster_manager', 'employee', 'partner']`"
    },
    "department_ids": {
      "type": "array",
      "description": "The department (team) ids that the user is a member of"
    },
    "preferred_hours": {
      "type": "number",
      "description": "The preferred number of hours to be rostered each week"
    },
    "award": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the award"
        },
        "identifier": {
          "type": "string",
          "description": "The award's identifier (will be the award code for all modern awards)"
        },
        "note": {
          "type": "string",
          "description": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_id` field instead."
        }
      },
      "required": [
        "name"
      ],
      "description": "Information about the user's award, null if user isn't on award"
    },
    "award_template_id": {
      "type": "number",
      "description": "The ID of the award template thte user is on"
    },
    "award_tag_ids": {
      "type": "array",
      "description": "The award tag ids that apply to the user"
    },
    "report_department_id": {
      "type": "number",
      "description": "The user's default team"
    },
    "managed_department_ids": {
      "type": "array",
      "description": "The department ids that this user manages"
    },
    "active": {
      "type": "boolean",
      "description": "Whether the user is active in the system"
    },
    "email": {
      "type": "string",
      "description": "The user's email"
    },
    "photo": {
      "type": "string",
      "description": "An avatar for the user"
    },
    "phone": {
      "type": "string",
      "description": "Phone number for the user"
    },
    "normalised_phone": {
      "type": "string",
      "description": "Phone number for user with international dialing code"
    },
    "salary": {
      "type": "number",
      "description": "The weekly salary of the user, if `show_wages=true` parameter is set"
    },
    "hourly_rate": {
      "type": "number",
      "description": "The hourly rate of the user, if `show_wages=true` parameter is set, will not show if the salary exists"
    },
    "time_zone": {
      "type": "string",
      "description": "The user's time zone"
    },
    "utc_offset": {
      "type": "number",
      "description": "The user's time zone's UTC offset"
    },
    "part_time_fixed_hours": {
      "type": "number",
      "description": "readonly: for part time staff, can be used to configure when overtime starts to apply"
    },
    "expected_hours_in_pay_period": {
      "type": "number",
      "description": "readonly: for salaried staff, defines expected number of hours worked per pay period"
    },
    "days_overtime_averaged_over": {
      "type": "number",
      "description": "readonly: date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run"
    },
    "overtime_calculated_over_period_start": {
      "type": "string",
      "description": "readonly: date from which overtime averaging periods should commence"
    },
    "qualifications": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "license_number": {
          "type": "string"
        },
        "expires": {
          "type": "string"
        },
        "in_training": {
          "type": "boolean"
        }
      },
      "description": "Information about qualifications the user holds, if Qualifications are enabled"
    },
    "created_at": {
      "type": "number",
      "description": "When the user's Tanda profile was created"
    }
  },
  "required": [
    "id",
    "name",
    "passcode",
    "user_levels",
    "department_ids",
    "preferred_hours",
    "award_tag_ids",
    "active",
    "utc_offset",
    "created_at"
  ]
}
Headers
Content-Type: application/json
Body
{
  "active": false
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 123456,
  "name": "Lenny Leonard",
  "date_of_birth": "1955-05-12",
  "employment_start_date": "1989-12-17",
  "employee_id": "LL1",
  "passcode": "01234568975461",
  "user_levels": [
    "employee",
    "manager",
    "organisation_admin"
  ],
  "department_ids": [
    111
  ],
  "preferred_hours": 20,
  "award": {
    "name": "Fast Food Industry",
    "identifier": "MA000003",
    "note": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_id` field instead."
  },
  "award_template_id": 990,
  "award_tag_ids": [
    3816
  ],
  "report_department_id": 111,
  "managed_department_ids": [
    222
  ],
  "active": false,
  "email": "lenny.leonard@springfieldpowerplant.com",
  "photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
  "phone": "0404 123 123",
  "normalised_phone": "+61404123123",
  "salary": 1234.12,
  "hourly_rate": 32.47,
  "time_zone": "Australia/Brisbane",
  "utc_offset": 36000,
  "part_time_fixed_hours": 20,
  "expected_hours_in_pay_period": 38,
  "days_overtime_averaged_over": 7,
  "overtime_calculated_over_period_start": "2016-09-12",
  "qualifications": {
    "enabled": true,
    "license_number": "ABC123",
    "expires": "2012-10-20",
    "in_training": false
  },
  "created_at": 1430715548
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the user"
    },
    "name": {
      "type": "string",
      "description": "The user's name"
    },
    "date_of_birth": {
      "type": "string",
      "description": "The user's date of birth"
    },
    "employment_start_date": {
      "type": "string",
      "description": "The user's employment start date"
    },
    "employee_id": {
      "type": "string",
      "description": "The user's employee id, used for external systems"
    },
    "passcode": {
      "type": "string",
      "description": "The user's system passcode (used for clocking in and out)"
    },
    "user_levels": {
      "type": "array",
      "description": "The user's privilege levels in the system, must be in set of `['organisation_admin', 'payroll_officer', 'roster_manager', 'employee', 'partner']`"
    },
    "department_ids": {
      "type": "array",
      "description": "The department (team) ids that the user is a member of"
    },
    "preferred_hours": {
      "type": "number",
      "description": "The preferred number of hours to be rostered each week"
    },
    "award": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the award"
        },
        "identifier": {
          "type": "string",
          "description": "The award's identifier (will be the award code for all modern awards)"
        },
        "note": {
          "type": "string",
          "description": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_id` field instead."
        }
      },
      "required": [
        "name"
      ],
      "description": "Information about the user's award, null if user isn't on award"
    },
    "award_template_id": {
      "type": "number",
      "description": "The ID of the award template thte user is on"
    },
    "award_tag_ids": {
      "type": "array",
      "description": "The award tag ids that apply to the user"
    },
    "report_department_id": {
      "type": "number",
      "description": "The user's default team"
    },
    "managed_department_ids": {
      "type": "array",
      "description": "The department ids that this user manages"
    },
    "active": {
      "type": "boolean",
      "description": "Whether the user is active in the system"
    },
    "email": {
      "type": "string",
      "description": "The user's email"
    },
    "photo": {
      "type": "string",
      "description": "An avatar for the user"
    },
    "phone": {
      "type": "string",
      "description": "Phone number for the user"
    },
    "normalised_phone": {
      "type": "string",
      "description": "Phone number for user with international dialing code"
    },
    "salary": {
      "type": "number",
      "description": "The weekly salary of the user, if `show_wages=true` parameter is set"
    },
    "hourly_rate": {
      "type": "number",
      "description": "The hourly rate of the user, if `show_wages=true` parameter is set, will not show if the salary exists"
    },
    "time_zone": {
      "type": "string",
      "description": "The user's time zone"
    },
    "utc_offset": {
      "type": "number",
      "description": "The user's time zone's UTC offset"
    },
    "part_time_fixed_hours": {
      "type": "number",
      "description": "readonly: for part time staff, can be used to configure when overtime starts to apply"
    },
    "expected_hours_in_pay_period": {
      "type": "number",
      "description": "readonly: for salaried staff, defines expected number of hours worked per pay period"
    },
    "days_overtime_averaged_over": {
      "type": "number",
      "description": "readonly: date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run"
    },
    "overtime_calculated_over_period_start": {
      "type": "string",
      "description": "readonly: date from which overtime averaging periods should commence"
    },
    "qualifications": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "license_number": {
          "type": "string"
        },
        "expires": {
          "type": "string"
        },
        "in_training": {
          "type": "boolean"
        }
      },
      "description": "Information about qualifications the user holds, if Qualifications are enabled"
    },
    "created_at": {
      "type": "number",
      "description": "When the user's Tanda profile was created"
    }
  },
  "required": [
    "id",
    "name",
    "passcode",
    "user_levels",
    "department_ids",
    "preferred_hours",
    "award_tag_ids",
    "active",
    "utc_offset",
    "created_at"
  ]
}
Headers
Content-Type: application/json
Body
{
  "department_ids": null
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 123456,
  "name": "Lenny Leonard",
  "date_of_birth": "1955-05-12",
  "employment_start_date": "1989-12-17",
  "employee_id": "LL1",
  "passcode": "0456",
  "user_levels": [
    "employee",
    "manager",
    "organisation_admin"
  ],
  "department_ids": [],
  "preferred_hours": 20,
  "award": {
    "name": "Fast Food Industry",
    "identifier": "MA000003",
    "note": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_id` field instead."
  },
  "award_template_id": 990,
  "award_tag_ids": [
    3816
  ],
  "report_department_id": 111,
  "managed_department_ids": [
    222
  ],
  "active": true,
  "email": "lenny.leonard@springfieldpowerplant.com",
  "photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
  "phone": "0404 123 123",
  "normalised_phone": "+61404123123",
  "salary": 1234.12,
  "hourly_rate": 32.47,
  "time_zone": "Australia/Brisbane",
  "utc_offset": 36000,
  "part_time_fixed_hours": 20,
  "expected_hours_in_pay_period": 38,
  "days_overtime_averaged_over": 7,
  "overtime_calculated_over_period_start": "2016-09-12",
  "created_at": 1430715548
}

Update User
PUT/api/v2/users/{id}

This method requires the user scope (see Scopes for more information).

If you plan to update wage information you will need the cost scope. This includes the employee_id field.

To set financial information, you will need the financial scope.

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.

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.

URI Parameters
HideShow
id
number (required) Example: 123456

The id of the user

DELETE https://my.tanda.co/api/v2/users/654321
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 123456,
  "name": "Lenny Leonard",
  "date_of_birth": "1955-05-12",
  "employment_start_date": "1989-12-17",
  "employee_id": "LL1",
  "passcode": "01234568975461",
  "user_levels": [
    "employee",
    "manager",
    "organisation_admin"
  ],
  "department_ids": [
    111
  ],
  "preferred_hours": 20,
  "award": {
    "name": "Fast Food Industry",
    "identifier": "MA000003",
    "note": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_id` field instead."
  },
  "award_template_id": 990,
  "award_tag_ids": [
    3816
  ],
  "report_department_id": 111,
  "managed_department_ids": [
    222
  ],
  "active": false,
  "email": "lenny.leonard@springfieldpowerplant.com",
  "photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
  "phone": "0404 123 123",
  "normalised_phone": "+61404123123",
  "salary": 1234.12,
  "hourly_rate": 32.47,
  "time_zone": "Australia/Brisbane",
  "utc_offset": 36000,
  "part_time_fixed_hours": 20,
  "expected_hours_in_pay_period": 38,
  "days_overtime_averaged_over": 7,
  "overtime_calculated_over_period_start": "2016-09-12",
  "qualifications": {
    "enabled": true,
    "license_number": "ABC123",
    "expires": "2012-10-20",
    "in_training": false
  },
  "created_at": 1430715548
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the user"
    },
    "name": {
      "type": "string",
      "description": "The user's name"
    },
    "date_of_birth": {
      "type": "string",
      "description": "The user's date of birth"
    },
    "employment_start_date": {
      "type": "string",
      "description": "The user's employment start date"
    },
    "employee_id": {
      "type": "string",
      "description": "The user's employee id, used for external systems"
    },
    "passcode": {
      "type": "string",
      "description": "The user's system passcode (used for clocking in and out)"
    },
    "user_levels": {
      "type": "array",
      "description": "The user's privilege levels in the system, must be in set of `['organisation_admin', 'payroll_officer', 'roster_manager', 'employee', 'partner']`"
    },
    "department_ids": {
      "type": "array",
      "description": "The department (team) ids that the user is a member of"
    },
    "preferred_hours": {
      "type": "number",
      "description": "The preferred number of hours to be rostered each week"
    },
    "award": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the award"
        },
        "identifier": {
          "type": "string",
          "description": "The award's identifier (will be the award code for all modern awards)"
        },
        "note": {
          "type": "string",
          "description": "This field is deprecated, and may be removed in the future. Please rely on the `award_template_id` field instead."
        }
      },
      "required": [
        "name"
      ],
      "description": "Information about the user's award, null if user isn't on award"
    },
    "award_template_id": {
      "type": "number",
      "description": "The ID of the award template thte user is on"
    },
    "award_tag_ids": {
      "type": "array",
      "description": "The award tag ids that apply to the user"
    },
    "report_department_id": {
      "type": "number",
      "description": "The user's default team"
    },
    "managed_department_ids": {
      "type": "array",
      "description": "The department ids that this user manages"
    },
    "active": {
      "type": "boolean",
      "description": "Whether the user is active in the system"
    },
    "email": {
      "type": "string",
      "description": "The user's email"
    },
    "photo": {
      "type": "string",
      "description": "An avatar for the user"
    },
    "phone": {
      "type": "string",
      "description": "Phone number for the user"
    },
    "normalised_phone": {
      "type": "string",
      "description": "Phone number for user with international dialing code"
    },
    "salary": {
      "type": "number",
      "description": "The weekly salary of the user, if `show_wages=true` parameter is set"
    },
    "hourly_rate": {
      "type": "number",
      "description": "The hourly rate of the user, if `show_wages=true` parameter is set, will not show if the salary exists"
    },
    "time_zone": {
      "type": "string",
      "description": "The user's time zone"
    },
    "utc_offset": {
      "type": "number",
      "description": "The user's time zone's UTC offset"
    },
    "part_time_fixed_hours": {
      "type": "number",
      "description": "readonly: for part time staff, can be used to configure when overtime starts to apply"
    },
    "expected_hours_in_pay_period": {
      "type": "number",
      "description": "readonly: for salaried staff, defines expected number of hours worked per pay period"
    },
    "days_overtime_averaged_over": {
      "type": "number",
      "description": "readonly: date range (weekly, fortnightly, or 4-weekly) over which overtime calculations should run"
    },
    "overtime_calculated_over_period_start": {
      "type": "string",
      "description": "readonly: date from which overtime averaging periods should commence"
    },
    "qualifications": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "license_number": {
          "type": "string"
        },
        "expires": {
          "type": "string"
        },
        "in_training": {
          "type": "boolean"
        }
      },
      "description": "Information about qualifications the user holds, if Qualifications are enabled"
    },
    "created_at": {
      "type": "number",
      "description": "When the user's Tanda profile was created"
    }
  },
  "required": [
    "id",
    "name",
    "passcode",
    "user_levels",
    "department_ids",
    "preferred_hours",
    "award_tag_ids",
    "active",
    "utc_offset",
    "created_at"
  ]
}

Delete User
DELETE/api/v2/users/{id}

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

This method requires the user scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 654321

The id of the user

Invite Users

POST https://my.tanda.co/api/v2/users/654321/invite
Responses201
Headers
Content-Type: application/json

Invite User
POST/api/v2/users/{id}/invite

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

This method requires the user scope (see Scopes for more information).

It also requires the following prerequisites to work

  • User must exist

  • You must be able to manage the User

  • The User must have an email and it must be valid

  • The User must not have already signed up

  • The User must not already have a valid invitation

Failure to meet these pre reqs will result in a returned 400, 403 or 404. Otherwise a 201 CREATED will be returned

URI Parameters
HideShow
id
number (required) Example: 654321

The id of the user

Invite Users for Onboarding

POST https://my.tanda.co/api/v2/users/onboarding
RequestsCreate User for Onboarding
Headers
Content-Type: application/json
Body
{
  "name": "Eddard Sheppard",
  "email": "carl.carlson@springfieldpowerplant.com",
  "phone": "+61408123654"
}
Responses201
Headers
Content-Type: application/json

Invite User for Onboarding
POST/api/v2/users/onboarding

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

Clocked In Users

GET https://my.tanda.co/api/v2/users/clocked_in
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "user_id": 123456,
    "shift_id": 1337
  }
]

Get Clocked In Users
GET/api/v2/users/clocked_in

Gets a list of staff who are currently at work. Essentially this looks for valid shifts that have a start time but no end time. The shift’s ID is also returned.

This method requires the user and timesheet scopes (see Scopes for more information).

URI Parameters
HideShow
updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified users

User Versions

GET https://my.tanda.co/api/v2/users/123456/versions
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "version_id": 123456,
    "time": 1459209907,
    "event": "update",
    "author": {
      "id": 123456,
      "name": "API v2"
    },
    "changes": [
      {
        "field": "name",
        "previous": "Lenny L Leonard",
        "updated": "Lenny Leonard"
      },
      {
        "field": "preferred_hours",
        "previous": 28,
        "updated": 20
      }
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get User Versions
GET/api/v2/users/{id}/versions

This method requires the user scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 123456

The id of the user

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified user versions

Locations

Admins and general managers can CRUD locations. Team managers can read locations which contain teams they manage.

Public Holiday Regions

HideShow

CLick "show" to see a list of Tanda supported public holiday regions.

Region CodeRegion Name
auAustralia (national holidays only)
au_actAustralian Capital Territory
au_nswNew South Wales
au_ntNorthern Territory
au_qldQueensland
au_saSouth Australia
au_tasTasmania
au_vicVictoria
au_waWestern Australia
gbUnited Kingdom (national holidays only)
gb_engEngland
gb_nirNorthern Island
gb_sctScotland
gb_wlsWales
jpJapan (national holidays)
nzNew Zealand (national holidays)
usUnited States of America (national holidays)
zaSouth Africa (national holidays)
phThe Philippines (national holidays)
viVietnam (national holidays)
caCanada (national holidays)

You can see holiday dates in your System Settings.

Location List

GET https://my.tanda.co/api/v2/locations
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 111,
    "name": "Springfield",
    "short_name": "S",
    "latitude": -27.459687,
    "longitude": 153.032108,
    "address": "Springfield Powerplant Reactors",
    "time_zone": "Australia/Brisbane",
    "public_holiday_regions": [
      "au",
      "au_qld"
    ],
    "specific_holiday_dates": [
      {
        "date": "2016-08-08",
        "from": 8,
        "to": 17
      }
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Locations
GET/api/v2/locations

This method requires the department scope (see Scopes for more information).

URI Parameters
HideShow
updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified locations

POST https://my.tanda.co/api/v2/locations
RequestsCreate LocationCreate basic Location
Headers
Content-Type: application/json
Body
{
  "name": "Springfield",
  "short_name": "S",
  "latitude": -27.467004,
  "longitude": 153.025453,
  "address": "Springfield Powerplant Logistics Centre",
  "public_holiday_regions": [
    "au"
  ],
  "specific_holiday_dates": [
    {
      "date": "2016-03-14"
    },
    {
      "date": "2016-08-08",
      "from": 12,
      "to": 17
    }
  ]
}
Responses200
Headers
Content-Type: application/json
Body
{
  "name": "Springfield",
  "short_name": "S",
  "latitude": -27.467004,
  "longitude": 153.025453,
  "address": "Springfield Powerplant Logistics Centre",
  "time_zone": null,
  "public_holiday_regions": [
    "au"
  ],
  "specific_holiday_dates": [
    {
      "date": "2016-03-14"
    },
    {
      "date": "2016-08-08",
      "from": 12,
      "to": 17
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "name": "Springfield"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 801,
  "name": "Springfield",
  "short_name": null,
  "latitude": null,
  "longitude": null,
  "address": null,
  "time_zone": null,
  "public_holiday_regions": [],
  "specific_holiday_dates": [],
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the location"
    },
    "name": {
      "type": "string",
      "description": "The name of the location"
    },
    "short_name": {
      "type": "string",
      "description": "The abbreviated form of the location's name"
    },
    "latitude": {
      "type": "number",
      "description": "The latitude of the location"
    },
    "longitude": {
      "type": "number",
      "description": "The longitude of the location"
    },
    "address": {
      "type": "string",
      "description": "Address of the location"
    },
    "time_zone": {
      "type": "string",
      "description": "The location's time zone"
    },
    "public_holiday_regions": {
      "type": "array",
      "description": "Public holiday regions (see Locations section for list of options)"
    },
    "specific_holiday_dates": {
      "type": "array",
      "description": "The dates and times of specific holidays for the location"
    }
  },
  "required": [
    "id",
    "name",
    "time_zone"
  ]
}

Create Location
POST/api/v2/locations

Use this endpoint to create a Location object. Location objects should have addresses, but the field is not mandatory - you can create a Location with just a name (though it will not be as useful).

If an address is provided, latitude and longitude are also required.

This method requires the department scope (see Scopes for more information).

Location

GET https://my.tanda.co/api/v2/locations/111
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 111,
  "name": "Springfield",
  "short_name": "S",
  "latitude": -27.459687,
  "longitude": 153.032108,
  "address": "Springfield Powerplant Reactors",
  "time_zone": "Australia/Brisbane",
  "public_holiday_regions": [
    "au",
    "au_qld"
  ],
  "specific_holiday_dates": [
    {
      "date": "2016-08-08",
      "from": 8,
      "to": 17
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the location"
    },
    "name": {
      "type": "string",
      "description": "The name of the location"
    },
    "short_name": {
      "type": "string",
      "description": "The abbreviated form of the location's name"
    },
    "latitude": {
      "type": "number",
      "description": "The latitude of the location"
    },
    "longitude": {
      "type": "number",
      "description": "The longitude of the location"
    },
    "address": {
      "type": "string",
      "description": "Address of the location"
    },
    "time_zone": {
      "type": "string",
      "description": "The location's time zone"
    },
    "public_holiday_regions": {
      "type": "array",
      "description": "Public holiday regions (see Locations section for list of options)"
    },
    "specific_holiday_dates": {
      "type": "array",
      "description": "The dates and times of specific holidays for the location"
    }
  },
  "required": [
    "id",
    "name",
    "time_zone"
  ]
}

Get Location
GET/api/v2/locations/{id}

This method requires the department scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 111

The id of the location

PUT https://my.tanda.co/api/v2/locations/111
RequestsUpdate Location
Headers
Content-Type: application/json
Body
{
  "name": "Shelbyville"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 111,
  "name": "Shelbyville",
  "short_name": "S",
  "latitude": -27.459687,
  "longitude": 153.032108,
  "address": "Springfield Powerplant Reactors",
  "time_zone": "Australia/Brisbane",
  "public_holiday_regions": [
    "au",
    "au_qld"
  ],
  "specific_holiday_dates": [
    {
      "date": "2016-08-08",
      "from": 8,
      "to": 17
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the location"
    },
    "name": {
      "type": "string",
      "description": "The name of the location"
    },
    "short_name": {
      "type": "string",
      "description": "The abbreviated form of the location's name"
    },
    "latitude": {
      "type": "number",
      "description": "The latitude of the location"
    },
    "longitude": {
      "type": "number",
      "description": "The longitude of the location"
    },
    "address": {
      "type": "string",
      "description": "Address of the location"
    },
    "time_zone": {
      "type": "string",
      "description": "The location's time zone"
    },
    "public_holiday_regions": {
      "type": "array",
      "description": "Public holiday regions (see Locations section for list of options)"
    },
    "specific_holiday_dates": {
      "type": "array",
      "description": "The dates and times of specific holidays for the location"
    }
  },
  "required": [
    "id",
    "name",
    "time_zone"
  ]
}

Update Location
PUT/api/v2/locations/{id}

This method requires the department scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 111

The id of the location

DELETE https://my.tanda.co/api/v2/locations/111
Responses200
Headers
Content-Type: application/json

Delete Location
DELETE/api/v2/locations/{id}

This method requires the department scope (see Scopes for more information).

Locations cannot be deleted if they have any teams.

URI Parameters
HideShow
id
number (required) Example: 111

The id of the location

Location Versions

GET https://my.tanda.co/api/v2/locations/111/versions
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "version_id": 123456,
    "time": 1459209907,
    "event": "update",
    "author": {
      "id": 123456,
      "name": "API v2"
    },
    "changes": [
      {
        "field": "name",
        "previous": "Spring field",
        "updated": "Springfield"
      },
      {
        "field": "longitude",
        "previous": 153.032108,
        "updated": 100.500169
      }
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Location Versions
GET/api/v2/locations/{id}/versions

This method requires the department scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 111

The id of the location

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified location versions

Teams (Departments)

Departments are often referred to as Teams inside Tanda. Teams belong to a Location.

Department managers can read and update information about the departments they manage. Admins can CRUD departments. Employees can read the departments that they belong to, with a subset of fields (see below)

Team List

GET https://my.tanda.co/api/v2/departments
RequestsAs a managerAs an employee
This response has no content.
Responses200
Body
[
  {
    "id": 808,
    "location_id": 111,
    "name": "Waiters",
    "export_name": "WGB",
    "colour": "#FBB829",
    "staff": [
      1,
      2,
      123456
    ],
    "managers": [
      4,
      5
    ]
  }
]
Schema
{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "number",
        "description": "The id of the team"
      },
      "location_id": {
        "type": "number",
        "description": "The id of the team's location"
      },
      "name": {
        "type": "string",
        "description": "The name of the team"
      },
      "export_name": {
        "type": "string",
        "description": "30 (string) - The payroll export name of the team (if different to the name)"
      },
      "colour": {
        "type": "string",
        "description": "The team's colour"
      },
      "staff": {
        "type": "array",
        "items": {
          "type": "number"
        },
        "description": "The user ids of the staff in the team"
      },
      "managers": {
        "type": "array",
        "items": {
          "type": "number"
        },
        "description": "The user ids of the managers of the team"
      }
    },
    "required": [
      "id",
      "location_id",
      "name"
    ]
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
This response has no content.
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 608,
    "name": "Waiters",
    "location_id": 111,
    "colour": "#FBB830"
  }
]

Get Teams
GET/api/v2/departments

This method requires the department scope (see Scopes for more information).

URI Parameters
HideShow
updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified teams

POST https://my.tanda.co/api/v2/departments
RequestsCreate TeamCreate Basic Team
Headers
Content-Type: application/json
Body
{
  "name": "Waiters",
  "location_id": 111,
  "export_name": "WGB-32",
  "colour": "#FBB830"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 809,
  "location_id": "111",
  "name": "Waiters",
  "export_name": "WGB",
  "colour": "#FBB830",
  "staff": [],
  "managers": []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the team"
    },
    "location_id": {
      "type": "string",
      "description": "The id of the team's location"
    },
    "name": {
      "type": "string",
      "description": "The name of the team"
    },
    "export_name": {
      "type": "string",
      "description": "32"
    },
    "colour": {
      "type": "string",
      "description": "The team's colour"
    },
    "staff": {
      "description": "The user ids of the staff in the team"
    },
    "managers": {
      "description": "The user ids of the managers of the team"
    }
  },
  "required": [
    "id",
    "location_id",
    "name"
  ]
}
Headers
Content-Type: application/json
Body
{
  "name": "Waiters",
  "location_id": "111",
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 809,
  "location_id": 111,
  "name": "Waiters",
  "export_name": null,
  "colour": null,
  "staff": [],
  "managers": []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the team"
    },
    "location_id": {
      "type": "number",
      "description": "The id of the team's location"
    },
    "name": {
      "type": "string",
      "description": "The name of the team"
    },
    "export_name": {
      "type": "string",
      "description": "30 (string) - The payroll export name of the team (if different to the name)"
    },
    "colour": {
      "type": "string",
      "description": "The team's colour"
    },
    "staff": {
      "type": "array",
      "description": "The user ids of the staff in the team"
    },
    "managers": {
      "type": "array",
      "description": "The user ids of the managers of the team"
    }
  },
  "required": [
    "id",
    "location_id",
    "name"
  ]
}

Create Team
POST/api/v2/departments

This method requires the department scope (see Scopes for more information).

Team

GET https://my.tanda.co/api/v2/departments/111
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 808,
  "location_id": 111,
  "name": "Waiters",
  "export_name": "WGB",
  "colour": "#FBB829",
  "staff": [
    1,
    2,
    123456
  ],
  "managers": [
    4,
    5
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the team"
    },
    "location_id": {
      "type": "number",
      "description": "The id of the team's location"
    },
    "name": {
      "type": "string",
      "description": "The name of the team"
    },
    "export_name": {
      "type": "string",
      "description": "30 (string) - The payroll export name of the team (if different to the name)"
    },
    "colour": {
      "type": "string",
      "description": "The team's colour"
    },
    "staff": {
      "type": "array",
      "description": "The user ids of the staff in the team"
    },
    "managers": {
      "type": "array",
      "description": "The user ids of the managers of the team"
    }
  },
  "required": [
    "id",
    "location_id",
    "name"
  ]
}

Get Team
GET/api/v2/departments/{id}

This method requires the department scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 111

The id of the team

PUT https://my.tanda.co/api/v2/departments/111
RequestsUpdate Team
Headers
Content-Type: application/json
Body
{
  "name": "Kitchen Staff"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 808,
  "location_id": 111,
  "name": "Kitchen Staff",
  "export_name": "WGB",
  "colour": "#FBB829",
  "staff": [
    1,
    2,
    123456
  ],
  "managers": [
    4,
    5
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the team"
    },
    "location_id": {
      "type": "number",
      "description": "The id of the team's location"
    },
    "name": {
      "type": "string",
      "description": "The name of the team"
    },
    "export_name": {
      "type": "string",
      "description": "30 (string) - The payroll export name of the team (if different to the name)"
    },
    "colour": {
      "type": "string",
      "description": "The team's colour"
    },
    "staff": {
      "type": "array",
      "description": "The user ids of the staff in the team"
    },
    "managers": {
      "type": "array",
      "description": "The user ids of the managers of the team"
    }
  },
  "required": [
    "id",
    "location_id",
    "name"
  ]
}

Update Team
PUT/api/v2/departments/{id}

This method requires the department scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 111

The id of the team

DELETE https://my.tanda.co/api/v2/departments/111
Responses200
Headers
Content-Type: application/json

Delete Team
DELETE/api/v2/departments/{id}

This method requires the department scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 111

The id of the team

Team Versions

GET https://my.tanda.co/api/v2/departments/111/versions
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "version_id": 123456,
    "time": 1459209907,
    "event": "update",
    "author": {
      "id": 123456,
      "name": "API v2"
    },
    "changes": [
      {
        "field": "name",
        "previous": "Wait staff",
        "updated": "Waiters"
      },
      {
        "field": "colour",
        "previous": "#3FAFD7",
        "updated": "#FBB829"
      }
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Team Versions
GET/api/v2/departments/{id}/versions

This method requires the department scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 111

The id of the team

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified team versions

Shift Details

Shift details belong to a Team, and can be assigned on Schedules within that team.

Teams managers can read and update information about the shift details from the teams they manage. Admins can CRUD shift details.

Shift Detail List

GET https://my.tanda.co/api/v2/shift_details
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 36,
    "department_id": 808,
    "name": "Higher Duties"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Shift Details
GET/api/v2/shift_details

This method requires the department scope (see Scopes for more information).

POST https://my.tanda.co/api/v2/shift_details
RequestsCreate Shift Detail
Headers
Content-Type: application/json
Body
{
  "name": "Manager",
  "department_id": 808
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 532,
  "department_id": "808",
  "name": "Manager"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the shift detail"
    },
    "department_id": {
      "type": "string",
      "description": "The id of the shift detail's department"
    },
    "name": {
      "type": "string",
      "description": "The name of the shift detail"
    }
  },
  "required": [
    "id",
    "department_id",
    "name"
  ]
}

Create Shift Detail
POST/api/v2/shift_details

This method requires the department scope (see Scopes for more information).

Shift Detail

GET https://my.tanda.co/api/v2/shift_details/36
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 36,
  "department_id": 808,
  "name": "Higher Duties"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the shift detail"
    },
    "department_id": {
      "type": "number",
      "description": "The id of the shift detail's department"
    },
    "name": {
      "type": "string",
      "description": "The name of the shift detail"
    }
  },
  "required": [
    "id",
    "department_id",
    "name"
  ]
}

Get Shift Detail
GET/api/v2/shift_details/{id}

This method requires the department scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 36

The id of the shift detail

PUT https://my.tanda.co/api/v2/shift_details/36
RequestsUpdate Shift Detail
Headers
Content-Type: application/json
Body
{
  "name": "Shift Runner"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 36,
  "department_id": 808,
  "name": "Shift Runner"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the shift detail"
    },
    "department_id": {
      "type": "number",
      "description": "The id of the shift detail's department"
    },
    "name": {
      "type": "string",
      "description": "The name of the shift detail"
    }
  },
  "required": [
    "id",
    "department_id",
    "name"
  ]
}

Update Shift Detail
PUT/api/v2/shift_details/{id}

This method requires the department scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 36

The id of the shift detail

DELETE https://my.tanda.co/api/v2/shift_details/36
Responses200
Headers
Content-Type: application/json

Delete Shift Detail
DELETE/api/v2/shift_details/{id}

This method requires the department scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 36

The id of the shift detail

Roles

The roles endpoint has been deprecated. Please migrate your code to use Teams (Departments) instead.

Award Tags

No special permissions are required to read award tags.

Award Tag List

GET https://my.tanda.co/api/v2/award_tags
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 3816,
    "name": "Casual"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Award Tags
GET/api/v2/award_tags

This method requires the user scope (see Scopes for more information).

URI Parameters
HideShow
updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified award tags

Award Tag

GET https://my.tanda.co/api/v2/award_tags/3816
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 3816,
  "name": "Casual"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the award tag"
    },
    "name": {
      "type": "string",
      "description": "The name of the award tag"
    }
  },
  "required": [
    "id",
    "name"
  ]
}

Get Award Tag
GET/api/v2/award_tags/{id}

This method requires the user scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 3816

The id of the Award Tag

Leave Requests

Leave is time formally not worked by an employee, due to things like public holidays, sickness, or by accruing annual leave.

For specifying times when an employee requests not to be rostered, please see Unavailability.

Admins, payroll officers, and roster managers can create, read and update leave requests for all users, and department managers can create, read and update leave requests for users that they manage. Other users are able to create, read and update leave requests for themself. Note that the current user may not update status for their own leave requests unless they are an Admin, payroll officer or roster manager. Deletion of leave requests is not supported.

Leave List

GET https://my.tanda.co/api/v2/leave?ids=1,2,666&from=2016-03-15&to=2016-04-05&user_ids=1,2,123456
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 666,
    "department_id": 808,
    "user_id": 123456,
    "reason": "Terribly Sick",
    "leave_type": "Personal/Carer's Leave",
    "hours": 7.6,
    "start": "2016-04-01",
    "finish": "2016-04-01",
    "status": "pending",
    "multitagging": "false"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Leave List
GET/api/v2/leave{?ids,from,to,user_ids}

Lookup multiple leave requests in a single request.

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

This method requires the leave scope (see Scopes for more information).

You will only be able to query up to 366 days when specifying from and to.

URI Parameters
HideShow
ids
string (optional) Example: 1,2,666

Comma separated list of leave ids to lookup

from
string (optional) Example: 2016-03-15

From date to lookup leave in

to
string (optional) Example: 2016-04-05

To date to lookup leave in

user_ids
string (optional) Example: 1,2,123456

Comma separated list of user ids to lookup leave for

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified leave requests

POST https://my.tanda.co/api/v2/leave
RequestsCreate Leave
Headers
Content-Type: application/json
Body
{
  "reason": "Holiday in France",
  "department_id": 2,
  "user_id": 123456,
  "hours": 114,
  "start": "2016-03-07",
  "finish": "2016-03-27",
  "leave_type": "Annual Leave",
  "status": "pending"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 7250,
  "department_id": 808,
  "user_id": 123456,
  "reason": "Holiday in France",
  "leave_type": "Annual Leave",
  "hours": 114,
  "start": "2016-03-07",
  "finish": "2016-03-27",
  "status": "pending",
  "multitagging": "false"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the leave request"
    },
    "department_id": {
      "type": "number",
      "description": "The id of the team with which the leave request's shifts will be tagged"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who owns the leave request"
    },
    "reason": {
      "type": "string",
      "description": "The reason for the leave request - optional"
    },
    "leave_type": {
      "type": "string",
      "description": "The type of leave request"
    },
    "hours": {
      "type": "number",
      "description": "The number of workable hours the leave request spans"
    },
    "start": {
      "type": "string",
      "description": "The start date for the leave request"
    },
    "finish": {
      "type": "string",
      "description": "The end date for the leave request"
    },
    "status": {
      "type": "string",
      "description": "The status for the leave request. One of ['pending', 'approved', 'rejected']"
    },
    "multitagging": {
      "type": "string",
      "description": "Determines whether shifts on the leave request can be tagged differently."
    }
  },
  "required": [
    "id",
    "user_id",
    "leave_type",
    "hours",
    "start",
    "finish",
    "status"
  ]
}

Create Leave Request
POST/api/v2/leave

Note that a status for a new Leave Request is required. Managers can create approved leave requests for their staff, and themselves if permitted by the organisation settings. Admins can create approved leave requests for all staff. Employees may only create pending leave requests. The server will respond with a 400 when a user creates a leave request violating the above requirements.

Leave request status must be one of: “pending”, “approved”, “rejected”.

When a leave request is created with status “approved”, a Shift will be created for each day the leave request spans, and will be attached to the leave request. If a department_id is passed, these shifts will be categorised with the team corresponding to the department_id. Passing a department_id will have no consequence if the leave request status is “pending” or “rejected”. Note that the department_id will not be returned by the API, since technically it is a property of the shift, not of the leave request.

If you would like a notification email to be sent when the leave request is created, include the send_notification querystring parameter (ie. make your POST to /api/v2/leave?send_notification=true). The notification logic will match that for leave requests created through the Tanda UI. This will only apply for pending leave requests.

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.

This method requires the leave scope (see Scopes for more information).

Leave Request

GET https://my.tanda.co/api/v2/leave/666
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 666,
  "department_id": 808,
  "user_id": 123456,
  "reason": "Terribly Sick",
  "leave_type": "Personal/Carer's Leave",
  "hours": 7.6,
  "start": "2016-04-01",
  "finish": "2016-04-01",
  "status": "pending",
  "multitagging": "false"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the leave request"
    },
    "department_id": {
      "type": "number",
      "description": "The id of the team with which the leave request's shifts will be tagged"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who owns the leave request"
    },
    "reason": {
      "type": "string",
      "description": "The reason for the leave request - optional"
    },
    "leave_type": {
      "type": "string",
      "description": "The type of leave request"
    },
    "hours": {
      "type": "number",
      "description": "The number of workable hours the leave request spans"
    },
    "start": {
      "type": "string",
      "description": "The start date for the leave request"
    },
    "finish": {
      "type": "string",
      "description": "The end date for the leave request"
    },
    "status": {
      "type": "string",
      "description": "The status for the leave request. One of ['pending', 'approved', 'rejected']"
    },
    "multitagging": {
      "type": "string",
      "description": "Determines whether shifts on the leave request can be tagged differently."
    }
  },
  "required": [
    "id",
    "user_id",
    "leave_type",
    "hours",
    "start",
    "finish",
    "status"
  ]
}

Get Leave Request
GET/api/v2/leave/{id}

This method requires the leave scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 666

The id of the leave to lookup

PUT https://my.tanda.co/api/v2/leave/666
RequestsUpdate Leave
Headers
Content-Type: application/json
Body
{
  "reason": "Really Really Sick",
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 666,
  "department_id": 808,
  "user_id": 123456,
  "reason": "Really Really Sick",
  "leave_type": "Personal/Carer's Leave",
  "hours": 7.6,
  "start": "2016-04-01",
  "finish": "2016-04-01",
  "status": "pending",
  "multitagging": "false"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the leave request"
    },
    "department_id": {
      "type": "number",
      "description": "The id of the team with which the leave request's shifts will be tagged"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who owns the leave request"
    },
    "reason": {
      "type": "string",
      "description": "The reason for the leave request - optional"
    },
    "leave_type": {
      "type": "string",
      "description": "The type of leave request"
    },
    "hours": {
      "type": "number",
      "description": "The number of workable hours the leave request spans"
    },
    "start": {
      "type": "string",
      "description": "The start date for the leave request"
    },
    "finish": {
      "type": "string",
      "description": "The end date for the leave request"
    },
    "status": {
      "type": "string",
      "description": "The status for the leave request. One of ['pending', 'approved', 'rejected']"
    },
    "multitagging": {
      "type": "string",
      "description": "Determines whether shifts on the leave request can be tagged differently."
    }
  },
  "required": [
    "id",
    "user_id",
    "leave_type",
    "hours",
    "start",
    "finish",
    "status"
  ]
}

Update Leave Request
PUT/api/v2/leave/{id}

This method requires the leave scope (see Scopes for more information).

Employees cannot update a leave request, with the exception of rejecting their own pending leave request.

URI Parameters
HideShow
id
number (required) Example: 666

The id of the leave to update

Leave Types

GET https://my.tanda.co/api/v2/leave/types_for/123456
Responses200
Headers
Content-Type: application/json
Body
[
  "Annual Leave",
  "Personal/Carer's Leave",
  "Public Holiday (Paid/Not Worked)"
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Leave Types for User
GET/api/v2/leave/types_for/{user_id}

This method requires the leave scope (see Scopes for more information).

URI Parameters
HideShow
user_id
number (required) Example: 123456

The id of the user to lookup leave types for

Leave Request Versions

GET https://my.tanda.co/api/v2/leave/666/versions
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "version_id": 123456,
    "time": 1459209907,
    "event": "update",
    "author": {
      "id": 123456,
      "name": "API v2"
    },
    "changes": [
      {
        "field": "status",
        "previous": "pending",
        "updated": "approved"
      },
      {
        "field": "reason",
        "previous": "Holiday",
        "updated": "Terribly Sick"
      }
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Leave Request Versions
GET/api/v2/leave/{id}/versions

This method requires the leave scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 666

The id of the leave request

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified leave request versions

Default Leave Hours

GET https://my.tanda.co/api/v2/leave/hours_between?user_id=123456&start=2016-03-15&finish=2016-03-17&leave_type=Annual Leave
Responses200
Headers
Content-Type: application/json
Body
{
  "hours": "22.8",
}

Get Default Hours for a Leave Request
GET/api/v2/leave/hours_between{?user_id,start,finish,leave_type}

Use this endpoint to get a recommendation for the number of hours of leave someone should take based on the given dates. This will take into account public holidays and weekends, and the default leave hours setting in an account. For example, if given a date range of 5 days, of which 1 is a weekend and 1 is a holiday, and with a default leave hours setting of 7.6, the endpoint will return 22.8 hours.

This method requires the leave scope (see Scopes for more information).

URI Parameters
HideShow
user_id
number (required) Example: 123456

The id of the user

start
string (required) Example: 2016-03-15

Start date of leave request

finish
string (required) Example: 2016-03-17

Finish date of leave request

leave_type
string (optional) Example: Annual Leave

The leave type

Leave Balances

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

Leave balance interactions require the same permissions as leave requests.

Leave Balance List

GET https://my.tanda.co/api/v2/leave_balances?user_ids=1,2,666
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 666,
    "user_id": 123456,
    "leave_type": "Annual Leave",
    "hours": 4,
    "should_accrue": false
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Leave Balances
GET/api/v2/leave_balances{?user_ids}

Lookup leave balances for one or more user_ids.

This method requires the leave scope (see Scopes for more information).

URI Parameters
HideShow
user_ids
string (optional) Example: 1,2,666

Comma separated list of user ids to lookup leave balances for

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified leave balances

POST https://my.tanda.co/api/v2/leave_balances
RequestsCreate Leave
Headers
Content-Type: application/json
Body
{
  "user_id": 123456,
  "leave_type": "Annual Leave",
  "hours": 18
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 666,
  "user_id": 123456,
  "leave_type": "Annual Leave",
  "hours": 18,
  "should_accrue": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the leave balance"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who owns the leave balance"
    },
    "leave_type": {
      "type": "string",
      "description": "The type of leave"
    },
    "hours": {
      "type": "number",
      "description": "The number of hours of leave accrued"
    },
    "should_accrue": {
      "type": "boolean",
      "description": "If true, this leave balance will accrue in Tanda automatically. If false, you should keep it up to date. Default is false."
    }
  },
  "required": [
    "id",
    "user_id",
    "leave_type",
    "hours"
  ]
}

Create Leave Balance
POST/api/v2/leave_balances

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

This method requires the leave scope (see Scopes for more information).

Leave Balance

GET https://my.tanda.co/api/v2/leave_balances/666
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 666,
  "user_id": 123456,
  "leave_type": "Annual Leave",
  "hours": 4,
  "should_accrue": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the leave balance"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who owns the leave balance"
    },
    "leave_type": {
      "type": "string",
      "description": "The type of leave"
    },
    "hours": {
      "type": "number",
      "description": "The number of hours of leave accrued"
    },
    "should_accrue": {
      "type": "boolean",
      "description": "If true, this leave balance will accrue in Tanda automatically. If false, you should keep it up to date. Default is false."
    }
  },
  "required": [
    "id",
    "user_id",
    "leave_type",
    "hours"
  ]
}

Get Leave Balance
GET/api/v2/leave_balances/{id}

This method requires the leave scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 666

The id of the leave balance to lookup

PUT https://my.tanda.co/api/v2/leave_balances/666
RequestsUpdate Leave
Headers
Content-Type: application/json
Body
{
  "hours": 22.5
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 666,
  "user_id": 123456,
  "leave_type": "Annual Leave",
  "hours": 22.5,
  "should_accrue": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the leave balance"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user who owns the leave balance"
    },
    "leave_type": {
      "type": "string",
      "description": "The type of leave"
    },
    "hours": {
      "type": "number",
      "description": "The number of hours of leave accrued"
    },
    "should_accrue": {
      "type": "boolean",
      "description": "If true, this leave balance will accrue in Tanda automatically. If false, you should keep it up to date. Default is false."
    }
  },
  "required": [
    "id",
    "user_id",
    "leave_type",
    "hours"
  ]
}

Update Leave Balance
PUT/api/v2/leave_balances/{id}

This method requires the leave scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 666

The id of the leave balance to update

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.

If the organisation has unavailability enabled, then all employees can CRUD unavailability about themselves. Roster managers, and admins can CRUD unavailability for everyone and department managers can CRUD unavailability for users they can manage.

Unavailability List

GET https://my.tanda.co/api/v2/unavailability?ids=1,2,42&from=2016-03-15&to=2016-04-05&user_ids=1,2,123456
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 42,
    "user_id": 123456,
    "title": "Doing errr... something",
    "start": 1459814400,
    "finish": 1459836000,
    "repeating": false,
    "repeating_info": null,
    "all_day": false
  }
]

Get Unavailabilities
GET/api/v2/unavailability{?ids,from,to,user_ids}

Lookup multiple leave requests in a single request.

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

This method requires the unavailability scope (see Scopes for more information).

You will only be able to query up to 366 days when specifying from and to.

URI Parameters
HideShow
ids
string (optional) Example: 1,2,42

Comma separated list of unavailability ids to lookup

from
string (optional) Example: 2016-03-15

From date to lookup unavailability in

to
string (optional) Example: 2016-04-05

To date to lookup unavailability in

user_ids
string (optional) Example: 1,2,123456

Comma separated list of user ids to lookup unavailability for

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified unavailability

POST https://my.tanda.co/api/v2/unavailability
RequestsCreate UnavailabilityCreate all day UnavailabilityCreate repeating Unavailability
Headers
Content-Type: application/json
Body
{
  "user_id": 123456,
  "title": "Buying a unicycle",
  "start": 1459375200,
  "finish": 1459382400,
  "repeating": false
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 106092,
  "user_id": 123456,
  "title": "Buying a unicycle",
  "start": 1459375200,
  "finish": 1459382400,
  "repeating": false,
  "repeating_info": null,
  "all_day": false
}
Headers
Content-Type: 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
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 106092,
  "user_id": 123456,
  "title": "Buying a unicycle",
  "start": 1494770400,
  "finish": 1494856800,
  "repeating": false,
  "repeating_info": null,
  "all_day": true
}
Headers
Content-Type: application/json
Body
{
  "user_id": 123456,
  "title": "Learning to ride my unicycle",
  "start": 1459382400,
  "finish": 1459389600,
  "repeating": true,
  "repeating_info": {
    "interval": "day",
    "occurrences": 3
  }
}
Responses200
Headers
Content-Type: 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
}

Create Unavailability
POST/api/v2/unavailability

This method requires the unavailability scope (see Scopes for more information).

There’s two ways to create unavailabilities: using dates (for all_day events), or using times (for events that don’t go all day).

Regardless of which method you use, you should use the unavailability minimum date from the Settings endpoint to validate your 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.

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

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.

Repeating Unavailability List

GET https://my.tanda.co/api/v2/unavailability/repeating_for/43
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 43,
    "user_id": 123456,
    "title": "Doing errr... something else",
    "start": 1459994400,
    "finish": 1460001600,
    "repeating": true,
    "repeating_info": {
      "interval": "week",
      "occurrences": 2,
      "start": 1459994400,
      "ids": [
        43,
        44
      ]
    }
  },
  {
    "id": 44,
    "user_id": 123456,
    "title": "Doing errr... something else",
    "start": 1460599200,
    "finish": 1460606400,
    "repeating": true,
    "repeating_info": {
      "interval": "week",
      "occurrences": 2,
      "start": 1459994400,
      "ids": [
        43,
        44
      ]
    }
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Repeating Unavailabilities
GET/api/v2/unavailability/repeating_for/{id}

This method requires the unavailability scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 43

The id of the unavailability to get repeating information for

Unavailability

GET https://my.tanda.co/api/v2/unavailability/42
RequestsNon-repeating unavailabilityRepeating unavailability
This response has no content.
Responses200
Headers
Content-Type: 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
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the unavailability"
    },
    "user_id": {
      "type": "number",
      "description": "The user that the unavailability applies for"
    },
    "title": {
      "type": "string",
      "description": "The reason for the unavailability"
    },
    "start": {
      "type": "number",
      "description": "The start time for the unavailability"
    },
    "finish": {
      "type": "number",
      "description": "The end time for the unavailability"
    },
    "repeating": {
      "type": "boolean",
      "description": "Whether this is part of a set of repeating unavailabilities"
    },
    "repeating_info": {
      "type": "object",
      "properties": {
        "interval": {
          "type": "string",
          "description": "The time between repeating events"
        },
        "occurrences": {
          "type": "number",
          "description": "The number of unavailabilities in the repeating set of unavailabilities"
        },
        "start": {
          "type": "number",
          "description": "The start of the first unavailability in the repeating set"
        },
        "ids": {
          "type": "array",
          "description": "The ids of the unavailabilities that are part of the this repeating set"
        }
      },
      "required": [
        "interval",
        "occurrences",
        "start",
        "ids"
      ],
      "description": "Info about the unavailabilities that are part of this repeating set of unavailabilities (if the unavailability is repeating)"
    }
  },
  "required": [
    "id",
    "user_id",
    "start",
    "finish",
    "repeating"
  ]
}
This response has no content.
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 43,
  "user_id": 123456,
  "title": "Doing errr... something else",
  "start": 1459994400,
  "finish": 1460001600,
  "repeating": true,
  "repeating_info": {
    "interval": "week",
    "occurrences": 2,
    "start": 1459994400,
    "ids": [
      43,
      44
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the unavailability"
    },
    "user_id": {
      "type": "number",
      "description": "The user that the unavailability applies for"
    },
    "title": {
      "type": "string",
      "description": "The reason for the unavailability"
    },
    "start": {
      "type": "number",
      "description": "The start time for the unavailability"
    },
    "finish": {
      "type": "number",
      "description": "The end time for the unavailability"
    },
    "repeating": {
      "type": "boolean",
      "description": "Whether this is part of a set of repeating unavailabilities"
    },
    "repeating_info": {
      "type": "object",
      "properties": {
        "interval": {
          "type": "string",
          "description": "The time between repeating events"
        },
        "occurrences": {
          "type": "number",
          "description": "The number of unavailabilities in the repeating set of unavailabilities"
        },
        "start": {
          "type": "number",
          "description": "The start of the first unavailability in the repeating set"
        },
        "ids": {
          "type": "array",
          "description": "The ids of the unavailabilities that are part of the this repeating set"
        }
      },
      "required": [
        "interval",
        "occurrences",
        "start",
        "ids"
      ],
      "description": "Info about the unavailabilities that are part of this repeating set of unavailabilities (if the unavailability is repeating)"
    }
  },
  "required": [
    "id",
    "user_id",
    "start",
    "finish",
    "repeating"
  ]
}

Get Unavailability
GET/api/v2/unavailability/{id}

This method requires the unavailability scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 42

The id of unavailability to lookup

PUT https://my.tanda.co/api/v2/unavailability/42
RequestsUpdate Unavailability
Headers
Content-Type: application/json
Body
{
  "title": "Helping Grandma"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 42,
  "user_id": 123456,
  "title": "Helping Grandma",
  "start": 1459814400,
  "finish": 1459836000,
  "repeating": false,
  "repeating_info": null,
  "all_day": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the unavailability"
    },
    "user_id": {
      "type": "number",
      "description": "The user that the unavailability applies for"
    },
    "title": {
      "type": "string",
      "description": "The reason for the unavailability"
    },
    "start": {
      "type": "number",
      "description": "The start time for the unavailability"
    },
    "finish": {
      "type": "number",
      "description": "The end time for the unavailability"
    },
    "repeating": {
      "type": "boolean",
      "description": "Whether this is part of a set of repeating unavailabilities"
    },
    "repeating_info": {
      "type": "object",
      "properties": {
        "interval": {
          "type": "string",
          "description": "The time between repeating events"
        },
        "occurrences": {
          "type": "number",
          "description": "The number of unavailabilities in the repeating set of unavailabilities"
        },
        "start": {
          "type": "number",
          "description": "The start of the first unavailability in the repeating set"
        },
        "ids": {
          "type": "array",
          "description": "The ids of the unavailabilities that are part of the this repeating set"
        }
      },
      "required": [
        "interval",
        "occurrences",
        "start",
        "ids"
      ],
      "description": "Info about the unavailabilities that are part of this repeating set of unavailabilities (if the unavailability is repeating)"
    }
  },
  "required": [
    "id",
    "user_id",
    "start",
    "finish",
    "repeating"
  ]
}

Update Unavailability
PUT/api/v2/unavailability/{id}

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

This method requires the unavailability scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 42

The id of unavailability to lookup

DELETE https://my.tanda.co/api/v2/unavailability/42
Responses200
Headers
Content-Type: application/json

Delete Unavailability
DELETE/api/v2/unavailability/{id}

This method requires the unavailability scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 42

The id of the leave to delete

Data Streams

Our user guide has more information on working with data streams through the API.

A data stream is a container for many Store Stats. The data stream specifies the origin of the data, an identifier for the origin (if any), and the interval of the data. All store stats added to a data stream should be totaled data for a time period equal to the data_interval.

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

Team managers can read data streams that are joined to their team. General managers and payroll officers can read all data streams, and admins can create read and update all data streams.

Data Stream List

GET https://my.tanda.co/api/v2/datastreams
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 24,
    "name": "Reactor Revenue",
    "source": "generic",
    "data_interval": 900,
    "print_mode": "hidden",
    "roster_display_mode": "values"
  },
  {
    "id": 25,
    "name": "User Entered: Springfield Powerplant",
    "source": "user_entered",
    "data_interval": 86400,
    "print_mode": "hidden",
    "roster_display_mode": "values"
  },
  {
    "id": 26,
    "name": "Reactor Revenue (Retail Express)",
    "source": "retail_express",
    "section_identifier": "11223344",
    "data_interval": 900,
    "print_mode": "hidden",
    "roster_display_mode": "values"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Data Streams
GET/api/v2/datastreams

This method requires the datastream scope (see Scopes for more information).

URI Parameters
HideShow
updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified data streams

POST https://my.tanda.co/api/v2/datastreams
RequestsCreate Data Stream
Headers
Content-Type: application/json
Body
{
  "name": "My Special Data",
  "data_interval": 900
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 1069,
  "name": "My Special Data",
  "source": "api",
  "data_interval": 900,
  "print_mode": "hidden",
  "roster_display_mode": "values"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the data stream"
    },
    "name": {
      "type": "string",
      "description": "The name of the data stream"
    },
    "source": {
      "type": "string",
      "description": "The data stream's source"
    },
    "data_interval": {
      "type": "number",
      "description": "The time between the data stream's store stats in seconds"
    },
    "print_mode": {
      "type": "string",
      "description": "Should the data stream be printed when printing a roster? Options: hidden, values, cumulative_sum"
    },
    "roster_display_mode": {
      "type": "string",
      "description": "Should the data stream be displayed on rosters? Options: hidden, values, cumulative_sum"
    }
  },
  "required": [
    "id",
    "name",
    "data_interval"
  ]
}

Create Data Stream
POST/api/v2/datastreams

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.

This method requires the datastream scope (see Scopes for more information).

Data Stream

GET https://my.tanda.co/api/v2/datastreams/26
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 26,
  "name": "Reactor Revenue (Retail Express)",
  "source": "retail_express",
  "section_identifier": "11223344",
  "data_interval": 900,
  "print_mode": "hidden",
  "roster_display_mode": "values"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the data stream"
    },
    "name": {
      "type": "string",
      "description": "The name of the data stream"
    },
    "source": {
      "type": "string",
      "description": "The data stream's source"
    },
    "section_identifier": {
      "type": "string",
      "description": "A way to map to the external data provider"
    },
    "data_interval": {
      "type": "number",
      "description": "The time between the data stream's store stats in seconds"
    },
    "print_mode": {
      "type": "string",
      "description": "Should the data stream be printed when printing a roster? Options: hidden, values, cumulative_sum"
    },
    "roster_display_mode": {
      "type": "string",
      "description": "Should the data stream be displayed on rosters? Options: hidden, values, cumulative_sum"
    }
  },
  "required": [
    "id",
    "name",
    "source",
    "data_interval"
  ]
}

Get Data Stream
GET/api/v2/datastreams/{id}

This method requires the datastream scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 26

The id of the data stream to lookup

PUT https://my.tanda.co/api/v2/datastreams/26
RequestsUpdate Data Stream
Headers
Content-Type: application/json
Body
{
  "name": "Foot Traffic!",
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 1069,
  "name": "Foot Traffic!",
  "source": "api",
  "data_interval": 900,
  "print_mode": "hidden",
  "roster_display_mode": "values"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the data stream"
    },
    "name": {
      "type": "string",
      "description": "The name of the data stream"
    },
    "source": {
      "type": "string",
      "description": "The data stream's source"
    },
    "data_interval": {
      "type": "number",
      "description": "The time between the data stream's store stats in seconds"
    },
    "print_mode": {
      "type": "string",
      "description": "Should the data stream be printed when printing a roster? Options: hidden, values, cumulative_sum"
    },
    "roster_display_mode": {
      "type": "string",
      "description": "Should the data stream be displayed on rosters? Options: hidden, values, cumulative_sum"
    }
  },
  "required": [
    "id",
    "name",
    "data_interval"
  ]
}

Update Data Stream
PUT/api/v2/datastreams/{id}

This method requires the datastream scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 26

The id of the data stream to update

DELETE https://my.tanda.co/api/v2/datastreams/26
Responses202
Headers
Content-Type: application/json

Delete Data Stream
DELETE/api/v2/datastreams/{id}

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

The data stream will be scheduled for deletion, but may not be removed immediately. You can GET the data stream to check if it’s been deleted.

This method requires the datastream scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 26

The id of the data stream

Data Stream Versions

GET https://my.tanda.co/api/v2/datastreams/26/versions
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "version_id": 123456,
    "time": 1459209907,
    "event": "update",
    "author": {
      "id": 123456,
      "name": "API v2"
    },
    "changes": [
      {
        "field": "data_interval",
        "previous": 900,
        "updated": 1800
      },
      {
        "field": "name",
        "previous": "Employee Superfund",
        "updated": "Reactor Revenue"
      }
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Data Stream Versions
GET/api/v2/datastreams/{id}/versions

This method requires the datastream scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 26

The id of the data stream

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified data stream versions

Data Stream Joins

Our user guide has more information on working with data streams through the API.

Data Stream Joins connect Data Streams to the object which owns the stream’s data. For example, data from a stream may be relate to a Team, Location, or to the Organisation itself.

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

Only admins can manage data stream joins.

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

Data Stream Join List

GET https://my.tanda.co/api/v2/datastreamjoins
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 162,
    "data_stream_id": 24,
    "data_streamable_id": 111,
    "data_streamable_type": "Department",
    "rostering_ratio": 1.175
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Data Stream Joins
GET/api/v2/datastreamjoins

This method requires the datastream scope (see Scopes for more information).

URI Parameters
HideShow
updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified data stream joins

POST https://my.tanda.co/api/v2/datastreamjoins
RequestsCreate Joined to TeamCreate Joined to Organisation
Headers
Content-Type: application/json
Body
{
  "data_stream_id": 24,
  "data_streamable_id": 111,
  "data_streamable_type": "Department",
  "rostering_ratio": 2.5
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 162,
  "data_stream_id": 24,
  "data_streamable_id": 111,
  "data_streamable_type": "Department",
  "rostering_ratio": 2.5
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the data stream join"
    },
    "data_stream_id": {
      "type": "number",
      "description": "The id of the data stream join's data stream"
    },
    "data_streamable_id": {
      "type": "number",
      "description": "The id of the data stream join's data streamable (location or team)"
    },
    "data_streamable_type": {
      "type": "string",
      "description": "The type of the data stream join's data streamable (\"Location\", \"Department\", or \"Organisation\")"
    },
    "rostering_ratio": {
      "type": "number",
      "description": "The ratio of units to staff required when rostering to this data stream"
    }
  },
  "required": [
    "id",
    "data_stream_id",
    "data_streamable_id",
    "data_streamable_type"
  ]
}
Headers
Content-Type: application/json
Body
{
  "data_stream_id": 24,
  "data_streamable_type": "Organisation"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 162,
  "data_stream_id": 24,
  "data_streamable_id": null,
  "data_streamable_type": "Organisation",
  "rostering_ratio": 1.175
}

Create Data Stream Join
POST/api/v2/datastreamjoins

This method requires the datastream scope (see Scopes for more information).

Data Stream Join

GET https://my.tanda.co/api/v2/datastreamjoins/162
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 162,
  "data_stream_id": 24,
  "data_streamable_id": 111,
  "data_streamable_type": "Department",
  "rostering_ratio": 1.175
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the data stream join"
    },
    "data_stream_id": {
      "type": "number",
      "description": "The id of the data stream join's data stream"
    },
    "data_streamable_id": {
      "type": "number",
      "description": "The id of the data stream join's data streamable (location or team)"
    },
    "data_streamable_type": {
      "type": "string",
      "description": "The type of the data stream join's data streamable (\"Location\", \"Department\", or \"Organisation\")"
    },
    "rostering_ratio": {
      "type": "number",
      "description": "The ratio of units to staff required when rostering to this data stream"
    }
  },
  "required": [
    "id",
    "data_stream_id",
    "data_streamable_id",
    "data_streamable_type"
  ]
}

Get Data Stream Join
GET/api/v2/datastreamjoins/{id}

This method requires the datastream scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 162

The id of the data stream join to lookup

PUT https://my.tanda.co/api/v2/datastreamjoins/162
RequestsUpdate Data Stream Join
Headers
Content-Type: application/json
Body
{
  "rostering_ratio": 1.5
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 162,
  "data_stream_id": 24,
  "data_streamable_id": 111,
  "data_streamable_type": "Department",
  "rostering_ratio": 1.5
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the data stream join"
    },
    "data_stream_id": {
      "type": "number",
      "description": "The id of the data stream join's data stream"
    },
    "data_streamable_id": {
      "type": "number",
      "description": "The id of the data stream join's data streamable (location or team)"
    },
    "data_streamable_type": {
      "type": "string",
      "description": "The type of the data stream join's data streamable (\"Location\", \"Department\", or \"Organisation\")"
    },
    "rostering_ratio": {
      "type": "number",
      "description": "The ratio of units to staff required when rostering to this data stream"
    }
  },
  "required": [
    "id",
    "data_stream_id",
    "data_streamable_id",
    "data_streamable_type"
  ]
}

Update Data Stream Join
PUT/api/v2/datastreamjoins/{id}

This method requires the datastream scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 162

The id of the data stream join to update

DELETE https://my.tanda.co/api/v2/datastreamjoins/162
Responses200
Headers
Content-Type: application/json

Delete Data Stream Join
DELETE/api/v2/datastreamjoins/{id}

This method requires the datastream scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 162

The id of the data stream join to delete

Store Stats

Our user guide has more information on working with data streams through the API.

Store stats are the individual statistics that belong to a Data Stream. All store stats for a data stream should be totaled data for a time period equal to the data stream’s data_interval, starting at the store stat’s time.

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

Store stats can be read by a user, if that user is able to read the data stream that the store stat belongs to.

Only admins can create store stats. They are able to do this for any data stream.

Store Stats for Datastream

GET https://my.tanda.co/api/v2/storestats/for_datastream/26/from/2016-03-01/to/2016-03-20?type=sales
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 3518,
    "time": 1459295100,
    "stat": 3.5,
    "type": "sales"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Store Stats for Datastream
GET/api/v2/storestats/for_datastream/{datastream_id}/from/{from}/to/{to}{?type}

This method requires the datastream scope (see Scopes for more information).

You will only be able to query up to 31 days using the from and to parameters.

URI Parameters
HideShow
datastream_id
number (required) Example: 26

The id of the data stream to lookup store stats for

from
string (required) Example: 2016-03-01

The start date of the range to lookup store stats in

to
string (required) Example: 2016-03-20

The id of the data stream to lookup store stats for

type
string (optional) Example: sales

The type of store stats to lookup (if not specified, all stats are returned)

Create Store Stats for Datastream

POST https://my.tanda.co/api/v2/storestats/for_datastream/27
RequestsCreate single Store StatCreate multiple Store Stats
Headers
Content-Type: application/json
Body
{
  "time": 1459296900,
  "stat": 3.5,
  "type": "sales"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 12231,
  "time": 1459296900,
  "stat": 3.5,
  "type": "sales"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the stat"
    },
    "time": {
      "type": "number",
      "description": "The time of the stat"
    },
    "stat": {
      "type": "number",
      "description": "The value of the stat"
    },
    "type": {
      "type": "string",
      "description": "The type of the stat"
    }
  },
  "required": [
    "id",
    "time",
    "stat",
    "type"
  ]
}
Headers
Content-Type: application/json
Body
{
  "stats": [
    {
      "time": 1459296900,
      "stat": 3.5,
      "type": "sales"
    },
    {
      "time": 1459296900,
      "stat": 1,
      "type": "transactions"
    },
    {
      "time": 1459297800,
      "stat": 20.1,
      "type": "sales"
    }
  ]
}
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 12231,
    "time": 1459296900,
    "stat": 3.5,
    "type": "sales"
  },
  {
    "id": 12232,
    "time": 1459296900,
    "stat": 1,
    "type": "transactions"
  },
  {
    "id": 12233,
    "time": 1459297800,
    "stat": 20.1,
    "type": "sales"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Create Store Stats for Datastream
POST/api/v2/storestats/for_datastream/{datastream_id}

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

Store stats will only be able to be created on data streams that were created using the API.

All existing store stats on the data stream within the newly posted store stats’ parameter range will be replaced with the newly posted store stats.

Please see the general Store Stat information above for an example.

This method requires the datastream scope (see Scopes for more information).

URI Parameters
HideShow
datastream_id
number (required) Example: 27

The id of the data stream to create store stats on

Deleting Store Stats

POST https://my.tanda.co/api/v2/storestats/for_datastream

Deleting Store Stats
POST/api/v2/storestats/for_datastream

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

Devices

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

Admins and department managers can read devices, and admins can and update all devices.

Device List

GET https://my.tanda.co/api/v2/devices
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 1234,
    "location_id": 111,
    "nickname": "Reactor Timeclock",
    "returned": false,
    "last_heard_from": 1459296900,
    "dispatch_date": "2016-01-02"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Devices
GET/api/v2/devices

This method requires the device scope (see Scopes for more information).

URI Parameters
HideShow
updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified devices

POST https://my.tanda.co/api/v2/devices
RequestsCreate new timeclock
Headers
Content-Type: application/json
Body
{
  "nickname": "Old Reactor Timeclock",
  "location_id": 111
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 1234,
  "location_id": 111,
  "nickname": "Old Reactor Timeclock",
  "returned": false,
  "last_heard_from": 1459296900,
  "dispatch_date": "2016-01-02"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the device"
    },
    "location_id": {
      "type": "number",
      "description": "The ID of the time clock's [location](#locations)."
    },
    "nickname": {
      "type": "string",
      "description": "The nickname of the device. If not provided, the location's name is used."
    },
    "returned": {
      "type": "boolean",
      "description": "Whether the device has been returned"
    },
    "last_heard_from": {
      "type": "number",
      "description": "The time that the device last communicated with the Tanda server"
    },
    "dispatch_date": {
      "type": "string",
      "description": "The date that the device was sent out"
    }
  },
  "required": [
    "id",
    "nickname",
    "returned"
  ]
}

Create Device
POST/api/v2/devices

This method requires the device scope (see Scopes for more information).

Provide one or both of location_id and nickname when registering a time clock. If a location_id is provided, but a nickname isn’t, the location’s name is used as a nickname.

You can use the following attributes to store hardware information about the device: data_provider, mobile_number, sim_number, serial_number, imei, model.

Returned Device List

GET https://my.tanda.co/api/v2/devices/returned
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 8403,
    "location_id": 111,
    "nickname": "Meltdown Reactor Timeclock",
    "returned": true,
    "return_date": "2016-03-02",
    "last_heard_from": 1456877652,
    "dispatch_date": "2015-10-12"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Returned Devices
GET/api/v2/devices/returned

This method requires the device scope (see Scopes for more information).

URI Parameters
HideShow
updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified returned devices

Device

GET https://my.tanda.co/api/v2/devices/1234
RequestsActive deviceReturned device
This response has no content.
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 1234,
  "location_id": 111,
  "nickname": "Reactor Timeclock",
  "returned": false,
  "last_heard_from": 1459296900,
  "dispatch_date": "2016-01-02"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the device"
    },
    "location_id": {
      "type": "number",
      "description": "The ID of the time clock's [location](#locations)."
    },
    "nickname": {
      "type": "string",
      "description": "The nickname of the device. If not provided, the location's name is used."
    },
    "returned": {
      "type": "boolean",
      "description": "Whether the device has been returned"
    },
    "last_heard_from": {
      "type": "number",
      "description": "The time that the device last communicated with the Tanda server"
    },
    "dispatch_date": {
      "type": "string",
      "description": "The date that the device was sent out"
    }
  },
  "required": [
    "id",
    "nickname",
    "returned"
  ]
}
This response has no content.
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 8403,
  "location_id": 111,
  "nickname": "Meltdown Reactor Timeclock",
  "returned": true,
  "return_date": "2016-03-02",
  "last_heard_from": 1456877652,
  "dispatch_date": "2015-10-12"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the device"
    },
    "location_id": {
      "type": "number",
      "description": "The ID of the time clock's [location](#locations)."
    },
    "nickname": {
      "type": "string",
      "description": "The nickname of the device. If not provided, the location's name is used."
    },
    "returned": {
      "type": "boolean",
      "description": "Whether the device has been returned"
    },
    "return_date": {
      "type": "string",
      "description": "The date the device was returned"
    },
    "last_heard_from": {
      "type": "number",
      "description": "The time that the device last communicated with the Tanda server"
    },
    "dispatch_date": {
      "type": "string",
      "description": "The date that the device was sent out"
    }
  },
  "required": [
    "id",
    "nickname",
    "returned",
    "return_date"
  ]
}

Get Device
GET/api/v2/devices/{id}

This method requires the device scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 1234

The id of the device to lookup

PUT https://my.tanda.co/api/v2/devices/1234
RequestsUpdate device information
Headers
Content-Type: application/json
Body
{
  "nickname": "Old Reactor Timeclock",
  "location_id": 111
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 1234,
  "location_id": 111,
  "nickname": "Old Reactor Timeclock",
  "returned": false,
  "last_heard_from": 1459296900,
  "dispatch_date": "2016-01-02"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the device"
    },
    "location_id": {
      "type": "number",
      "description": "The ID of the time clock's [location](#locations)."
    },
    "nickname": {
      "type": "string",
      "description": "The nickname of the device. If not provided, the location's name is used."
    },
    "returned": {
      "type": "boolean",
      "description": "Whether the device has been returned"
    },
    "last_heard_from": {
      "type": "number",
      "description": "The time that the device last communicated with the Tanda server"
    },
    "dispatch_date": {
      "type": "string",
      "description": "The date that the device was sent out"
    }
  },
  "required": [
    "id",
    "nickname",
    "returned"
  ]
}

Update Device
PUT/api/v2/devices/{id}

This method requires the device scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 1234

The id of the device to edit

Return Device

POST https://my.tanda.co/api/v2/devices/1234/return
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 1234,
  "location_id": 111,
  "nickname": "Reactor Timeclock",
  "returned": "true",
  "last_heard_from": 1459296900,
  "dispatch_date": "2016-01-02",
  "return_date": "2016-04-01"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the device"
    },
    "location_id": {
      "type": "number",
      "description": "The ID of the time clock's [location](#locations)."
    },
    "nickname": {
      "type": "string",
      "description": "The nickname of the device. If not provided, the location's name is used."
    },
    "returned": {
      "type": "string",
      "description": "Whether the device has been returned"
    },
    "last_heard_from": {
      "type": "number",
      "description": "The time that the device last communicated with the Tanda server"
    },
    "dispatch_date": {
      "type": "string",
      "description": "The date that the device was sent out"
    },
    "return_date": {
      "type": "string",
      "description": "The date the device was returned"
    }
  },
  "required": [
    "id",
    "nickname",
    "returned"
  ]
}

Return Device
POST/api/v2/devices/{id}/return

This method requires the device scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 1234

The id of the device to return

Device Versions

GET https://my.tanda.co/api/v2/devices/1234/versions
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "version_id": 123456,
    "time": 1459209907,
    "event": "update",
    "author": {
      "id": 123456,
      "name": "API v2"
    },
    "changes": [
      {
        "field": "nickname",
        "previous": "Breakroom",
        "updated": "Reactor Timeclock"
      },
      {
        "field": "location_id",
        "previous": 111,
        "updated": 112
      }
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Device Versions
GET/api/v2/devices/{id}/versions

This method requires the device scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 1234

The id of the device

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified device versions

Device Access Code

POST https://my.tanda.co/api/v2/devices/reset_access_code
Responses200
Headers
Content-Type: application/json
Body
{
  "access_code": "12345678"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "access_code": {
      "type": "string",
      "description": "Randomly generated 8 digit string"
    }
  },
  "required": [
    "access_code"
  ]
}

Reset Device Access Code
POST/api/v2/devices/reset_access_code

This method requires the device scope (see Scopes for more information).

The access code is used by admins when setting up a device as an alternative to entering their username and password.

Clock Ins

Clock ins represent actual times that the employee arrived and left from a location (most often a work site or office).

You must be able to manage the user to make a clock in for them. To read clock ins for a user or device, the user must be able to manage the the user, or read the device respectively.

Clock In

POST https://my.tanda.co/api/v2/clockins
RequestsClock InClock OutSpecific Photo & Time ClockSpecific TeamBad Image
Headers
Content-Type: application/json
Body
{
  "user_id": 123456,
  "type": "clockin",
  "time": 1459296192
}
Responses201
Headers
Content-Type: application/json
Body
{
  "id": 6108,
  "user_id": 123456,
  "device_id": 1234,
  "time": 1459296192,
  "type": "clockin",
  "latitude": null,
  "longitude": null,
  "photo": null,
  "department_id": null,
  "shift_id": null,
  "removed": false
}
Headers
Content-Type: application/json
Body
{
  "user_id": 123456,
  "type": "clockout",
  "time": 1459296192
}
Responses201
Headers
Content-Type: application/json
Body
{
  "id": 6108,
  "user_id": 123456,
  "device_id": 1234,
  "time": 1459296192,
  "type": "clockout",
  "latitude": null,
  "longitude": null,
  "photo": null,
  "department_id": null,
  "shift_id": null,
  "removed": false
}
Headers
Content-Type: application/json
Body
{
  "user_id": 123456,
  "type": "clockin",
  "time": 1459296192,
  "device_id": 1234,
  "photo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAB0AAAAaCAI..."
}
Responses201
Headers
Content-Type: application/json
Body
{
  "id": 6108,
  "user_id": 123456,
  "device_id": 1234,
  "time": 1459296192,
  "type": "clockin",
  "latitude": null,
  "longitude": null,
  "photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
  "department_id": null,
  "shift_id": null,
  "removed": false
}
Headers
Content-Type: application/json
Body
{
  "user_id": 123456,
  "type": "clockin",
  "time": 1459296192,
  "department_id": 808
}
Responses201
Headers
Content-Type: application/json
Body
{
  "id": 6108,
  "user_id": 123456,
  "device_id": 1234,
  "time": 1459296192,
  "type": "clockin",
  "latitude": null,
  "longitude": null,
  "photo": null,
  "department_id": 808,
  "shift_id": null,
  "removed": false
}
Headers
Content-Type: application/json
Body
{
  "user_id": 123456,
  "type": "clockin",
  "time": 1459296192,
  "department_id": 808,
  "photo": "non-base64 png string"
}
Responses400
Headers
Content-Type: application/json
Body
{
  "error": "Photo parameter is not in png base64 format!"
}

Perform Clock In for User
POST/api/v2/clockins

Use this endpoint to send clock ins to Tanda in “real time” as employees clock in or out of work. The clock in will be stored as a distinct object in Tanda, but will also be copied to a Shift, which will then be visible on a Timesheets. When posting clockins to Tanda, here’s a few things to be aware of:

Time rounding

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

De-duplication

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

Non-immediate processing

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

Clock Ins are copied to timesheets

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

Clock In image format

Images on Clock Ins are optional. However, if you wish to include an image with a Clock In, the image must be a base64 PNG using the Data URI scheme. An example encoded image can be seen below:

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAAAAAA6fptVAAAACklEQVQYV2P4DwABAQEAWk1v8QAAAABJRU5ErkJggg==

If you do choose to provide an image, and the image isn’t in the correct format, you will receive a response with a 400 HTTP status. An example of the response can be seen on the right.

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

  • user_id - required, integer - the ID of the User clocking in or out.

  • type - required, string - must be either clockin or clockout.

  • time - required, integer - a unix timestamp representing when the clock in or out happened. This time cannot be in the future.

  • device_id - optional, integer - the ID of the Time Clock used to clock in or out. If provided, is used to verify the location the clock in took place at.

  • photo - optional, string - a photo of the user clocking in. If provided, must be a base64 encoded PNG image.

  • department_id - optional, integer - the Team being clocked in to. If provided, the User must already be in this Team (otherwise it will be ignored). This will show on the user’s timesheet.

  • tag - optional, string - an Award Tag for the shift. If provided, is used for award interpretation purposes. This should be the tag’s name, not its ID.

  • relaxed_time_constraint - optional, boolean - by default, clockins more than 10 minutes into the future (as computed at the server’s time) will be rejected. If this parameter is set to true, clock ins up to 2 hours in the future will be permitted.

If a device_id is provided, you can also use these attributes to store hardware information about the time clock: data_provider, mobile_number, sim_number, serial_number, imei, model.

This method requires the device scope (see Scopes for more information).

You will only be able to clock in for users you can manage, on devices you can see.

Clock In List

GET https://my.tanda.co/api/v2/clockins?user_id=123456&from=2016-03-15&to=2016-04-05
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 6108,
    "user_id": 123456,
    "device_id": 1234,
    "time": 1459209907,
    "type": "clockin",
    "latitude": -27.459687,
    "longitude": 153.032108,
    "photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
    "department_id": 808,
    "shift_id": 1337,
    "removed": false
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Clock Ins for User
GET/api/v2/clockins{?user_id,from,to}

Both from and to are required, and at least one of user_id and device_id are required.

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

This method requires the device scope (see Scopes for more information).

You will only be able to query up to 31 days using the from and to parameters.

URI Parameters
HideShow
user_id
number (required) Example: 123456

The id of the user to lookup clock ins for

from
string (required) Example: 2016-03-15

From date to lookup clock ins within

to
string (required) Example: 2016-04-05

To date to lookup clock ins within

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified clock ins

GET https://my.tanda.co/api/v2/clockins?device_id=1234&from=2016-03-15&to=2016-04-05
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 6108,
    "user_id": 123456,
    "device_id": 1234,
    "time": 1459209907,
    "type": "clockin",
    "latitude": -27.459687,
    "longitude": 153.032108,
    "photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
    "department_id": 808,
    "shift_id": 1337,
    "removed": false
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Clock Ins for Device
GET/api/v2/clockins{?device_id,from,to}

Both from and to are required, and at least one of user_id and device_id are required.

This method requires the device scope (see Scopes for more information).

You will only be able to query up to 31 days using the from and to parameters.

URI Parameters
HideShow
device_id
number (required) Example: 1234

The id of the device to lookup clock ins for

from
string (required) Example: 2016-03-15

From date to lookup clock ins within

to
string (required) Example: 2016-04-05

To date to lookup clock ins within

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified clock ins

GET https://my.tanda.co/api/v2/clockins?user_id=123456&device_id=1234&from=2016-03-15&to=2016-04-05
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 6108,
    "user_id": 123456,
    "device_id": 1234,
    "time": 1459209907,
    "type": "clockin",
    "latitude": -27.459687,
    "longitude": 153.032108,
    "photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
    "department_id": 808,
    "shift_id": 1337,
    "removed": false
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Clock Ins for User on Device
GET/api/v2/clockins{?user_id,device_id,from,to}

Both from and to are required, and at least one of user_id and device_id are required.

This method requires the device scope (see Scopes for more information).

You will only be able to query up to 31 days using the from and to parameters.

URI Parameters
HideShow
user_id
number (required) Example: 123456

The id of the user to lookup clock ins for

device_id
number (required) Example: 1234

The id of the device to lookup clock ins for

from
string (required) Example: 2016-03-15

From date to lookup clock ins within

to
string (required) Example: 2016-04-05

To date to lookup clock ins within

updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified clock ins

Clock In

GET https://my.tanda.co/api/v2/clockins/6108
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 6108,
  "user_id": 123456,
  "device_id": 1234,
  "time": 1459209907,
  "type": "clockin",
  "latitude": -27.459687,
  "longitude": 153.032108,
  "photo": "http://vignette1.wikia.nocookie.net/family-guyamerican-dadthe-simpsons-and-futurama/images/f/ff/250px-Lenny_Leonard.png",
  "department_id": 808,
  "shift_id": 1337,
  "removed": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the clock in"
    },
    "user_id": {
      "type": "number",
      "description": "The id of the user clocking in"
    },
    "device_id": {
      "type": "number",
      "description": "The id of the time clock the user clocks in using. If not provided a generic time clock record will be used."
    },
    "time": {
      "type": "number",
      "description": "The time the clock in was made"
    },
    "type": {
      "type": "string",
      "description": "`clockin` if the user clocks in, `clockout` if the user clocks out"
    },
    "latitude": {
      "type": "number",
      "description": "The latitude of the clock in"
    },
    "longitude": {
      "type": "number",
      "description": "The longitude of the clock in"
    },
    "photo": {
      "type": "string",
      "description": "The photo the device took when the user clocked in"
    },
    "department_id": {
      "type": "number",
      "description": "The id of the department the clock in (if clock in was for a specific department)"
    },
    "shift_id": {
      "type": "number",
      "description": "The id of the shift the clock in got applied to (will be nil until the clock in has been processed)"
    },
    "removed": {
      "type": "boolean",
      "description": "True if the clock in was removed from the shift due to de-duplication or another reason, see the Clock In endpoint for more information"
    }
  },
  "required": [
    "id",
    "user_id",
    "time",
    "type",
    "removed"
  ]
}

Get Clock In
GET/api/v2/clockins/{id}

For information about how clock ins work, please see the Perform Clock In for User endpoint.

This method requires the device scope (see Scopes for more information).

You will only be able to see clock ins for users you can manage, or for devices you can see.

URI Parameters
HideShow
id
number (required) Example: 6108

The id of the clockin to lookup

SMS

SMSes can be sent to Users who have valid phone numbers.

SMSes can be sent to everyone by admins and roster managers, and department managers can send messages to users they manage.

Send SMS

POST https://my.tanda.co/api/v2/sms/send
RequestsSend SMS
Headers
Content-Type: application/json
Body
{
  "message": "Hello World",
  "user_ids": [
    1,
    123456
  ]
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 4321,
  "date": "2016-03-02",
  "messages": [
    {
      "recipient": "+61404123123",
      "message": "Hello world!\\n\\nSent from Tanda",
      "status": "Not delivered yet"
    },
    {
      "recipient": "+61404456456",
      "message": "Hello world!\\n\\nSent from Tanda",
      "status": "Sent"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the SMS status"
    },
    "date": {
      "type": "string",
      "description": "The date the messages were sent"
    },
    "messages": {
      "type": "array",
      "description": "Messages that were sent"
    }
  },
  "required": [
    "id",
    "date",
    "messages"
  ]
}

Send SMS
POST/api/v2/sms/send

Send an SMS to a list of users.

Messages are queued up to be sent by Tanda so often the response of the post will not contain any information about the messages. Please use the SMS Status method to check the statuses of the messages.

SMSes can be up to 1580 characters long (up to ten 160 character messages with the Tanda footer).

You will only be able to SMS users that you can manage.

The cost of sending SMSes to Users will be billed on the authenticated user’s next Tanda invoice.

This method requires the sms scope (see Scopes for more information).

SMS Status

GET https://my.tanda.co/api/v2/sms/status/4321
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 4321,
  "date": "2016-03-02",
  "messages": [
    {
      "recipient": "+61404123123",
      "message": "Hello world!\\n\\nSent from Tanda",
      "status": "Not delivered yet"
    },
    {
      "recipient": "+61404456456",
      "message": "Hello world!\\n\\nSent from Tanda",
      "status": "Sent"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The id of the SMS status"
    },
    "date": {
      "type": "string",
      "description": "The date the messages were sent"
    },
    "messages": {
      "type": "array",
      "description": "Messages that were sent"
    }
  },
  "required": [
    "id",
    "date",
    "messages"
  ]
}

SMS Status
GET/api/v2/sms/status/{id}

Messages are queued up to be sent by Tanda so checking this endpoint soon after sending the SMSes may return an empty messages array. If this is the case, please wait a few seconds and try again.

This method requires the sms scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 4321

The id of the SMS status to lookup

Qualifications

The Qualifications Power-Up needs to be enabled before you can access this endpoint.

Qualifications List

GET https://my.tanda.co/api/v2/qualifications
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 123706,
    "name": "Blue Card",
    "maximum_hours": 21.34
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Qualifications
GET/api/v2/qualifications

This method requires the qualifications scope (see Scopes for more information).

POST https://my.tanda.co/api/v2/qualifications
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "name": "Responsible Service of Alcohol",
  "maximum_hours": 20.5
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 123706,
  "name": "Responsible Service of Alcohol",
  "maximum_hours": "20.5"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The qualification ID"
    },
    "name": {
      "type": "string",
      "description": "The name of the qualification"
    },
    "maximum_hours": {
      "type": "string",
      "description": "Maximum number of hours that can be worked per week if this qualification is enabled"
    }
  },
  "required": [
    "id",
    "name"
  ]
}

Create Qualification
POST/api/v2/qualifications

Once created, a qualification will be visible in your qualifications list. Use its ID to add it to staff profiles, and to teams.

This method requires the qualifications scope (see Scopes for more information).

Qualification

GET https://my.tanda.co/api/v2/qualifications/123706
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 123706,
  "name": "Blue Card",
  "maximum_hours": 21.34
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The qualification ID"
    },
    "name": {
      "type": "string",
      "description": "The name of the qualification"
    },
    "maximum_hours": {
      "type": "number",
      "description": "Maximum number of hours that can be worked per week if this qualification is enabled"
    }
  },
  "required": [
    "id",
    "name"
  ]
}

Get Qualification
GET/api/v2/qualifications/{id}

This method requires the qualifications scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 123706

The id of the qualification

PUT https://my.tanda.co/api/v2/qualifications/123706
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "name": "RSA v2"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 123706,
  "name": "RSA v2",
  "maximum_hours": 21.34
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The qualification ID"
    },
    "name": {
      "type": "string",
      "description": "The name of the qualification"
    },
    "maximum_hours": {
      "type": "number",
      "description": "Maximum number of hours that can be worked per week if this qualification is enabled"
    }
  },
  "required": [
    "id",
    "name"
  ]
}

Update Qualification
PUT/api/v2/qualifications/{id}

This method requires the qualifications scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 123706

The id of the qualification to edit

DELETE https://my.tanda.co/api/v2/qualifications/123706
Responses200
Headers
Content-Type: application/json

Delete Qualification
DELETE/api/v2/qualifications/{id}

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

This method requires the qualifications scope (see Scopes for more information).

URI Parameters
HideShow
id
number (required) Example: 123706

The id of the qualification

System Settings

System settings are accessible through the API if they are visible on the Tanda settings page. Please refer to the settings page inside Tanda for up to date documentation on each setting and the options available.

Only admins are able to access settings.

Settings

GET https://my.tanda.co/api/v2/settings
Responses200
Headers
Content-Type: application/json
Body
{
  "enable_availability": false,
  "unavailability_minimum_date": "2016-02-29",
  "enable_employee_leave": true,
  "leave_request_default_length": 7.6
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "enable_availability": {
      "type": "boolean",
      "description": "Employees can use an app to enter unavailability"
    },
    "unavailability_minimum_date": {
      "type": "string",
      "description": "The earliest date for which Unavailability can be entered."
    },
    "enable_employee_leave": {
      "type": "boolean",
      "description": "Allow employees to enter leave requests through Tanda"
    },
    "leave_request_default_length": {
      "type": "number",
      "description": "Default leave request length (hours)"
    }
  }
}

Get Settings
GET/api/v2/settings

This method requires the settings scope (see Scopes for more information).

The full range of properties that are returned may vary on a per-user basis. To the right is a sample, to illustrate the structure of responses. Therefore, your code should gracefully handle the condition where a particular key is not present.

Settings Versions

GET https://my.tanda.co/api/v2/settings/versions
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "version_id": 123456,
    "time": 1459209907,
    "event": "update",
    "author": {
      "id": 123456,
      "name": "API v2"
    },
    "changes": [
      {
        "field": "enable_availability",
        "previous": true,
        "updated": false
      },
      {
        "field": "unavailability_minimum_days",
        "previous": 3,
        "updated": 4
      }
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Settings Versions
GET/api/v2/settings/versions

This method requires the settings scope (see Scopes for more information).

The full range of properties that are returned may vary on a per-user basis. To the right is a sample, to illustrate the structure of responses. Therefore, your code should gracefully handle the condition where a particular key is not present.

URI Parameters
HideShow
updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified settings versions

Award Templates

Use the award templates endpoint to read and update which managed awards an organisation has enabled.

Only admins are able to access this endpoint.

Award Templates List

GET https://my.tanda.co/api/v2/award_templates
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "award_template_id": 990,
    "name": "Clerks Private Sector",
    "identifier": "MA000002"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Enabled Award Templates
GET/api/v2/award_templates

This method returns a list of award templates enabled for the API user’s organisation.

This method requires the settings scope (see Scopes for more information).

URI Parameters
HideShow
updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified award templates

POST https://my.tanda.co/api/v2/award_templates
RequestsEnable Award TemplateEnable Award Template With Leave Types Extracted
Headers
Content-Type: application/json
Body
{
  "award_template_id": 990,
}
Responses200
Headers
Content-Type: application/json
Body
{
  "award_template_id": 990,
  "name": "Clerks Private Sector",
  "identifier": "MA000002"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "award_template_id": {
      "type": "number",
      "description": "The award template ID"
    },
    "name": {
      "type": "string",
      "description": "The name of the award or EBA"
    },
    "identifier": {
      "type": "string",
      "description": "An identifier for the award or EBA"
    }
  },
  "required": [
    "award_template_id"
  ]
}
Headers
Content-Type: application/json
Body
{
  "award_template_id": 990,
  "extract_leave_types": true,
  "replace_leave_types": true
}
Responses200
Headers
Content-Type: application/json
Body
{
  "award_template_id": 990,
  "name": "Clerks Private Sector",
  "identifier": "MA000002"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "award_template_id": {
      "type": "number",
      "description": "The award template ID"
    },
    "name": {
      "type": "string",
      "description": "The name of the award or EBA"
    },
    "identifier": {
      "type": "string",
      "description": "An identifier for the award or EBA"
    }
  },
  "required": [
    "award_template_id"
  ]
}

Enable Award Template
POST/api/v2/award_templates

Use this method to enable an award template for a particular organisation. A single field, the award_template_id, is required. This field is unique across Tanda. You can get a list of valid IDs by making a call to the available award templates method.

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

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

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

This method requires the settings scope (see Scopes for more information).

Award Templates List

GET https://my.tanda.co/api/v2/award_templates/available
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "award_template_id": 990,
    "name": "Clerks Private Sector",
    "identifier": "MA000002"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Available Award Templates
GET/api/v2/award_templates/available

This method returns a full list of award templates available in Tanda.

This method requires the settings scope (see Scopes for more information).

Organisations

Use the organisations endpoint to get a list of clients you manage, and register new clients. If you have access to this endpoint, you can also get access tokens for clients you manage.

To get access to this endpoint, please contact Tanda.

Organisation List

GET https://my.tanda.co/api/v2/organisations
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 747,
    "name": "Tom's Restaurant",
    "payroll_system": "myob",
    "country": "Australia",
    "locale": "en",
    "time_zone": "Brisbane",
    "customer_ids": [
      748,
      749
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Organisations
GET/api/v2/organisations

This method requires the organisation scope (see Scopes for more information).

URI Parameters
HideShow
updated_after
number (optional) Example: 1451570400

Time filter to find recently created or modified organisations

POST https://my.tanda.co/api/v2/organisations
RequestsCreate Organisation
Headers
Content-Type: application/json
Body
{
  "name": "Vandelay Industries",
  "country": "New Zealand",
  "locale": "en-NZ",
  "timesheet_interval": 1,
  "week_start_day": 0,
  "time_zone": "Auckland",
  "award_template_ids": [
    1,
    2,
    3
  ],
  "customer_ids": []
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 748,
  "name": "Vandelay Industries",
  "payroll_system": "myob",
  "country": "New Zealand",
  "locale": "en",
  "time_zone": "Auckland",
  "customer_ids": []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "Organisation's unique ID"
    },
    "name": {
      "type": "string",
      "description": "The organisation's name"
    },
    "payroll_system": {
      "type": "string",
      "description": "The payroll software used by the organisation"
    },
    "country": {
      "type": "string",
      "description": "The country in which the organisation is legally based"
    },
    "locale": {
      "type": "string",
      "description": "NZ"
    },
    "time_zone": {
      "type": "string",
      "description": "The organisation's time zone name"
    },
    "customer_ids": {
      "type": "array",
      "description": "Organisation IDs for customers of this organisation"
    }
  },
  "required": [
    "id",
    "name",
    "country"
  ]
}

Create Organisation
POST/api/v2/organisations

This method requires the organisation scope (see Scopes for more information).

The following fields can be used when creating a new organisation:

  • name - required, string - the organisation’s name.

  • country - required, string - the country the organisation is legally established in.

  • timesheet_interval - required, integer - 1 for weekly timesheets, 2 for fortnightly timesheets.

  • week_start_day - required, integer - the day of the week that timesheets should start on. 0 is Sunday, 1 is Monday, and so on.

  • locale - optional, string - the language tag for system translation. Defaults to en. Click here for more information.

  • time_zone - optional, string - the time zone for the new organisation. If not provided, defaults to authenticated user’s time zone. Uses zone names from here, eg “Brisbane” or “Perth”.

  • award_template_ids - optional, array[integer] - IDs of award templates you’d like to make available to this organisation. Note that you’ll still need to enable the award template once the organisation is created.

  • customer_ids - optional, array[integer] - IDs of other organisations which are customers of this organisation. This organisation will be able to access its customers and impersonate users within them through the Tanda UI.

Organisation

GET https://my.tanda.co/api/v2/organisations
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 747,
  "name": "Tom's Restaurant",
  "payroll_system": "myob",
  "country": "Australia",
  "locale": "en",
  "time_zone": "Brisbane",
  "customer_ids": [
    748,
    749
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "Organisation's unique ID"
    },
    "name": {
      "type": "string",
      "description": "The organisation's name"
    },
    "payroll_system": {
      "type": "string",
      "description": "The payroll software used by the organisation"
    },
    "country": {
      "type": "string",
      "description": "The country in which the organisation is legally based"
    },
    "locale": {
      "type": "string",
      "description": "The i18n locale for the organisation"
    },
    "time_zone": {
      "type": "string",
      "description": "The organisation's time zone name"
    },
    "customer_ids": {
      "type": "array",
      "description": "Organisation IDs for customers of this organisation"
    }
  },
  "required": [
    "id",
    "name",
    "country"
  ]
}

Get Organisation
GET/api/v2/organisations

Get an organisation by id.

This method requires the organisation scope (see Scopes for more information).

PUT https://my.tanda.co/api/v2/organisations/747
RequestsAdd CustomerClear Customers
Headers
Content-Type: application/json
Body
{
  "customer_ids": [
    737,
    727
  ]
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 747,
  "name": "Tom's Restaurant",
  "payroll_system": "myob",
  "country": "Australia",
  "locale": "en",
  "time_zone": "Brisbane",
  "customer_ids": [
    727,
    737
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "Organisation's unique ID"
    },
    "name": {
      "type": "string",
      "description": "The organisation's name"
    },
    "payroll_system": {
      "type": "string",
      "description": "The payroll software used by the organisation"
    },
    "country": {
      "type": "string",
      "description": "The country in which the organisation is legally based"
    },
    "locale": {
      "type": "string",
      "description": "The i18n locale for the organisation"
    },
    "time_zone": {
      "type": "string",
      "description": "The organisation's time zone name"
    },
    "customer_ids": {
      "type": "array",
      "description": "Organisation IDs for customers of this organisation"
    }
  },
  "required": [
    "id",
    "name",
    "country"
  ]
}
Headers
Content-Type: application/json
Body
{
  "customer_ids": []
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 747,
  "name": "Tom's Restaurant",
  "payroll_system": "myob",
  "country": "Australia",
  "locale": "en",
  "time_zone": "Brisbane",
  "customer_ids": []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "Organisation's unique ID"
    },
    "name": {
      "type": "string",
      "description": "The organisation's name"
    },
    "payroll_system": {
      "type": "string",
      "description": "The payroll software used by the organisation"
    },
    "country": {
      "type": "string",
      "description": "The country in which the organisation is legally based"
    },
    "locale": {
      "type": "string",
      "description": "The i18n locale for the organisation"
    },
    "time_zone": {
      "type": "string",
      "description": "The organisation's time zone name"
    },
    "customer_ids": {
      "type": "array",
      "description": "Organisation IDs for customers of this organisation"
    }
  },
  "required": [
    "id",
    "name",
    "country"
  ]
}

Update Organisation
PUT/api/v2/organisations/{id}

This method requires the organisation scope (see Scopes for more information).

The following fields can be updated using this endpoint:

  • name - required, string - the organisation’s name.

  • country - required, string - the country the organisation is legally established in.

  • locale - optional, string - the language tag for system translation. Defaults to en. Click here for more information.

  • award_template_ids - optional, array[integer] - IDs of award templates you’d like to make available to this organisation. Note that you’ll still need to enable the award template once the organisation is created.

  • customer_ids - optional, array[integer] - IDs of other organisations which are customers of this organisation. This organisation will be able to access its customers and impersonate users within them through the Tanda UI.

URI Parameters
HideShow
id
number (required) Example: 747

The ID of the organisation

Organisation Access Tokens

POST https://my.tanda.co/api/oauth/token
RequestsCreate Access Token
Body
curl https://my.tanda.co/api/oauth/token -X POST -H "Cache-Control: no-cache" \
-F "access_token=YOUR_CURRENT_ACCESS_TOKEN" \
-F "organisation_id=747" \
-F "scope=user me" \
-F "grant_type=partner_token"
Responses200
Body
{
  "access_token": "6833b9ecaa84ce420da3cafaa43124d241cb28b5287b72d131f6b38bcb64cd91",
  "token_type": "bearer",
  "scope": "user me",
  "created_at": 1457304578
}

Create Access Token
POST/api/oauth/token

Use this endpoint to get an access token for an organisation that you have read access to. To request a token, make a POST to /api/oauth/token - the same path you would use to request a regular Password access token. Supply these fields:

  • access_token - required, string - your current valid access token (the one you use to get a list of organisations)

  • organisation_id - required, integer - the organisation you’d like to get an access token for - get this from the list of organisations

  • scope - required, string - one or more Scopes separated by spaces

  • grant_type - required, string - must be partner_token

The right sidebar contains an example access token reques & response. The access token in the response will give you access to the organisation ID provided in the request.

Personal Details

Update your own details.

These details will apply to all accounts linked under your profile

All endpoints here require the personal scope. Some endpoints require the financial scope to view financial data, or the user scope to view data about an employee.

This endpoint is not strictly RESTful. The root-level request doesn’t refer to all records, but to the records only of the currently-authenticated user. Similarly, updates can only be performed for the currently authenticated user.

Your Personal Details

GET https://my.tanda.co/api/v2/personal_details
Responses200
Headers
Content-Type: application/json
Body
{
  "residential_address": {
    "street_line_one": "742 Evergreen Terrace",
    "street_line_two": null,
    "city": "Springfield",
    "state": "Oregon",
    "country": "United States of America",
    "postcode": "97475"
  },
  "gender": "male",
  "tax_file_number": "123 456 789",
  "emergency_contacts": [
    {
      "name": "Marge Simpson",
      "relationship": "Wife",
      "phone": "0400 000 000"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "residential_address": {
      "type": "object",
      "properties": {
        "street_line_one": {
          "type": "string"
        },
        "street_line_two": {
          "type": [
            "string",
            "null"
          ],
          "description": "Apartment, Suite, etc"
        },
        "city": {
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "type": [
            "string",
            "null"
          ]
        },
        "country": {
          "type": "string"
        },
        "postcode": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "street_line_two"
      ]
    },
    "gender": {
      "type": "string",
      "enum": [
        "male",
        "female"
      ]
    },
    "tax_file_number": {
      "type": "string",
      "description": "The tax file number for the user. This property only exists when using the `financial` scope is in use."
    },
    "emergency_contacts": {
      "type": "array"
    }
  }
}

Get Personal Details
GET/api/v2/personal_details

Gets the personal details of the currently authenticated user

This method requires the personal scope.

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

PUT https://my.tanda.co/api/v2/personal_details
RequestsUpdate postcodeMissing ScopeClear all emergency contacts
Headers
Content-Type: application/json
Body
{
  "residential_address": {
    "postcode": "97477"
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "residential_address": {
    "street_line_one": "742 Evergreen Terrace",
    "street_line_two": null,
    "city": "Springfield",
    "state": "Oregon",
    "country": "United States of America",
    "postcode": "97477"
  },
  "gender": "male",
  "tax_file_number": "123 456 789",
  "emergency_contacts": [{
    "id": 1234
    "name": "Marge Simpson",
    "relationship": "Wife",
    "phone": "0400 000 000"
  }]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "residential_address": {
      "type": "object",
      "properties": {
        "street_line_one": {
          "type": "string"
        },
        "street_line_two": {
          "type": [
            "string",
            "null"
          ],
          "description": "Apartment, Suite, etc"
        },
        "city": {
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "type": [
            "string",
            "null"
          ]
        },
        "country": {
          "type": "string"
        },
        "postcode": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "street_line_two"
      ]
    },
    "gender": {
      "type": "string",
      "enum": [
        "male",
        "female"
      ]
    },
    "tax_file_number": {
      "type": "string",
      "description": "The tax file number for the user. This property only exists when using the `financial` scope is in use."
    },
    "emergency_contacts": {
      "type": "array"
    }
  }
}
Headers
Content-Type: application/json
Body
{
  "tax_file_number": "987654321"
}
Responses403
Headers
Content-Type: application/json
Body
{
  "error": "You must have the financial scope to update a Tax File Number"
}
Headers
Content-Type: application/json
Body
{
  "emergency_contacts": []
}
Responses200
Headers
Content-Type: application/json
Body
{
  "residential_address": {
    "street_line_one": "742 Evergreen Terrace",
    "street_line_two": null,
    "city": "Springfield",
    "state": "Oregon",
    "country": "United States of America",
    "postcode": "97477"
  },
  "gender": "male",
  "tax_file_number": "123 456 789",
  "emergency_contacts": []
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "residential_address": {
      "type": "object",
      "properties": {
        "street_line_one": {
          "type": "string"
        },
        "street_line_two": {
          "type": [
            "string",
            "null"
          ],
          "description": "Apartment, Suite, etc"
        },
        "city": {
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "type": [
            "string",
            "null"
          ]
        },
        "country": {
          "type": "string"
        },
        "postcode": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "street_line_two"
      ]
    },
    "gender": {
      "type": "string",
      "enum": [
        "male",
        "female"
      ]
    },
    "tax_file_number": {
      "type": "string",
      "description": "The tax file number for the user. This property only exists when using the `financial` scope is in use."
    },
    "emergency_contacts": {
      "type": "array"
    }
  }
}

Update Personal Details
PUT/api/v2/personal_details

Update the currently authenticated user’s personal details.

At this point in time, a user may only update their own personal details. You cannot update the personal details for any user other than the currently authenticated user.

To update the tax_file_number, you must have the financial scope.

Using this endpoint with emergency_contacts will overwrite the existing contacts. An empty array will clear all contacts.

Valid values for a Tax File Number are:

  • A tax file number (8 or 9 numeric characters only, with or without spaces), or

  • The exemption:

    • If underage: exempt_underage
    • If applied: exempt_applied
    • If claiming a benefit or allowance, exempt_allowance
    • If intentionally witheld, exempt_blank

Personal Details

GET https://my.tanda.co/api/v2/personal_details/123456
Responses200
Headers
Content-Type: application/json
Body
{
  "residential_address": {
    "street_line_one": "742 Evergreen Terrace",
    "street_line_two": null,
    "city": "Springfield",
    "state": "Oregon",
    "country": "United States of America",
    "postcode": "97477"
  },
  "gender": "male",
  "tax_file_number": "123 456 789",
  "emergency_contacts": [{
    "id": 1234
    "name": "Marge Simpson",
    "relationship": "Wife",
    "phone": "0400 000 000"
  }]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "residential_address": {
      "type": "object",
      "properties": {
        "street_line_one": {
          "type": "string"
        },
        "street_line_two": {
          "type": [
            "string",
            "null"
          ],
          "description": "Apartment, Suite, etc"
        },
        "city": {
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "type": [
            "string",
            "null"
          ]
        },
        "country": {
          "type": "string"
        },
        "postcode": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "street_line_two"
      ]
    },
    "gender": {
      "type": "string",
      "enum": [
        "male",
        "female"
      ]
    },
    "tax_file_number": {
      "type": "string",
      "description": "The tax file number for the user. This property only exists when using the `financial` scope is in use."
    },
    "emergency_contacts": {
      "type": "array"
    }
  }
}

Get Employee's Personal Details
GET/api/v2/personal_details/{user_id}

This endpoint requires the user scope. The authenticated user must also be a manager of the employee identified by user_id. The financial scope is required to see financial data.

URI Parameters
HideShow
user_id
number (required) Example: 123456

The id of the user

Emergency Contacts

POST https://my.tanda.co/api/v2/personal_details/emergency_contacts
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "name": "Marge Simpson",
  "relationship": "Wife",
  "phone": "0400 000 000"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "relationship": {
      "type": "string"
    },
    "phone": {
      "type": "string"
    }
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "residential_address": {
    "street_line_one": "742 Evergreen Terrace",
    "street_line_two": null,
    "city": "Springfield",
    "state": "Oregon",
    "country": "United States of America",
    "postcode": "97477"
  },
  "gender": "male",
  "tax_file_number": "123 456 789",
  "emergency_contacts": [{
    "id": 1234
    "name": "Marge Simpson",
    "relationship": "Wife",
    "phone": "0400 000 000"
  }]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "residential_address": {
      "type": "object",
      "properties": {
        "street_line_one": {
          "type": "string"
        },
        "street_line_two": {
          "type": [
            "string",
            "null"
          ],
          "description": "Apartment, Suite, etc"
        },
        "city": {
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "type": [
            "string",
            "null"
          ]
        },
        "country": {
          "type": "string"
        },
        "postcode": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "street_line_two"
      ]
    },
    "gender": {
      "type": "string",
      "enum": [
        "male",
        "female"
      ]
    },
    "tax_file_number": {
      "type": "string",
      "description": "The tax file number for the user. This property only exists when using the `financial` scope is in use."
    },
    "emergency_contacts": {
      "type": "array"
    }
  }
}

Create an emergency contact
POST/api/v2/personal_details/emergency_contacts

Emergency Contacts

DELETE https://my.tanda.co/api/v2/personal_details/emergency_contacts/654321
Responses200
This response has no content.

Delete an emergency contact
DELETE/api/v2/personal_details/emergency_contacts/{contact_id}

URI Parameters
HideShow
contact_id
number (required) Example: 654321

The id of the emergency contact to delete

Webhooks

Get notified when things happen inside Tanda.

Consult our user guide to walk you through setting up a Webhook - there’s no programming knowledge required!

There are three concepts to understand when working with webhooks:

  • Topics: a topic is a type of event that can happen inside Tanda, for example “user.created” or “clockin.updated” - a full list of topics can be found below.

  • Subscriptions: a subscription is comprised of a URL (where we send the notification payload) and the specific events in Tanda (topics) you want sent to the URL, think of these as the events you have subscribed to be notified about.

  • Notifications: a notification is a HTTP POST request we make to the URL you configure in the subscription. All notifications received will follow the format outlined in the notification payload section below.

Notification Payload

Headers

Content-Length: 475
Content-Type: application/json
User-Agent: tanda-webhooks
X-Request-Id: 58c0be3e-677b-4364-94ff-e01afa866d34
X-Hook-Signature: g7LZCBPlwBg1vid0dOHgt7HToR0=

Payload

{
  "hook_key": "",
  "hook_time": "",
  "hook_signature": "",
  "payload": {
    "body": {},
    "topic": ""
  }
}

  • hook_key: The hook_key is a UUID associated with the webhook event, if you’re worried about duplications interfering with your integration, use this to dedup.

  • hook_time: The hook_time is the time the event was emitted in epoch format.

  • hook_signature: The hook_signature is a pointer to the Header you should retrieve to access the security token.

  • body: The contents of the payload.body depend upon what topic the subscription is for, for each topic you can generally find the payload body under the corresponding API endpoint documentation e.g. a subscription to the leaverequest.created event will have the same fields as the response to the endpoint to create a leave request.

  • topic: This is the topic name as detailed in the ‘Topic’ column below.

Available Topics

TopicDescription
clockin.updatedSent when a clockin is updated, for example to get a shift ID attached post-processing. Not sent for when a clockin with a photo is processed, use clockin.photo for this.
clockin.photoSent when a clockin with a photo is processed. Not all clockins have photos, so this will be a subset of clockin.updated.
department.createdSent when a team is created.
department.updatedSent when a team is updated.
department.destroyedSent when a team is destroyed.
leaverequest.approvedSent when a leave request is approved.
leaverequest.createdSent when a leave request is created.
leaverequest.rejectedSent when a leave request is rejected.
leaverequest.updatedSent when a leave request is updated (this includes approval and rejection).
schedule.createdSent when a schedule is created (doesn't send for roster templates).
schedule.updatedSent when a schedule is changed (doesn't send for roster templates).
schedule.destroyedSent when a schedule is deleted (doesn't send for roster templates).
schedule.publishedSent when a schedule is sent to an employee by email or SMS, or when it's printed
shift.approvedSent when a shift is approved.
shift.unapprovedSent when a shift is unapproved.
shift.updatedSent when a shift is changed (includes approval).
super_fund_membership.updatedSent when a user's super fund membership is changed.
timesheet.approvedSent when a timesheet is approved.
timesheet.exportedSent when a timesheet is exported.
unavailability.createdSent when an unavailability is created.
qualification.createdSent when an qualification is created.
qualification.updatedSent when an qualification is changed.
qualification.destroyedSent when an qualification is deleted.
user.createdSent when a new user is created, either manually, by API, or by bulk import.
user.deactivatedSent when a new user is deactivated, either manually or via the API.
user.updatedSent when a user is changed.

Want to see other topics added to this list? Let us know!

Creating Webhooks

To manage Webhooks you have two choices:

  • the API if this is part of a more complicated integration with Tanda.

  • the UI if the use case is simple enough.

Programmatically

Webhooks can be managed via API calls, please note you’ll need to be authenticated as an Admin user when making calls to the /api/v2/webhooks endpoints.

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

Through the UI

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

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

Testing your Webhooks

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

Securing Webhooks

To validate that the Webhook has come from Tanda and not an unknown 3rd party, we attach a security token to each request in the headers under X-Hook-Signature. The security token is constructed from a secret you provide when you first create the subscription.

The token is computed using the HMAC SHA1 hashing algorithm, you can likely find a package for computing the hash on your client. The secret you provide during subscription creation is used as the key and the request body (all of it) is the message passed to the hashing function.

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

By checking that the X-Hook-Signature matches when you receive it you can be sure that the webhook came from Tanda & was not tampered with along the way to your system.

Some samples for validating the HMACSHA1 are below:

NodeJS 

const crypto       = require('crypto');

app.get('/webhook', (req, res) => {
  const signature = request.headers['X-Hook-Signature'];
  const requestBody = request.body;
  
  function sign (requestBody, signature) {
    return 'sha1=' + crypto.createHmac('sha1', signature).update(requestBody).digest('hex')
  }
  
  function verify (secret, requestBody, signature) {
    return crypto.timingSafeEqual(Buffer.from(secret), Buffer.from(sign(requestBody, signature)))
  }
  
  const secret = 'IAmASecretYouProvidedDuringSubscription';
  if (!verify(secret, requestBody, signature))
    return new Error('X-Hook-Signature does not match the computed request body signature')
})

Ruby 

ENV['WEBHOOK_SECRET'] = 'IAmASecretYouProvidedDuringSubscription'
def verify_signature(request_body)
  if ENV['WEBHOOK_SECRET']
    signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), ENV['WEBHOOK_SECRET'], request)
    halt 500, "Signatures didn't match!" unless Rack::Utils.secure_compare(signature, request.env['X-Hook-Signature'])
  end
end

Failures & Retries

When we send a notification, we expect to get back a 200 response code. If we don’t get a 200, we’ll consider the webhook failed & begin retrying it. We process retries as described below:

  • Once every 5 minutes for the first hour

  • Once every hour for the next 12 hours

  • At this point if there has been no successful delivery, we give up

Subscriptions List

Only admin users are able to access these endpoints. Webhook configuration is common across an organisation.

GET https://my.tanda.co/api/v2/webhooks
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 123456,
    "url": "https://requestb.in/TaNdA",
    "token": "IaMaSeCrEt",
    "topics": [
      "user.created",
      "clockin.updated"
    ]
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Subscriptions
GET/api/v2/webhooks

POST https://my.tanda.co/api/v2/webhooks
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "url": "https://requestb.in/TaNdA",
  "secret": "IaMaOptionalSeCrEt"
  "topics": ["user.created", "clockin.updated"]
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": 123456,
  "url": "https://requestb.in/TaNdA",
  "token": "IaMaSeCrEt",
  "topics": [
    "user.created",
    "clockin.updated"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object"<