Teamdeck API (1.0.0)

Download OpenAPI specification:Download

Introduction

Teamdeck API is a RESTful interface, which allows you to access and update much of your data in the app.

Responses (including errors) are returned in JSON format. We use built-in HTTP features, like HTTP verbs, to receive commands and return responses. The API is designed to have predictable, resource-oriented URLs.

Authentication

In order to authorize your account, you need to generate a token.

Log in to your Teamdeck account and go to Settings > Integrations > API keys.

Note: You have to be an owner of your Teamdeck organization to access this tab.

Type in the name of your token, select the permission you want to receive and click the plus icon.

There are two permission types in Teamdeck:

  • read - allows you to read the data using the GET method
  • read + write - allows you to read & modify the data using the GET, PUT, POST & DELETE methods

api_key

In order to authenticate Teamdeck API, send a request with the following HTTP header:

Security Scheme Type API Key
Header parameter name: X-Api-Key

Errors

Teamdeck uses standard HTTP response codes to indicate API errors or successful requests:

  • 2xx - the request was fulfilled successfully,
  • 4xx - there was an issue with the request that was sent,
  • 5xx - there is a server-side problem - something went wrong on Teamdeck’s end.

Rate limiting

Teamdeck accounts are subject to rate limiting: 5000 requests per hour per key.

Webhooks

Important changes happening in your Teamdeck account are recorded as events. For example, each time a new project is added, an event is created.

You can listen to these events and be notified about changes in your organization by configuring Webhook URL.

Log in to your Teamdeck account and go to Settings > Integrations > Webhooks.

Note: You have to be an owner of your Teamdeck organization to access this tab.

Here you can paste a payload URL and name it. You can create multiple webhooks, but all of the events (listed below) will be sent to any webhook you set up.

Note: You have to use HTTPS in your webhook URL.

Retry policy: In an event your request fails (the response status > 300), we will try sending a request after 30 seconds, and then the last one 60 seconds later.

The events are returned in JSON format, following this basic structure:

  {
    "id": 1,
    "type": "booking_created",
    "date": "2018-01-01 15:00:00",
    "creator_resource_id": 1,
    "data": {
      "id": 1,
      ...
    }
  }

For update events the structure will be:

  {
    "id": 1,
    "type": "booking_created",
    "date": "2018-01-01 15:00:00",
    "creator_resource_id": 1,
    "data": {
      "id": 1,
      ...
    },
    "data_before": {
        "id": 1,
        ...
    }
  }

The following events are available:

Event type Description
booking_created New booking created
booking_updated Booking updated
booking_deleted Booking deleted
time_entry_created New time entry created
time_entry_updated Time entry updated
time_entry_deleted Time entry deleted
vacation_created New vacation created
vacation_updated Vacation updated
vacation_deleted Vacation deleted
project_created New project created
project_updated Project updated

Bookings

When you plan your team’s work in Teamdeck, every assignment is called a booking. Bookings are always assigned to resources and projects, have a start and end data, as well as a specified daily duration.

Return bookings in organization

Returns a list of bookings in your organization.

Authorizations:
query Parameters
sort
any

Pick the order in which the bookings will be returned. You can sort by any field: ?sort=start_date will return a list of bookings sorted by their starting dates in ascending order, whereas ?sort=-start_date will return a list in descending order.

fields
any

Select the fields you want to be returned. By default, all of the fields are returned.

expand
any

Select the extended fields you want to be returned. Available fields: [tags, occurrences]

page
integer
Default: 0

Select the page you want to display. By default, this is set to 0.

resource_id
integer

Filter the resource_id values of the bookings you want to be returned. Multiple IDs can be passed as comma-separated values. By default, all of the bookings are returned.

project_id
integer

Filter the project_id values of the bookings you want to be returned. Multiple IDs can be passed as comma-separated values. By default, all of the bookings are returned.

external_id
string

Filter the external_id values of the entries you want to be returned. Multiple IDs can be passed as comma-separated values. By default, all of the entries are returned.

start_date_from
date

Filter bookings by their start_date field. Use the YYYY-MM-DD format.

start_date_to
date

Filter bookings by their start_date field. Use the YYYY-MM-DD format.

end_date_from
date

Filter bookings by their end_date field. Use the YYYY-MM-DD format.

end_date_to
date

Filter bookings by their end_date field. Use the YYYY-MM-DD format.

date
date

Filter bookings by single date. Use the YYYY-MM-DD format. You can`t use this filter with date range filters.

Responses

200

Successful operation

401

Invalid authorization response

422

Invalid input

get /bookings

This is Teamdecks Public API documentation

https://api.teamdeck.io/v1/bookings

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Add a new booking

Authorizations:
header Parameters
X-TD-DISABLE-NOTIFICATIONS
boolean
Default: false

If set to true notifications won't be sent

Request Body schema: application/json

Booking object that needs to be added

resource_id
required
integer (Resource identifier)

ID of the resource assigned to this entry.

project_id
required
integer (Project identifier)

ID of the project assigned to this entry.

hours
int64
Deprecated

The length of a booking in hours.

minutes
required
int64

The length of a booking in minutes.

weekend_booking
boolean
Default: false

This is set to false by default, meaning that the booking is set not to happen during a weekend day. true signifies bookings that don’t take weekends into account.

holidays_booking
boolean
Default: false

This is set to false by default, meaning that the booking is is set not to happen during a holiday. true signifies bookings that don’t take holidays into account.

vacations_booking
boolean
Default: false

This is set to false by default, meaning that the booking is is set not to happen during a vacation (personal time off of a given resource). true signifies bookings that don’t take vacations into account.

rrule
string

The RRULE if you want to repeat the booking. We allow for FREQ=DAILY|WEEKLY|MONTHLY|YEARLY, BYDAY|BYMONTHDAY. We require to set UNTIL or COUNT, and max duration is 3 years.

description
string

Description of a booking.

external_id
string

External id of a booking for internal use.

start_date
required
string <YYYY-MM-DD>

Starting date of a booking.

end_date
required
string <YYYY-MM-DD>

End date of a booking.

creator_resource_id
integer (Resource identifier)

ID of the resource who has created this booking.

editor_resource_id
integer (Resource identifier)

ID of the resource who has updated this booking.

Responses

200

Successful operation

401

Invalid authorization response

403

Invalid token rights response

422

Invalid input

post /bookings

This is Teamdecks Public API documentation

https://api.teamdeck.io/v1/bookings

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "resource_id": 1,
  • "project_id": 1,
  • "hours": 8,
  • "minutes": 120,
  • "weekend_booking": true,
  • "holidays_booking": true,
  • "vacations_booking": true,
  • "rrule": "FREQ=DAILY;COUNT=2",
  • "description": "string",
  • "external_id": "string",
  • "start_date": "2018-07-01",
  • "end_date": "2018-07-01",
  • "creator_resource_id": 1,
  • "editor_resource_id": 1
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "resource_id": 1,
  • "project_id": 1,
  • "hours": 8,
  • "minutes": 120,
  • "weekend_booking": true,
  • "holidays_booking": true,
  • "vacations_booking": true,
  • "rrule": "FREQ=DAILY;COUNT=2",
  • "description": "string",
  • "external_id": "string",
  • "start_date": "2018-07-01",
  • "end_date": "2018-07-01",
  • "creator_resource_id": 1,
  • "editor_resource_id": 1
}

Return single booking from organization

Return a single booking from your organization based on its ID.

Authorizations:
path Parameters
id
required
integer (Booking identifier)
Example: 1

ID of a booking you want to get.

query Parameters
expand
any

Select the extended fields you want to be returned. Available fields: [tags, occurrences]

Responses

200

Successful operation

401

Invalid authorization response

403

Invalid token rights response

get /bookings/{id}

This is Teamdecks Public API documentation

https://api.teamdeck.io/v1/bookings/{id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "resource_id": 1,
  • "project_id": 1,
  • "hours": 8,
  • "minutes": 120,
  • "weekend_booking": true,
  • "holidays_booking": true,
  • "vacations_booking": true,
  • "rrule": "FREQ=DAILY;COUNT=2",
  • "description": "string",
  • "external_id": "string",
  • "start_date": "2018-07-01",
  • "end_date": "2018-07-01",
  • "creator_resource_id": 1,
  • "editor_resource_id": 1
}

Update booking

Update information about any booking within your organization.

Authorizations:
path Parameters
id
required
integer (Booking identifier)
Example: 1

ID of a booking you want to update.

header Parameters
X-TD-DISABLE-NOTIFICATIONS
boolean
Default: false

If set to true notifications won't be sent

Request Body schema: application/json

Booking object that needs to be added

resource_id
required
integer (Resource identifier)

ID of the resource assigned to this entry.

project_id
required
integer (Project identifier)

ID of the project assigned to this entry.

hours
int64
Deprecated

The length of a booking in hours.

minutes
required
int64

The length of a booking in minutes.

weekend_booking
boolean
Default: false

This is set to false by default, meaning that the booking is set not to happen during a weekend day. true signifies bookings that don’t take weekends into account.

holidays_booking
boolean
Default: false

This is set to false by default, meaning that the booking is is set not to happen during a holiday. true signifies bookings that don’t take holidays into account.

vacations_booking
boolean
Default: false

This is set to false by default, meaning that the booking is is set not to happen during a vacation (personal time off of a given resource). true signifies bookings that don’t take vacations into account.

rrule
string

The RRULE if you want to repeat the booking. We allow for FREQ=DAILY|WEEKLY|MONTHLY|YEARLY, BYDAY|BYMONTHDAY. We require to set UNTIL or COUNT, and max duration is 3 years.

description
string

Description of a booking.

external_id
string

External id of a booking for internal use.

start_date
required
string <YYYY-MM-DD>

Starting date of a booking.

end_date
required
string <YYYY-MM-DD>

End date of a booking.

creator_resource_id
integer (Resource identifier)

ID of the resource who has created this booking.

editor_resource_id
integer (Resource identifier)

ID of the resource who has updated this booking.

Responses

200

Successful operation

401

Invalid authorization response

403

Invalid token rights response

422

Invalid input

put /bookings/{id}

This is Teamdecks Public API documentation

https://api.teamdeck.io/v1/bookings/{id}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "resource_id": 1,
  • "project_id": 1,
  • "hours": 8,
  • "minutes": 120,
  • "weekend_booking": true,
  • "holidays_booking": true,
  • "vacations_booking": true,
  • "rrule": "FREQ=DAILY;COUNT=2",
  • "description": "string",
  • "external_id": "string",
  • "start_date": "2018-07-01",
  • "end_date": "2018-07-01",
  • "creator_resource_id": 1,
  • "editor_resource_id": 1
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "resource_id": 1,
  • "project_id": 1,
  • "hours": 8,
  • "minutes": 120,
  • "weekend_booking": true,
  • "holidays_booking": true,
  • "vacations_booking": true,
  • "rrule": "FREQ=DAILY;COUNT=2",
  • "description": "string",
  • "external_id": "string",